Functional Specification

Scope

In scope for 0.2.1: local Markdown/JSON import, schema validation, deterministic question prompts, reviewable acceptance scenarios, explicit self-attested approval, revision history, evidence links with SHA-256, change impact, traceability reports, independent audit report, audit chain, authenticated loopback read-only API, project-local IDE instruction packs.

Out of scope (planned): natural-language semantic extraction, rich Markdown grammar, executing tests, authenticated stakeholder review, ticketing sync, dashboard, enterprise SSO/RBAC.

Personas

PersonaGoalPrimary commands
Product ownerTurn a rough ask into approved, testable requirementsingest, review, approve
Business analystClose open questions, manage revisionsreview, revise, impact
Engineering leadLink implementation to a requirement revisionlink --kind code
QA engineerRecord test outcomes without overstating them`link --kind testtest-run`
Release managerSee what is evidenced and what is staletrace, report
Internal auditorVerify the record independentlyaudit, verify

Functional requirements

IDRequirementVerified by
F-01Import .md, .txt and .json; reject anything else; cap input at 2 MiBsecurity tests
F-02Assign deterministic stable IDs; re-import of identical content is skipped; same ID with different content is refused (use revise)registry tests
F-03Generate questions for every missing field and for invitation, role, billing topicsrequirements tests
F-04Generate five candidate scenarios (primary, unauthorized, invalid input, repeat, audit) labelled unapproveddemo test
F-05approve requires reviewer, note, exact current revision, --confirm-humanregistry tests
F-06revise increments the revision only when canonical content changes; keeps a snapshotregistry tests
F-07link is bound to the current revision; an old revision is rejectedregistry tests
F-08test links record the file hash and nothing more; test-run and release outcomes are labelled not independently verifiedregistry/audit tests
F-09attest requires current approval, observed code, imported passed test-run and imported release claimregistry tests
F-10trace/report write JSON, Markdown, HTML, feature file, questions, assumptions, evidence manifestsecurity tests
F-11audit writes sealed audit-report.json/.md/.html; verify checks the seal; --strict exits 2 on FAILassurance tests
F-12serve binds 127.0.0.1, bearer token of 24+ characters, GET only, no CORS, rate limitedserver tests
F-13install-ide copies project-local instructions only; refuses overwrite without --forceinstaller tests

Traceability states

StateMeaning
needs-stakeholder-approvalNo self-attested approval for the current revision
approved-unverifiedApproved; no current evidence
partial-evidenceApproved; some current evidence
human-review-requiredApproved with code, imported passed test-run and imported release claim; waiting for attestation
human-attested-evidence-linkedA human attested to the evidence. Not "completed".

Exit codes

0 success · 1 error or refused action · 2 audit verdict FAIL when --strict is set.

Acceptance demo

Input Add team invitations with roles yields open questions about authorization, roles, expiry and delivery; five candidate scenarios; five structured requirements; three linked test-file references; and a report showing no requirement approved or completed. Revising one requirement makes its old approvals and links stale.