mindforge-cc 8.1.0 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/autonomous/auto-executor.md

@@ -0,0 +1,266 @@
+# MindForge v2 — Auto-Executor Engine
+
+## Purpose
+Orchestrate complete autonomous execution of a MindForge phase without
+human intervention. The auto-executor is the brain behind `/mindforge:auto`.
+
+## Design principles
+
+### Principle 1 — Fresh context per task
+Every task is executed by a new subagent with a fresh context window.
+Never accumulate context across tasks. The only state that persists between
+tasks is written to `.planning/` files (HANDOFF.json, AUDIT.jsonl, SUMMARY files).
+
+### Principle 2 — Durable execution
+Auto mode is designed to survive interruption. Every task completion writes
+to HANDOFF.json before moving to the next. If the session dies:
+- HANDOFF.json shows exactly where execution stopped
+- Next `/mindforge:auto` call resumes from the last completed task
+- No work is repeated, no work is lost
+
+### Principle 3 — Governance is non-negotiable
+Compliance gates run between every wave. CRITICAL security findings stop
+the loop immediately. Tier 3 changes (auth/payment/PII code patterns) trigger
+ESCALATE — they are never auto-approved in autonomous mode.
+
+### Principle 4 — Signal over silence
+Auto mode never silently fails. Every decision (RETRY, DECOMPOSE, PRUNE,
+ESCALATE) is written to AUDIT.jsonl with full context. The progress stream
+reports every state change in real time.
+
+---
+
+## Auto-executor state machine
+
+```
+IDLE
+  │
+  ▼ /mindforge:auto [phase N]
+PRE_FLIGHT_CHECK
+  │ fail → ESCALATE with specific error
+  │ pass
+  ▼
+PHASE_ASSESSMENT
+  │ PLAN files exist?
+  │   NO → AUTO_PLAN (discuss if ambiguity > 3.5, then plan)
+  │   YES → check if any are incomplete
+  ▼
+DEPENDENCY_RESOLUTION
+  │ Build wave DAG from PLAN files
+  │ Identify completed tasks (SUMMARY files exist)
+  │ Resume from first incomplete task
+  ▼
+WAVE_EXECUTION_LOOP ←──────────────────────────────┐
+  │                                                 │
+  │ For each wave:                                  │
+  │   Dispatch N tasks in parallel (subagents)      │
+  │   Each task: EXECUTE → VERIFY → COMMIT          │
+  │                                                 │
+  │   Task result:                                  │
+  │     SUCCESS → write SUMMARY, AUDIT, HANDOFF     │
+  │     FAILURE → NODE_REPAIR (see node-repair.md)  │
+  │       REPAIR result:                            │
+  │         RECOVERED → continue                   │
+  │         DEFERRED  → add to DEFERRED-ITEMS.md    │
+  │         ESCALATE  → stop, notify, write report  │
+  │                                                 │
+  │ Poll steering-queue.jsonl at task boundaries    │
+  │ Apply any queued steering guidance              │
+  │                                                 │
+  │ After each wave:                                │
+  │   Run compliance gates (Gate 1-5)               │
+  │   CRITICAL finding → ESCALATE                  │
+  │   Update HANDOFF.json wave completion           │
+  │   Push if AUTO_PUSH_ON_WAVE_COMPLETE=true        │
+  │                                                 │
+  └─────────────── all waves complete ─────────────┘
+  │
+  ▼
+POST_EXECUTION
+  │ Run automated verification (no human UAT in auto mode)
+  │ Write AUTONOMOUS-REPORT-[phase]-[timestamp].md
+  │ Update STATE.md
+  │ Send Slack notification (if configured)
+  ▼
+COMPLETE (or ESCALATED)
+```
+
+---
+
+## Pre-flight check protocol
+
+Before starting any autonomous execution, verify:
+
+```bash
+# 1. Health check — must be healthy
+/mindforge:health
+# Expected: ✅ Installation integrity, ✅ State consistency
+
+# 2. Schema version check
+SCHEMA_VER=$(node -e "try{const h=require('./.planning/HANDOFF.json');
+  console.log(h.schema_version)}catch{console.log('missing')}")
+[ "${SCHEMA_VER}" = "1.0.0" ] || {
+  echo "⚠️  HANDOFF.json schema outdated (${SCHEMA_VER}). Run /mindforge:migrate"
+  exit 1
+}
+
+# 3. Uncommitted changes check
+# HARDENED: Exclude .planning/ and MINDFORGE.md
+DIRTY=$(git status --porcelain | \
+  grep -v "^??" | \
+  grep -v "^.. \.planning/" | \
+  grep -v "^.. MINDFORGE\.md" | \
+  wc -l | tr -d ' ')
+
+if [ "${DIRTY}" -gt 0 ]; then
+  echo "❌ ${DIRTY} uncommitted change(s) in application code."
+  echo "   Commit or stash before running auto mode:"
+  git status --porcelain | grep -v "^??" | grep -v "^.. \.planning/"
+  exit 1
+fi
+echo "✅ Working tree clean (application code)"
+
+# 4. Phase PLAN files check
+PLAN_COUNT=$(ls .planning/phases/${PHASE_NUM}/PLAN-${PHASE_NUM}-*.md 2>/dev/null | wc -l | tr -d ' ')
+if [ "${PLAN_COUNT}" -eq 0 ]; then
+  echo "ℹ️  No PLAN files for Phase ${PHASE_NUM}. Will auto-plan first."
+  # Trigger auto-plan path
+fi
+
+# 5. Governance configuration check — warn if Tier 2/3 approvers not configured
+APPROVERS=$(grep "TIER2_APPROVERS=" .mindforge/governance/GOVERNANCE-CONFIG.md 2>/dev/null | \
+  grep -v "senior-engineer" | head -1)
+[ -n "${APPROVERS}" ] || {
+  echo "⚠️  Tier 2/3 approvers not configured. Tier 3 changes will ESCALATE immediately."
+}
+
+# 6. Timeout sanity check
+TIMEOUT_MINS="${AUTO_MODE_DEFAULT_TIMEOUT_MINUTES:-120}"
+echo "ℹ️  Timeout: ${TIMEOUT_MINS} minutes from now ($(date -d "+${TIMEOUT_MINS} minutes" '+%H:%M'))"
+```
+
+---
+
+## Task dispatch model
+
+### Subagent context package (fresh per task)
+Each task's subagent receives ONLY:
+1. CLAUDE.md (persona instructions)
+2. The specific persona file (e.g., developer.md)
+3. Relevant loaded skills (JIT-loaded per triggers)
+4. The specific PLAN-N-MM.md file
+5. CONVENTIONS.md (org coding standards)
+6. Referenced architecture sections only (not full ARCHITECTURE.md)
+7. Any steering guidance from steering-queue.jsonl
+8. Implicit knowledge from HANDOFF.json relevant to this task
+
+This is the minimum-context principle from the v1 context-injector — carried
+forward and enforced strictly in auto mode to prevent context rot.
+
+### Fresh context enforcement
+```bash
+# Auto mode subagent spawn — each task gets a new conversation
+# (In Claude Code: each task is a new sub-session with /clear between tasks)
+# Context budget per task: max 60,000 tokens
+# If context estimate > 60K: DECOMPOSE the task before execution
+
+CONTEXT_EST=$(estimate_task_context "${PLAN_FILE}")
+if [ "${CONTEXT_EST}" -gt 60000 ]; then
+  echo "Context estimate ${CONTEXT_EST} exceeds 60K — triggering pre-execution DECOMPOSE"
+  decompose_plan "${PLAN_FILE}"
+fi
+```
+
+### Compliance gate timing — CRITICAL DISTINCTION
+
+### Gate 3 (secret detection) — runs PRE-COMMIT, not post-wave
+Gate 3 must run on the STAGED diff before every commit.
+A committed secret is a git history violation even if caught 30 seconds later.
+
+```bash
+# Before every git commit in auto mode:
+STAGED_DIFF=$(git diff --cached)
+
+# Secret detection on staged content
+SECRET_FOUND=$(echo "${STAGED_DIFF}" | \
+  grep -E "(sk-[a-zA-Z0-9]{20,}|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36}|xoxb-[a-zA-Z0-9-]+)" | \
+  head -1)
+
+if [ -n "${SECRET_FOUND}" ]; then
+  # DO NOT COMMIT
+  git reset HEAD  # Unstage everything
+  echo "🔴 GATE 3 VIOLATION: Secret detected in staged changes"
+  echo "   Pattern: ${SECRET_FOUND:0:30}***"
+  echo "   Auto mode ESCALATING — secret must be removed before continuing"
+  write_escalation "Gate 3: secret credential pattern in staged diff"
+  write_audit_gate3_violation
+  notify_slack_critical
+  exit 3  # Exit code 3 = gate failure
+fi
+```
+
+### Gates 1, 2, 4, 5 — run POST-WAVE (as before)
+These gates check the wave's overall output, not individual commits.
+They run after all tasks in a wave complete.
+
+---
+
+## Progress state file: `.planning/auto-state.json`
+
+Written after every task. The source of truth for progress display and resumption.
+
+```json
+{
+  "schema_version": "2.0.0",
+  "auto_mode_active": true,
+  "session_id": "auto-sess-uuid",
+  "phase": 3,
+  "started_at": "ISO-8601",
+  "timeout_at": "ISO-8601",
+  "elapsed_ms": 1083000,
+  "estimated_remaining_ms": 741000,
+  "wave_current": 2,
+  "wave_total": 3,
+  "tasks_completed": 4,
+  "tasks_total": 8,
+  "tasks_failed": 0,
+  "node_repairs": 0,
+  "escalations": 0,
+  "steering_items_applied": 1,
+  "token_consumed_estimate": 82400,
+  "last_commit": "abc1234ef",
+  "last_task": "Plan 3-04",
+  "current_task": "Plan 3-05",
+  "current_task_started_at": "ISO-8601",
+  "gate_failures": 0,
+  "deferred_items": [],
+  "status": "running|paused|completed|escalated|timeout",
+  "_warning": "Never store secrets in this file."
+}
+```
+
+---
+
+## AUDIT entries for auto mode
+
+Three new AUDIT event types:
+
+```json
+{ "event": "auto_mode_started",
+  "phase": 3, "session_id": "auto-sess-uuid",
+  "plans_total": 8, "waves_total": 3,
+  "timeout_minutes": 120 }
+
+{ "event": "auto_mode_completed",
+  "phase": 3, "session_id": "auto-sess-uuid",
+  "tasks_completed": 8, "tasks_total": 8,
+  "node_repairs": 0, "escalations": 0,
+  "duration_ms": 1834000, "commits": ["abc1234", "def5678"] }
+
+{ "event": "auto_mode_escalated",
+  "phase": 3, "session_id": "auto-sess-uuid",
+  "reason": "CRITICAL security finding in Plan 3-06",
+  "last_completed_task": "Plan 3-05",
+  "next_task": "Plan 3-06",
+  "resume_command": "/mindforge:auto --phase 3 --resume" }
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/autonomous/headless-adapter.md

@@ -0,0 +1,66 @@
+# MindForge v2 — Headless Adapter
+
+## Purpose
+Enable MindForge execution in non-interactive environments (CI/CD, GitHub
+Actions, remote build servers). The headless adapter handles SIGTERM,
+prevents terminal UI rendering, and enforces strict exit codes.
+
+---
+
+## Headless characteristics
+
+### 1. Zero-interaction
+All prompts are auto-answered with defaults (or `yes` for security gates
+if `TIER_1_AUTO_APPROVE=true`). If a Tier 3 change is detected, it
+immediately exits with code 10 (Escalation Required).
+
+### 2. Output redirection
+Standard terminal UI (Progress stream) is disabled.
+Instead, a structured JSON stream is written to `stdout`.
+Informational logs go to `stderr`.
+
+### 3. Graceful termination (SIGTERM/SIGINT) - HARDENED
+When running in environments like GitHub Actions, the runner might receive
+a SIGTERM (timeout).
+**Hardening rule:** On SIGTERM, the engine MUST:
+- Finish the current `git commit` if in progress.
+- Write the current state to HANDOFF.json.
+- Upload current `.planning/` artifacts as a "resume package".
+- Prevent the race condition where `SIGTERM` kills the process mid-write.
+
+```javascript
+// bin/autonomous/headless.js logic
+process.on('SIGTERM', async () => {
+  console.error('⚠️ Received SIGTERM. Snapshotting state for resumption...');
+  await autoExecutor.pause(); // Flushes all state buffers
+  process.exit(0); // Exit 0 to show graceful pause vs failure
+});
+```
+
+---
+
+## CI Configuration (`.mindforge/ci.yaml`)
+
+Typical GitHub Action setup:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - name: Run MindForge Auto
+    run: npx mindforge auto --phase 3 --headless
+    env:
+      MINDFORGE_TOKEN: ${{ secrets.MINDFORGE_TOKEN }}
+      AUTO_PUSH_ON_WAVE_COMPLETE: true
+```
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success (Phase complete) |
+| 1    | General Error (Check logs) |
+| 3    | Gate/Compliance Failure |
+| 10   | Escalation Required (Human needed) |
+| 124  | Timeout (Max duration exceeded) |

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/autonomous/node-repair.md

