feat: per-stage traceability enforcement with deterministic JSON sensor#401
Open
jeromevdl wants to merge 2 commits into
Open
feat: per-stage traceability enforcement with deterministic JSON sensor#401jeromevdl wants to merge 2 commits into
jeromevdl wants to merge 2 commits into
Conversation
- Stable ID conventions: FR{n}, NFR{n}, US{n}.{m}, AC{story}.{seq}, BR{group}.{seq}, NFRx.y
- Each stage produces traceability.md mapping upstream elements to outputs
- New traceability sensor (aidlc-sensor-traceability.ts) fires at gate, checks for GAP/ORPHAN markers
- Phase boundaries: delivery-planning aggregates inception tables, build-and-test does final coverage gate
- Moved Construction→Operation boundary from ci-pipeline (conditional) to build-and-test (always runs)
- NFR numbering: inception NFRs decompose to NFRx.y in construction
- AC numbering: acceptance criteria numbered as AC{story}.{seq}
- BR numbering: business rules numbered as BR{group}.{seq}
- Fixed typo in infrastructure-design.md ("ok letstages")
- Updated docs and knowledge base to reflect new verification model
Known limitations:
- Sensor checks self-reported gaps only (marker grep), not completeness (ID diffing) — v2 sensor needed
- Ideation→Inception boundary unchanged (no numbered IDs at that phase)
- Empty traceability.md passes (no minimum-rows check yet)
…nd unit scoping
Replaces the fragile markdown-table sensor with a structured JSON approach:
- traceability.json (not .md/.yaml): parsed via JSON.parse, zero ambiguity
- Three-layer verification: minimum coverage + status scan + upstream ID cross-check
- Per-unit scoping via unit-of-work-story-map.md (U{n} prefix matching)
- Deferred/N/A without target treated as gaps
- Malformed JSON emits pass:false (not exit 1 swallowed by dispatcher)
- Removed traceability from produces: (sensor-only artifact, not consumed downstream)
ID conventions enforced in stage prose:
- FR{n}, NFR{n} at requirements-analysis
- US{n}.{m} at user-stories (+ AC{story}.{seq} 3-segment)
- BR{group}.{seq} at functional-design
- NFRx.y at nfr-requirements
- U{n} / u{n}-{desc} naming at units-generation
Upstream ID cross-check catches silent omissions:
- Extracts IDs from upstream files via regex
- Compares against declared upstream_ids in the JSON
- Two independent sources must agree (LLM declaration + file extraction)
Test coverage: 14 cases covering status detection, minimum coverage,
upstream diffing, per-unit scoping, malformed JSON, and error handling.
Known limitations:
- Unit-name join assumes u{n}-{desc} dir / U{n} column convention
- Free-text elements (component names) not diffable — marker scan only
- Empty expected set on naming mismatch: advisory warning, not failure
8238a48 to
3b47e04
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds element-level traceability enforcement across the AIDLC workflow — ensuring nothing from the initial intent (requirements, stories, acceptance criteria) is silently dropped between stages.
What this adds
Stable ID conventions (enforced in stage prose)
FR{n},NFR{n}— requirements-analysisUS{n}.{m}— user-storiesAC{story}.{seq}(3-segment) — user-storiesBR{group}.{seq}— functional-designNFRx.y— nfr-requirements decompositionU{n}/u{n}-{desc}— units-generation namingPer-stage traceability.json
Each stage produces a structured JSON file mapping upstream elements to downstream coverage:
{ "stage": "functional-design", "unit": "u1-auth", "upstream_ids": ["AC1.1.1", "AC1.1.2"], "coverage": [ { "id": "AC1.1.1", "status": "OK", "target": "BR01" }, { "id": "AC1.1.2", "status": "GAP" } ], "reverse": [ { "id": "BR03", "status": "ORPHAN" } ] }Deterministic traceability sensor
aidlc-sensor-traceability.tsfires at each gate with three checks:upstream_ids. Two independent sources must agree.Per-unit stages scope via
unit-of-work-story-map.mdto avoid false positives across units.Phase boundaries
Other changes
Known limitations
u{n}convention — advisory warning emitted on naming mismatchPre-existing test failures (not introduced by this PR)