feed-the-machine 1.2.0 → 1.3.1

package/ftm-mind/references/event-registry.md

@@ -256,6 +256,33 @@ Guidelines for writing clear declarations:
 
 ---
 
+### capture_complete
+- **Description**: ftm-capture finished processing and persisting a captured item (snippet, link, thought, or known issue)
+- **Emitted by**: ftm-capture
+- **Listened to by**: ftm-mind (log capture on blackboard, optionally surface to user)
+- **Fast-path**: no
+- **Payload**: `{ capture_type, title, file_path, timestamp }`
+
+---
+
+### known_issue_recorded
+- **Description**: A known issue was captured and recorded for future reference, avoiding repeated investigation of the same problem
+- **Emitted by**: ftm-capture
+- **Listened to by**: ftm-mind (index known issue on blackboard for dedup during future debug sessions)
+- **Fast-path**: no
+- **Payload**: `{ issue_title, issue_description, file_path, tags: [string], timestamp }`
+
+---
+
+### push_requested
+- **Description**: A git push was requested — triggers ftm-git pre-push validation (secret scanning, branch policy checks)
+- **Emitted by**: git-workflow, external systems
+- **Listened to by**: ftm-git (run pre-push secret scan and branch policy validation)
+- **Fast-path**: no
+- **Payload**: `{ branch, remote, commit_range, task_number }`
+
+---
+
 ## Fast-Path Summary
 
 | Event | Always triggers |
@@ -296,4 +323,7 @@ Use this table to quickly look up which skills are involved when an event fires:
 | secrets_found | git | executor, mind |
 | secrets_clear | git | executor, mind |
 | secrets_remediated | git | executor, mind |
+| capture_complete | capture | mind |
+| known_issue_recorded | capture | mind |
+| push_requested | git-workflow, external systems | git |
 | map_updated | map | mind, intent, diagram |

package/ftm-pause/SKILL.md

@@ -14,9 +14,15 @@ description: Save the current ftm skill session state so work can be resumed in
 
 # FTM Pause — Session State Capture
 
-Save the full state of any active ftm skill session to disk so it can be resumed in a new conversation with zero context loss.
+Save the full state of any active ftm skill session to disk so it can be resumed in a new conversation with zero context loss. This skill understands the internal structure of every ftm skill and captures exactly what's needed to pick up where you left off.
 
-## Step 1: Detect the Active FTM Skill
+## Why This Exists
+
+FTM skills — brainstorm, executor, debug, council, audit — are multi-phase, multi-turn workflows that accumulate significant context over time. Research findings, agent results, user decisions, worktree branches, plan progress — all of this lives in the conversation and dies when the conversation ends. A brainstorm session 8 turns deep with 3 completed research sprints and 2 rounds of questioning is hours of work that evaporates if the user needs to stop.
+
+This skill captures that state to a structured file that ftm-resume can read to reconstruct the session in a fresh conversation. The user loses nothing.
+
+## Step 1: Detect the Active Panda Skill
 
 Scan the current conversation context to determine which ftm skill is active. Look for these signals:
 
