feed-the-machine 1.0.0

package/ftm/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ftm
+description: Universal entry point for all ftm skills. Routes freeform text to the right ftm skill. ftm-mind is the default cognitive entry point for all unclassified input.
+---
+
+# Feed The Machine — Universal Skill Router
+
+You are the entry point for the ftm skill system. Your job is routing — fast, thin, decisive.
+
+## Routing Rules
+
+Evaluate the user's input in this order:
+
+### 1. Help Menu
+If input is empty, "help", "?", or "menu" → display the help menu below. Do NOT invoke any skill.
+
+### 2. Explicit Skill Name
+If input starts with a recognized skill name, route directly to that skill:
+
+| Input prefix | Route to |
+|---|---|
+| `brainstorm` | ftm-brainstorm |
+| `execute`, `run` (+ file path) | ftm-executor |
+| `debug` | ftm-debug |
+| `audit` | ftm-audit |
+| `council` | ftm-council |
+| `intent` | ftm-intent |
+| `diagram` | ftm-diagram |
+| `codex-gate`, `codex gate` | ftm-codex-gate |
+| `pause` | ftm-pause |
+| `resume` | ftm-resume |
+| `browse` | ftm-browse |
+| `upgrade` | ftm-upgrade |
+| `retro` | ftm-retro |
+| `config` | ftm-config |
+| `mind` | ftm-mind |
+
+When routing to a specific skill:
+1. Update the blackboard context: read `~/.claude/ftm-state/blackboard/context.json`, set `current_task` to reflect the incoming request, append to `session_metadata.skills_invoked`, write back.
+2. Show: `Routing to ftm-[skill]: [one-line reason]`
+3. Invoke the skill via the Skill tool with the user's full input as args.
+
+### 3. Everything Else → ftm-mind
+All freeform input that does not match an explicit skill prefix goes to ftm-mind for OODA processing:
+1. Update the blackboard context (same as above).
+2. Show: `Routing to ftm-mind: analyzing your request.`
+3. Invoke: Skill tool with skill="ftm-mind", args="<full user input>"
+
+### Legacy Fallback
+If ftm-mind fails (errors, timeouts, no actionable output) AND `legacy_router_fallback` is `true` in `~/.claude/ftm-config.yml`, fall back to keyword matching:
+
+- "bug", "broken", "error", "fix", "crash", "failing" → ftm-debug
+- "plan", "think", "build", "design", "how should" → ftm-brainstorm
+- file path + "execute"/"go"/"run" → ftm-executor
+- All other → ftm-brainstorm (default)
+
+This fallback can be disabled after stable operation.
+
+## Help Menu
+
+When the user provides no input or asks for help, display this exactly:
+
+```
+FTM Skills:
+  /ftm mind [anything]       — Default cognitive entry point (OODA reasoning)
+  /ftm brainstorm [idea]     — Research-backed idea development
+  /ftm execute [plan-path]   — Autonomous plan execution with agent teams
+  /ftm debug [description]   — Multi-vector deep debugging war room
+  /ftm audit                 — Wiring verification (knip + adversarial)
+  /ftm council [question]    — Multi-model deliberation (Claude + Codex + Gemini)
+  /ftm intent                — Manage INTENT.md documentation layer
+  /ftm diagram               — Manage ARCHITECTURE.mmd diagram layer
+  /ftm codex-gate            — Run adversarial Codex validation
+  /ftm pause                 — Save session state for later
+  /ftm resume                — Resume a paused session
+  /ftm browse [url]          — Visual verification with headless browser
+  /ftm upgrade               — Check for and install skill updates
+  /ftm retro                 — Post-execution retrospective
+  /ftm config                — View and edit ftm configuration
+
+Or just describe what you need and ftm-mind will handle it.
+```
+
+## Important Notes
+- Pass through the full user input as args to the target skill. Let the target skill parse details.
+- Do not attempt to do the work yourself — route only.
+- Be fast — decisive routing, not conversation.
+- Case insensitive matching for all prefix detection.

