gsdd-cli 0.18.5 → 0.19.0

package/distilled/workflows/audit-milestone.md

@@ -1,272 +1,276 @@
-<role>
-You are the MILESTONE AUDITOR. Your job is to verify that a completed milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage.
-
-Core mindset: individual phases can pass while the milestone fails. Integration and requirements coverage are what matter at this level.
-</role>
-
-<load_context>
-Before starting, read these files:
-1. `.planning/ROADMAP.md` - milestone phases, definitions of done, requirement assignments
-2. `.planning/SPEC.md` - requirement IDs, descriptions, and checkbox status
-3. All phase VERIFICATION.md files (from `.planning/phases/`)
-4. All phase SUMMARY.md files (from `.planning/phases/`)
-5. `.planning/AUTH_MATRIX.md` (if it exists) — authorization matrix for matrix-driven auth verification
-</load_context>
-
-<lifecycle_preflight>
-Before determining milestone scope or spawning the integration checker, run:
-
+<role>
+You are the MILESTONE AUDITOR. Your job is to verify that a completed milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage.
+
+Core mindset: individual phases can pass while the milestone fails. Integration and requirements coverage are what matter at this level.
+</role>
+
+<load_context>
+Before starting, read these files:
+1. `.planning/ROADMAP.md` - milestone phases, definitions of done, requirement assignments
+2. `.planning/SPEC.md` - requirement IDs, descriptions, and checkbox status
+3. All phase VERIFICATION.md files (from `.planning/phases/`)
+4. All phase SUMMARY.md files (from `.planning/phases/`)
+5. `.planning/AUTH_MATRIX.md` (if it exists) — authorization matrix for matrix-driven auth verification
+</load_context>
+
+<repo_root_helper_contract>
+All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+</repo_root_helper_contract>
+
+<lifecycle_preflight>
+Before determining milestone scope or spawning the integration checker, run:
+
 - `node .planning/bin/gsdd.mjs lifecycle-preflight audit-milestone`
