@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/approve-spec.md

@@ -0,0 +1,194 @@
+<purpose>
+Approve a draft spec by running completeness validation (required sections, P0 requirements, blocking open questions), presenting warnings for optional sections, and transitioning to final status with an approved_date and Refinement Log entry. If the spec is already final, show an informational message and make no changes. This is the core approval pipeline for the `/dgs:approve-spec` command.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+Load planning context:
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
+```
+
+Extract: `project_root`, `config_path` as needed by the workflow.
+
+Load planning-tier context files (spec scope added after slug is parsed):
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+</step>
+
+<step name="parse_arguments">
+Extract the spec slug from `$ARGUMENTS`.
+
+**Spec slug extraction:**
+- The first positional argument is the spec slug (required).
+- If no argument is provided, display an error and stop:
+  ```
+  Usage: /dgs:approve-spec <spec-slug>
+  ```
+- Store the value as `SPEC_SLUG`.
+</step>
+
+<step name="load_and_check_status">
+Find the spec and check whether it is already approved.
+
+1. Run the validate command to get validation results and spec identity:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs validate --id "$SPEC_SLUG"
+   ```
+2. Parse the JSON output to extract: `id`, `valid`, `errors`, `warnings`, `error_count`, `warning_count`.
+3. Also read the spec file directly using the Read tool to check the current `status` and `version` from frontmatter.
+
+**Already-final gate (APR-04):**
+If the spec's status is already `final`, display an informational message:
+```
+This spec is already approved (v{version}, approved {approved_date}).
+No changes needed.
+```
+Stop execution. Do NOT run further validation, do NOT modify any files.
+</step>
+
+<step name="load_spec_docs">
+Load the spec's supporting documents for approval context.
+
+1. Derive the spec's docs directory:
+   Use the spec file path from the validate step to find docs/:
+   ```bash
+   SPEC_DOCS_DIR="$(dirname "${SPEC_FILE_PATH}")/docs"
+   ```
+   Or derive from spec slug: `${project_root}/specs/${SPEC_SLUG}/docs`
+
+2. If docs/ exists, read all files:
+   - **Text files** (.md, .txt, .json, .yaml, .yml): Read with Read tool
+   - **Image files** (.png, .jpg, .jpeg, .gif, .svg, .webp): Read with Read tool (multimodal). Cap at 5 images.
+   - **PDF files** (.pdf): Prefer .txt sidecar, fallback to 5 pages via Read tool
+   - **Other files**: skip silently
+   - If docs/ does not exist: silent skip
+   - If any file is unreadable: skip silently
+
+These docs provide context for evaluating the spec's completeness during approval.
+</step>
+
+<step name="check_blocking_open_questions">
+Read the spec file content and locate the `## Open Questions` section (if it exists).
+
+Evaluate whether any open questions are blocking:
+- Look for explicit markers first: `[BLOCKING]`, `(blocking)`, `[Unresolved]`
+- Use judgment: questions describing fundamental uncertainties that make implementation impossible, or referencing missing decisions that affect P0 requirements, count as blocking.
+- Questions about nice-to-haves, future scope, or already-deferred items are NOT blocking.
+
+If blocking questions are found, add them to the errors list with clear descriptions:
+```
+{ code: 'BLOCKING_QUESTION', message: 'Blocking open question: <summary of the question>' }
+```
+</step>
+
+<step name="error_gate">
+Combine errors from the validate command (step 3) with any blocking open questions (step 4).
+
+If total errors > 0:
+- Display all errors with clear formatting:
+  ```
+  ## Approval Blocked
+
+  The following issues must be resolved before this spec can be approved:
+
+  - [error message 1]
+  - [error message 2]
+  ...
+
+  Run /dgs:refine-spec <spec-slug> to address these issues.
+  ```
+- Stop execution. Do NOT proceed to approval.
+
+This enforces APR-02.
+</step>
+
+<step name="warning_gate">
+**Check for roadmap linkage:**
+
+Read the spec's frontmatter for a `milestones` field (array of milestone references). If the field is empty, null, or absent, add an informational warning to the warnings list:
+
+```
+- This spec has no roadmap linkage (no milestones field). Consider linking it to a milestone for implementation tracking.
+```
+
+This is a warning, not a blocker. It runs after structural validation so it appears alongside other warnings in this gate.
+
+If warnings exist (from validate command output, plus any roadmap linkage warning added above):
+- Display each warning clearly:
+  ```
+  ## Approval Warnings
+
+  The following items need attention:
+
+  - [warning message 1]
+  - [warning message 2]
+  ```
+- Ask the user using AskUserQuestion: "Approve this spec despite these warnings? (yes/no)"
+- If the user declines (answers "no", "n", or "cancel"):
+  - Suggest running `/dgs:refine-spec <spec-slug>` to address them.
+  - Stop execution.
+- If the user confirms (answers "yes", "y", or any affirmative): proceed to approval.
+
+If no warnings exist: proceed directly to approval.
+
+This enforces APR-03.
+</step>
+
+<step name="execute_approval">
+Perform the approval state transition and audit trail update.
+
+1. Run `set-status` to transition to final (this auto-sets `approved_date`):
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs set-status --id "$SPEC_SLUG" --status final
+   ```
+
+2. Run `add-log-entry` to record the approval in the Refinement Log:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs add-log-entry --id "$SPEC_SLUG" --date "$(date +%Y-%m-%d)" --version "$VERSION" --action Approved --summary "Spec approved after completeness validation"
+   ```
+
+3. Determine the spec filename from the validate output or Read step.
+
+4. Commit the changes:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: approve $SPEC_ID v$VERSION" --files "$SPEC_FILE_PATH"
+   ```
+</step>
+
+<step name="confirmation">
+Display the approval confirmation:
+
+```
+Spec approved: {title} (v{version})
+```
+
+Suggest next steps:
+
+```
+Next steps:
+  - Run /dgs:new-milestone to create a milestone from this spec
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Draft spec transitions to final status with approved_date set
+- [ ] Approval log entry added to Refinement Log
+- [ ] Already-final specs show informational message with no changes
+- [ ] Validation errors block approval with clear messages
+- [ ] Validation warnings allow user confirmation before proceeding
+- [ ] Blocking open questions are detected and treated as errors
+- [ ] Changes committed to git
+</success_criteria>

