feat(progress): add --forensic flag for 6-check integrity audit after standard report (#2231)

Extends /gsd-progress with opt-in --forensic mode that appends a
6-check integrity audit after the standard routing report. Default
behavior is byte-for-byte unchanged — the audit only runs when
--forensic is explicitly passed.

Checks: (1) STATE vs artifact consistency, (2) orphaned handoff files,
(3) deferred scope drift, (4) memory-flagged pending work, (5) blocking
operational todos, (6) uncommitted source code. Emits CLEAN or
N INTEGRITY ISSUE(S) FOUND verdict with concrete next actions.

Closes #2189

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

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

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`

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}`
-  </step>
+</step>
+
+<step name="forensic_audit">
+**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`
+</step>
 
 </process>
 

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('<step name="forensic_audit">'),
+      '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('<step name="forensic_audit">'),
+      workflow.indexOf('</step>', workflow.indexOf('<step name="forensic_audit">'))
+    );
+    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('<step name="forensic_audit">'),
+      workflow.indexOf('</step>', workflow.indexOf('<step name="forensic_audit">'))
+    );
+    // 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('<step name="forensic_audit">'),
+      workflow.indexOf('</step>', workflow.indexOf('<step name="forensic_audit">'))
+    );
+    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('<step name="forensic_audit">'),
+      workflow.indexOf('</step>', workflow.indexOf('<step name="forensic_audit">'))
+    );
+    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'
+    );
+  });
+});