mindforge-cc 9.0.0 → 10.0.1

package/.agent/workflows/mindforge-forensics.md

@@ -1,265 +0,0 @@
-# Forensics Workflow
-
-Post-mortem investigation for failed or stuck MindForge 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., `/mindforge-resume-work`, `/mindforge-execute-phase N`}
-
----
-
-*Report generated by `/mindforge-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
-mindforge-tools.cjs state record-session \
-  --stopped-at "Forensic investigation complete" \
-  --resume-file ".planning/forensics/report-{timestamp}.md"
-```

package/.agent/workflows/mindforge-health.md

@@ -1,181 +0,0 @@
-<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 ".agent/bin/mindforge-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:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MindForge 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 /mindforge-health --repair to reset to defaults
-
-- [E002] PROJECT.md not found
-  Fix: Run /mindforge-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: /mindforge-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 /mindforge-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 ".agent/bin/mindforge-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=".agent/tasks"
-if [ -d "$TASKS_DIR" ]; then
-  STALE_COUNT=$(find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null | wc -l)
-  if [ "$STALE_COUNT" -gt 0 ]; then
-    echo "⚠️  Found $STALE_COUNT stale task directories in .agent/tasks/"
-    echo "   These are leftover from crashed subagent sessions."
-    echo "   Run: rm -rf .agent/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>