@@ -0,0 +1,190 @@
+# MindForge v2 — Node Repair Operator
+
+## Purpose
+When a task fails in auto mode, the node repair operator decides whether to
+RETRY, DECOMPOSE, PRUNE, or ESCALATE — in that order of preference.
+The goal: recover autonomously without escalating to the human unless truly necessary.
+
+## The four repair strategies
+
+### RETRY — Re-execute the same plan with a fresh context
+
+**When to use:**
+- First failure of any kind (default first response)
+- Test failures that look transient (no deterministic root cause identifiable)
+- Timeout (task ran > task timeout without completing)
+- `error: Cannot find module` or similar environment setup errors
+
+**How it works:**
+1. Clear any partial file changes from the failed attempt: `git checkout -- .`
+2. Read the failure output carefully for error signals
+3. Inject the error output as additional context for the retry subagent:
+   ```
+   [RETRY CONTEXT — previous attempt failed]
+   Error observed: [exact error message]
+   This is attempt 2/2. Fix this specific error.
+   ```
+4. Re-dispatch the task with fresh context + error context
+5. If retry succeeds: write `node_repair_type: RETRY` to AUDIT entry
+6. If retry fails: proceed to DECOMPOSE
+
+**Budget:** Max 1 retry per task (configurable via `AUTO_NODE_REPAIR_BUDGET`)
+
+---
+
+### DECOMPOSE — Split the failed task into smaller tasks
+
+**When to use:**
+- RETRY failed (scope was too broad for one pass)
+- Context estimate > 60K tokens (before even attempting)
+- Verify step fails on multiple distinct criteria simultaneously
+- Task has files from 2+ distinct domains (auth + database + UI in one plan)
+
+**How it works:**
+
+Step 1 — Analyse the failed plan:
+Read the `<action>` and `<files>` fields. Identify:
+- How many distinct concerns are in this plan?
+- What is the minimal first step that would unblock the rest?
+- What is the logical split that creates two independent tasks?
+
+Step 2 — Create two replacement PLAN files:
+
+Original: `PLAN-3-05.md` (failed)
+→ `PLAN-3-05a.md` (first part — the foundation)
+→ `PLAN-3-05b.md` (second part — depends on 05a)
+
+```xml
+<!-- PLAN-3-05a.md -->
+<task type="auto">
+  <n>[Original name] — Part A: [foundation concern]</n>
+  <persona>developer</persona>
+  <phase>3</phase>
+  <plan>05a</plan>
+  <dependencies>04</dependencies>
+  <decomposed_from>05</decomposed_from>
+  <files>[subset of original files — foundation only]</files>
+  <action>[Action for part A only — narrower scope]</action>
+  <verify>[Verify step for part A specifically]</verify>
+  <done>[Part A definition of done]</done>
+</task>
+```
+
+Step 3 — Insert the new plans into the wave execution at the current position
+Step 4 — Update dependency chain: any plan that depended on the original plan now depends on the second sub-plan (Xb). Xa gets original dependencies.
+Step 5 — Write AUDIT: `{ "event": "node_decomposed", "original": "3-05", "into": ["3-05a", "3-05b"] }`
+Step 6 — Execute 3-05a. If it succeeds, execute 3-05b.
+
+**Budget:** Max 1 decomposition per original plan. If 3-05a also fails: PRUNE or ESCALATE.
+
+---
+
+### PRUNE — Skip and defer to a follow-up task
+
+**When to use:**
+- Plan is not on the critical path (other plans don't depend on it)
+- RETRY and DECOMPOSE both failed
+- Plan is a "nice-to-have" improvement, not core functionality
+
+**How it works:**
+1. Mark the plan as `status: PRUNED` in auto-state.json
+2. Write to `.planning/phases/[N]/DEFERRED-ITEMS.md`:
+   ```markdown
+   # Deferred Items — Phase [N]
+
+   ## PRUNED-[plan-id]: [task name]
+   **Reason:** RETRY + DECOMPOSE both failed. Non-critical path.
+   **Last error:** [error from final attempt]
+   **Retry when:** [suggested condition — e.g., "after database schema is stable"]
+   **Manual steps:** [what a human would need to do to complete this]
+   ```
+3. Log AUDIT: `{ "event": "node_pruned", "plan": "3-05", "reason": "..." }`
+4. Send Slack notification if `AUTO_NOTIFY_ON_ESCALATION=true`:
+   "⚠️ Auto mode pruned Plan 3-05 — non-critical, deferred to follow-up"
+5. Continue auto mode with the next task
+
+**Guard:** PRUNE only if no other plans declare `<dependencies>` on this plan (check wave DAG and physical PLAN files).
+If other plans depend on this one: ESCALATE instead (cannot skip a critical path dependency).
+
+---
+
+### ESCALATE — Stop, save state, notify human
+
+**When to use (ANY of these):**
+- Tier 3 change detected (auth/payment/PII code — requires human compliance approval)
+- CRITICAL security finding in compliance gates
+- Plan is on critical path and RETRY + DECOMPOSE both failed
+- Gate 3 violation (secrets detected in diff)
+- Node repair budget exhausted (ALL RETRY and DECOMPOSE attempts failed)
+- Timeout exceeded AND work in progress (clean timeout → exit 0, mid-task timeout → ESCALATE)
+- Human explicitly requested via `CTRL+C` pause
+
+**How it works:**
+1. Stop execution immediately (do NOT start the next task)
+2. `git stash` any uncommitted partial changes
+3. Write comprehensive ESCALATION-[timestamp].md:
+   ```markdown
+   # Auto Mode Escalation — Phase [N]
+   **Time:** [ISO-8601]
+   **Trigger:** [exact escalation reason]
+   **Last completed task:** Plan [N]-[MM] (commit: [sha])
+   **Blocked on:** Plan [N]-[MM+1] — [task name]
+   **Error details:** [full error output]
+   **Required human action:** [exactly what needs to happen]
+   **Resume command:** /mindforge:auto --phase [N] --resume
+   ```
+4. Update auto-state.json: `"status": "escalated"`
+5. Update HANDOFF.json: `"next_task": "ESCALATED — see .planning/phases/[N]/ESCALATION-[ts].md"`
+6. Write AUDIT: `{ "event": "auto_mode_escalated", "reason": "...", "resume_command": "..." }`
+7. Send Slack notification with the ESCALATION.md content (if configured)
+8. Exit auto mode with status message printed to terminal
+
+## Repair decision tree
+
+```
+Task fails
+    │
+    ▼
+Is this a Tier 3 governance trigger?
+    YES → ESCALATE immediately (never auto-approve auth/payment/PII)
+    NO
+    │
+    ▼
+Is this attempt 1?
+    YES → RETRY (inject error context)
+    NO (retry also failed)
+    │
+    ▼
+Is plan decomposable (2+ concerns)?
+    YES → DECOMPOSE into sub-plans
+    NO
+    │
+    ▼
+Is plan on critical path (other plans depend on it)?
+    YES → ESCALATE (cannot skip dependency)
+    NO
+    │
+    ▼
+PRUNE (defer to DEFERRED-ITEMS.md)
+```
+
+## Repair AUDIT schema
+
+Every repair action writes an AUDIT entry:
+
+```json
+{
+  "id": "uuid",
+  "timestamp": "ISO-8601",
+  "event": "node_repair",
+  "session_id": "auto-sess-uuid",
+  "phase": 3,
+  "plan": "05",
+  "repair_type": "RETRY|DECOMPOSE|PRUNE|ESCALATE",
+  "attempt_number": 2,
+  "original_error": "[first 200 chars of error output]",
+  "repair_outcome": "recovered|failed|deferred|escalated",
+  "decomposed_into": ["05a", "05b"],
+  "agent": "mindforge-auto-repair"
+}
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/autonomous/progress-reporter.md

@@ -0,0 +1,58 @@
+# MindForge v2 — Progress Reporter
+
+## Purpose
+Provide real-time visibility into autonomous execution. The reporter
+translates the raw AUDIT.jsonl stream into a user-friendly terminal UI
+and a persistent `AUTONOMOUS-REPORT.md` file.
+
+---
+
+## Terminal UI (Progress stream)
+
+The progress stream uses standard TTY escape codes (via `ora` or similar)
+to show current status without flooding the terminal.
+
+```
+MindForge v2 [PHASE 3: API Hardening]
+──────────────────────────────────────────────────────────────────
+[WAVE 2/3] [TASK 5/8]
+[██████████████░░░░░░] 75% Complete
+
+Current:  Plan 3-05 — Implement JWT Refresh Logic
+Status:   Running (attempt 1) [elapsed: 1:42]
+Token Est: 18,400
+
+Latest:
+✅ Plan 3-04 complete (abc1234)
+✅ Gate 1-2 Passed
+⚠️  Steering applied: "Use jsonwebtoken lib"
+──────────────────────────────────────────────────────────────────
+Use /mindforge:steer "..." to guide the agent mid-flight.
+```
+
+---
+
+## Autonomous report generation
+
+At the end of an auto-mode session (Success or Escalation), a markdown
+report is generated in `.planning/phases/[N]/AUTONOMOUS-REPORT-[timestamp].md`.
+
+### Content requirements:
+1. **Summary**: Overall status, start/end time, total duration.
+2. **Stats**: Tasks completed, tokens consumed (estimate), commits made.
+3. **Audit log**: Filtered list of major events (starts, completions, repairs, gates).
+4. **Repairs**: Detailed breakdown of any RETRY or DECOMPOSE actions.
+5. **Steering**: List of applied steering instructions and their outcomes.
+6. **Escalation**: If failed, clear instructions on why and how to resume.
+
+---
+
+## JSON Output (Stream)
+
+For integration with other tools or web UIs, the progress reporter
+can output line-delimited JSON messages to a separate file or pipe.
+
+```json
+{"type":"progress","phase":3,"wave":2,"task":5,"status":"running","ts":"ISO-8601"}
+{"type":"event","id":"abc-123","event":"gate_passed","gate":2}
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.mindforge/engine/autonomous/steering-manager.md

@@ -0,0 +1,64 @@
+# MindForge v2 — Steering Manager
+
+## Purpose
+Allow a human to "steer" the autonomous agent without stopping it.
+Steering guidance is injected at the next task boundary, allowing for
+mid-course corrections, scope changes, or specific technical preferences.
+
+---
+
+## Steering protocol
+
+### 1. Queuing guidance
+Human uses `/mindforge:steer "[instruction]"` or writes to `.planning/steering-queue.jsonl`.
+Instructions are timestamped and queued.
+
+```json
+{ "id": "steer-uuid", "timestamp": "ISO-8601", "instruction": "Use PostgreSQL instead of SQLite", "scope": "global|current_phase|current_task" }
+```
+
+### 2. Injection point
+The Auto-Executor checks for queued steering guidance MUST happen at
+every task boundary (before starting a new subagent).
+
+```javascript
+// auto-executor injection logic
+const guidance = await steeringManager.popPending();
+if (guidance) {
+  const currentPlan = await loadCurrentPlan();
+  const modifiedPlan = applyGuidanceToPlan(currentPlan, guidance);
+  await savePlan(modifiedPlan);
+  writeAudit('steering_applied', guidance);
+}
+```
+
+### 3. Application logic — HARDENED
+When guidance is applied to a task:
+
+- **Constraint:** Steering cannot override core security constraints (Gears 1-5).
+- **Injection:** Guidance is added to the `<action>` field of the PLAN-N-MM.md,
+  prefixed with `[STEERING GUIDANCE — DO NOT IGNORE]`.
+- **Precedence:** Steering instruction takes precedence over the original
+  plan description if they conflict.
+
+---
+
+## Steering commands
+
+### `/mindforge:steer "..."`
+Adds global guidance to the queue. Available even if auto mode is not running.
+
+### `/mindforge:steer --task 3-05 "..."`
+Targeted guidance for a specific future task.
+
+### `/mindforge:steer --cancel`
+Clear the entire steering queue.
+
+---
+
+## Steering feedback loop
+
+When steering is applied, the Progress Reporter (terminal UI) shows:
+`🚢 Steering applied: "Use PostgreSQL instead of SQLite"`
+
+The applied guidance is also recorded in `AUTONOMOUS-REPORT.md`.