@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,462 @@
+<purpose>
+Audit a completed phase through automated test execution and structural verification. Produces a phase-level audit report that confirms deliverables exist, are wired correctly, and pass their test suite. Mirrors the audit-milestone pattern but scoped to a single phase.
+
+verify-work = manual UAT (human tests interactively)
+audit-phase = automated inspection (tests + structural verification)
+audit-milestone = cross-phase integration audit (milestone level)
+</purpose>
+
+<context_tier>execution</context_tier>
+
+<philosophy>
+**Trust the code, not the SUMMARY.**
+
+A completed task is not a verified deliverable. Code can be written without being wired in. An API route can exist without being called. A component can render without importing its data source. Audit-phase verifies the connections, not just the existence.
+
+Two independent verification layers:
+1. **Test execution** — run the actual test suite and task-level verify commands
+2. **Structural inspection** — cross-reference PLAN.md with what's on disk (files, exports, wiring)
+
+Both must pass for a phase to be considered clean.
+</philosophy>
+
+<process>
+
+<step name="initialize" priority="first">
+Parse arguments and load phase context:
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init audit-phase "${PHASE_ARG}")
+```
+
+Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `dgs_mode`, `author`.
+
+**Load execution tier context:**
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier execution --phase "${PHASE_ARG}" --raw 2>/dev/null)
+```
+
+**Flag Detection:**
+
+1. Check if `$ARGUMENTS` contains `--rerun-failed`. If yes, set `RERUN_FAILED_MODE = true` and strip from `$ARGUMENTS`.
+
+**v2 Multi-Repo Detection:**
+
+If `dgs_mode` is `v2`, load repo context:
+
+```bash
+REPOS_MD=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos list --raw 2>/dev/null)
+```
+
+Parse JSON for the list of registered repos with paths.
+
+**Resolve test execution directory (v2 only):**
+
+If `dgs_mode` is `v2` and repos were detected from REPOS_MD:
+
+1. Parse REPOS_MD JSON for the list of repos (each has `name` and `path`)
+2. If exactly 1 repo registered: use its `path` as `TEST_CWD`
+3. If multiple repos: check PLAN.md files in the phase for `<repos>` tags. Use the first repo name found, look up its path from REPOS_MD. If no `<repos>` tag found, use the first registered repo's path.
+4. Resolve `TEST_CWD` to an absolute path: if the repo path is relative (starts with `../`), resolve it relative to `process.cwd()` / the current working directory.
+5. Set `CWD_FLAG` to `--cwd "${TEST_CWD}"` if TEST_CWD was determined, otherwise set to empty string.
+
+If `dgs_mode` is NOT `v2` or no repos detected: set `CWD_FLAG` to empty string (single-repo, no override needed).
+
+```
+{If CWD_FLAG is set:}
+Test execution directory: ${TEST_CWD} (from REPOS.md)
+```
+</step>
+
+<step name="run_tests">
+**Layer 1: Test Execution**
+
+Collect and run automated test commands for this phase.
+
+```bash
+COLLECT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs auto-test collect "${PHASE_ARG}" ${CWD_FLAG} --raw 2>/dev/null)
+```
+
+Parse JSON result. If `empty` is true: note "No automated tests available" and proceed to structural verification (tests are not required — structural verification still runs).
+
+Otherwise, display collected commands:
+
+```
+## Audit Phase {N}: Test Execution
+
+### Collected Commands
+{grouped by source: VALIDATION.md / PLAN.md}
+---
+Collected {total} test commands ({from_validation} from VALIDATION.md, {from_plans} from PLAN.md)
+```
+
+Execute the test suite:
+
+```bash
+RUN_RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs auto-test run "${PHASE_ARG}" --timeout 30000 ${CWD_FLAG} --raw 2>/dev/null)
+```
+
+Parse and display results:
+
+```
+## Test Results: Phase {N}
+
+| # | Command | Result | Duration | Type |
+|---|---------|--------|----------|------|
+| 1 | npm test | PASS | 2.3s | - |
+| 2 | node --test tests/foo.test.cjs | FAIL | 0.8s | code |
+
+---
+**Summary:** {passed}/{total} passed, {failed} failed, {timed_out} timed out, {suspects} suspect, {skipped_covered} skipped (covered)
+```
+
+Generate the UAT file for test results:
+
+```bash
+MAP_RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs auto-test map "${PHASE_ARG}" --timeout 30000 ${CWD_FLAG} --raw 2>/dev/null)
+```
+
+Parse for: `uat_path`, `log_path`, `summary`, `manual_count`, `status`.
+
+**RERUN_FAILED_MODE:**
+
+If `RERUN_FAILED_MODE` is true, instead of running the full suite:
+
+```bash
+RERUN_RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs auto-test rerun "${PHASE_ARG}" ${CWD_FLAG} --raw 2>/dev/null)
+```
+
+Parse for: `rerun_count`, `all_passed`, `status`, `uat_path`, `log_path`, `summary`.
+
+If `rerun_count` is 0: note "No failed tests to rerun" and proceed to structural verification.
+
+Display rerun results, then proceed to structural verification as normal.
+</step>
+
+<step name="structural_verification">
+**Layer 2: Structural Verification (Phase Verifier)**
+
+After test execution (or if no tests were available), spawn the dgs-phase-verifier agent to inspect the actual deliverables against the plan.
+
+Build prior phase context:
+
+```bash
+# Collect prior phase summaries for upstream dependency checking
+PRIOR_SUMMARIES=$(find "${phase_dir}/../" -name "*-SUMMARY.md" -not -path "*/${phase_number}-*" 2>/dev/null | sort)
+```
+
+Spawn the structural verifier:
+
+```
+Task(
+  prompt="""
+<structural_verification>
+
+**Phase:** {phase_number} — {phase_name}
+**Phase directory:** {phase_dir}
+
+<files_to_read>
+{For each PLAN.md in phase_dir:}
+- {phase_dir}/{plan_file}
+{For each SUMMARY.md in phase_dir:}
+- {phase_dir}/{summary_file}
+{For each prior phase SUMMARY.md (max 5 most recent):}
+- {prior_summary_path}
+</files_to_read>
+
+{If dgs_mode is v2 and repos detected:}
+<repo_context>
+Repo Paths (from REPOS.md):
+{For each repo:}
+name: {repo_name}, path: {repo_path}
+</repo_context>
+{End if}
+
+Verify that Phase {phase_number}'s deliverables:
+1. All planned files exist and have substance (not stubs)
+2. Expected exports are present in the actual files
+3. must_have artifacts and key_links are satisfied
+4. Upstream dependencies from prior phases are actually wired in the code
+5. No critical anti-patterns (TODOs, empty catch blocks, stubs)
+
+Return your structured verification report.
+
+</structural_verification>
+""",
+  subagent_type="dgs-phase-verifier",
+  model="{checker_model}",
+  description="Structural verify Phase {phase_number}"
+)
+```
+
+Parse the structural verification result. The verifier returns a structured report with a `gaps:` YAML section.
+</step>
+
+<step name="merge_results">
+**Merge structural gaps into the UAT file:**
+
+Parse the structural verifier's response. The verifier returns a structured report with a `gaps:` YAML section and optionally an `anti_patterns:` YAML section.
+
+**Gap Type Mapping (verifier output to UAT entry):**
+
+| Verifier gap.type | UAT truth | gap_type |
+|-------------------|-----------|----------|
+| missing_file | "File {planned} exists" | structural |
+| missing_export | "File {file} exports {export}" | structural |
+| unwired_dependency | "{dependency} wired in {expected_in}" | structural |
+| stub_file | "File {file} has substance (not stub)" | structural |
+| broken_key_link | "{from} connected to {to}" | structural |
+| missing_must_have_artifact | "must_have artifact {artifact} satisfied" | structural |
+
+For each structural gap (severity >= major) returned by the verifier:
+
+1. Create a new test entry in the UAT file's ## Tests section:
+   ```
+   ### {next_test_number}. [STRUCTURAL] {gap description derived from type mapping above}
+   expected: {truth from mapping table}
+   result: issue
+   reported: "{detail from verifier}"
+   severity: {severity from verifier}
+   source: structural_verification
+   ```
+
+2. Append to the ## Gaps section in UAT YAML format:
+   ```yaml
+   - truth: "{truth from mapping table}"
+     status: failed
+     reason: "Structural verification: {detail}"
+     severity: {severity}
+     test: {test_number}
+     gap_type: structural
+     artifacts: []
+     missing: []
+   ```
+
+   Each gap entry MUST include all fields required by the diagnosis pipeline: `truth`, `status`, `reason`, `severity`, `test`, `gap_type`, `artifacts`, `missing`.
+
+**Anti-pattern handling:**
+
+Anti-patterns (severity: minor) from the verifier are:
+- Recorded as test entries (`### N. [STRUCTURAL] ...`) with severity: minor and source: structural_verification
+- Included in the `total` count in the ## Summary section
+- NOT included in the `issues` count (since they do not trigger diagnosis)
+- NOT added to the ## Gaps section
+- They do not affect status determination
+
+**Count update logic (after appending structural entries):**
+
+```
+1. Read current total from ## Summary section
+2. structural_gap_count = number of gaps with severity >= major (blocker + major)
+3. anti_pattern_count = number of anti-patterns (severity: minor)
+4. Add (structural_gap_count + anti_pattern_count) to total
+5. Add structural_gap_count to issues (anti-patterns excluded)
+6. If issues > 0: set frontmatter status to 'gaps_found'
+7. If issues == 0: keep frontmatter status as-is (passed or passed with human_needed)
+```
+
+**Compute combined status:**
+
+```
+test_failures = (test execution failure count, 0 if no tests available)
+structural_gaps = (structural verification gap count, excluding minor anti-patterns)
+total_gaps = test_failures + structural_gaps
+
+If total_gaps == 0 and manual_count == 0:
+  status = 'passed'
+Else if total_gaps == 0 and manual_count > 0:
+  status = 'passed'  (with human_needed flag)
+Else:
+  status = 'gaps_found'
+```
+
+**Structural re-check in RERUN_FAILED_MODE:**
+
+When `RERUN_FAILED_MODE` is true, the structural verifier also reruns, but only checks the specific gaps that were previously identified (not a full re-scan). Pass the previous structural gap list to the verifier so it can re-check only those items. Include the previous UAT file path in the verifier spawn prompt so it can extract the structural gap entries and verify whether they are now resolved.
+
+**Commit the UAT file:**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "[AUDIT] audit(${PHASE_ARG}): ${test_failures} test failures, ${structural_gaps} structural gaps" --files "${uat_path}" "${log_path}"
+```
+</step>
+
+<step name="diagnose_gaps">
+**If gaps found, diagnose and plan fixes:**
+
+This mirrors the verify-work diagnosis pipeline. When `status == 'gaps_found'`, proceed through the same diagnosis flow:
+
+```
+---
+**{total_gaps} gap(s) found** ({test_failures} test failures, {structural_gaps} structural gaps). Initiating automatic diagnosis...
+```
+
+**Step A: Diagnose Issues**
+
+- Load diagnose-issues workflow
+- Follow @~/.claude/deliver-great-systems/workflows/diagnose-issues.md
+- Spawn parallel debug agents for each gap
+- Debug agents receive enriched context: test failures get stderr/exit codes, structural gaps get the verifier's specific findings (missing files, unwired dependencies, broken key_links)
+- Collect root causes
+- Update UAT.md with root causes
+
+**Step B: Plan Gap Closure**
+
+Spawn dgs-planner in --gaps mode:
+
+```
+Task(
+  prompt="""
+<planning_context>
+
+**Phase:** {phase_number}
+**Mode:** gap_closure
+
+<files_to_read>
+- {phase_dir}/{phase_num}-UAT.md (UAT with diagnoses)
+- ${state_path} (Project State)
+- ${roadmap_path} (Roadmap)
+</files_to_read>
+
+</planning_context>
+
+<repo_context>
+<!-- v2 only: include if dgs_mode is v2 and repos were detected -->
+**Repos touched by this phase:**
+| Repo | Path | Stack |
+|------|------|-------|
+| {repo} | {path} | {detected stack} |
+</repo_context>
+
+<downstream_consumer>
+Output consumed by /dgs:execute-phase
+Plans must be executable prompts.
+</downstream_consumer>
+""",
+  subagent_type="dgs-planner",
+  model="{planner_model}",
+  description="Plan gap fixes for Phase {phase}"
+)
+```
+
+**Step C: Verify Gap Plans**
+
+Spawn dgs-plan-checker:
+
+```
+Task(
+  prompt="""
+<verification_context>
+
+**Phase:** {phase_number}
+**Phase Goal:** Close diagnosed gaps from phase audit
+
+<files_to_read>
+- {phase_dir}/*-PLAN.md (Plans to verify)
+</files_to_read>
+
+</verification_context>
+
+<expected_output>
+Return one of:
+- ## VERIFICATION PASSED — all checks pass
+- ## ISSUES FOUND — structured issue list
+</expected_output>
+""",
+  subagent_type="dgs-plan-checker",
+  model="{checker_model}",
+  description="Verify Phase {phase} fix plans"
+)
+```
+
+**Step D: Revision Loop**
+
+Iterate planner <-> checker until plans pass (max 3 iterations). Same logic as verify-work's revision_loop step.
+
+After plans are verified, update UAT status to `diagnosed` and proceed to present_results.
+</step>
+
+<step name="present_results">
+**Present audit results and next steps:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS ► PHASE AUDIT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Audit Results: Phase {N} — {Name}
+
+| Metric | Count |
+|--------|-------|
+| Tests Passed | {passed} |
+| Tests Failed | {test_failures} |
+| Structural Gaps | {structural_gaps} |
+| Human Needed | {manual_count} |
+
+Status: {status}
+UAT file: {uat_path}
+```
+
+**Branch based on status:**
+
+{If status == 'passed' and manual_count == 0:}
+```
+---
+Phase {N} audit passed. All tests pass. Structural verification clean. Ready for next phase.
+```
+Stop here.
+
+{If status == 'passed' and manual_count > 0:}
+```
+---
+Phase {N} audit passed. **{manual_count} verification(s) require human review.**
+Run `/dgs:verify-work {phase}` interactively to complete manual checks.
+```
+Stop here.
+
+{If status == 'gaps_found' and diagnosis completed:}
+```
+---
+**{total_gaps} gap(s) diagnosed, {M} fix plan(s) created.**
+
+| Gap | Root Cause | Fix Plan |
+|-----|------------|----------|
+| {truth 1} | {root_cause} | {phase}-04 |
+| {truth 2} | {root_cause} | {phase}-04 |
+
+Status: diagnosed — fix plans ready for execution.
+```
+
+In a job context, the job orchestrator reads the `diagnosed` status and dynamically inserts `execute-phase --gaps-only` and `audit-phase --rerun-failed` steps. In interactive mode:
+
+```
+## ▶ Next Up
+
+**Execute fixes** — run fix plans
+
+`/clear` then `/dgs:execute-phase {phase} --gaps-only`
+Then re-audit: `/dgs:audit-phase {phase} --rerun-failed`
+```
+
+Stop here.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Phase context loaded (init, phase_dir, mode)
+- [ ] Test commands collected from VALIDATION.md and PLAN.md sources
+- [ ] Tests executed with results captured (pass/fail/timeout)
+- [ ] Test results mapped to UAT file format
+- [ ] Structural verifier spawned after test execution
+- [ ] Structural gaps merged into UAT file alongside test results
+- [ ] Combined status reflects both test failures AND structural gaps
+- [ ] If gaps found: parallel debug agents diagnose root causes
+- [ ] If gaps found: dgs-planner creates fix plans (gap_closure mode)
+- [ ] If gaps found: dgs-plan-checker verifies fix plans
+- [ ] If gaps found: revision loop until plans pass (max 3 iterations)
+- [ ] UAT file committed with audit results
+- [ ] Clear status signal for job orchestrator (passed / diagnosed)
+- [ ] If --rerun-failed: only re-runs previously failed tests + structural re-check
+</success_criteria>

