gsd-code-first 1.0.0

package/get-shit-done/workflows/forensics.md

@@ -0,0 +1,265 @@
+# Forensics Workflow
+
+Post-mortem investigation for failed or stuck GSD workflows. Analyzes git history,
+`.planning/` artifacts, and file system state to detect anomalies and generate a
+structured diagnostic report.
+
+**Principle:** This is a read-only investigation. Do not modify project files.
+Only write the forensic report.
+
+---
+
+## Step 1: Get Problem Description
+
+```bash
+PROBLEM="$ARGUMENTS"
+```
+
+If `$ARGUMENTS` is empty, ask the user:
+> "What went wrong? Describe the issue — e.g., 'autonomous mode got stuck on phase 3',
+> 'execute-phase failed silently', 'costs seem unusually high'."
+
+Record the problem description for the report.
+
+## Step 2: Gather Evidence
+
+Collect data from all available sources. Missing sources are fine — adapt to what exists.
+
+### 2a. Git History
+
+```bash
+# Recent commits (last 30)
+git log --oneline -30
+
+# Commits with timestamps for gap analysis
+git log --format="%H %ai %s" -30
+
+# Files changed in recent commits (detect repeated edits)
+git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
+
+# Uncommitted work
+git status --short
+git diff --stat
+```
+
+Record:
+- Commit timeline (dates, messages, frequency)
+- Most-edited files (potential stuck-loop indicator)
+- Uncommitted changes (potential crash/interruption indicator)
+
+### 2b. Planning State
+
+Read these files if they exist:
+- `.planning/STATE.md` — current milestone, phase, progress, blockers, last session
+- `.planning/ROADMAP.md` — phase list with status
+- `.planning/config.json` — workflow configuration
+
+Extract:
+- Current phase and its status
+- Last recorded session stop point
+- Any blockers or flags
+
+### 2c. Phase Artifacts
+
+For each phase directory in `.planning/phases/*/`:
+
+```bash
+ls .planning/phases/*/
+```
+
+For each phase, check which artifacts exist:
+- `{padded}-PLAN.md` or `{padded}-PLAN-*.md` (execution plans)
+- `{padded}-SUMMARY.md` (completion summary)
+- `{padded}-VERIFICATION.md` (quality verification)
+- `{padded}-CONTEXT.md` (design decisions)
+- `{padded}-RESEARCH.md` (pre-planning research)
+
+Track: which phases have complete artifact sets vs gaps.
+
+### 2d. Session Reports
+
+Read `.planning/reports/SESSION_REPORT.md` if it exists — extract last session outcomes,
+work completed, token estimates.
+
+### 2e. Git Worktree State
+
+```bash
+git worktree list
+```
+
+Check for orphaned worktrees (from crashed agents).
+
+## Step 3: Detect Anomalies
+
+Evaluate the gathered evidence against these anomaly patterns:
+
+### Stuck Loop Detection
+
+**Signal:** Same file appears in 3+ consecutive commits within a short time window.
+
+```bash
+# Look for files committed repeatedly in sequence
+git log --name-only --format="---COMMIT---" -20
+```
+
+Parse commit boundaries. If any file appears in 3+ consecutive commits, flag as:
+- **Confidence HIGH** if the commit messages are similar (e.g., "fix:", "fix:", "fix:" on same file)
+- **Confidence MEDIUM** if the file appears frequently but commit messages vary
+
+### Missing Artifact Detection
+
+**Signal:** Phase appears complete (has commits, is past in roadmap) but lacks expected artifacts.
+
+For each phase that should be complete:
+- PLAN.md missing → planning step was skipped
+- SUMMARY.md missing → phase was not properly closed
+- VERIFICATION.md missing → quality check was skipped
+
+### Abandoned Work Detection
+
+**Signal:** Large gap between last commit and current time, with STATE.md showing mid-execution.
+
+```bash
+# Time since last commit
+git log -1 --format="%ai"
+```
+
+If STATE.md shows an active phase but the last commit is >2 hours old and there are
+uncommitted changes, flag as potential abandonment or crash.
+
+### Crash/Interruption Detection
+
+**Signal:** Uncommitted changes + STATE.md shows mid-execution + orphaned worktrees.
+
+Combine:
+- `git status` shows modified/staged files
+- STATE.md has an active execution entry
+- `git worktree list` shows worktrees beyond the main one
+
+### Scope Drift Detection
+
+**Signal:** Recent commits touch files outside the current phase's expected scope.
+
+Read the current phase PLAN.md to determine expected file paths. Compare against
+files actually modified in recent commits. Flag any files that are clearly outside
+the phase's domain.
+
+### Test Regression Detection
+
+**Signal:** Commit messages containing "fix test", "revert", or re-commits of test files.
+
+```bash
+git log --oneline -20 | grep -iE "fix test|revert|broken|regression|fail"
+```
+
+## Step 4: Generate Report
+
+Create the forensics directory if needed:
+```bash
+mkdir -p .planning/forensics
+```
+
+Write to `.planning/forensics/report-$(date +%Y%m%d-%H%M%S).md`:
+
+```markdown
+# Forensic Report
+
+**Generated:** {ISO timestamp}
+**Problem:** {user's description}
+
+---
+
+## Evidence Summary
+
+### Git Activity
+- **Last commit:** {date} — "{message}"
+- **Commits (last 30):** {count}
+- **Time span:** {earliest} → {latest}
+- **Uncommitted changes:** {yes/no — list if yes}
+- **Active worktrees:** {count — list if >1}
+
+### Planning State
+- **Current milestone:** {version or "none"}
+- **Current phase:** {number — name — status}
+- **Last session:** {stopped_at from STATE.md}
+- **Blockers:** {any flags from STATE.md}
+
+### Artifact Completeness
+| Phase | PLAN | CONTEXT | RESEARCH | SUMMARY | VERIFICATION |
+|-------|------|---------|----------|---------|-------------|
+{for each phase: name | ✅/❌ per artifact}
+
+## Anomalies Detected
+
+### {Anomaly Type} — {Confidence: HIGH/MEDIUM/LOW}
+**Evidence:** {specific commits, files, or state data}
+**Interpretation:** {what this likely means}
+
+{repeat for each anomaly found}
+
+## Root Cause Hypothesis
+
+Based on the evidence above, the most likely explanation is:
+
+{1-3 sentence hypothesis grounded in the anomalies}
+
+## Recommended Actions
+
+1. {Specific, actionable remediation step}
+2. {Another step if applicable}
+3. {Recovery command if applicable — e.g., `/gsd:resume-work`, `/gsd:execute-phase N`}
+
+---
+
+*Report generated by `/gsd:forensics`. All paths redacted for portability.*
+```
+
+**Redaction rules:**
+- Replace absolute paths with relative paths (strip `$HOME` prefix)
+- Remove any API keys, tokens, or credentials found in git diff output
+- Truncate large diffs to first 50 lines
+
+## Step 5: Present Report
+
+Display the full forensic report inline.
+
+## Step 6: Offer Interactive Investigation
+
+> "Report saved to `.planning/forensics/report-{timestamp}.md`.
+>
+> I can dig deeper into any finding. Want me to:
+> - Trace a specific anomaly to its root cause?
+> - Read specific files referenced in the evidence?
+> - Check if a similar issue has been reported before?"
+
+If the user asks follow-up questions, answer from the evidence already gathered.
+Read additional files only if specifically needed.
+
+## Step 7: Offer Issue Creation
+
+If actionable anomalies were found (HIGH or MEDIUM confidence):
+
+> "Want me to create a GitHub issue for this? I'll format the findings and redact paths."
+
+If confirmed:
+```bash
+# Check if "bug" label exists before using it
+BUG_LABEL=$(gh label list --search "bug" --json name -q '.[0].name' 2>/dev/null)
+LABEL_FLAG=""
+if [ -n "$BUG_LABEL" ]; then
+  LABEL_FLAG="--label bug"
+fi
+
+gh issue create \
+  --title "bug: {concise description from anomaly}" \
+  $LABEL_FLAG \
+  --body "{formatted findings from report}"
+```
+
+## Step 8: Update STATE.md
+
+```bash
+gsd-tools.cjs state record-session \
+  --stopped-at "Forensic investigation complete" \
+  --resume-file ".planning/forensics/report-{timestamp}.md"
+```

