feed-the-machine 1.0.0 → 1.2.0

package/ftm-dashboard/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: ftm-dashboard
+description: Session and weekly analytics dashboard for the FTM skill ecosystem. Reads events.log and blackboard state to show skills invoked, plans presented, approval rates, experiences recorded, and patterns promoted. Use when user says "dashboard", "analytics", "stats", "ftm-dashboard", "show session stats", or "how's the system doing".
+---
+
+# FTM Dashboard
+
+Provides analytics about FTM system usage by reading the event log and blackboard state.
+
+## Commands
+
+### `/ftm-dashboard` (default: current session)
+
+Shows stats for the current session:
+
+```
+━━━━━━━━━━━ FTM Session Dashboard ━━━━━━━━━━━
+
+Session started: [timestamp]
+Duration: [hours:minutes]
+
+Skills Invoked:
+  ftm-mind      ████████████  12
+  ftm-debug     ████          4
+  ftm-executor  ██            2
+  ftm-brainstorm █            1
+
+Plans:
+  Presented: 5
+  Approved: 4 (80%)
+  Modified before approval: 2
+  Saved as playbook: 1
+
+Experiences Recorded:
+  Total: 8
+  From LLM: 5 (rich)
+  From git hook: 3 (minimal)
+
+Patterns:
+  Active: 12
+  Reinforced this session: 3
+  Aging (>30 days): 2
+  Decayed: 0
+
+Context Budget:
+  Orient mode: Full (conversation ~25% used)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### `/ftm-dashboard week`
+
+Shows aggregate stats for the past 7 days:
+
+```
+━━━━━━━━━━ FTM Weekly Dashboard ━━━━━━━━━━━━━
+
+Period: [date] — [date]
+
+Tasks by Complexity:
+  Micro:  ██████████████████  18
+  Small:  ████████████        12
+  Medium: ██████              6
+  Large:  ██                  2
+
+Top Skills:
+  1. ftm-mind (45 invocations)
+  2. ftm-executor (12 invocations)
+  3. ftm-debug (8 invocations)
+  4. ftm-brainstorm (6 invocations)
+  5. ftm-audit (4 invocations)
+
+Playbooks:
+  Created: 2
+  Reused: 3
+  Parameterized: 0
+
+Learning:
+  Experiences recorded: 38
+  Patterns promoted: 1
+  Patterns decayed: 0
+  Sizing corrections: 0
+
+Approval Rate: 85% (34/40 plans approved on first presentation)
+Average plan modifications: 1.2 per plan
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Data Sources
+
+### events.log (`~/.claude/ftm-state/events.log`)
+- JSONL format, one entry per line
+- Each entry has: timestamp, event_type, tool_name, session_id, skill_context
+- Filter by session_id for current session, by date range for weekly
+
+### Blackboard State
+- `~/.claude/ftm-state/blackboard/context.json` — current session metadata
+- `~/.claude/ftm-state/blackboard/experiences/index.json` — experience counts and types
+- `~/.claude/ftm-state/blackboard/patterns.json` — pattern health
+
+### Playbooks (`~/.ftm/playbooks/`)
+- Count `.yml` files for total playbooks
+- Check `use_count` field for reuse stats
+- Check `parameterized` field for parameterization stats
+
+## Implementation
+
+1. Read the relevant data sources
+2. Compute aggregates
+3. Render as markdown tables with ASCII bar charts
+4. Output directly — no approval gates needed (read-only operation)
+
+## Rendering
+
+- Use Unicode block characters for bar charts: █ ▓ ░
+- Tables in markdown format for terminal rendering
+- 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
+- `task_completed` — for session stats tracking
+
+### Blackboard Read
+- `context.json` — session metadata
+- `experiences/index.json` — experience inventory
+- `patterns.json` — pattern health

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