kandev/docs/specs/guide/traceability-and-lifecycle.md

Traceability and Lifecycle

Traceability chain

Kandev uses this traceability chain:

REQ -> AC -> system design -> work order -> test

Requirements own product behavior. System designs own the technical path. Work orders own implementation scope. Tests provide executable evidence.

References

A system design lists its REQ-* references in frontmatter. A work order lists the applicable REQ-* and AC-* identifiers and its system-design paths.

Use an @covers AC-... annotation in a test name or nearby comment when the mapping is not clear from the test location. Do not add a second coverage ID unless a tool requires one.

Do not copy requirement text into a system design or work order. If an isolated execution environment needs the text, generate a snapshot and record the source commit.

Status values

System README files use draft, active, or retired. Their migration field uses in_progress or complete.

Requirement documents use:

• draft: The behavior is not yet accepted.
• active: The behavior is the current product contract.
• deprecated: The behavior remains documented during removal or transition.

System-design documents use:

• draft: The technical design is not yet accepted.
• current: The design describes the current intended system.
• superseded: Another design replaced this design.

Work orders use pending, in_progress, blocked, done, or cancelled. Implementation state does not change a requirement document from active to shipped. Delivery state belongs to plans, work orders, and coverage evidence.

Stable identities

Requirement and acceptance-criterion IDs are globally unique and retain one meaning across concurrent branches; they do not change when a file moves. Do not reuse removed IDs or renumber an ID to hide a parallel-branch collision. A replacement requirement references the requirement that it supersedes. Reconcile parallel specification changes before merging them so every artifact continues to point to one authoritative contract.

Migration

Migrate one system at a time. Use this sequence:

1. Create the system README.md, define its boundary, and set migration: in_progress.
2. Inventory the legacy specifications that the system owns.
3. Extract observable behavior into requirement documents.
4. Extract technical contracts and design into system-design documents.
5. Add stable IDs and cross-references.
6. Keep the system boundary and migration record in the system README.md.
7. Add a short link to the system README.md, or archive the legacy document outside docs/specs/<system>/.
8. Run the catalog and specification linters.
9. Set migration: complete and remove obsolete size exceptions.

Do not keep two editable sources of truth during migration.

Do not mark migration complete while requirement files contain generic criteria that defer to copied legacy prose. Extract observable behavior into AC-* IDs. Move technical facts into system designs, then remove the copied source detail.