fix: tighten milestone audit requirements verification with 3-source cross-reference
Closes five gaps where requirements could slip through unchecked at milestone level: audit now cross-references VERIFICATION.md + SUMMARY frontmatter + REQUIREMENTS.md traceability, integration checker receives req IDs, gap objects carry plan-level detail, plan-milestone-gaps updates traceability, and complete-milestone gates on requirements status. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -45,6 +45,12 @@ A "complete" codebase with broken wiring is a broken product.
|
||||
|
||||
- Which phases should connect to which
|
||||
- What each phase provides vs. consumes
|
||||
|
||||
**Milestone Requirements:**
|
||||
|
||||
- List of REQ-IDs with descriptions and assigned phases (provided by milestone auditor)
|
||||
- MUST map each integration finding to affected requirement IDs where applicable
|
||||
- Requirements with no cross-phase wiring MUST be flagged in the Requirements Integration Map
|
||||
</inputs>
|
||||
|
||||
<verification_process>
|
||||
@@ -391,6 +397,15 @@ Return structured report to milestone auditor:
|
||||
#### Unprotected Routes
|
||||
|
||||
{List each with path/reason}
|
||||
|
||||
#### Requirements Integration Map
|
||||
|
||||
| Requirement | Integration Path | Status | Issue |
|
||||
|-------------|-----------------|--------|-------|
|
||||
| {REQ-ID} | {Phase X export → Phase Y import → consumer} | WIRED / PARTIAL / UNWIRED | {specific issue or "—"} |
|
||||
|
||||
**Requirements with no cross-phase wiring:**
|
||||
{List REQ-IDs that exist in a single phase with no integration touchpoints — these may be self-contained or may indicate missing connections}
|
||||
```
|
||||
|
||||
</output>
|
||||
@@ -419,5 +434,7 @@ Return structured report to milestone auditor:
|
||||
- [ ] Orphaned code identified
|
||||
- [ ] Missing connections identified
|
||||
- [ ] Broken flows identified with specific break points
|
||||
- [ ] Requirements Integration Map produced with per-requirement wiring status
|
||||
- [ ] Requirements with no cross-phase wiring identified
|
||||
- [ ] Structured report returned to auditor
|
||||
</success_criteria>
|
||||
|
||||
@@ -57,6 +57,8 @@ If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is
|
||||
|
||||
With phase context collected:
|
||||
|
||||
Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt="Check cross-phase integration and E2E flows.
|
||||
@@ -65,6 +67,11 @@ Phases: {phase_dirs}
|
||||
Phase exports: {from SUMMARYs}
|
||||
API routes: {routes created}
|
||||
|
||||
Milestone Requirements:
|
||||
{MILESTONE_REQ_IDS — list each REQ-ID with description and assigned phase}
|
||||
|
||||
MUST map each integration finding to affected requirement IDs where applicable.
|
||||
|
||||
Verify cross-phase wiring and E2E user flows.",
|
||||
subagent_type="gsd-integration-checker",
|
||||
model="{integration_checker_model}"
|
||||
@@ -77,12 +84,48 @@ Combine:
|
||||
- Phase-level gaps and tech debt (from step 2)
|
||||
- Integration checker's report (wiring gaps, broken flows)
|
||||
|
||||
## 5. Check Requirements Coverage
|
||||
## 5. Check Requirements Coverage (3-Source Cross-Reference)
|
||||
|
||||
For each requirement in REQUIREMENTS.md mapped to this milestone:
|
||||
- Find owning phase
|
||||
- Check phase verification status
|
||||
- Determine: satisfied | partial | unsatisfied
|
||||
MUST cross-reference three independent sources for each requirement:
|
||||
|
||||
### 5a. Parse REQUIREMENTS.md Traceability Table
|
||||
|
||||
Extract all REQ-IDs mapped to milestone phases from the traceability table:
|
||||
- Requirement ID, description, assigned phase, current status, checked-off state (`[x]` vs `[ ]`)
|
||||
|
||||
### 5b. Parse Phase VERIFICATION.md Requirements Tables
|
||||
|
||||
For each phase's VERIFICATION.md, extract the expanded requirements table:
|
||||
- Requirement | Source Plan | Description | Status | Evidence
|
||||
- Map each entry back to its REQ-ID
|
||||
|
||||
### 5c. Extract SUMMARY.md Frontmatter Cross-Check
|
||||
|
||||
For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter:
|
||||
```bash
|
||||
for summary in .planning/phases/*-*/*-SUMMARY.md; do
|
||||
node ~/.claude/get-shit-done/bin/gsd-tools.cjs summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
|
||||
done
|
||||
```
|
||||
|
||||
### 5d. Status Determination Matrix
|
||||
|
||||
For each REQ-ID, determine status using all three sources:
|
||||
|
||||
| VERIFICATION.md Status | SUMMARY Frontmatter | REQUIREMENTS.md | → Final Status |
|
||||
|------------------------|---------------------|-----------------|----------------|
|
||||
| passed | listed | `[x]` | **satisfied** |
|
||||
| passed | listed | `[ ]` | **satisfied** (update checkbox) |
|
||||
| passed | missing | any | **partial** (verify manually) |
|
||||
| gaps_found | any | any | **unsatisfied** |
|
||||
| missing | listed | any | **partial** (verification gap) |
|
||||
| missing | missing | any | **unsatisfied** |
|
||||
|
||||
### 5e. FAIL Gate and Orphan Detection
|
||||
|
||||
**REQUIRED:** Any `unsatisfied` requirement MUST force `gaps_found` status on the milestone audit.
|
||||
|
||||
**Orphan detection:** Requirements present in REQUIREMENTS.md traceability table but absent from ALL phase VERIFICATION.md files MUST be flagged as orphaned. Orphaned requirements are treated as `unsatisfied` — they were assigned but never verified by any phase.
|
||||
|
||||
## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
|
||||
|
||||
@@ -99,7 +142,14 @@ scores:
|
||||
integration: N/M
|
||||
flows: N/M
|
||||
gaps: # Critical blockers
|
||||
requirements: [...]
|
||||
requirements:
|
||||
- id: "{REQ-ID}"
|
||||
status: "unsatisfied | partial | orphaned"
|
||||
phase: "{assigned phase}"
|
||||
claimed_by_plans: ["{plan files that reference this requirement}"]
|
||||
completed_by_plans: ["{plan files whose SUMMARY marks it complete}"]
|
||||
verification_status: "passed | gaps_found | missing | orphaned"
|
||||
evidence: "{specific evidence or lack thereof}"
|
||||
integration: [...]
|
||||
flows: [...]
|
||||
tech_debt: # Non-critical, deferred
|
||||
@@ -235,8 +285,13 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
|
||||
<success_criteria>
|
||||
- [ ] Milestone scope identified
|
||||
- [ ] All phase VERIFICATION.md files read
|
||||
- [ ] SUMMARY.md `requirements-completed` frontmatter extracted for each phase
|
||||
- [ ] REQUIREMENTS.md traceability table parsed for all milestone REQ-IDs
|
||||
- [ ] 3-source cross-reference completed (VERIFICATION + SUMMARY + traceability)
|
||||
- [ ] Orphaned requirements detected (in traceability but absent from all VERIFICATIONs)
|
||||
- [ ] Tech debt and deferred gaps aggregated
|
||||
- [ ] Integration checker spawned for cross-phase wiring
|
||||
- [ ] v{version}-MILESTONE-AUDIT.md created
|
||||
- [ ] Integration checker spawned with milestone requirement IDs
|
||||
- [ ] v{version}-MILESTONE-AUDIT.md created with structured requirement gap objects
|
||||
- [ ] FAIL gate enforced — any unsatisfied requirement forces gaps_found status
|
||||
- [ ] Results presented with actionable next steps
|
||||
</success_criteria>
|
||||
|
||||
@@ -48,6 +48,12 @@ This returns all phases with plan/summary counts and disk status. Use this to ve
|
||||
- All phases complete (all plans have summaries)? Check `disk_status === 'complete'` for each.
|
||||
- `progress_percent` should be 100%.
|
||||
|
||||
**Requirements completion check (REQUIRED before presenting):**
|
||||
|
||||
Parse REQUIREMENTS.md traceability table:
|
||||
- Count total v1 requirements vs checked-off (`[x]`) requirements
|
||||
- Identify any non-Complete rows in the traceability table
|
||||
|
||||
Present:
|
||||
|
||||
```
|
||||
@@ -60,8 +66,25 @@ Includes:
|
||||
- Phase 4: Polish (1/1 plan complete)
|
||||
|
||||
Total: {phase_count} phases, {total_plans} plans, all complete
|
||||
Requirements: {N}/{M} v1 requirements checked off
|
||||
```
|
||||
|
||||
**If requirements incomplete** (N < M):
|
||||
|
||||
```
|
||||
⚠ Unchecked Requirements:
|
||||
|
||||
- [ ] {REQ-ID}: {description} (Phase {X})
|
||||
- [ ] {REQ-ID}: {description} (Phase {Y})
|
||||
```
|
||||
|
||||
MUST present 3 options:
|
||||
1. **Proceed anyway** — mark milestone complete with known gaps
|
||||
2. **Run audit first** — `/gsd:audit-milestone` to assess gap severity
|
||||
3. **Abort** — return to development
|
||||
|
||||
If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md under `### Known Gaps` with REQ-IDs and descriptions.
|
||||
|
||||
<config-check>
|
||||
|
||||
```bash
|
||||
@@ -669,6 +692,9 @@ Milestone completion is successful when:
|
||||
- [ ] STATE.md updated with fresh project reference
|
||||
- [ ] Git tag created (v[X.Y])
|
||||
- [ ] Milestone commit made (includes archive files and deletion)
|
||||
- [ ] Requirements completion checked against REQUIREMENTS.md traceability table
|
||||
- [ ] Incomplete requirements surfaced with proceed/audit/abort options
|
||||
- [ ] Known gaps recorded in MILESTONES.md if user proceeded with incomplete requirements
|
||||
- [ ] User knows next step (/gsd:new-milestone)
|
||||
|
||||
</success_criteria>
|
||||
|
||||
@@ -123,19 +123,34 @@ Add new phases to current milestone:
|
||||
...
|
||||
```
|
||||
|
||||
## 7. Create Phase Directories
|
||||
## 7. Update REQUIREMENTS.md Traceability Table (REQUIRED)
|
||||
|
||||
For each REQ-ID assigned to a gap closure phase:
|
||||
- Update the Phase column to reflect the new gap closure phase
|
||||
- Reset Status to `Pending`
|
||||
|
||||
Reset checked-off requirements the audit found unsatisfied:
|
||||
- Change `[x]` → `[ ]` for any requirement marked unsatisfied in the audit
|
||||
- Update coverage count at top of REQUIREMENTS.md
|
||||
|
||||
```bash
|
||||
# Verify traceability table reflects gap closure assignments
|
||||
grep -c "Pending" .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 8. Create Phase Directories
|
||||
|
||||
```bash
|
||||
mkdir -p ".planning/phases/{NN}-{name}"
|
||||
```
|
||||
|
||||
## 8. Commit Roadmap Update
|
||||
## 9. Commit Roadmap and Requirements Update
|
||||
|
||||
```bash
|
||||
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md
|
||||
node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 9. Offer Next Steps
|
||||
## 10. Offer Next Steps
|
||||
|
||||
```markdown
|
||||
## ✓ Gap Closure Phases Created
|
||||
@@ -250,7 +265,10 @@ becomes:
|
||||
- [ ] Gaps grouped into logical phases
|
||||
- [ ] User confirmed phase plan
|
||||
- [ ] ROADMAP.md updated with new phases
|
||||
- [ ] REQUIREMENTS.md traceability table updated with gap closure phase assignments
|
||||
- [ ] Unsatisfied requirement checkboxes reset (`[x]` → `[ ]`)
|
||||
- [ ] Coverage count updated in REQUIREMENTS.md
|
||||
- [ ] Phase directories created
|
||||
- [ ] Changes committed
|
||||
- [ ] Changes committed (includes REQUIREMENTS.md)
|
||||
- [ ] User knows to run `/gsd:plan-phase` next
|
||||
</success_criteria>
|
||||
|
||||
Reference in New Issue
Block a user