diff --git a/commands/gsd/progress.md b/commands/gsd/progress.md index ff3f32b5f..3f2b5b749 100644 --- a/commands/gsd/progress.md +++ b/commands/gsd/progress.md @@ -1,6 +1,7 @@ --- name: gsd:progress -description: Check project progress, show context, and route to next action (execute or plan) +description: Check project progress, show context, and route to next action (execute or plan). Use --forensic to append a 6-check integrity audit after the standard report. +argument-hint: "[--forensic]" allowed-tools: - Read - Bash diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 250b10072..b34ac49d3 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -484,8 +484,13 @@ Retroactively audit and fill Nyquist validation gaps. Show status and next steps. +| Flag | Description | +|------|-------------| +| `--forensic` | Append a 6-check integrity audit after the standard report (STATE consistency, orphaned handoffs, deferred scope drift, memory-flagged pending work, blocking todos, uncommitted code) | + ```bash /gsd-progress # "Where am I? What's next?" +/gsd-progress --forensic # Standard report + integrity audit ``` ### `/gsd-resume-work` diff --git a/get-shit-done/workflows/progress.md b/get-shit-done/workflows/progress.md index 20f1b8707..b3ebbc4c6 100644 --- a/get-shit-done/workflows/progress.md +++ b/get-shit-done/workflows/progress.md @@ -492,7 +492,119 @@ Ready to plan the next milestone. - All work complete → offer milestone completion - Blockers present → highlight before offering to continue - Handoff file exists → mention it, offer `/gsd-resume-work ${GSD_WS}` - + + + +**Forensic Integrity Audit** — only runs when `--forensic` is present in ARGUMENTS. + +If `--forensic` is NOT present in ARGUMENTS: skip this step entirely. Default progress behavior (standard report + routing) is unchanged. + +If `--forensic` IS present: after the standard report and routing suggestion have been displayed, append the following audit section. + +--- + +## Forensic Integrity Audit + +Running 6 deep checks against project state... + +Run each check in order. For each check, emit ✓ (pass) or ⚠ (warning) with concrete evidence when a problem is found. + +**Check 1 — STATE vs artifact consistency** + +Read STATE.md `status` / `stopped_at` fields (from the STATE snapshot already loaded). Compare against the artifact count from the roadmap analysis. If STATE.md claims the current phase is pending/mid-flight but the artifact count shows it as complete (all PLAN.md files have matching SUMMARY.md files), flag inconsistency. Emit: +- ✓ `STATE.md consistent with artifact count` — if both agree +- ⚠ `STATE.md claims [status] but artifact count shows phase complete` — with the specific values + +**Check 2 — Orphaned handoff files** + +Check for existence of: +```bash +ls .planning/HANDOFF.json .planning/phases/*/.continue-here.md .planning/phases/*/*HANDOFF*.md 2>/dev/null || true +``` +Also check `.planning/continue-here.md`. + +Emit: +- ✓ `No orphaned handoff files` — if none found +- ⚠ `Orphaned handoff files found` — list each file path, add: `→ Work was paused mid-flight. Read the handoff before continuing.` + +**Check 3 — Deferred scope drift** + +Search phase artifacts (CONTEXT.md, DISCUSSION-LOG.md, BUG-BRIEF.md, VERIFICATION.md, SUMMARY.md, HANDOFF.md files under `.planning/phases/`) for patterns: +```bash +grep -rl "defer to Phase\|future phase\|out of scope Phase\|deferred to Phase" .planning/phases/ 2>/dev/null || true +``` + +For each match, extract the referenced phase number. Cross-reference against ROADMAP.md phase list. If the referenced phase number is NOT in ROADMAP.md, flag as deferred scope not captured. + +Emit: +- ✓ `All deferred scope captured in ROADMAP` — if no mismatches +- ⚠ `Deferred scope references phase(s) not in ROADMAP` — list: file, reference text, missing phase number + +**Check 4 — Memory-flagged pending work** + +Check if `.planning/MEMORY.md` or `.planning/memory/` exists: +```bash +ls .planning/MEMORY.md .planning/memory/*.md 2>/dev/null || true +``` + +If found, grep for entries containing: `pending`, `status`, `deferred`, `not yet run`, `backfill`, `blocking`. + +Emit: +- ✓ `No memory entries flagging pending work` — if none found or no MEMORY.md +- ⚠ `Memory entries flag pending/deferred work` — list the matching lines (max 5, truncated at 80 chars) + +**Check 5 — Blocking operational todos** + +Check for pending todos: +```bash +ls .planning/todos/pending/*.md 2>/dev/null || true +``` + +For files found, scan for keywords indicating operational blockers: `script`, `credential`, `API key`, `manual`, `verification`, `setup`, `configure`, `run `. + +Emit: +- ✓ `No blocking operational todos` — if no pending todos or none match operational keywords +- ⚠ `Blocking operational todos found` — list the file names and matching keywords (max 5) + +**Check 6 — Uncommitted code** + +```bash +git status --porcelain 2>/dev/null | grep -v "^??" | grep -v "^.planning\/" | grep -v "^\.\." | head -10 +``` + +If output is non-empty (modified/staged files outside `.planning/`), flag as uncommitted code. + +Emit: +- ✓ `Working tree clean` — if no modified files outside `.planning/` +- ⚠ `Uncommitted changes in source files` — list up to 10 file paths + +--- + +After all 6 checks, display the verdict: + +**If all 6 checks passed:** +``` +### Verdict: CLEAN + +The standard progress report is trustworthy — proceed with the routing suggestion above. +``` + +**If 1 or more checks failed:** +``` +### Verdict: N INTEGRITY ISSUE(S) FOUND + +The standard progress report may not reflect true project state. +Review the flagged items above before acting on the routing suggestion. +``` + +Then for each failed check, add a concrete next action: +- Check 2 (orphaned handoff): `Read the handoff file(s) and resume from where work was paused: /gsd-resume-work ${GSD_WS}` +- Check 3 (deferred scope): `Add the missing phases to ROADMAP.md or update the deferred references` +- Check 4 (memory pending): `Review the flagged memory entries and resolve or clear them` +- Check 5 (blocking todos): `Complete the operational steps in .planning/todos/pending/ before continuing` +- Check 6 (uncommitted code): `Commit or stash the uncommitted changes before advancing` +- Check 1 (STATE inconsistency): `Run /gsd-verify-work ${PHASE} ${GSD_WS} to reconcile state` + diff --git a/tests/progress-forensic.test.cjs b/tests/progress-forensic.test.cjs new file mode 100644 index 000000000..994093124 --- /dev/null +++ b/tests/progress-forensic.test.cjs @@ -0,0 +1,131 @@ +/** + * Tests for --forensic flag on /gsd-progress (#2189) + * + * The --forensic flag appends a 6-check integrity audit after the standard + * progress report. Default behavior (no flag) is unchanged. + */ + +const { test, describe } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('fs'); +const path = require('path'); + +describe('#2189: progress --forensic flag', () => { + test('progress command argument-hint includes --forensic', () => { + const command = fs.readFileSync( + path.join(__dirname, '..', 'commands', 'gsd', 'progress.md'), 'utf8' + ); + assert.ok(command.includes('--forensic'), 'argument-hint should include --forensic'); + }); + + test('progress workflow has a forensic_audit step', () => { + const workflow = fs.readFileSync( + path.join(__dirname, '..', 'get-shit-done', 'workflows', 'progress.md'), 'utf8' + ); + assert.ok( + workflow.includes(''), + 'workflow should have a forensic_audit step' + ); + }); + + test('forensic_audit step is only triggered when --forensic is present', () => { + const workflow = fs.readFileSync( + path.join(__dirname, '..', 'get-shit-done', 'workflows', 'progress.md'), 'utf8' + ); + const forensicStep = workflow.slice( + workflow.indexOf(''), + workflow.indexOf('', workflow.indexOf('')) + ); + assert.ok( + forensicStep.includes('--forensic'), + 'forensic_audit step should be gated on --forensic flag' + ); + assert.ok( + forensicStep.includes('Skip') || forensicStep.includes('skip') || forensicStep.includes('exit'), + 'forensic_audit step should skip when --forensic is not present' + ); + }); + + test('forensic_audit step includes all 6 checks', () => { + const workflow = fs.readFileSync( + path.join(__dirname, '..', 'get-shit-done', 'workflows', 'progress.md'), 'utf8' + ); + const forensicStep = workflow.slice( + workflow.indexOf(''), + workflow.indexOf('', workflow.indexOf('')) + ); + // Check 1: STATE vs artifact consistency + assert.ok( + forensicStep.includes('STATE') && (forensicStep.includes('artifact') || forensicStep.includes('consistent')), + 'forensic step should check STATE vs artifact consistency (check 1)' + ); + // Check 2: Orphaned handoff files + assert.ok( + forensicStep.includes('HANDOFF') || forensicStep.includes('handoff'), + 'forensic step should check for orphaned handoff files (check 2)' + ); + // Check 3: Deferred scope drift + assert.ok( + forensicStep.includes('deferred') || forensicStep.includes('defer'), + 'forensic step should check for deferred scope drift (check 3)' + ); + // Check 4: Memory-flagged pending work + assert.ok( + forensicStep.includes('MEMORY') || forensicStep.includes('memory') || forensicStep.includes('pending'), + 'forensic step should check memory-flagged pending work (check 4)' + ); + // Check 5: Blocking todos + assert.ok( + forensicStep.includes('todo') || forensicStep.includes('Todo') || forensicStep.includes('TODO'), + 'forensic step should check blocking operational todos (check 5)' + ); + // Check 6: Uncommitted code + assert.ok( + forensicStep.includes('uncommitted') || forensicStep.includes('git status'), + 'forensic step should check for uncommitted code (check 6)' + ); + }); + + test('forensic_audit step produces a CLEAN or INTEGRITY ISSUE(S) FOUND verdict', () => { + const workflow = fs.readFileSync( + path.join(__dirname, '..', 'get-shit-done', 'workflows', 'progress.md'), 'utf8' + ); + const forensicStep = workflow.slice( + workflow.indexOf(''), + workflow.indexOf('', workflow.indexOf('')) + ); + assert.ok( + forensicStep.includes('CLEAN'), + 'forensic step should produce a CLEAN verdict when all checks pass' + ); + assert.ok( + forensicStep.includes('INTEGRITY ISSUE') || forensicStep.includes('integrity issue'), + 'forensic step should surface INTEGRITY ISSUE when checks fail' + ); + }); + + test('forensic_audit step does not change default progress behavior', () => { + const workflow = fs.readFileSync( + path.join(__dirname, '..', 'get-shit-done', 'workflows', 'progress.md'), 'utf8' + ); + // The forensic step must explicitly say default behavior is unchanged + const forensicStep = workflow.slice( + workflow.indexOf(''), + workflow.indexOf('', workflow.indexOf('')) + ); + assert.ok( + forensicStep.includes('unchanged') || forensicStep.includes('standard report'), + 'forensic step should clarify that default behavior is unchanged' + ); + }); + + test('COMMANDS.md documents --forensic flag for gsd-progress', () => { + const commands = fs.readFileSync( + path.join(__dirname, '..', 'docs', 'COMMANDS.md'), 'utf8' + ); + assert.ok( + commands.includes('--forensic'), + 'COMMANDS.md should document --forensic flag for gsd-progress' + ); + }); +});