package/ftm-audit/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ftm-audit
+description: Dual-purpose wiring audit that verifies all code is actually connected to the running application. Combines static analysis (knip) with adversarial LLM audit and auto-fixes anything it finds. Use when user says "audit", "wiring check", "verify wiring", "dead code", "check imports", "unused code", "find dead code", or "audit wiring". Also auto-invoked by ftm-executor after each task.
+---
+
+## Events
+
+### Emits
+- `audit_complete` — when all three audit layers finish and the final changelog is produced
+- `issue_found` — when Layer 1 (knip) or Layer 2 (adversarial audit) identifies an unwired or dead-code problem
+- `task_completed` — when an audit-initiated fix cycle finishes and the audited scope is verified clean
+
+### Listens To
+- `code_committed` — run post-commit verification: trigger Layer 1 and Layer 2 against the committed diff
+- `review_complete` — validate that review findings align with static analysis results; flag discrepancies
+
+## Blackboard Read
+
+Before starting, load context from the blackboard:
+
+1. Read `~/.claude/ftm-state/blackboard/context.json` — check current_task, recent_decisions, active_constraints
+2. Read `~/.claude/ftm-state/blackboard/experiences/index.json` — filter entries by task_type="test" or tags matching "audit" or "wiring"
+3. Load top 3-5 matching experience files for commonly found issues and effective fix strategies
+4. Read `~/.claude/ftm-state/blackboard/patterns.json` — check recurring_issues for common wiring failures and execution_patterns for what types of code changes need more scrutiny
+
+If index.json is empty or no matches found, proceed normally without experience-informed shortcuts.
+
+## Execution Protocol
+
+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
+
+
+## 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.
+
+**Quick scan:** `package.json` deps + `next.config.*`, `vite.config.*`, `app/` directory, `pages/` directory.
+
+**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.
+
+**Prerequisites:** Requires `package.json` — skip and note if absent. Use `npx knip` if not locally installed.
+
+```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`.
+
+Fix actions by finding type: see `references/strategies/AUTO-FIX-STRATEGIES.md`. Helper script: `scripts/run-knip.sh`.
+
+---
+
+## 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.
+
+**Scope:** `git diff HEAD~1` (or current task diff). For each new or modified export, check all five 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`.
+
+| 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" |
+
+**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.
+
+**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.
+
+---
+
+## Layer 3: Auto-Fix and Changelog
+
+**Purpose:** When Layers 1 or 2 find unwired code, generate fixes, apply them, re-verify, and produce a structured changelog.
+
+For fix strategies by finding type and the conditions that block auto-fix, see `references/strategies/AUTO-FIX-STRATEGIES.md`.
+
+**Fix protocol for each finding:** Report → determine fix (check wiring contract for WHERE) → show proposed change → apply → re-verify → log to changelog.
+
+```
+FIX: [UNWIRED_COMPONENT] NewWidget in Dashboard.tsx
+Proposed: Add <NewWidget /> to Dashboard.tsx return JSX after line 45
+```
+
+**When auto-fix is not possible:** Flag with `MANUAL_INTERVENTION_NEEDED`, a suggested action, and the reason skipped.
+
+**Re-verification:** After all fixes, re-run Layers 1+2. Maximum 3 iterations to prevent loops.
+
+---
+
+## 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.
+
+**Fields:** `exports`, `imported_by`, `rendered_in`, `route_path`, `nav_link`, `store_reads`, `store_writes`, `api_calls` — all optional.
+
+**Graceful degradation:** Full contract → check every wire. Partial → check what's declared. No contract → pure Layer 1 + Layer 2 analysis.
+
+---
+
+## 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.
+
+**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 fails:** Log the reason and skip. Do NOT fail the overall audit.
+
+---
+
+## Blackboard Write
+
+After completing:
+
+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`
+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).

package/ftm-audit/references/protocols/PROJECT-PATTERNS.md

