Skip to content

traceability.md

Latest commit

 

History

History
27 lines (20 loc) · 2.4 KB

traceability.md

File metadata and controls

27 lines (20 loc) · 2.4 KB
Raw

Traceability: requirements, evidence, findings

This part is for teams that keep a written design. It is optional and entirely authored: you write these files in instances/<name>/intent/; SourceCompass does not discover them from code. It shows where they disagree with the code.

  • Requirements have an id and a revision. They are PROPOSED until a named human authority approves them. An approval binds the id, the revision and the exact text. If someone edits the text, it reads as proposed again.
  • Planned evaluations are not proof. eb req <id> lists the checks a design plans. A plan is a plan.
  • Evidence records bind to one requirement revision and one layer. They do not transfer to another revision. Evidence for revision 1 says nothing about revision 2.
  • Findings from a review map to a requirement with a disposition and an owner. Owners are checked against your plan file. A proposed owner reads as not registered. An owner the plan file does not carry reads NOT FOUND. intent/findings.json maps every finding to the requirement revision that answers it, or marks it superseded, duplicate, non-actionable or unresolved. eb findings shows coverage and what is unresolved; eb findings <id> traces one finding from its source document to the evidence.
  • Trace and Maps are viewer tabs that show how requirements, findings and evidence connect, and the design's maps.

There are three kinds of update. Keep them apart, because they mean different things:

Kind Command What it does What it never does
Refresh eb build Re-reads the code and design files and rebuilds the map Change the design or approve anything
Evidence eb evidence add Records one check against one requirement revision Edit the design; make the map stale; count for another revision
Proposal eb propose, then eb proposals resolve Suggests new text against a revision, and later records how it ended Edit the design. The owner applies an accepted change

The demo ships no requirements, findings or evidence, so on the demo these commands answer only:

no findings for this instance (add intent/findings.json)
no requirement "reports.DW1". Ids look like <module>.DW<n>, R<nn> or <port>.DW<n>; eb arch <module> lists them.
no evidence recorded

The full command list is in commands.md and the agent routine in AGENT-CONTRACT.md.