package/get-shit-done/workflows/health.md

@@ -0,0 +1,181 @@
+<purpose>
+Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans. Optionally repairs auto-fixable issues.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_args">
+**Parse arguments:**
+
+Check if `--repair` flag is present in the command arguments.
+
+```
+REPAIR_FLAG=""
+if arguments contain "--repair"; then
+  REPAIR_FLAG="--repair"
+fi
+```
+</step>
+
+<step name="run_health_check">
+**Run health validation:**
+
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" validate health $REPAIR_FLAG
+```
+
+Parse JSON output:
+- `status`: "healthy" | "degraded" | "broken"
+- `errors[]`: Critical issues (code, message, fix, repairable)
+- `warnings[]`: Non-critical issues
+- `info[]`: Informational notes
+- `repairable_count`: Number of auto-fixable issues
+- `repairs_performed[]`: Actions taken if --repair was used
+</step>
+
+<step name="format_output">
+**Format and display results:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: HEALTHY | DEGRADED | BROKEN
+Errors: N | Warnings: N | Info: N
+```
+
+**If repairs were performed:**
+```
+## Repairs Performed
+
+- ✓ config.json: Created with defaults
+- ✓ STATE.md: Regenerated from roadmap
+```
+
+**If errors exist:**
+```
+## Errors
+
+- [E001] config.json: JSON parse error at line 5
+  Fix: Run /gsd:health --repair to reset to defaults
+
+- [E002] PROJECT.md not found
+  Fix: Run /gsd:new-project to create
+```
+
+**If warnings exist:**
+```
+## Warnings
+
+- [W002] STATE.md references phase 5, but only phases 1-3 exist
+  Fix: Review STATE.md manually before changing it; repair will not overwrite an existing STATE.md
+
+- [W005] Phase directory "1-setup" doesn't follow NN-name format
+  Fix: Rename to match pattern (e.g., 01-setup)
+```
+
+**If info exists:**
+```
+## Info
+
+- [I001] 02-implementation/02-01-PLAN.md has no SUMMARY.md
+  Note: May be in progress
+```
+
+**Footer (if repairable issues exist and --repair was NOT used):**
+```
+---
+N issues can be auto-repaired. Run: /gsd:health --repair
+```
+</step>
+
+<step name="offer_repair">
+**If repairable issues exist and --repair was NOT used:**
+
+Ask user if they want to run repairs:
+
+```
+Would you like to run /gsd:health --repair to fix N issues automatically?
+```
+
+If yes, re-run with --repair flag and display results.
+</step>
+
+<step name="verify_repairs">
+**If repairs were performed:**
+
+Re-run health check without --repair to confirm issues are resolved:
+
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" validate health
+```
+
+Report final status.
+</step>
+
+</process>
+
+<error_codes>
+
+| Code | Severity | Description | Repairable |
+|------|----------|-------------|------------|
+| E001 | error | .planning/ directory not found | No |
+| E002 | error | PROJECT.md not found | No |
+| E003 | error | ROADMAP.md not found | No |
+| E004 | error | STATE.md not found | Yes |
+| E005 | error | config.json parse error | Yes |
+| W001 | warning | PROJECT.md missing required section | No |
+| W002 | warning | STATE.md references invalid phase | No |
+| W003 | warning | config.json not found | Yes |
+| W004 | warning | config.json invalid field value | No |
+| W005 | warning | Phase directory naming mismatch | No |
+| W006 | warning | Phase in ROADMAP but no directory | No |
+| W007 | warning | Phase on disk but not in ROADMAP | No |
+| W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
+| W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
+| I001 | info | Plan without SUMMARY (may be in progress) | No |
+
+</error_codes>
+
+<repair_actions>
+
+| Action | Effect | Risk |
+|--------|--------|------|
+| createConfig | Create config.json with defaults | None |
+| resetConfig | Delete + recreate config.json | Loses custom settings |
+| regenerateState | Create STATE.md from ROADMAP structure when it is missing | Loses session history |
+| addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
+
+**Not repairable (too risky):**
+- PROJECT.md, ROADMAP.md content
+- Phase directory renaming
+- Orphaned plan cleanup
+
+</repair_actions>
+
+<stale_task_cleanup>
+**Windows-specific:** Check for stale Claude Code task directories that accumulate on crash/freeze.
+These are left behind when subagents are force-killed and consume disk space.
+
+When `--repair` is active, detect and clean up:
+
+```bash
+# Check for stale task directories (older than 24 hours)
+TASKS_DIR="$HOME/.claude/tasks"
+if [ -d "$TASKS_DIR" ]; then
+  STALE_COUNT=$( (find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null || true) | wc -l )
+  if [ "$STALE_COUNT" -gt 0 ]; then
+    echo "⚠️  Found $STALE_COUNT stale task directories in ~/.claude/tasks/"
+    echo "   These are leftover from crashed subagent sessions."
+    echo "   Run: rm -rf ~/.claude/tasks/*  (safe — only affects dead sessions)"
+  fi
+fi
+```
+
+Report as info diagnostic: `I002 | info | Stale subagent task directories found | Yes (--repair removes them)`
+</stale_task_cleanup>