v1.4.0 ·
From requirement to code and back: AC traceability
Acceptance criteria, tests and code were linked only in prose. The testing notes said "each criterion has a test," an agent wrote that down, and nobody checked. aidlc gate passed when the document existed, not when the coverage did. I had built the framework with numbered traceability in its own code, and it offered users none of that.
Coverage the machine finds
Now the gate looks. Criteria in a requirements file follow a strict form: a short numbered identifier, a colon, then the text. The gate greps the project's test files for those identifiers. For a testing check on an instance with criteria, every active criterion has to be referenced somewhere, or the gate says which ones are not. On this release's own instance, aidlc gate traceability-ids testing passes with all 25 criteria covered.
The strictness is what makes "found" possible. The matching is word-boundary and case-sensitive, so a reference to criterion 12 never counts as coverage for criterion 1, and a leading zero makes a different token. A line that almost looks like a criterion, with a misplaced colon or a leading zero, produces a warning instead of silently dropping out of the required set. A gap in the numbering warns too. Criteria that were retired stay out of required coverage but remain easy to reference.
If two instances define the same identifier, a bare reference counts for neither and warns. A reference qualified with the instance name counts for exactly that instance. An instance with no criteria sees no change at all in the gate output.
Test file globs have defaults and can be replaced in .aidlc/config.yaml. Dependencies, build output, .git and .aidlc are always skipped. Unreadable, binary and oversized files are skipped with a warning, and the scan never throws out of the gate.
Why this way
I first wanted a dedicated aidlc trace command with its own coverage matrix. I dropped it because it would have worked in the worst way: a credible-looking document that nothing enforces, and a second source of truth that drifts from the first.
I also considered having the agent keep the mapping in the testing notes. That survives, as an optional supplement: a fenced block lists criteria with evidence, and counts alongside the scan. On its own it puts us back where we started, with coverage asserted instead of discovered.
So this extends the gate that already blocks phase changes, already has a command for asking why, and already runs in CI. No new file, no new place for the truth to live.
What it does not do
It proves a criterion is mentioned in a test file. It cannot tell whether that test checks anything. An empty test that cites the identifier passes.
The release itself was messy. A timing bound failed under parallel load, a few tests failed on CI runners, and publishing hit ENEEDAUTH twice. Node 22 bundles npm 10, and trusted publishing needs npm 11.5.1 or later, so the workflow now upgrades npm. I re-pointed the unpublished tag twice before anything reached the registry. Cost to build was about $66.75.