feed-the-machine 1.1.0 → 1.3.0

package/ftm-config/SKILL.md

@@ -308,3 +308,38 @@ If the YAML cannot be parsed, the skill will back up the broken file as `~/.clau
 
 ### Changes not taking effect
 Other ftm skills read the config at startup. If a ftm skill is already running, it will use the config that was active when it started. Changes apply to the next invocation.
+
+## Requirements
+
+- config: `~/.claude/ftm-config.yml` | optional | main config file (created with defaults if missing)
+
+## Risk
+
+- level: low_write
+- scope: reads and writes ~/.claude/ftm-config.yml only; backs up malformed config to ftm-config.yml.bak before overwriting; no project files touched
+- rollback: restore from ~/.claude/ftm-config.yml.bak or delete the file to reset to defaults on next invocation
+
+## Approval Gates
+
+- trigger: reset command issued | action: show current config and ask "Proceed?" before restoring defaults
+- trigger: invalid model name or profile name provided | action: reject with clear error showing valid options, do not write
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: ftm-config.yml missing | action: create file with default balanced profile and all defaults
+- condition: ftm-config.yml malformed YAML | action: back up as ftm-config.yml.bak, create fresh default config
+- condition: invalid model or profile value provided | action: reject and show valid options without writing
+
+## Capabilities
+
+- env: none required
+
+## Event Payloads
+
+### task_completed
+- skill: string — "ftm-config"
+- action: string — "display" | "set_profile" | "set_value" | "reset" | "show_profiles" | "show_skills"
+- changed_key: string | null — dotted path of changed setting
+- old_value: string | null — value before change
+- new_value: string | null — value after change

package/ftm-council/SKILL.md

@@ -130,3 +130,59 @@ After completing, update the blackboard:
 2. Write an experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` capturing decision domain, verdict, round reached, dissent summary, and whether the verdict held up
 3. Update `~/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
 4. Emit `task_completed` event
+
+## Requirements
+
+- tool: `codex` | required | Codex CLI for independent peer investigation
+- tool: `gemini` | required | Gemini CLI for independent peer investigation
+- reference: `references/protocols/PREREQUISITES.md` | required | availability check, fallback logic, timeout config
+- reference: `references/protocols/STEP-0-FRAMING.md` | required | problem framing format
+- reference: `references/prompts/CLAUDE-INVESTIGATION.md` | required | Claude investigation prompt template
+- reference: `references/prompts/CODEX-INVESTIGATION.md` | required | Codex investigation prompt template
+- reference: `references/prompts/GEMINI-INVESTIGATION.md` | required | Gemini investigation prompt template
+- reference: `references/prompts/REBUTTAL-TEMPLATE.md` | required | rebuttal round prompt template
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state
+
+## Risk
+
+- level: read_only
+- scope: reads codebase for independent investigation; does not modify source files; writes blackboard experience after verdict
+- rollback: no source mutations; blackboard write can be reverted by editing JSON files
+
+## Approval Gates
+
+- trigger: council prompt framed in Step 0 | action: show framed prompt to user and wait for confirmation before dispatching to council
+- trigger: 2-of-3 majority reached | action: present verdict summary to user and ask if they want to proceed or dig into dissent
+- trigger: auto-invocation by ftm-executor (INTENT.md conflict) | action: skip user framing confirmation, run immediately and return structured COUNCIL VERDICT to caller
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: codex CLI not found | action: report missing dependency with install instructions and stop (do not run degraded council)
+- condition: gemini CLI not found | action: report missing dependency with install instructions and stop
+- condition: no majority after 5 rounds | action: synthesize final positions, highlight core tension, present 2-3 concrete options for user decision
+- condition: model times out during a round | action: note timeout for that model, continue round with remaining models' responses
+
+## Capabilities
+
+- cli: `codex` | required | OpenAI Codex CLI peer reviewer
+- cli: `gemini` | required | Google Gemini CLI peer reviewer
+- env: `OPENAI_API_KEY` | required | for Codex CLI authentication
+- env: `GEMINI_API_KEY` | required | for Gemini CLI authentication
+
+## Event Payloads
+
+### review_complete
+- skill: string — "ftm-council"
+- verdict: string — "update_intent" | "revert_fix" | "option_a" | "option_b" | custom decision
+- round: number — round in which majority was reached (1-5, or 5+ for synthesis)
+- agreed_by: string[] — which models agreed on the verdict
+- dissent: string | null — summary of dissenting position
+- reasoning: string — why the majority won
+
+### task_completed
+- skill: string — "ftm-council"
+- decision_domain: string — topic the council deliberated on
+- verdict: string — final decision
+- round: number — rounds taken to reach verdict
+- duration_ms: number — total deliberation time

package/ftm-dashboard/SKILL.md

@@ -118,6 +118,40 @@ Average plan modifications: 1.2 per plan
 - Keep output concise — one screen max
 - If data sources are empty (fresh install), show: "No data yet. Use FTM for a few sessions and check back."
 
+## Requirements
+
+- reference: `~/.claude/ftm-state/events.log` | optional | JSONL event log for skill invocation tracking
+- reference: `~/.claude/ftm-state/blackboard/context.json` | required | current session metadata
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | optional | experience inventory and counts
+- reference: `~/.claude/ftm-state/blackboard/patterns.json` | optional | pattern health for weekly stats
+- reference: `~/.ftm/playbooks/` | optional | playbook use counts and stats
+
+## Risk
+
+- level: read_only
+- scope: reads event log and blackboard state only; does not modify any files
+- rollback: no mutations to reverse
+
+## Approval Gates
+
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: events.log missing or empty | action: show "No session events recorded yet" for relevant sections
+- condition: blackboard context.json missing | action: show "No session data available" and suggest using FTM skills first
+- condition: experiences/index.json missing | action: skip experience stats sections
+- condition: playbooks directory missing | action: show 0 for all playbook stats
+
+## Capabilities
+
+- env: none required
+
+## Event Payloads
+
+### (none)
+ftm-dashboard is read-only and does not emit events directly. It listens to task_completed for session tracking only.
+
 ## Events
 
 ### Listens To

package/ftm-debug/SKILL.md

@@ -144,3 +144,87 @@ After completing, update the blackboard. Read `references/protocols/BLACKBOARD.m
 Before dispatching agents, read `~/.claude/ftm-config.yml`:
 - Use the `planning` model from the active profile for all investigation agents
 - If config missing, use session default