package/deliver-great-systems/workflows/audit-milestone.md

@@ -0,0 +1,364 @@
+<purpose>
+Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</purpose>
+
+<context_tier>verification</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 0. Initialize Milestone Context
+
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init milestone-op)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
+
+**Load verification tier context:**
+
+```bash
+LAST_PHASE=$(echo "$completed_phases" | tail -1)
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier verification --phase "${LAST_PHASE}" --raw 2>/dev/null)
+```
+
+This provides base verification context for the last phase. For cross-phase audit, the workflow still manually reads all phase VERIFICATION.md files in step 2 (the tier provides only the current phase's verification artifacts).
+
+Resolve integration checker model:
+```bash
+integration_checker_model=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" resolve-model dgs-integration-checker --raw)
+```
+
+## 1. Determine Milestone Scope
+
+```bash
+# Get phases in milestone (sorted numerically, handles decimals)
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phases list
+```
+
+- Parse version from arguments or detect current from ROADMAP.md
+- Identify all phase directories in scope
+- Extract milestone definition of done from ROADMAP.md
+- Extract requirements mapped to this milestone from REQUIREMENTS.md
+
+## 2. Read All Phase Verifications
+
+For each phase directory, read the VERIFICATION.md:
+
+```bash
+# For each phase, use find-phase to resolve the directory (handles archived phases)
+PHASE_INFO=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" find-phase 01 --raw)
+# Extract directory from JSON, then read VERIFICATION.md from that directory
+# Repeat for each phase number from ROADMAP.md
+```
+
+From each VERIFICATION.md, extract:
+- **Status:** passed | gaps_found
+- **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 is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.
+
+## 3. Spawn Integration Checker
+
+With phase context collected:
+
+Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.
+
+**Multi-repo resolution (REQUIRED before spawning):**
+
+In multi-project setups, code lives in separate repos from the planning repo. The integration checker needs actual code repo paths to search for imports/exports.
+
+```bash
+# Read REPOS.md from the planning root (product-level, not project-level)
+REPOS_CONTENT=$(cat $(dirname "${project_root}")/REPOS.md 2>/dev/null || cat ${project_root}/REPOS.md 2>/dev/null || echo "")
+```
+
+If REPOS.md exists and contains repo entries:
+1. Parse each repo row for name and path
+2. Resolve absolute paths: `realpath $(dirname "${project_root}")/{repo_path}`
+3. Include resolved paths in the integration checker prompt (see below)
+
+If no REPOS.md exists (single-repo setup), skip this step — the integration checker will use its default `src/` search path.
+
+```
+Task(
+  prompt="Check cross-phase integration and E2E flows.
+
+Phases: {phase_dirs}
+Phase exports: {from SUMMARYs}
+API routes: {routes created}
+
+{If REPOS.md exists and has entries:}
+Repo Paths (from REPOS.md — search these directories for code instead of src/):
+{For each repo: name: {name}, path: {resolved_absolute_path}}
+{End if}
+
+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="dgs-integration-checker",
+  model="{integration_checker_model}"
+)
+```
+
+## 4. Collect Results
+
+Combine:
+- Phase-level gaps and tech debt (from step 2)
+- Integration checker's report (wiring gaps, broken flows)
+
+## 5. Check Requirements Coverage (3-Source Cross-Reference)
+
+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 ${project_root}/phases/*-*/*-SUMMARY.md; do
+  node "$HOME/.claude/deliver-great-systems/bin/dgs-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.
+
+## 5.5. Nyquist Compliance Discovery
+
+Skip if `workflow.nyquist_validation` is explicitly `false` (absent = enabled).
+
+```bash
+NYQUIST_CONFIG=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config get workflow.nyquist_validation --raw 2>/dev/null)
+```
+
+If `false`: skip entirely.
+
+For each phase directory, check `*-VALIDATION.md`. If exists, parse frontmatter (`nyquist_compliant`, `wave_0_complete`).
+
+Classify per phase:
+
+| Status | Condition |
+|--------|-----------|
+| COMPLIANT | `nyquist_compliant: true` and all tasks green |
+| PARTIAL | VALIDATION.md exists, `nyquist_compliant: false` or red/pending |
+| MISSING | No VALIDATION.md |
+
+Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, overall }`
+
+Discovery only — never auto-calls `/dgs:validate-phase`.
+
+## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
+
+Create `${project_root}/v{version}-MILESTONE-AUDIT.md` with:
+
+```yaml
+---
+milestone: {version}
+audited: {timestamp}
+status: passed | gaps_found | tech_debt
+scores:
+  requirements: N/M
+  phases: N/M
+  integration: N/M
+  flows: N/M
+gaps:  # Critical blockers
+  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
+  - phase: 01-auth
+    items:
+      - "TODO: add rate limiting"
+      - "Warning: no password strength validation"
+  - phase: 03-dashboard
+    items:
+      - "Deferred: mobile responsive layout"
+---
+```
+
+Plus full markdown report with tables for requirements, phases, integration, tech debt.
+
+**Status values:**
+- `passed` — all requirements met, no critical gaps, minimal tech debt
+- `gaps_found` — critical blockers exist
+- `tech_debt` — no blockers but accumulated deferred items need review
+
+## 7. Present Results
+
+Route by status (see `<offer_next>`).
+
+</process>
+
+<offer_next>
+Output this markdown directly (not as a code block). Route based on status:
+
+---
+
+**If passed:**
+
+## ✓ Milestone {version} — Audit Passed
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** ${project_root}/v{version}-MILESTONE-AUDIT.md
+
+All requirements covered. Cross-phase integration verified. E2E flows complete.
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Complete milestone** — archive and tag
+
+/dgs:complete-milestone {version}
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**If gaps_found:**
+
+## ⚠ Milestone {version} — Gaps Found
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** ${project_root}/v{version}-MILESTONE-AUDIT.md
+
+### Unsatisfied Requirements
+
+{For each unsatisfied requirement:}
+- **{REQ-ID}: {description}** (Phase {X})
+  - {reason}
+
+### Cross-Phase Issues
+
+{For each integration gap:}
+- **{from} → {to}:** {issue}
+
+### Broken Flows
+
+{For each flow gap:}
+- **{flow name}:** breaks at {step}
+
+### Nyquist Coverage
+
+| Phase | VALIDATION.md | Compliant | Action |
+|-------|---------------|-----------|--------|
+| {phase} | exists/missing | true/false/partial | `/dgs:validate-phase {N}` |
+
+Phases needing validation: run `/dgs:validate-phase {N}` for each flagged phase.
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan gap closure** — create phases to complete milestone
+
+/dgs:plan-milestone-gaps
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- cat ${project_root}/v{version}-MILESTONE-AUDIT.md — see full report
+- /dgs:complete-milestone {version} — proceed anyway (accept tech debt)
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**If tech_debt (no blockers but accumulated debt):**
+
+## ⚡ Milestone {version} — Tech Debt Review
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** ${project_root}/v{version}-MILESTONE-AUDIT.md
+
+All requirements met. No critical blockers. Accumulated tech debt needs review.
+
+### Tech Debt by Phase
+
+{For each phase with debt:}
+**Phase {X}: {name}**
+- {item 1}
+- {item 2}
+
+### Total: {N} items across {M} phases
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Options
+
+**A. Complete milestone** — accept debt, track in backlog
+
+/dgs:complete-milestone {version}
+
+**B. Plan cleanup phase** — address debt before completing
+
+/dgs:plan-milestone-gaps
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+</offer_next>
+
+<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 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
+- [ ] Nyquist compliance scanned for all milestone phases (if enabled)
+- [ ] Missing VALIDATION.md phases flagged with validate-phase suggestion
+- [ ] Results presented with actionable next steps
+</success_criteria>