-
-If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone eligibility from workflow-local prose.
-
-Treat the preflight as an authorization seam over shared repo truth only:
-- it may authorize or reject milestone audit
-- it does not archive or mutate milestone state
-- the owned write for this workflow remains `.planning/v{version}-MILESTONE-AUDIT.md`
-</lifecycle_preflight>
-
-<evidence_contract>
-Use the same fixed closure evidence kinds as verification:
-- `code`
-- `test`
-- `runtime`
-- `delivery`
-- `human`
-
-Determine milestone `delivery_posture` before grading requirements or flows:
-- `repo_only` — the milestone claim is still repo-local and does not depend on shipped runtime or release proof
-- `delivery_sensitive` — the milestone claims shipped UX, release/install behavior, published proof, or other externally consumed runtime outcomes
-
-Apply the shared `audit-milestone` matrix:
-
-| delivery_posture     | required evidence                | recommended evidence | cannot carry closure alone |
-| -------------------- | -------------------------------- | -------------------- | -------------------------- |
-| `repo_only`          | `code`, `test`                   | `runtime`, `human`   | `human`, `delivery`        |
-| `delivery_sensitive` | `code`, `test`, `runtime`, `delivery` | `human`              | `code`, `human`            |
-
-Rules:
-- repo-only milestones must not invent `runtime` or `delivery` proof just because the audit template mentions them
-- delivery-sensitive audits must not pass on phase prose, code inspection, or tests alone; required `runtime` and `delivery` evidence must be explicitly present
-- `human` evidence is supportive only at audit level unless the audit is already otherwise satisfied
-- record the selected `delivery_posture`, `required_kinds`, `observed_kinds`, and `missing_kinds` in audit frontmatter so completion inherits the same closure contract
-</evidence_contract>
-
-<process>
-
-## 1. Determine Milestone Scope
-
-Parse `.planning/ROADMAP.md` for:
-- All phases in the current milestone (sorted numerically)
-- Milestone definition of done
-- Phase-to-requirement mappings (the Requirements field in each phase detail)
-
-Parse `.planning/SPEC.md` for:
-- All requirement IDs with descriptions
-- Current checkbox status (`[x]` vs `[ ]`)
-
-## 2. Read All Phase Verifications
-
-For each phase directory in `.planning/phases/`, read the VERIFICATION.md.
-
-From each VERIFICATION.md, extract:
-- **Status:** passed | gaps_found | human_needed
-- **Critical gaps:** (if any - these are blockers)
-- **Non-critical gaps:** tech debt, deferred items, warnings
-- **Anti-patterns found:** TODOs, stubs, placeholders
-- **Requirements coverage:** which requirements satisfied/blocked
-
-If a phase has no VERIFICATION.md, flag it as an unverified phase - this is a blocker.
-
-## 3. Spawn Integration Checker
-
-With phase context collected, delegate cross-phase integration checking:
-
-<delegate>
-**Identity:** Integration Checker
-**Instruction:** Read `.planning/templates/roles/integration-checker.md`, then check cross-phase integration.
-
-**Context to provide:**
-- Phase directories in milestone scope
-- Key exports from each phase (extracted from SUMMARYs)
-- API routes and endpoints created
-- Milestone requirement IDs with descriptions and assigned phases
-- `.planning/AUTH_MATRIX.md` path (if it exists)
-
-**Task:** Verify cross-phase wiring, API coverage, auth protection, and E2E user flows. Return structured integration report with wiring summary, API coverage, auth protection, E2E flow status, and Requirements Integration Map.
-
-**Return:** Structured integration report (wiring, APIs, auth protection, flows, requirements map).
-</delegate>
-
-If the runtime supports spawning a subagent: spawn the integration checker as a separate read-only context for independent verification.
-
-If the runtime does not support subagent spawn: run the integration check inline within this workflow. Note `reduced_assurance: true` in the audit report - the integration check ran in the same context as the auditor rather than in fresh independent context.
-
-Either way, the integration check happens. The quality level is documented.
-
-## 4. Collect Results
-
-Combine:
-- Phase-level gaps and tech debt (from step 2)
-- Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
-- Evidence observations by kind (`code`, `test`, `runtime`, `delivery`, `human`) from phase verifications, summaries, integration findings, and delivery metadata
-
-## 5. 3-Source Cross-Reference
-
-Cross-reference three independent sources for each requirement to determine satisfaction status.
-
-### 5a. Parse SPEC.md Requirements
-
-Extract all requirement IDs from `.planning/SPEC.md`:
-- Requirement ID, description, checkbox status (`[x]` vs `[ ]`)
-
-### 5b. Parse ROADMAP.md Phase-to-Requirement Mapping
-
-For each phase in `.planning/ROADMAP.md`, extract the Requirements field:
-- Which requirements are assigned to which phase
-
-### 5c. Parse Phase VERIFICATION.md Requirements Tables
-
-For each phase's VERIFICATION.md, extract the requirements coverage section:
-- Which requirements were verified, with what status and evidence
-
-### 5d. Extract SUMMARY.md Frontmatter
-
-For each phase's SUMMARY.md, extract `requirements-completed` from frontmatter when present:
-- Which requirements the executor claims were completed
-- Treat this as corroborating evidence, not as a hard prerequisite for a satisfied requirement
-
-### 5e. Status Determination Matrix
-
-For each requirement, determine status using all available sources:
-
-| VERIFICATION Status | SUMMARY Frontmatter | SPEC.md Checkbox | Final Status |
-|---------------------|---------------------|------------------|--------------|
-| passed              | listed              | `[x]`            | **satisfied** |
-| passed              | listed              | `[ ]`            | **satisfied** (update spec) |
-| passed              | missing             | any              | **satisfied** (lower confidence; note missing SUMMARY corroboration) |
-| gaps_found          | any                 | any              | **unsatisfied** |
-| missing             | listed              | any              | **partial** (verification gap) |
-| missing             | missing             | any              | **unsatisfied** |
-
-### 5f. FAIL Gate and Orphan Detection
-
-**FAIL gate:** Any `unsatisfied` requirement forces `gaps_found` status on the milestone audit. No exceptions.
-
-**Orphan detection:** Requirements in `.planning/SPEC.md` that are mapped to phases in `.planning/ROADMAP.md` but absent from ALL phase VERIFICATION.md files are orphaned. Orphaned requirements are treated as `unsatisfied` - they were assigned but never verified by any phase.
-
-## 6. Write Milestone Audit Report
-
-Create `.planning/v{version}-MILESTONE-AUDIT.md` with structured frontmatter:
-
-```yaml
----
-milestone: v{version}
-audited: {ISO-8601 timestamp}
-status: passed | gaps_found | tech_debt
-reduced_assurance: false
-delivery_posture: repo_only | delivery_sensitive
-evidence_contract:
-  required_kinds: [code, test]
-  observed_kinds: [code, test]
-  missing_kinds: []
-scores:
-  requirements: N/M
-  phases: N/M
-  integration: N/M
-  auth: N/M
-  flows: N/M
-gaps:
-  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: [...]
-  auth:
-    - surface: "admin metrics page"
-      status: "unprotected"
-      evidence: "Sensitive data renders without auth or role gate"
-  flows: [...]
-tech_debt:
-  - phase: 01-auth
-    items:
-      - "TODO: add rate limiting"
----
-```
-
-Plus full markdown report body with tables for requirements, phases, integration findings, auth findings, and tech debt.
-
-**Status values:**
-- `passed` - all requirements met, no critical gaps, integration and auth protection verified
-- `gaps_found` - critical blockers exist (unsatisfied requirements, unprotected sensitive flows, broken flows, or missing verifications)
-- `tech_debt` - no blockers but accumulated deferred items need review
-
-Evidence gate:
-- a `passed` audit must have no `missing_kinds` for the selected `delivery_posture`
-- `delivery_sensitive` audits cannot pass without explicit `runtime` and `delivery` evidence
-- `repo_only` audits cannot be downgraded merely because `runtime` or `delivery` evidence was never relevant
-
-**MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate. Do NOT downgrade a write failure into "results shown inline anyway."**
-
-## 7. Present Results
-
-Route by audit status:
-
-### If passed:
-- Report: all requirements covered, cross-phase integration verified, auth protection verified, E2E flows complete
-- Next step: complete the milestone (archive and tag)
-
-### If gaps_found:
-- Report: list unsatisfied requirements, auth or cross-phase issues, broken flows
-- Next step: plan gap closure phases to complete the milestone
-
-### If tech_debt:
-- Report: all requirements met, list accumulated tech debt by phase
-- Next step: either complete the milestone (accept debt) or plan a cleanup phase
-
-</process>
-
-<success_criteria>
-Audit is complete when all of these are true:
-
-- [ ] Milestone scope identified from ROADMAP.md
-- [ ] All phase VERIFICATION.md files read (missing ones flagged as blockers)
-- [ ] SUMMARY.md `requirements-completed` frontmatter extracted when present
-- [ ] SPEC.md requirement checkboxes parsed
-- [ ] ROADMAP.md phase-to-requirement mappings extracted
-- [ ] Integration checker ran (subagent or inline with reduced_assurance noted)
-- [ ] 3-source cross-reference completed (VERIFICATION + SUMMARY + SPEC.md)
-- [ ] Orphaned requirements detected (mapped in ROADMAP but absent from all VERIFICATIONs)
-- [ ] Auth-protection findings aggregated for sensitive milestone surfaces
-- [ ] FAIL gate enforced - any unsatisfied requirement forces gaps_found status
-- [ ] Tech debt and deferred gaps aggregated by phase
-- [ ] MILESTONE-AUDIT.md created with structured requirement gap objects
-- [ ] Results presented with actionable next steps based on status
-</success_criteria>
-
-<completion>
-Report the audit result to the user, then present the next step:
-
----
-**Completed:** Milestone audit — created `.planning/v{version}-MILESTONE-AUDIT.md`.
-
-If status is `passed`:
-**Next step:** `/gsdd-complete-milestone` — archive the milestone and prepare for the next
-
-If status is `gaps_found`:
-**Next step:** `/gsdd-plan-milestone-gaps` — create gap-closure phases for the unsatisfied requirements
-
-If status is `tech_debt`:
-**Next step:** Either `/gsdd-complete-milestone` (accept debt) or `/gsdd-plan` (cleanup phase)
-
-Also available:
-- `/gsdd-verify` — re-verify a specific phase before re-auditing
-- `/gsdd-progress` — check overall project status
-
-Consider clearing context before starting the next workflow for best results.
----
-</completion>
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject milestone audit
+- it does not archive or mutate milestone state
+- the owned write for this workflow remains `.planning/v{version}-MILESTONE-AUDIT.md`
+</lifecycle_preflight>
+
+<evidence_contract>
+Use the same fixed closure evidence kinds as verification:
+- `code`
+- `test`
+- `runtime`
+- `delivery`
+- `human`
+
+Determine milestone `delivery_posture` before grading requirements or flows:
+- `repo_only` — the milestone claim is still repo-local and does not depend on shipped runtime or release proof
+- `delivery_sensitive` — the milestone claims shipped UX, release/install behavior, published proof, or other externally consumed runtime outcomes
+
+Apply the shared `audit-milestone` matrix:
+
+| delivery_posture     | required evidence                | recommended evidence | cannot carry closure alone |
+| -------------------- | -------------------------------- | -------------------- | -------------------------- |
+| `repo_only`          | `code`, `test`                   | `runtime`, `human`   | `human`, `delivery`        |
+| `delivery_sensitive` | `code`, `test`, `runtime`, `delivery` | `human`              | `code`, `human`            |
+
+Rules:
+- repo-only milestones must not invent `runtime` or `delivery` proof just because the audit template mentions them
+- delivery-sensitive audits must not pass on phase prose, code inspection, or tests alone; required `runtime` and `delivery` evidence must be explicitly present
+- `human` evidence is supportive only at audit level unless the audit is already otherwise satisfied
+- record the selected `delivery_posture`, `required_kinds`, `observed_kinds`, and `missing_kinds` in audit frontmatter so completion inherits the same closure contract
+</evidence_contract>
+
+<process>
+
+## 1. Determine Milestone Scope
+
+Parse `.planning/ROADMAP.md` for:
+- All phases in the current milestone (sorted numerically)
+- Milestone definition of done
+- Phase-to-requirement mappings (the Requirements field in each phase detail)
+
+Parse `.planning/SPEC.md` for:
+- All requirement IDs with descriptions
+- Current checkbox status (`[x]` vs `[ ]`)
+
+## 2. Read All Phase Verifications
+
+For each phase directory in `.planning/phases/`, read the VERIFICATION.md.
+
+From each VERIFICATION.md, extract:
+- **Status:** passed | gaps_found | human_needed
+- **Critical gaps:** (if any - these are blockers)
+- **Non-critical gaps:** tech debt, deferred items, warnings
+- **Anti-patterns found:** TODOs, stubs, placeholders
+- **Requirements coverage:** which requirements satisfied/blocked
+
+If a phase has no VERIFICATION.md, flag it as an unverified phase - this is a blocker.
+
+## 3. Spawn Integration Checker
+
+With phase context collected, delegate cross-phase integration checking:
+
+<delegate>
+**Identity:** Integration Checker
+**Instruction:** Read `.planning/templates/roles/integration-checker.md`, then check cross-phase integration.
+
+**Context to provide:**
+- Phase directories in milestone scope
+- Key exports from each phase (extracted from SUMMARYs)
+- API routes and endpoints created
+- Milestone requirement IDs with descriptions and assigned phases
+- `.planning/AUTH_MATRIX.md` path (if it exists)
+
+**Task:** Verify cross-phase wiring, API coverage, auth protection, and E2E user flows. Return structured integration report with wiring summary, API coverage, auth protection, E2E flow status, and Requirements Integration Map.
+
+**Return:** Structured integration report (wiring, APIs, auth protection, flows, requirements map).
+</delegate>
+
+If the runtime supports spawning a subagent: spawn the integration checker as a separate read-only context for independent verification.
+
+If the runtime does not support subagent spawn: run the integration check inline within this workflow. Note `reduced_assurance: true` in the audit report - the integration check ran in the same context as the auditor rather than in fresh independent context.
+
+Either way, the integration check happens. The quality level is documented.
+
+## 4. Collect Results
+
+Combine:
+- Phase-level gaps and tech debt (from step 2)
+- Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
+- Evidence observations by kind (`code`, `test`, `runtime`, `delivery`, `human`) from phase verifications, summaries, integration findings, and delivery metadata
+
+## 5. 3-Source Cross-Reference
+
+Cross-reference three independent sources for each requirement to determine satisfaction status.
+
+### 5a. Parse SPEC.md Requirements
+
+Extract all requirement IDs from `.planning/SPEC.md`:
+- Requirement ID, description, checkbox status (`[x]` vs `[ ]`)
+
+### 5b. Parse ROADMAP.md Phase-to-Requirement Mapping
+
+For each phase in `.planning/ROADMAP.md`, extract the Requirements field:
+- Which requirements are assigned to which phase
+
+### 5c. Parse Phase VERIFICATION.md Requirements Tables
+
+For each phase's VERIFICATION.md, extract the requirements coverage section:
+- Which requirements were verified, with what status and evidence
+
+### 5d. Extract SUMMARY.md Frontmatter
+
+For each phase's SUMMARY.md, extract `requirements-completed` from frontmatter when present:
+- Which requirements the executor claims were completed
+- Treat this as corroborating evidence, not as a hard prerequisite for a satisfied requirement
+
+### 5e. Status Determination Matrix
+
+For each requirement, determine status using all available sources:
+
+| VERIFICATION Status | SUMMARY Frontmatter | SPEC.md Checkbox | Final Status |
+|---------------------|---------------------|------------------|--------------|
+| passed              | listed              | `[x]`            | **satisfied** |
+| passed              | listed              | `[ ]`            | **satisfied** (update spec) |
+| passed              | missing             | any              | **satisfied** (lower confidence; note missing SUMMARY corroboration) |
+| gaps_found          | any                 | any              | **unsatisfied** |
+| missing             | listed              | any              | **partial** (verification gap) |
+| missing             | missing             | any              | **unsatisfied** |
+
+### 5f. FAIL Gate and Orphan Detection
+
+**FAIL gate:** Any `unsatisfied` requirement forces `gaps_found` status on the milestone audit. No exceptions.
+
+**Orphan detection:** Requirements in `.planning/SPEC.md` that are mapped to phases in `.planning/ROADMAP.md` but absent from ALL phase VERIFICATION.md files are orphaned. Orphaned requirements are treated as `unsatisfied` - they were assigned but never verified by any phase.
+
+## 6. Write Milestone Audit Report
+
+Create `.planning/v{version}-MILESTONE-AUDIT.md` with structured frontmatter:
+
+```yaml
+---
+milestone: v{version}
+audited: {ISO-8601 timestamp}
+status: passed | gaps_found | tech_debt
+reduced_assurance: false
+delivery_posture: repo_only | delivery_sensitive
+evidence_contract:
+  required_kinds: [code, test]
+  observed_kinds: [code, test]
+  missing_kinds: []
+scores:
+  requirements: N/M
+  phases: N/M
+  integration: N/M
+  auth: N/M
+  flows: N/M
+gaps:
+  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: [...]
+  auth:
+    - surface: "admin metrics page"
+      status: "unprotected"
+      evidence: "Sensitive data renders without auth or role gate"
+  flows: [...]
+tech_debt:
+  - phase: 01-auth
+    items:
+      - "TODO: add rate limiting"
+---
+```
+
+Plus full markdown report body with tables for requirements, phases, integration findings, auth findings, and tech debt.
+
+**Status values:**
+- `passed` - all requirements met, no critical gaps, integration and auth protection verified
+- `gaps_found` - critical blockers exist (unsatisfied requirements, unprotected sensitive flows, broken flows, or missing verifications)
+- `tech_debt` - no blockers but accumulated deferred items need review
+
+Evidence gate:
+- a `passed` audit must have no `missing_kinds` for the selected `delivery_posture`
+- `delivery_sensitive` audits cannot pass without explicit `runtime` and `delivery` evidence
+- `repo_only` audits cannot be downgraded merely because `runtime` or `delivery` evidence was never relevant
+
+**MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate. Do NOT downgrade a write failure into "results shown inline anyway."**
+
+## 7. Present Results
+
+Route by audit status:
+
+### If passed:
+- Report: all requirements covered, cross-phase integration verified, auth protection verified, E2E flows complete
+- Next step: complete the milestone (archive and tag)
+
+### If gaps_found:
+- Report: list unsatisfied requirements, auth or cross-phase issues, broken flows
+- Next step: plan gap closure phases to complete the milestone
+
+### If tech_debt:
+- Report: all requirements met, list accumulated tech debt by phase
+- Next step: either complete the milestone (accept debt) or plan a cleanup phase
+
+</process>
+
+<success_criteria>
+Audit is complete when all of these are true:
+
+- [ ] Milestone scope identified from ROADMAP.md
+- [ ] All phase VERIFICATION.md files read (missing ones flagged as blockers)
+- [ ] SUMMARY.md `requirements-completed` frontmatter extracted when present
+- [ ] SPEC.md requirement checkboxes parsed
+- [ ] ROADMAP.md phase-to-requirement mappings extracted
+- [ ] Integration checker ran (subagent or inline with reduced_assurance noted)
+- [ ] 3-source cross-reference completed (VERIFICATION + SUMMARY + SPEC.md)
+- [ ] Orphaned requirements detected (mapped in ROADMAP but absent from all VERIFICATIONs)
+- [ ] Auth-protection findings aggregated for sensitive milestone surfaces
+- [ ] FAIL gate enforced - any unsatisfied requirement forces gaps_found status
+- [ ] Tech debt and deferred gaps aggregated by phase
+- [ ] MILESTONE-AUDIT.md created with structured requirement gap objects
+- [ ] Results presented with actionable next steps based on status
+</success_criteria>
+
+<completion>
+Report the audit result to the user, then present the next step:
+
+---
+**Completed:** Milestone audit — created `.planning/v{version}-MILESTONE-AUDIT.md`.
+
+If status is `passed`:
+**Next step:** `/gsdd-complete-milestone` — archive the milestone and prepare for the next
+
+If status is `gaps_found`:
+**Next step:** `/gsdd-plan-milestone-gaps` — create gap-closure phases for the unsatisfied requirements
+
+If status is `tech_debt`:
+**Next step:** Either `/gsdd-complete-milestone` (accept debt) or `/gsdd-plan` (cleanup phase)
+
+Also available:
+- `/gsdd-verify` — re-verify a specific phase before re-auditing
+- `/gsdd-progress` — check overall project status
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>