feed-the-machine 1.3.0 → 1.3.1

package/ftm-audit/SKILL.md

@@ -25,125 +25,451 @@ Before starting, load context from the blackboard:
 
 If index.json is empty or no matches found, proceed normally without experience-informed shortcuts.
 
-## Execution Protocol
+# FTM Audit — Wiring Verification
 
-1. Phase 0 — detect project patterns (framework, router, state, API layer)
-2. Layer 1 — knip static analysis
-3. Layer 2 — adversarial audit, calibrated to detected patterns
-4. Combine findings, deduplicate
-5. Layer 3 — auto-fix each finding
-6. Re-verify (re-run Layers 1+2)
-7. Phase 3 — runtime wiring via ftm-browse (if prerequisites met)
-8. Produce final changelog report
+Three-layer verification system: knip for import-graph dead code, LLM adversarial trace for semantic wiring, and auto-fix with changelog.
+
+## Why This Exists
 
+Code that compiles but isn't wired into the running application is worse than code that doesn't compile — it silently wastes space, confuses readers, and creates false confidence. This skill catches unwired code through two complementary lenses and fixes it automatically.
 
 ## Phase 0: Detect Project Patterns
 
-Scan the project to calibrate which wiring dimensions apply. Read `references/protocols/PROJECT-PATTERNS.md` for the full detection table and dimension activation matrix.
+Before running any checks, scan the project to calibrate which wiring dimensions apply and how to check them. This takes seconds and prevents false positives from applying React patterns to a Vue project (or Next.js App Router patterns to a Pages Router project).
+
+**Read `package.json` and check for:**
+
+| Signal | Detection | Impact on Audit |
+|---|---|---|
+| **Framework** | `react`, `next`, `vue`, `svelte`, `angular` in deps | Determines which dimensions are relevant |
+| **Router** | `react-router-dom`, `@tanstack/react-router`, `next` (file-based), `vue-router` | Changes how Dimension 3 (Route Registration) works |
+| **State management** | `zustand`, `@reduxjs/toolkit`, `pinia`, `jotai`, `recoil` | Changes how Dimension 4 (Store Consumption) works |
+| **API layer** | `@tanstack/react-query`, `swr`, `trpc`, `@apollo/client`, `axios` | Changes how Dimension 5 (API Invocation) works |
+| **Build tool** | `vite`, `next`, `webpack`, `turbopack` | Affects knip entry point detection |
+
+**Quick file checks:**
+
+- `next.config.*` exists → Next.js project. Check for `app/` directory (App Router) vs `pages/` (Pages Router). This completely changes route checking.
+- `vite.config.*` exists → Vite project. Entry point is usually `index.html` → `src/main.tsx`.
+- `app/layout.tsx` or `app/page.tsx` exists → Next.js App Router. Routes are file-based (`app/dashboard/page.tsx` = `/dashboard`). No router config file to check — Dimension 3 checks directory structure instead.
+- `src/router.*` or `src/routes.*` exists → Explicit router config. Dimension 3 checks this file.
 
-**Quick scan:** `package.json` deps + `next.config.*`, `vite.config.*`, `app/` directory, `pages/` directory.
+**Framework-specific dimension adjustments:**
+
+| Framework | D1 (Import) | D2 (JSX) | D3 (Routes) | D4 (Store) | D5 (API) |
+|---|---|---|---|---|---|
+| React + react-router | Standard | Standard | Check router config file | Standard | Standard |
+| Next.js App Router | Check `app/` tree | Standard | File-based: `page.tsx` in directory = route | Standard | Check for Server Actions too |
+| Next.js Pages Router | Check `pages/` tree | Standard | File-based: `pages/foo.tsx` = `/foo` | Standard | Check `getServerSideProps`/`getStaticProps` |
+| Remix | Check `app/routes/` | Standard | File-based + `remix.config` | Standard | Check `loader`/`action` exports |
+| Vue + vue-router | Standard | `<template>` instead of JSX | Check router config | Pinia: `defineStore` | Standard |
+| Svelte | Standard | Svelte components | SvelteKit: file-based routes | Svelte stores | Standard |
+| No framework (Node.js) | Standard | Skip D2 | Skip D3 | Skip D4 | Standard |
+
+**Output:** Store the detected pattern as context for all subsequent layers. Don't include it in the report unless something unusual was detected.
 