+
+## Requirements
+
+- config: `~/.claude/ftm-config.yml` | optional | model profiles for investigation agents
+- reference: `references/protocols/BLACKBOARD.md` | required | blackboard read/write protocol
+- reference: `references/protocols/EDGE-CASES.md` | required | anti-patterns and fallback handling
+- reference: `references/phases/PHASE-0-INTAKE.md` | required | intake steps and Explore agent prompt
+- reference: `references/phases/PHASE-1-TRIAGE.md` | required | agent selection guide and worktree strategy
+- reference: `references/phases/PHASE-2-WAR-ROOM-AGENTS.md` | required | all four agent prompts
+- reference: `references/phases/PHASE-3-TO-6-EXECUTION.md` | required | synthesis, solver, reviewer prompts
+- tool: `git` | required | worktree creation, diff inspection, commit history
+- reference: `~/.claude/ftm-state/blackboard/context.json` | optional | session state
+- reference: `~/.claude/ftm-state/blackboard/experiences/index.json` | optional | past bug fixes and known issues
+- reference: `~/.claude/ftm-state/blackboard/patterns.json` | optional | recurring failure patterns
+
+## Risk
+
+- level: medium_write
+- scope: creates git worktrees for investigation and fix branches; modifies source files in Solver agent worktree; merges fix after Reviewer approval
+- rollback: git worktree remove + git branch -D for debug/* worktrees; all fix changes isolated until user confirms merge
+
+## Approval Gates
+
+- trigger: investigation plan formulated in Phase 0 | action: present plan to user and proceed unless user objects
+- trigger: Solver produces fix | action: Reviewer agent must independently verify before presenting to user (hard gate — cannot skip)
+- trigger: Reviewer APPROVED | action: present root cause + changes + evidence to user, wait for user confirmation before merging
+- trigger: Solver NEEDS REWORK after 3 attempts | action: escalate to user with full context, wait for direction
+- complexity_routing: micro → auto | small → auto | medium → plan_first | large → plan_first | xl → always_ask
+
+## Fallbacks
+
+- condition: Instrumenter agent fails or produces no useful output | action: skip instrumentation worktree, proceed with remaining agents
+- condition: Reproducer cannot create a minimal failing test | action: note as "reproduction failed", proceed with hypothesis-only approach
+- condition: Researcher finds no relevant issues or docs | action: proceed with instrumentation and hypothesis findings only
+- condition: fix still failing after 3 Solver iterations | action: escalate to user with all hypotheses tested and evidence gathered
+- condition: project has no test suite | action: Reviewer uses build check + diff review + live runtime verification instead of test runner
+
+## Capabilities
+
+- cli: `git` | required | worktree isolation for investigation agents
+- mcp: `sequential-thinking` | optional | complex multi-hypothesis analysis
+- mcp: `playwright` | optional | visual bug verification in Reviewer phase
+- mcp: `WebSearch` | optional | Researcher agent for GitHub issues and Stack Overflow
+- mcp: `WebFetch` | optional | Researcher agent for docs and changelogs
+
+## Event Payloads
+
+### bug_fixed
+- skill: string — "ftm-debug"
+- root_cause: string — one-sentence root cause description
+- fix_approach: string — description of the fix applied
+- worktree: string — path to fix worktree
+- iterations: number — number of solver-reviewer cycles needed
+- duration_ms: number — total war room duration
+
+### issue_found
+- skill: string — "ftm-debug"
+- phase: string — "phase1" | "phase2"
+- agent: string — "instrumenter" | "researcher" | "reproducer" | "hypothesizer"
+- finding: string — description of the specific issue found
+- confidence: string — high | medium | low
+
+### test_passed
+- skill: string — "ftm-debug"
+- scope: string — "reproduction" | "full_suite"
+- worktree: string — worktree path where tests ran
+
+### test_failed
+- skill: string — "ftm-debug"
+- scope: string — "reproduction" | "full_suite"
+- worktree: string — worktree path
+- error_summary: string — brief failure description
+
+### error_encountered
+- skill: string — "ftm-debug"
+- phase: string — war room phase where error occurred
+- agent: string | null — agent that encountered the error
+- error: string — error description
+
+### task_completed
+- skill: string — "ftm-debug"
+- outcome: string — "fixed" | "escalated" | "unresolved"
+- root_cause: string — root cause if found
+- duration_ms: number — total session duration

package/ftm-diagram/SKILL.md

@@ -231,3 +231,47 @@ Read and display `ARCHITECTURE.mmd` + list available module diagrams.
 ### Auto-Invocation by ftm-executor
 
 This skill's format is used by ftm-executor's documentation pipeline. After every commit during plan execution, agents update INTENT.md (or DIAGRAM.mmd) entries following this skill's templates. The updates are automatic and don't require explicit skill invocation — agents reference the format directly.
+
+## Requirements
+
+- reference: `.ftm-map/map.db` | optional | SQLite knowledge graph for accurate diagram generation (graph-powered mode)
+- tool: `ftm-map/scripts/.venv/bin/python3` | optional | Python runtime for graph-powered views.py
+- reference: `package.json` | optional | project structure detection for bootstrap
+- reference: `tsconfig.json` | optional | TypeScript project structure detection
+
+## Risk
+
+- level: low_write
+- scope: writes .mmd diagram files to project directories; only creates or modifies ARCHITECTURE.mmd and per-module DIAGRAM.mmd files; does not touch source code
+- rollback: git checkout on modified .mmd files; delete newly created .mmd files
+
+## Approval Gates
+
+- trigger: bootstrap mode on large codebase (50+ modules) | action: report what was found and what will be created before writing, proceed unless user objects
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: .ftm-map/map.db not found | action: fall back to standard import-grep analysis for diagram generation
+- condition: Python venv not set up | action: fall back to standard analysis, log "Graph-powered mode unavailable — run ftm-map to enable"
+- condition: no src/ or identifiable source root | action: ask user for source root before bootstrapping
+
+## Capabilities
+
+- cli: `ftm-map/scripts/.venv/bin/python3` | optional | graph-powered diagram generation
+- mcp: `git` | optional | detect changed files for incremental updates
+
+## Event Payloads
+
+### documentation_updated
+- skill: string — "ftm-diagram"
+- files_written: string[] — absolute paths to .mmd files created or modified
+- modules_added: number — new module nodes added to ARCHITECTURE.mmd
+- functions_added: number — new function nodes added across module DIAGRAMs
+- edges_added: number — new dependency edges added
+
+### task_completed
+- skill: string — "ftm-diagram"
+- mode: string — "bootstrap" | "incremental"
+- files_count: number — total .mmd files written
+- duration_ms: number — total diagram sync duration

package/ftm-executor/SKILL.md

@@ -655,3 +655,100 @@ After completing, update the blackboard:
 2. Write an experience file to `/Users/kioja.kudumu/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` capturing task_type, agent team used, wave count, audit outcomes, and lessons learned
 3. Update `/Users/kioja.kudumu/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
 4. Emit `task_completed` event
+
+## Requirements
+
+- tool: `git` | required | worktree creation, branch management, commit operations
+- config: `~/.claude/ftm-config.yml` | optional | model profiles, max_parallel_agents, auto_audit, progress_tracking
+- reference: `~/.claude/plans/` | optional | plan documents for execution
+- tool: `node` | optional | project setup commands in worktrees
+- reference: `~/.claude/skills/ftm-executor/references/STYLE-TEMPLATE.md` | optional | STYLE.md bootstrap template
+
+## Risk
+
+- level: high_write
+- scope: creates git worktrees and branches, modifies source files across multiple tasks, runs tests and builds, optionally pushes branches or creates PRs
+- rollback: git worktree remove + git branch -D for each worktree; all changes isolated to plan-exec/* branches until explicitly merged
+
+## Approval Gates
+
+- trigger: no plan document provided | action: generate plan and wait for explicit user approval before any code is written
+- trigger: plan_checker returns FAIL | action: present blockers and ask user to fix or override before proceeding
+- trigger: plan_checker returns WARN | action: show warnings to user, proceed unless they object
+- trigger: wave complete and all agents done | action: auto-invoke ftm-codex-gate (no user gate needed for this step)
+- trigger: final phase 6 verification passes | action: present 4 branch finishing options and wait for explicit user choice
+- trigger: codex gate FAIL after 2 fix attempts | action: report to user and wait for input before continuing
+- complexity_routing: micro → auto | small → auto | medium → plan_first | large → plan_first | xl → always_ask
+
+## Fallbacks
+
+- condition: ftm-browse not installed at $HOME/.claude/skills/ftm-browse/bin/ftm-browse | action: skip visual smoke test checks, log "Visual smoke test skipped — ftm-browse not installed"
+- condition: ftm-retro skill not available | action: skip retrospective phase, note in output and proceed to branch finishing
+- condition: codex CLI not found | action: skip codex gate, log "Codex gate skipped — codex not installed", proceed to next wave
+- condition: no package.json in project | action: skip npm install in worktree setup; skip knip-based audit layers
+- condition: project has no test suite | action: skip test verification gates, rely on diff review and build checks
+- condition: agent fails or gets stuck | action: read agent output, fix directly or respawn with more context
+
+## Capabilities
+
+- cli: `git` | required | worktree management and version control
+- cli: `node` | optional | project dependency installation
+- mcp: `sequential-thinking` | optional | complex dependency analysis and plan validation
+- env: none required directly (agents inherit from session)
+
+## Event Payloads
+
+### task_received
+- skill: string — "ftm-executor"
+- task_description: string — description of the task being queued
+- plan_path: string — absolute path to plan document
+
+### plan_generated
+- skill: string — "ftm-executor"
+- plan_path: string — absolute path to saved plan file
+- task_count: number — total tasks in the plan
+- wave_count: number — number of parallel execution waves
+
+### plan_approved
+- skill: string — "ftm-executor"
+- plan_path: string — absolute path to approved plan
+- approved_steps: number[] — step numbers approved for execution
+
+### code_changed
+- skill: string — "ftm-executor"
+- worktree: string — path to the worktree where files changed
+- files: string[] — list of modified file paths
+- agent: string — agent type that made the changes
+
+### code_committed
+- skill: string — "ftm-executor"
+- worktree: string — path to worktree
+- commit_hash: string — short commit hash
+- message: string — commit message
+- task_number: number — plan task number this commit belongs to
+
+### test_passed
+- skill: string — "ftm-executor"
+- scope: string — "task" | "full_suite"
+- task_number: number | null — task number if scoped to task
+- worktree: string — worktree path
+
+### test_failed
+- skill: string — "ftm-executor"
+- scope: string — "task" | "full_suite"
+- task_number: number | null — task number if scoped
+- worktree: string — worktree path
+- error_summary: string — brief description of failure
+
+### task_completed
+- skill: string — "ftm-executor"
+- task_number: number — completed task number
+- audit_result: string — "pass" | "pass_with_fixes" | "fail" | "skipped"
+- auto_fixed_count: number — issues auto-remediated by ftm-audit
+- duration_ms: number — task execution time
+
+### error_encountered
+- skill: string — "ftm-executor"
+- phase: string — execution phase where error occurred
+- task_number: number | null — associated task if applicable
+- error: string — error description

package/ftm-git/SKILL.md

@@ -193,3 +193,63 @@ After completing, update the blackboard:
    - Which patterns matched (to improve future scans)
 3. Update `experiences/index.json` with the new entry
 4. Emit `secrets_clear` or `secrets_remediated` or `secrets_blocked`
+
+## Requirements
+
+- tool: `git` | required | staged file inspection, commit history scanning
+- reference: `references/patterns/SECRET-PATTERNS.md` | required | Tier 1/2 patterns, severity table, ignore list
+- reference: `references/protocols/REMEDIATION.md` | required | remediation protocol, env var patterns, report formats
+- reference: `~/.claude/skills/ftm-git/scripts/pre-commit-secrets.sh` | required | pre-commit hook script for installation
+- reference: `~/.claude/skills/ftm-git/hooks/post-commit-experience.sh` | optional | post-commit experience recorder hook
+
+## Risk
+
+- level: medium_write
+- scope: modifies source files to replace hardcoded secrets with env var references; creates/updates .env and .env.example files; installs git hooks in .git/hooks/; re-stages files after remediation
+- rollback: git checkout on refactored source files; manually remove added .env and .gitignore entries; remove hook from .git/hooks/pre-commit
+
+## Approval Gates
+
+- trigger: CRITICAL or HIGH severity secret found | action: BLOCK commit/push immediately, announce "BLOCKED — N secret(s) found", then attempt auto-remediation
+- trigger: auto-remediation proposed for a finding | action: show proposed change (file, variable name, env var name) before applying
+- trigger: re-scan after remediation still finds secrets | action: report remaining findings to user, do not proceed with commit
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: .env file does not exist | action: create .env and .env.example and add .env to .gitignore before extracting secrets
+- condition: .gitignore does not exist | action: create .gitignore with .env entry before remediation
+- condition: language detection fails for env var pattern | action: extract secret to .env but flag source file refactoring as MANUAL_INTERVENTION_NEEDED
+- condition: pre-commit hook already exists | action: append ftm-git scan to existing hook rather than overwriting
+
+## Capabilities
+
+- cli: `git` | required | staged file listing, diff inspection, commit history traversal
+
+## Event Payloads
+
+### secrets_found
+- skill: string — "ftm-git"
+- findings_count: number — total secrets detected
+- critical_count: number — CRITICAL severity findings
+- high_count: number — HIGH severity findings
+- files_affected: string[] — files containing secrets
+- blocked: boolean — whether commit/push was halted
+
+### secrets_clear
+- skill: string — "ftm-git"
+- files_scanned: number — total files checked
+- scope: string — "staged" | "working_tree" | "history" | "pre-push"
+
+### secrets_remediated
+- skill: string — "ftm-git"
+- findings_remediated: number — secrets successfully extracted
+- env_vars_added: string[] — environment variable names created
+- files_refactored: string[] — source files updated to use env vars
+- manual_needed: number — findings requiring manual intervention
+
+### task_completed
+- skill: string — "ftm-git"
+- outcome: string — "clear" | "remediated" | "blocked"
+- files_scanned: number — total files scanned
+- duration_ms: number — total scan and remediation time

package/ftm-inbox/backend/adapters/_retry.py

@@ -0,0 +1,64 @@
+"""
+Exponential-backoff retry decorator for HTTP adapter calls.
+
+Usage:
+    @retry(max_attempts=3, base_delay=1.0)
+    def poll(self) -> list[dict]:
+        ...
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import time
+from typing import Callable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+F = TypeVar("F", bound=Callable)
+
+
+def retry(
+    max_attempts: int = 3,
+    base_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+) -> Callable[[F], F]:
+    """
+    Decorator: retry on exception with exponential backoff.
+
+    Args:
+        max_attempts: Total number of attempts (including the first).
+        base_delay: Initial sleep duration in seconds.
+        backoff_factor: Multiplier applied to delay after each failure.
+        exceptions: Exception types that trigger a retry.
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            delay = base_delay
+            last_exc: Exception | None = None
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as exc:
+                    last_exc = exc
+                    if attempt == max_attempts:
+                        break
+                    logger.warning(
+                        "%s failed (attempt %d/%d): %s — retrying in %.1fs",
+                        func.__qualname__,
+                        attempt,
+                        max_attempts,
+                        exc,
+                        delay,
+                    )
+                    time.sleep(delay)
+                    delay *= backoff_factor
+            raise last_exc  # type: ignore[misc]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator