Skip to content

v1.4.0 ·

From requirement to code and back: AC traceability

The problem

Acceptance criteria, tests, and code are linked only in prose. The requirements skill demands testable criteria and the testing skill says "each criterion needs at least one test," but the linkage lives in testing.md coverage notes — asserted by the agent, never verified. aidlc gate passes when the document exists, not when the coverage exists. The framework itself was built with Kiro-numbered traceability (gate.ts header: Requirements: 9.1, 9.2, 9.6) that it does not offer its users.

How it could be solved

Traceability is easy to fake. Any project can maintain a document claiming that requirement seven is covered by test twelve, and that document starts rotting the day after it is written. The design question was therefore not "how do we record coverage" but "how do we make coverage something the machine finds rather than something a human asserts".

The first instinct was a dedicated command with its own matrix file — aidlc trace, a coverage report, a artifact listing every requirement against its implementation. It was rejected precisely because it would work: it produces a credible-looking document that nothing enforces, and a second source of truth that drifts from the first. New machinery, new file, no teeth.

The second option was to have the agent maintain the mapping in the testing artifact. Kept, but not as the mechanism — as an optional supplement. On its own it puts us back where we started, with linkage asserted rather than discovered.

What shipped extends the gate that already exists. AIDLC already blocks phase transitions on unmet criteria, already has a CLI surface for asking why, and already has CI semantics. Adding acceptance-criteria coverage as one more gate criterion meant no new machinery, no new file, and no new place for the truth to live. The linkage is computed by grepping for AC identifiers in the code and tests, which is why the identifier grammar had to become strict — a closed grammar is what makes "found" possible instead of "claimed".

How AIDLC solves it

  • Feature commit d0a10a6 on feat/20260815-traceability-ids, merged to main as d1f42dd, released as tag v1.4.0 (final tag at e457037).
  • GitHub release: https://github.com/rasensio/aidlc/releases/tag/v1.4.0
  • npm: @rasensio/aidlc-content@1.4.0 and @rasensio/aidlc@1.4.0 published via the new tag-triggered workflow (.github/workflows/release.yml, npm Trusted Publishing/OIDC — no token, no OTP). dist-tags.latest = 1.4.0 for both.
  • Smoke test in CI: npm i -g @rasensio/aidlc@1.4.0 + aidlc --version → 1.4.0.