@@ -0,0 +1,91 @@
+# Project Pattern Detection
+
+Pre-audit calibration: detect framework, router, state management, and API layer so wiring checks apply the right rules. This prevents false positives from applying React patterns to a Vue project, or App Router patterns to a Pages Router project.
+
+**Cross-reference:** ftm-debug uses this same detection to calibrate its error tracing. Run once and share results with both skills.
+
+---
+
+## Detection Protocol
+
+Read `package.json` dependencies and scan key config/directory signals.
+
+### Framework Detection
+
+| Signal | Detection | Impact on Audit |
+|---|---|---|
+| **React** | `react` in deps | Dimensions 1-5 all apply |
+| **Next.js** | `next` in deps | File-based routing, check App vs Pages Router |
+| **Vue** | `vue` in deps | `<template>` instead of JSX, check vue-router |
+| **Svelte** | `svelte` in deps | Svelte components, SvelteKit file-based routes |
+| **Angular** | `@angular/core` in deps | Module-based wiring, check NgModule declarations |
+| **No framework** | None of the above | Skip D2 (JSX) and D3 (Routes) |
+
+### Router Detection
+
+| Signal | Detection | Dimension 3 Behavior |
+|---|---|---|
+| `react-router-dom` | dep exists | Check explicit router config file |
+| `@tanstack/react-router` | dep exists | Check router config file |
+| `next` + `app/` directory | `app/layout.tsx` or `app/page.tsx` exists | File-based: `app/path/page.tsx` = `/path` |
+| `next` + `pages/` directory | `pages/` exists, no `app/` | File-based: `pages/foo.tsx` = `/foo` |
+| `vue-router` | dep exists | Check router config file |
+| SvelteKit | `@sveltejs/kit` in deps | File-based routes in `src/routes/` |
+
+### State Management Detection
+
+| Signal | Detection | Dimension 4 Behavior |
+|---|---|---|
+| `zustand` | dep exists | Check `useStore` hooks and `create()` calls |
+| `@reduxjs/toolkit` | dep exists | Check `useSelector`/`useDispatch` and slice reducers |
+| `jotai` | dep exists | Check `useAtom` calls |
+| `recoil` | dep exists | Check `useRecoilState`/`useRecoilValue` calls |
+| `pinia` | dep exists | Check `defineStore` and `useXStore()` calls |
+| None detected | — | Skip D4 or adapt to any custom store pattern found |
+
+### API Layer Detection
+
+| Signal | Detection | Dimension 5 Behavior |
+|---|---|---|
+| `@tanstack/react-query` | dep exists | Check `useQuery`/`useMutation` calls |
+| `swr` | dep exists | Check `useSWR` calls |
+| `@trpc/client` | dep exists | Check tRPC router procedure calls |
+| `@apollo/client` | dep exists | Check `useQuery`/`useMutation` with gql tags |
+| `axios` / `fetch` | explicit patterns | Check direct call sites |
+
+### Build Tool Detection
+
+| Signal | Detection | Impact |
+|---|---|---|
+| `vite.config.*` exists | File scan | Entry point: `index.html` → `src/main.tsx` |
+| `next.config.*` exists | File scan | Entry managed by Next.js framework |
+| `webpack.config.*` exists | File scan | Check entry field in config |
+
+---
+
+## Dimension Activation Matrix
+
+Based on detected patterns, set active dimensions before running Layer 2.
+
+| Framework | D1 (Import) | D2 (JSX) | D3 (Routes) | D4 (Store) | D5 (API) |
+|---|---|---|---|---|---|
+| React + react-router | Standard | Standard | Router config file | Per state lib | Per API lib |
+| Next.js App Router | Check `app/` tree | Standard | File-based: `page.tsx` in dir = route | Per state lib | Check Server Actions too |
+| Next.js Pages Router | Check `pages/` tree | Standard | File-based: `pages/foo.tsx` = `/foo` | Per state lib | Check `getServerSideProps`/`getStaticProps` |
+| Remix | Check `app/routes/` | Standard | File-based + `remix.config` | Per state lib | Check `loader`/`action` exports |
+| Vue + vue-router | Standard | `<template>` | Router config file | Pinia: `defineStore` | Per API lib |
+| Svelte | Standard | Svelte components | SvelteKit: `src/routes/` | Svelte stores | Per API lib |
+| No framework (Node.js) | Standard | Skip D2 | Skip D3 | Skip D4 | Standard |
+
+---
+
+## Output
+
+Store detected context for use by all subsequent layers. Do not include it in the report unless something unusual was detected (e.g., conflicting signals, ambiguous router type).
+
+```
+Project detected: React 18 + Vite + react-router v6 + Zustand + TanStack Query
+Dimensions active: D1 ✓  D2 ✓  D3 (router config)  D4 (Zustand)  D5 (TanStack Query)
+```
+
+If signals are ambiguous (e.g., both `app/` and `pages/` directories exist), note the ambiguity and default to the more restrictive check — verify both routing patterns.

package/ftm-audit/references/protocols/RUNTIME-WIRING.md

