Requirements written from the code, kept true by every merge.
A business requirements document that was true when it was written and rots afterwards is the norm. Here the suite is generated from the codebase and your existing specs, every merged pull request produces a manifest of the requirements it touched, contradictions become tracked conflicts instead of silent rewrites, and each claim is scored against the code it describes.
# 01 Storefront
## 01.1 Product search
Search must match singular and plural terms (see issue 103).
## 01.2 Wishlists
A wishlist can be shared with a public link; the heart icon
reflects membership instantly.
## 3. Functional Requirements
| ID | Requirement | Status |
|------|----------------------------------------------------|-------------|
| 01.1 | Product search shall match singular and plural terms | IMPLEMENTED |
| 01.2 | A wishlist shall be shareable by public link | IMPLEMENTED |
| 01.3 | A customer shall be able to request a return | DRAFT |
<!-- Machine-Readable Context: modules, key_paths, open_items … -->Three levels, one tree.
A master document rolls up the modules; each module document lists its features and functional requirements; feature documents hold the detail. Every document carries a machine-readable block the pipeline uses to route changes, so a diff in the checkout code lands on the checkout requirements and nowhere else.
Generation reads the repository and any specs you upload (markdown, text, PDF, Word). What you already wrote is reconciled, not replaced. Every apply snapshots the previous version, so a wrong edit is a revert, never a loss. People can edit a document directly; the editor refuses to save a machine block it cannot parse and says which line.
Contradictions are kept, not smoothed over.
When a merged change contradicts a requirement that still stands, the platform records a conflict with the evidence on both sides. A person accepts it (the requirement changes), dismisses it (the code is wrong) or reopens it later. A conflict an apply pass rewrote is marked reconciled, distinct from a human decision. Conflicts live on the document they belong to, module or feature, so resolving one never touches another.
Each claim gets a score.
A validation run takes every requirement row, looks for it in the code, and records found, partial or not found. A row that honestly says NOT_FOUND about missing code is accurate; a row that claims IMPLEMENTED for code that is not there is a contradiction. Documents accumulate an accuracy trail over weeks, so the confidence view shows which modules are drifting and which are improving, and which have too few checkable claims to score at all.
From a manifest, the pipeline can also generate catalog tests linked to the requirement rows they verify. They land disabled, in the same catalog as every other test.
Where it stops today
- The prose generator underneath is a vendored engine; what the platform owns is the lifecycle around it (routing, snapshots, conflicts, scoring). Treat a generated sentence as a draft until a person or a validation run has checked it.
- Status labels on requirement rows lag reality until an apply pass runs; a fresh project shows many PROPOSED rows for shipped features.
- Confidence needs checkable claims. A document with no functional-requirements table scores nothing and says so, rather than showing zero.
- Uploaded specs are inputs to reconciliation, not a second source of truth; the generated tree is what the pipeline maintains.