Skip to content
Chelis docs

Introduction

c-earchin (v0.3.3) translates EARS requirement files into Chelis Deep witness definitions plus provenance spans. It is an external-notation bridge: you write requirements in EARS, the structured-English requirement syntax, and c-earchin lowers them into Chelis Deep so that chelis prove can run them as properties. It also ingests Kiro-style requirements.md files (EARS with bolded keywords) directly: .md files auto-detect, or pass --dialect kiro.

EARS (Easy Approach to Requirements Syntax) constrains requirement prose to a small set of templates built around the keyword shall. Each template names a system, a response, and an optional trigger, state, condition, or feature. That structure is regular enough to classify mechanically, which is what makes the translation possible.

What the bridge produces

Section titled “What the bridge produces”

For each translation, c-earchin writes two files:

  • A .dp Deep file. It contains a fixed vocabulary of pure-boolean predicates followed by one callable bool witness definition per requirement. Each resolved witness carries both the c_earchin_* metadata (pattern, clause spans, requirement id) and canonical Chelis property metadata (chelis_role: "property" and the property_* fields). Because the witnesses use canonical metadata, chelis prove discovers them by its normal property scan without requiring a new Deep tag.
  • A .spans.json provenance manifest. Every emitted Deep node records the EARS or Kiro source file, requirement id, requirement text, and byte and line span it came from, down to the individual clauses of the requirement.

The pipeline is a straight line:

EARS source -> parser -> classifier -> vocabulary lookup -> lowerer -> emitter

The Deep file uses only existing Chelis tags. Requirement intent is attached through c_earchin_* metadata, while the canonical chelis_role and property_* metadata make each witness discoverable.

Provenance is the point

Section titled “Provenance is the point”

A requirement that translates is not just runnable. It stays traceable. When a witness fails under chelis prove, the span manifest resolves the failing Deep node back to the exact EARS requirement line that produced it:

property failure: req_FIN_003
  --> references/finance_options/options_rules.ears:3:1 FIN-003
  | WHILE the exchange is open, the portfolio delta shall be at most the limit.

A stakeholder reading the EARS file and an engineer reading the proof output are looking at the same requirement, identified the same way.

What this book covers

Section titled “What this book covers”