requirements

Use the draft operation to create docs/requirements/<slug>.md from the template, filling in background, at least one source (S1), and at least one numbered requirement (R1) with rationale and acceptance criteria. The doc stays in draft status until flipped to approved, then an epic can link to it.

Requirements docs capture the *what* of a body of work: background, sources, and testable requirements R1 through Rn. ADRs capture the *how* and *why* of implementation decisions. Requirements docs sit before epics in the lifecycle, while ADRs document decisions made during design.

No, R-numbers must remain stable and are never renumbered. When a requirement is removed, mark it as (removed) in place rather than shifting subsequent numbers, so external references to specific R-numbers stay valid.

Use the supersede operation: set supersedes in the new doc's frontmatter, set status to superseded and superseded-by in the old doc, and add a one-sentence cross-link note in both docs' Background sections.

The audit walks docs/requirements/ and lists docs by status (draft, in-review, approved, superseded). It flags draft docs older than 30 days with no linked epic, approved docs whose linked epic is closed, and docs containing zero requirements.

It does not auto-generate requirements from issues or discussions, enforce approval signoff (status: approved is convention only), or support cross-repo requirements. Implementation decisions are out of scope and belong in ADRs.