@@ -34,9 +40,150 @@ If multiple skills have been invoked in the same conversation (e.g., brainstorm
 
 ## Step 2: Capture State by Skill Type
 
-Read `references/protocols/SKILL-RESTORE-PROTOCOLS.md` for the full per-skill capture specification. Each skill section defines exactly which fields must be captured and what is required for reliable restoration.
-
-Capture every field listed for the detected skill. Do not omit fields because a phase hasn't been reached yet — record those as "not started" or "N/A" so ftm-resume knows the session stopped before that phase.
+### ftm-brainstorm
+
+Capture all of the following that exist in the current session:
+
+**Phase tracking:**
+- Current phase (0, 1, 2, or 3)
+- If Phase 1: which round (1, 2, or 3), which path (A: Fresh Idea or B: Brain Dump)
+- If Phase 2: how many research+challenge turns have been completed
+- If Phase 3: which section of the plan has been presented (Vision, Tasks, Agents, or complete)
+
+**Phase 0 context:**
+- The full repo scan results (project type, tech stack, architecture, patterns, infrastructure, scale)
+- Whether the scan was skipped (no git repo) and any stack info gathered from the user instead
+
+**Phase 1 — Intake:**
+- The user's original idea/request (verbatim if short, summarized if long)
+- If Path B: the full brain dump extraction (decisions made, open questions, assumptions, contradictions, gaps)
+- All user answers from each completed round
+- Research Sprint 1 results (landscape context) — all findings from Web Researcher, GitHub Explorer, Competitive Analyst
+- Research Sprint 2 results (constraint-scoped research) — all findings from all three agents
+- If Path B: the novelty map (which claims are solved/partially solved/novel)
+
+**Phase 2 — Research + Challenge Loop:**
+- Every completed turn's 5 suggestions (or fewer if weak results) with evidence and links
+- Every challenge posed and the user's response
+- Every question asked and the user's answer
+- Accumulated decisions and direction chosen
+- Research agent results from each turn (summarized — full URLs and key findings, not raw agent output)
+- The current "direction" the brainstorm is heading (architecture chosen, scope narrowed, etc.)
+
+**Phase 3 — Plan Generation:**
+- Which sections have been presented and approved (Vision, Tasks, Agents/Waves)
+- The plan content generated so far
+- The plan file path if it's been saved
+- User feedback on each section
+
+### ftm-executor
+
+**Plan context:**
+- Plan file path (absolute)
+- Plan title and summary
+- Total task count
+- Agent team composition (agent names, roles, task assignments)
+
+**Execution progress:**
+- Current wave number
+- For each task: status (pending / in-progress / complete / failed / blocked)
+- For completed tasks: commit hashes, audit results (pass/fail/auto-fixed), brief summary of what was done
+- For in-progress tasks: which agent is working on it, what's been done so far
+- For failed/blocked tasks: what went wrong, error details
+
+**Worktree state:**
+- List of all worktree branches and their paths
+- Which worktrees are active vs merged vs abandoned
+- Any merge results or conflicts encountered
+- The main/working branch name
+
+**Verification state:**
+- Post-task audit results for each completed task
+- Any manual intervention items outstanding
+- Full test suite status (last run result)
+
+### ftm-debug
+
+**Problem context:**
+- The original problem statement (symptom, expected behavior, what's been tried, when it started, reproduction steps)
+- Codebase reconnaissance results (entry points, call graph, state flow, dependencies, recent changes, test coverage, config, error handling)
+- The investigation plan (likely category, which agents deployed, worktree strategy)
+
+**Phase 1 — Investigation results:**
+- Instrumenter report: what was instrumented, log point locations, DEBUG-INSTRUMENTATION.md content
+- Researcher report: findings with sources, relevance, solutions, confidence, RESEARCH-FINDINGS.md content
+- Reproducer report: trigger command, consistency, boundaries, minimal test path, REPRODUCTION.md content
+- Hypothesizer report: all hypotheses ranked with claims, mechanisms, code paths, evidence, HYPOTHESES.md content
+
+**Phase 2 — Synthesis & Solve:**
+- Cross-reference analysis (how findings align or conflict)
+- Recommended fix approach
+- Solver attempts: which hypotheses tried, what was implemented, commit hashes
+- FIX-SUMMARY.md content if fix was applied
+
+**Phase 3 — Review & Verify:**
+- Reviewer verdict (APPROVED / APPROVED WITH CHANGES / NEEDS REWORK)
+- REVIEW-VERDICT.md content
+- How many solver-reviewer iterations completed
+- Outstanding issues from review
+
+**Worktree state:**
+- debug-instrumentation branch and path
+- debug-reproduction branch and path
+- debug-fix branch and path (including any fix attempt sub-branches)
+- Which worktrees still exist vs cleaned up
+
+### ftm-council
+
+**Council setup:**
+- The council prompt (the framed problem statement)
+- Whether the user confirmed/edited the prompt
+- Prerequisites check result (codex and gemini available?)
+
+**Deliberation state:**
+- Current round number (1-5)
+- For each completed round, each model's full response:
+  - Research summary (what files examined, what was found)
+  - Position (their stance)
+  - Reasoning (with code references)
+  - Concerns
+  - Confidence level
+- For rebuttal rounds: each model's updated position, new evidence, responses to other models, remaining disagreements
+- Alignment analysis after each round (agreement areas, divergence points, different research paths, majority forming?)
+
+**Outcome:**
+- Whether consensus has been reached (and if so, which 2 models agreed)
+- The verdict if delivered (decision, agreed by, dissent, evidence basis)
+- If no consensus after 5 rounds: the synthesis and options presented
+
+### ftm-audit
+
+**Trigger context:**
+- What triggered the audit (manual invocation, post-task from executor, specific files/scope)
+- Scope (full project, specific files, specific task's changes)
+
+**Phase 0 — Project patterns:**
+- Detected framework, router, state management, API layer, build tool
+- Active dimensions (D1-D5) and their configuration
+- Any unusual patterns noted
+
+**Layer 1 — knip results:**
+- Full knip output (categorized: unused files, unused exports, unused deps, unlisted deps, unresolved imports)
+- Each finding with file:line
+
+**Layer 2 — Adversarial audit results:**
+- Each finding with type, location, evidence, and which dimension failed
+- Wiring contract checks if applicable (which checks passed, which failed)
+
+**Layer 3 — Auto-fix results:**
+- Fixes applied (finding, fix description, verification result)
+- Manual intervention items (finding, reason auto-fix skipped, suggested action)
+- Re-verification results
+- Current iteration count (of max 3)
+
+**Final status:**
+- PASS or FAIL
+- Remaining issues count and details
 
 ## Step 3: Gather Artifacts
 
@@ -57,80 +204,152 @@ Create the directory if it doesn't exist:
 mkdir -p ~/.claude/ftm-state
 ```
 
-Write the state file to `~/.claude/ftm-state/STATE.md`. Required structure:
+Write the state file to `~/.claude/ftm-state/STATE.md`:
 
 ```markdown
 ---
-skill: <skill-name>
-phase: <phase-number-or-name>
-phase_detail: "<human-readable one-liner: exactly where the session stopped>"
-timestamp: <ISO-8601>
-project_dir: <absolute-path>
-git_branch: <branch>       # omit if no git repo
-git_commit: <short-hash>   # omit if no git repo
+skill: ftm-brainstorm
+phase: 2
+phase_detail: "Research+Challenge turn 5, user chose microservices direction"
+timestamp: 2026-03-16T23:50:00
+project_dir: /Users/path/to/project
+git_branch: main
+git_commit: abc1234
 ---
 
 # FTM Session State
 
 ## Active Skill
-[One paragraph: skill, phase, path, turn, and current direction]
+ftm-brainstorm, Phase 2 (Research + Challenge Loop), Turn 5 of unlimited.
+Path A (Fresh Idea). User chose microservices direction in turn 3, currently exploring
+service mesh options.
 
 ## Context Snapshot
-[Full state for this skill per references/protocols/SKILL-RESTORE-PROTOCOLS.md]
+
+### Phase 0: Repo Scan
+[paste the full repo scan results here — project type, stack, architecture, patterns]
+
+### Phase 1: Intake Summary
+**Round 1 answers:**
+- Core idea: [user's answer]
+- Target users: [user's answer]
+- Problem solved: [user's answer]
+
+**Research Sprint 1 (Landscape):**
+- Web Researcher: [key findings with URLs]
+- GitHub Explorer: [key repos with URLs]
+- Competitive Analyst: [key products/tools]
+
+**Round 2 answers:**
+- Architecture preference: [user's choice from Sprint 1 options]
+- Integration requirements: [user's answer]
+- Scale/environment: [user's answer]
+
+**Research Sprint 2 (Constraint-Scoped):**
+- [findings, more targeted than Sprint 1]
+
+**Round 3 answers:**
+- Success criteria: [user's answer]
+- v1 scope: [user's answer]
+- Non-negotiables: [user's answer]
+
+### Phase 2: Research + Challenge Turns
+**Turn 1:**
+- Suggestions presented: [titles of 5 suggestions with brief summaries]
+- Challenges posed: [what was challenged]
+- User response: [what they said, what direction they chose]
+
+**Turn 2:**
+[same structure]
+
+[...repeat for each turn...]
+
+**Current direction:**
+[the accumulated picture of what's being built, architecture chosen, scope, key decisions]
 
 ## Decisions Made
-[Every decision the user confirmed — use real content, not placeholders]
+- Architecture: microservices with gRPC
+- Database: PostgreSQL with read replicas
+- Auth: OAuth2 with Okta integration
+- Scope: 3 core services for v1, defer analytics service
+- [every decision the user confirmed during the session]
 
 ## Open Questions
-[Anything unresolved or about to be explored]
+- Service mesh: Istio vs Linkerd — research presented, user hasn't decided
+- Deployment: Kubernetes vs ECS — not yet discussed
+- [anything that was about to be explored]
 
 ## Next Step
-[Specific and actionable: what ftm-resume does first, what the user needs to respond to,
-what research runs next. Must be specific enough to resume without "where were we?"]
+Phase 2, Turn 6. The user was presented with service mesh options (Istio vs Linkerd)
+in Turn 5 and needs to respond. After their response, research should focus on
+deployment strategy (Kubernetes vs ECS) as this is the last major architecture
+decision before the brainstorm can move to Phase 3.
+
+Research agents for next turn should query:
+- Web Researcher: "[chosen service mesh] production gotchas [stack]"
+- GitHub Explorer: "[chosen service mesh] example configurations"
+- Competitive Analyst: "companies using [chosen mesh] at [user's scale]"
 
 ## Artifacts
-[Absolute path for each artifact, or "none on disk"]
+- ~/.claude/plans/ — no plan generated yet (still in Phase 2)
+- No worktrees active (brainstorm doesn't use worktrees)
+- Research findings accumulated in conversation only (not saved to disk)
 ```
 
-**Rules:**
-- `git_commit`: run `git rev-parse --short HEAD`. `git_branch`: run `git branch --show-current`.
-- Include actual content — real URLs, real decisions, real findings. No placeholders.
-- Omit raw agent prompts (the skill files have them) and full file contents (reference by path).
+**Formatting rules:**
+- Use the YAML frontmatter exactly as shown — ftm-resume parses it
+- The `phase_detail` field should be a human-readable one-liner about exactly where in the phase the user stopped
+- `git_commit` should be the current HEAD commit hash (run `git rev-parse --short HEAD`)
+- `git_branch` should be the current branch (run `git branch --show-current`)
+- The "Next Step" section is the most important — it must be specific enough that a fresh conversation can pick up without asking "where were we?"
+- Include actual content, not placeholders — paste real findings, real decisions, real URLs
 
-See `references/protocols/VALIDATION.md` for the full pre-write and post-write validation checklist.
+**What to omit:**
+- Raw agent prompts (the skill files already have these)
+- Full file contents that were read during the session (reference by path instead)
+- Conversation pleasantries or back-and-forth that doesn't carry information
 
 ## Step 5: Confirm to User
 
-After saving, present a brief confirmation:
+After saving, present a confirmation:
 
 ```
 Session saved to ~/.claude/ftm-state/STATE.md
 
 Captured:
-- Skill: <skill-name>
-- Phase: <phase and detail>
-- <skill-specific counts: decisions, tasks, rounds, findings, etc.>
-- Artifacts: <count and locations, or "none on disk">
+- Skill: ftm-brainstorm
+- Phase: 2 (Research + Challenge Loop, Turn 5)
+- Decisions locked: 4 (architecture, database, auth, v1 scope)
+- Open questions: 2 (service mesh, deployment)
+- Research sprints completed: 2 (landscape + constraint-scoped)
+- Challenge turns completed: 5
+- Artifacts: none on disk (research in state file)
 
 To resume in a new conversation:
 /ftm-resume
 ```
 
-Tailor the counts to the skill: brainstorm shows decisions + turns, executor shows task completion, debug shows investigation agents, council shows round count + consensus status, audit shows layer completion + finding counts.
+Adjust the "Captured" summary to match the actual skill. For ftm-executor, show task completion counts. For ftm-debug, show which investigation agents completed. For ftm-council, show round count and consensus status. For ftm-audit, show layer completion and finding counts.
 
 ## Edge Cases
 
-**Multiple skills active:** Ask which to save. If "both," save most recent to STATE.md and the other to STATE-[skill].md.
+### Multiple ftm skills in one conversation
+If the user ran brainstorm and then executor in the same conversation, ask which one to save. If they say "both," save the most recent one to STATE.md and the other to STATE-[skill].md in the same directory.
 
-**Very early session:** Save what exists — even a Phase 0 scan is worth capturing. "Next Step" should say the user needs to answer the first intake question.
+### Very early in a session
+If the user pauses in Phase 0 or the first step of a skill, there may be almost nothing to capture. That's fine — save what exists. Even a Phase 0 repo scan result saves the user from re-scanning.
 
-**State file already exists:** Overwrite it. Prior state was either consumed or abandoned. FTM-resume archives before loading if the user needs the old one.
+### State file already exists
+Overwrite it. The previous state was either already resumed (and thus consumed) or abandoned. If the user wants to keep the old state, ftm-resume archives it before loading.
 
-**No git repo:** Omit `git_branch` and `git_commit` fields. Record `project_dir` only.
+### No git repo
+Skip the git_branch and git_commit fields. Note `project_dir` only.
 
-**Skill invoked, no user interaction yet:** Save what exists (Phase 0 scan, initial question). "Next Step" notes that the user hasn't answered yet.
+### Skill invoked but no user interaction yet
+If the skill was just invoked (e.g., the user said "/ftm-brainstorm" and Claude responded with the first question, but the user hasn't answered yet), save what exists — the Phase 0 scan and the initial question. The "Next Step" should note that the user needs to answer the first intake question.
 
-**Large state:** Do not truncate. Some sessions produce massive state files. Completeness is required for reliable restoration.
+### Large state
+Some sessions accumulate substantial state — 8+ brainstorm turns with full research results, or an executor session with 20+ tasks. Don't truncate. The state file can be large. FTM-resume needs all of it to reconstruct properly. If a single research finding has 5 URLs and detailed analysis, include all of it.
 
 ## Requirements