package/deliver-great-systems/workflows/cancel-job.md

@@ -0,0 +1,108 @@
+<purpose>
+Cancel an in-progress job, resetting it to pending for re-execution. After cancellation, generates a job summary documenting the partial progress.
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="load_context" priority="first">
+Load project context via tier system:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+</step>
+
+<step name="parse_arguments">
+Extract version from `$ARGUMENTS`.
+
+```
+VERSION = first argument from $ARGUMENTS
+```
+
+**If no version provided:**
+```
+Error: Version argument required. Usage: /dgs:cancel-job <version>
+```
+</step>
+
+<step name="cancel_job">
+Run the cancel-job CLI command:
+
+```bash
+RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs cancel-job "$VERSION")
+```
+
+Parse the JSON result. The response contains:
+```json
+{
+  "cancelled": true,
+  "version": "v6.0",
+  "steps_reset": 2,
+  "path": "jobs/pending/milestone-v6.0.md"
+}
+```
+
+Or on error:
+```json
+{
+  "cancelled": false,
+  "reason": "not_found" | "not_in_progress",
+  "version": "v6.0"
+}
+```
+</step>
+
+<step name="display_result">
+Display the result based on the response:
+
+**If `cancelled: true`:**
+```
+Job {version} cancelled. {steps_reset} in-progress step(s) reset. Job moved to pending/ -- re-run with /dgs:run-job {version}
+```
+
+**If `reason: 'not_found'`:**
+```
+No job found for version {version}. Run /dgs:list-jobs to see available jobs.
+```
+
+**If `reason: 'not_in_progress'`:**
+```
+Job {version} is not in progress. Only in-progress jobs can be cancelled.
+```
+
+No confirmation prompt -- cancel is not destructive per CONTEXT.md decisions.
+</step>
+
+<step name="generate_summary">
+After a successful cancellation, generate and write a job summary:
+
+```bash
+SUMMARY=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs generate-summary "$VERSION")
+```
+
+Parse the result. If `found: true`, write the `content` field to the path returned in the result using the Write tool.
+
+Display:
+```
+Job summary written to {path from result}
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Version extracted from arguments with error on missing
+- [ ] Cancel operation via `dgs-tools.cjs jobs cancel-job` CLI call
+- [ ] Success displays reset count and next-step hint
+- [ ] Not-found and not-in-progress errors display helpful messages
+- [ ] Job summary generated after successful cancellation
+- [ ] No confirmation prompt required
+</success_criteria>