@@ -0,0 +1,66 @@
+# Runtime Wiring Verification
+
+Phase 3 of the audit: verify that components and routes that passed static analysis actually render in the running application. Catches bugs static analysis cannot detect.
+
+---
+
+## Prerequisites
+
+This phase runs only when ALL of the following 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` (Create React App, Next.js default)
+   - `lsof -i :5173` (Vite default)
+   - `lsof -i :8080` (various)
+3. The wiring contracts for the audited tasks include at least one `route_path` entry
+
+If any prerequisite is not met, skip this phase and log: `Phase 3 (Runtime Wiring) skipped — [reason: no browse binary | no dev server | no route_path in contracts]`. Do NOT fail the overall audit.
+
+---
+
+## 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 expected components from the wiring contract appear in the ARIA tree:
+   - 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`.
+
+---
+
+## What Runtime Wiring Catches
+
+Static analysis (Layers 1-2) cannot detect these failure modes:
+
+| Failure Mode | Example | Detection |
+|---|---|---|
+| Conditional render always false | `{isAdmin && <AdminPanel />}` where `isAdmin` is hardcoded `false` | Component missing from ARIA tree |
+| Component crashes on mount | Runtime error in `useEffect` causes blank render | Error page or blank instead of expected content |
+| CSS visibility hidden | `display: none` or `visibility: hidden` | Component in ARIA tree but not visually accessible |
+| Server-side data dependency fails | `getServerSideProps` throws → component in error state | Error boundary rendered instead of component |
+| Route registered but redirects | Route exists in config but always redirects away | Final URL differs from expected `route_path` |
+
+These are flagged as **runtime-only findings** in the audit report if found after Layers 1-2 both passed.
+
+---
+
+## Integration with Layers 1-2
+
+Runtime wiring is additive — it extends static analysis, not replaces it. The layer execution order is:
+
+```
+Layer 1 (knip) → Layer 2 (adversarial) → Layer 3 (auto-fix) → Phase 3 (runtime, if prerequisites met)
+```
+
+Runtime findings that survive after Layers 1-2 are clean represent genuine runtime-only bugs. Flag them separately so the developer knows they cannot be caught by future static checks alone.

package/ftm-audit/references/protocols/WIRING-CONTRACTS.md

@@ -0,0 +1,135 @@
+# Wiring Contracts
+
+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.
+
+**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
+
+---
+
+## Schema
+
+```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. Include only the dimensions relevant to the task.
+
+---
+
+## Contract Examples
+
+### React Component
+
+```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
+```
+
+### API Client Functions
+
+```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
+```
+
+### New Route/View
+
+```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
+```
+
+---
+
+## Verification Checks
+
+For each field in the wiring contract, audit runs the corresponding check:
+
+| Field | Check | Method |
+|---|---|---|
+| `exports` | Symbol exists as named export in specified file | `grep "export.*SymbolName"` or AST check |
+| `imported_by` | Importing file contains the import statement | Check for `import { Symbol } from './path'` |
+| `rendered_in` | Parent component's JSX contains `<Symbol` | Search JSX/TSX return statements |
+| `route_path` | Router config contains route pointing to this component | Search router config file |
+| `nav_link` | Navigation component has link with matching label and path | Search sidebar/navbar file |
+| `store_reads` | Selector/hook call reads this field in the component | Search for selector usage |
+| `store_writes` | Dispatch/action call writes this field | Search for action dispatch |
+| `api_calls` | Function is imported and called in component or its hooks | Search for call sites |
+
+Each check produces: `✅ VERIFIED file:line` or `❌ NOT FOUND — [what was expected] [where it was expected]`
+
+**Rendering special cases:** Lazy imports (`React.lazy(() => import(...))`), conditional rendering (`{condition && <Component/>}`), render props, and HOCs all count as valid rendering for Dimension 2.

package/ftm-audit/references/strategies/AUTO-FIX-STRATEGIES.md

@@ -0,0 +1,69 @@
+# Auto-Fix Strategies
+
+Layer 3 applies fixes for each finding type, re-verifies, and produces a changelog. This document defines the fix strategy for each finding type and when to skip auto-fix.
+
+---
+
+## Fix Strategies by Finding Type
+
+| Finding Type | Fix Strategy | Fallback |
+|---|---|---|
+| `UNUSED_FILE` | If created by the current task, add import from the appropriate parent module. If 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, follow this sequence:
+
+1. **Report** — Log the finding with type, file:line, and evidence
+2. **Determine fix** — Match finding type to fix strategy above. Check wiring contract for WHERE to wire, if available.
+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 Safe
+
+Some findings cannot be auto-fixed without risking incorrect behavior:
+
+- **Ambiguous placement** — cannot determine where exactly in a component the new element should render
+- **Design decision needed** — whether a store field should exist at all requires product judgment
+- **Cross-cutting changes** — fix requires modifying 5+ files simultaneously
+- **Test-only code** — might be intentionally not wired into the app
+
+For these, flag clearly:
+
+```
+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)
+```
+
+---
+
+## Re-Verification Loop
+
+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
+
+**Loop limit:** Maximum 3 iterations to prevent infinite fix cycles. If issues persist after 3 iterations, stop and flag all remaining issues for manual intervention with a note explaining the loop was capped.