-**Output:** Store detected context for all subsequent layers.
 ```
 Project detected: React 18 + Vite + react-router v6 + Zustand + TanStack Query
 Dimensions active: D1 ✓  D2 ✓  D3 (router config)  D4 (Zustand)  D5 (TanStack Query)
 ```
 
----
-
 ## Layer 1: Static Analysis (knip)
 
-Detects unused files, exports, dependencies, and unreachable modules from the import graph.
+**What it does:** Runs [knip](https://knip.dev/) against the target project to detect unused files, exports, dependencies, and unreachable modules from the import graph.
+
+**Prerequisites check:**
+1. Check if the project has a `package.json` — if not, skip Layer 1 entirely and note "No package.json found — knip layer skipped" in the report
+2. Check if knip is installed (`node_modules/.bin/knip`) — if not, use `npx knip` (no install needed)
 
-**Prerequisites:** Requires `package.json` — skip and note if absent. Use `npx knip` if not locally installed.
+**Execution:**
 
+Run knip with JSON output for machine parsing:
 ```bash
 npx knip --reporter json 2>/dev/null
 ```
 
-**Output:** `files` (unused files) + `issues` array (`type`/`filePath`/`symbol`). Issue types: `exports`, `types`, `duplicates`, `dependencies`, `devDependencies`, `unlisted`, `binaries`, `unresolved`.
+If the project has a `knip.json` or `knip.config.ts`, knip uses it automatically. If not, knip auto-detects entry points from the framework (Vite, Next.js, React Router, etc.).
 
-Fix actions by finding type: see `references/strategies/AUTO-FIX-STRATEGIES.md`. Helper script: `scripts/run-knip.sh`.
+**Parsing the JSON output:**
 
----
+Knip's JSON output contains these categories:
+- `files` — completely unused files (not imported by anything)
+- `issues` — array of issues, each with:
+  - `type`: "exports", "types", "duplicates", "dependencies", "devDependencies", "optionalPeerDependencies", "unlisted", "binaries", "unresolved"
+  - `filePath`: the file containing the issue
+  - `symbol`: the unused export name (for export issues)
+  - `parentSymbol`: the re-exporting module (for re-export chains)
+
+**Categorize findings:**
+
+| Finding Type | Fix Action |
+|---|---|
+| Unused file | Remove file OR add import from appropriate parent |
+| Unused export | Remove export OR wire it into consumer |
+| Unused dependency | Remove from package.json OR add usage |
+| Unlisted dependency | Add to package.json |
+| Unresolved import | Fix import path OR install missing package |
+
+**Output format for this layer:**
+```
+Layer 1 findings:
+- [UNUSED_FILE] src/components/OldWidget.tsx — not imported anywhere
+- [UNUSED_EXPORT] src/utils/helpers.ts:42 — export `formatDate` not used
+- [UNUSED_DEP] package.json — `lodash` listed but never imported
+- [UNLISTED_DEP] src/api/client.ts — imports `axios` but it's not in package.json
+```
+
+**Helper script:** `scripts/run-knip.sh` handles execution and returns structured JSON output.
 
 ## Layer 2: LLM Adversarial Audit
 
-**Mindset:** Prove code is dead, not confirm it works. Every new/modified export is guilty until you find a complete chain from entry point to it.
+**Mindset:** You are an adversary trying to PROVE code is dead. Not "confirm it works" — PROVE it's dead. Every new/modified export is guilty until proven innocent. You must find a complete chain from app entry point to the code in question, or it's flagged.
 
-**Scope:** `git diff HEAD~1` (or current task diff). For each new or modified export, check all five wiring dimensions.
+**Scope:** Analyze the current git diff (`git diff HEAD~1` or the diff from the current task's changes). For each new or modified export:
 
-### The 5 Wiring Dimensions
+**The 5 Wiring Dimensions:**
 
-Calibrate each dimension to the detected project pattern from Phase 0. Framework-specific method variations are in `references/protocols/PROJECT-PATTERNS.md`.
+For each export, check ALL five. A component might be imported but never rendered. A function might be exported but never called. Check the full chain.
 
-| Dim | Name | Trace | GUILTY if | Evidence required |
-|---|---|---|---|---|
-| D1 | Import Chain | `export` → `import` → ... → entry point | No importer found, OR importing file itself unimported | Full chain with file:line each link |
-| D2 | JSX Rendering | Component → parent JSX → root (React/Vue/Svelte only) | Imported but absent from every JSX return | Parent file:line where rendered, or "NOT FOUND" |
-| D3 | Route Registration | View → route config → router (method varies by router type) | View exists but no route points to it | Route config file:line, or "NOT FOUND" |
-| D4 | Store Consumption | Store field defined → selector/hook → component | Field written but never read | Consumer file:line, or "NOT FOUND" |
-| D5 | API Invocation | API function → call site → used in app | Exported but never called | Call site file:line, or "NOT FOUND" |
+### Dimension 1: Import Chain
+- Trace: `export` → `import` → ... → entry point (`main.tsx`, `App.tsx`, `index.ts`)
+- Method: Use `grep -r "import.*{.*ExportName.*}.*from" src/` or equivalent
+- **GUILTY if:** No file imports this export, OR the importing file itself is not imported (broken chain)
+- Evidence required: Full import chain with file:line for each link
 
-**D2 valid rendering:** lazy imports, conditional rendering (`{cond && <C/>}`), render props, HOCs — all count.
-**D3 nav link check:** A route with no nav link might be orphaned — flag as a warning.
-**Non-React projects:** Skip D2-D3. Focus on D1, D4 (adapted to state management pattern), D5.
+### Dimension 2: JSX Rendering (React/Vue/Svelte projects)
+- Trace: Component → rendered in parent JSX → ... → root component
+- Method: Search for `<ComponentName` in JSX/TSX files
+- **GUILTY if:** Component is imported but never appears in any JSX return statement
+- Evidence required: The parent component file:line where it's rendered (or "NOT FOUND")
+- Special cases: Lazy imports (`React.lazy(() => import(...))`), conditional rendering (`{condition && <Component/>}`), render props, HOCs — all count as valid rendering
 
-**Key principle:** File:line evidence for EVERY finding. Show the grep results and the missing chain link — "I think this might be unused" is not acceptable.
+### Dimension 3: Route Registration
+- Trace: View/page component → route config → router entry point
+- Method: Search router config files (react-router `createBrowserRouter`, Next.js pages/, etc.)
+- **GUILTY if:** A view/page component exists but no route points to it
+- Evidence required: Route config file:line showing the route, or "NOT FOUND"
+- Also check: Does the route have a navigation link (sidebar, navbar, menu)? A route with no nav link might be intentionally hidden (deep link) or might be orphaned
 
----
+### Dimension 4: Store Field Consumption (Redux/Zustand/Pinia/etc.)
+- Trace: Store field defined → selector/hook reads it → component uses the value
+- Method: Search for store selectors, useSelector calls, useStore hooks that reference the field
+- **GUILTY if:** Store field is written but never read anywhere
+- Evidence required: Component file:line where the field is consumed, or "NOT FOUND"
 
-## Layer 3: Auto-Fix and Changelog
+### Dimension 5: API Function Invocation
+- Trace: API function defined → called by hook/component/other function → used in app
+- Method: Search for function call sites
+- **GUILTY if:** API function is exported but never called anywhere
+- Evidence required: Call site file:line, or "NOT FOUND"
 
-**Purpose:** When Layers 1 or 2 find unwired code, generate fixes, apply them, re-verify, and produce a structured changelog.
+**Non-React projects:** Skip Dimensions 2-3 if no JSX framework detected. Focus on import chain (D1), data flow (D4 adapted to the project's state management), and function invocation (D5).
 
-For fix strategies by finding type and the conditions that block auto-fix, see `references/strategies/AUTO-FIX-STRATEGIES.md`.
+**Output format for this layer:**
+```
+Layer 2 findings:
+- [UNWIRED_COMPONENT] src/components/NewWidget.tsx — imported in Dashboard.tsx:5 but never rendered in JSX (Dimension 2 FAIL)
+- [ORPHAN_ROUTE] src/views/SettingsView.tsx — no route in router config points to this view (Dimension 3 FAIL)
+- [DEAD_STORE_FIELD] src/store/userSlice.ts:23 — `userPreferences` written in reducer but never read by any selector (Dimension 4 FAIL)
+- [UNCALLED_API] src/api/billing.ts:15 — `fetchInvoices()` exported but never called (Dimension 5 FAIL)
+```
 
-**Fix protocol for each finding:** Report → determine fix (check wiring contract for WHERE) → show proposed change → apply → re-verify → log to changelog.
+**Key principle:** File:line evidence for EVERY finding. "I think this might be unused" is NOT acceptable. Show the grep results, show the missing link in the chain.
+
+## Layer 3: Auto-Fix and Changelog
 
+**Purpose:** When Layer 1 or Layer 2 finds unwired code, this layer generates fixes, applies them, re-verifies, and produces a structured changelog.
+
+**Fix Strategies by Finding Type:**
+
+| Finding Type | Fix Strategy | Fallback |
+|---|---|---|
+| `UNUSED_FILE` | If the file was created by the current task, add import from the appropriate parent module. If it's pre-existing dead code, flag for removal. | Flag for manual review — might be intentionally standalone (config, script) |
+| `UNUSED_EXPORT` | If another module should consume it (check wiring contract), add the import. If truly unnecessary, remove the export keyword. | Flag for manual review |
+| `UNWIRED_COMPONENT` | Add `<ComponentName />` to the parent component's JSX return. Determine placement from component name and parent structure. | Flag — can't determine correct placement |
+| `ORPHAN_ROUTE` | Add route entry to the router config. Infer path from component name (e.g., `SettingsView` → `/settings`). Add nav link to sidebar/navbar if one exists. | Flag — route path ambiguous |
+| `DEAD_STORE_FIELD` | If a component should read this field (check wiring contract), add the selector/hook usage. If truly unused, remove the field. | Flag — store design decision needed |
+| `UNCALLED_API` | If a hook or component should call this (check wiring contract), add the invocation. If truly unused, remove the function. | Flag — API integration decision needed |
+| `UNUSED_DEP` | Remove from package.json `dependencies` or `devDependencies`. | Flag if it might be used in scripts, config files, or CLI |
+| `UNLISTED_DEP` | Run `npm install <package>` (or appropriate package manager command). | Flag if the import might be wrong |
+
+**Fix Protocol (for each finding):**
+
+1. **Report** — Log the finding with type, file:line, and evidence
+2. **Determine fix** — Match finding type to fix strategy above. Check wiring contract if available for guidance on WHERE to wire.
+3. **Show proposed fix** — Display the exact code change before applying:
+   ```
+   FIX: [UNWIRED_COMPONENT] NewWidget in Dashboard.tsx
+   Proposed: Add <NewWidget /> to Dashboard.tsx return JSX after line 45
+   ```
+4. **Apply fix** — Use Edit tool to make the change
+5. **Re-verify** — Run the specific check that found the issue:
+   - For knip findings: re-run `npx knip --reporter json`
+   - For adversarial findings: re-trace the specific wiring dimension
+6. **Log to changelog** — Record: timestamp, finding, fix applied, verification result
+
+**When auto-fix is NOT possible:**
+
+Some findings can't be auto-fixed safely:
+- Ambiguous placement (where exactly should the component render?)
+- Design decisions needed (should this store field exist at all?)
+- Cross-cutting changes (fix requires modifying 5+ files)
+- Test-only code (might be intentionally not wired into app)
+
+For these, flag them clearly:
 ```
-FIX: [UNWIRED_COMPONENT] NewWidget in Dashboard.tsx
-Proposed: Add <NewWidget /> to Dashboard.tsx return JSX after line 45
+MANUAL_INTERVENTION_NEEDED:
+- [ORPHAN_ROUTE] src/views/AdminPanel.tsx — cannot determine route path or nav placement
+  Suggested action: Add route to router config and nav link to sidebar
+  Reason auto-fix skipped: Multiple possible route paths (/admin, /settings/admin, /dashboard/admin)
 ```
 
-**When auto-fix is not possible:** Flag with `MANUAL_INTERVENTION_NEEDED`, a suggested action, and the reason skipped.
+**Re-verification after all fixes:**
 
-**Re-verification:** After all fixes, re-run Layers 1+2. Maximum 3 iterations to prevent loops.
+After all auto-fixes are applied:
+1. Re-run Layer 1 (knip) — confirm no new unused code introduced by fixes
+2. Re-run Layer 2 (adversarial audit on the fix diff) — confirm fixes actually wire correctly
+3. If re-verification finds new issues, fix those too (max 3 iterations to prevent loops)
 
----
+**Changelog format:**
+
+```
+### FTM Audit Changelog — [YYYY-MM-DD HH:MM]
+
+#### Findings
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 1 | UNWIRED_COMPONENT | src/components/Widget.tsx | Imported but not rendered in Dashboard |
+| 2 | ORPHAN_ROUTE | src/views/Settings.tsx | No route config entry |
+
+#### Fixes Applied
+| # | Finding | Fix | Verified |
+|---|---------|-----|----------|
+| 1 | UNWIRED_COMPONENT Widget | Added <Widget /> to Dashboard.tsx:47 | ✅ PASS |
+| 2 | ORPHAN_ROUTE Settings | Added /settings route to router.tsx:23 | ✅ PASS |
+
+#### Manual Intervention Required
+| # | Finding | Reason | Suggested Action |
+|---|---------|--------|-----------------|
+| (none) | | | |
+
+#### Final Status: PASS (0 remaining issues)
+```
 
 ## Wiring Contracts
 
-A wiring contract is a YAML block in a plan task declaring expected wiring for code produced by that task. See `references/protocols/WIRING-CONTRACTS.md` for full schema, examples (React component, API functions, route/view), and per-field verification checks.
+**What:** A wiring contract is a YAML block in a plan task that declares the expected wiring for code produced by that task. It tells ftm-audit exactly what to verify — instead of guessing, the audit checks specific expectations.
 
-**Fields:** `exports`, `imported_by`, `rendered_in`, `route_path`, `nav_link`, `store_reads`, `store_writes`, `api_calls` — all optional.
+**Schema:**
 
-**Graceful degradation:** Full contract → check every wire. Partial → check what's declared. No contract → pure Layer 1 + Layer 2 analysis.
+```yaml
+Wiring:
+  exports:
+    - symbol: ComponentName          # What's being exported
+      from: src/components/Thing.tsx  # From which file
 
----
+  imported_by:
+    - file: src/views/Dashboard.tsx   # Which file should import it
+      line_hint: "import section"     # Approximate location (optional)
+
+  rendered_in:                        # For React components
+    - parent: Dashboard               # Parent component name
+      placement: "main content area"  # Where in the JSX (descriptive)
+
+  route_path: /dashboard/thing        # For routed views (optional)
+
+  nav_link:                           # For views that need navigation (optional)
+    - location: sidebar               # Where the nav link goes
+      label: "Thing"                  # Display text
+
+  store_reads:                        # Store fields this code reads (optional)
+    - store: useAppStore
+      field: user.preferences
+
+  store_writes:                       # Store fields this code writes (optional)
+    - store: useAppStore
+      field: user.preferences
+      action: setPreferences
+
+  api_calls:                          # API functions this code invokes (optional)
+    - function: fetchUserPrefs
+      from: src/api/user.ts
+```
+
+**All fields are optional.** Graceful degradation:
+- Full contract → audit checks every declared wire
+- Partial contract → audit checks what's declared, uses heuristics for the rest
+- No contract → audit falls back to pure Layer 1 + Layer 2 analysis
+
+**Example: React Component Task**
+
+```yaml
+### Task 3: Build UserPreferences component
+**Files:** Create src/components/UserPreferences.tsx
+**Wiring:**
+  exports:
+    - symbol: UserPreferences
+      from: src/components/UserPreferences.tsx
+  imported_by:
+    - file: src/views/SettingsView.tsx
+  rendered_in:
+    - parent: SettingsView
+      placement: "below profile section"
+  store_reads:
+    - store: useAppStore
+      field: user.preferences
+  api_calls:
+    - function: updatePreferences
+      from: src/api/user.ts
+```
+
+**Example: API Client Function Task**
+
+```yaml
+### Task 5: Add billing API functions
+**Files:** Create src/api/billing.ts
+**Wiring:**
+  exports:
+    - symbol: fetchInvoices
+      from: src/api/billing.ts
+    - symbol: createSubscription
+      from: src/api/billing.ts
+  imported_by:
+    - file: src/hooks/useBilling.ts
+  api_calls: []  # These ARE the API functions — nothing to call downstream
+```
+
+**Example: New Route/View Task**
+
+```yaml
+### Task 7: Build AnalyticsDashboard view
+**Files:** Create src/views/AnalyticsDashboard.tsx
+**Wiring:**
+  exports:
+    - symbol: AnalyticsDashboard
+      from: src/views/AnalyticsDashboard.tsx
+  imported_by:
+    - file: src/router.tsx
+  rendered_in:
+    - parent: RouterConfig
+      placement: "route element"
+  route_path: /analytics
+  nav_link:
+    - location: sidebar
+      label: "Analytics"
+      icon: BarChart
+  store_reads:
+    - store: useAppStore
+      field: analytics.dateRange
+```
+
+**How ftm-audit checks contracts:**
+
+For each field in the wiring contract:
+
+1. **exports** → Verify the symbol exists as a named export in the specified file. Use `grep "export.*ComponentName"` or AST-level check.
+2. **imported_by** → Verify the importing file contains `import { Symbol } from './path'`. Check the actual import statement exists.
+3. **rendered_in** → Verify the parent component's JSX contains `<Symbol`. If `placement` is specified, verify approximate location.
+4. **route_path** → Verify the router config contains a route with this path pointing to this component.
+5. **nav_link** → Verify the navigation component (sidebar/navbar) contains a link with matching label and path.
+6. **store_reads** → Verify a selector/hook call reads this field in the component.
+7. **store_writes** → Verify a dispatch/action call writes this field.
+8. **api_calls** → Verify the function is imported and called somewhere in the component or its hooks.
+
+Each check produces: `✅ VERIFIED file:line` or `❌ NOT FOUND — [what was expected] [where it was expected]`
 
 ## Phase 3: Runtime Wiring (Optional)
 
-Verify that components and routes that passed static analysis actually render in the running application. See `references/protocols/RUNTIME-WIRING.md` for full prerequisites, process, and what runtime wiring catches that static analysis misses.
+**Prerequisite**: This phase runs only when ALL of these conditions are met:
+1. The ftm-browse binary exists at `$HOME/.claude/skills/ftm-browse/bin/ftm-browse`
+2. A dev server is running (detected via `lsof -i :3000` or `lsof -i :5173` or `lsof -i :8080`)
+3. The wiring contracts for the audited tasks include `route_path` entries
 
-**Prerequisites (all required):** ftm-browse binary at `$HOME/.claude/skills/ftm-browse/bin/ftm-browse` + dev server running + wiring contracts include `route_path` entries.
+If any prerequisite is not met, skip this phase with a note explaining which condition failed.
 
-**If any prerequisite fails:** Log the reason and skip. Do NOT fail the overall audit.
+**What it checks**: Components and routes that passed static analysis (Phases 1-2) actually render in the running application.
 
----
+### Process
+
+For each wiring contract that includes a `route_path`:
+
+1. **Navigate**: `$PB goto <dev_server_url><route_path>`
+2. **Snapshot**: `$PB snapshot -i` to get the ARIA tree of interactive elements
+3. **Verify components render**: Check that the expected components from the wiring contract appear in the ARIA tree. Look for:
+   - Expected buttons, links, inputs by their labels/roles
+   - Expected headings and landmarks
+   - Expected form fields
+4. **Screenshot**: `$PB screenshot` as evidence of the render state
+5. **Report findings**:
+   - PASS: All expected components found in ARIA tree
+   - WARN: Page renders but some expected components are missing
+   - FAIL: Page doesn't render (blank, error page, 404)
+
+Where `$PB` is `$HOME/.claude/skills/ftm-browse/bin/ftm-browse`.
+
+### Integration with Phases 1-2
+
+Runtime wiring catches a category of bugs that static analysis cannot:
+- Component is imported and used in JSX but conditionally rendered (and the condition is false)
+- Route is registered but the page component crashes on mount
+- Component renders but is hidden via CSS (visibility: hidden, display: none)
+- Server-side data dependency fails, leaving the component in an error state
+
+If Phase 3 finds issues that Phases 1-2 missed, flag them as **runtime-only findings** in the audit report.
+
+### Graceful Degradation
+
+If ftm-browse is not installed or the dev server is not running:
+- Log: "Phase 3 (Runtime Wiring) skipped — [reason: no browse binary | no dev server | no route_path in contracts]"
+- Do NOT fail the overall audit
+- Phases 1-2 results stand on their own
+
+## Execution Protocol
+
+When invoked (manually via `/ftm-audit` or automatically post-task):
+
+1. Run Phase 0 (detect project patterns — framework, router, state, API layer)
+2. Run Layer 1 (knip static analysis)
+3. Run Layer 2 (LLM adversarial audit, calibrated to detected patterns)
+4. Combine findings, deduplicate
+5. Run Layer 3 (auto-fix) for each finding
+6. Re-verify (re-run Layers 1+2)
+7. Run Phase 3 (runtime wiring via ftm-browse, if prerequisites met)
+8. Produce final changelog report
 
 ## Blackboard Write
 
-After completing:
+After completing, update the blackboard:
 
-1. Update `~/.claude/ftm-state/blackboard/context.json` — set current_task complete, append to recent_decisions (cap 10), update session_metadata
-2. Write experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` — findings count, fix count, dimensions fired, manual interventions
-3. Update `experiences/index.json`
+1. Update `~/.claude/ftm-state/blackboard/context.json`:
+   - Set current_task status to "complete"
+   - Append decision summary to recent_decisions (cap at 10)
+   - Update session_metadata.skills_invoked and last_updated
+2. Write an experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` capturing findings count, fix count, which wiring dimensions fired, and any manual interventions required
+3. Update `~/.claude/ftm-state/blackboard/experiences/index.json` with the new entry
 4. Emit `audit_complete` event
 
 ## Report Format
 
-See `references/templates/REPORT-FORMAT.md` for the full report template (summary, changelog table, layer-by-layer finding format with examples).
+```
+## FTM Audit Report — [timestamp]
+
+### Layer 1: Static Analysis (knip)
+- Findings: [N]
+- [list each finding with file:line]
+
+### Layer 2: Adversarial Audit
+- Findings: [N]
+- [list each finding with file:line and evidence]
+
+### Layer 3: Auto-Fix Results
+- Fixed: [N]
+- Manual intervention needed: [N]
+- [list each fix applied]
+
+### Final Status: PASS / FAIL
+- Remaining issues: [list if any]
+```
 
 ## Requirements