feed-the-machine 1.6.0 → 1.7.0

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

@@ -1,91 +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.
+# 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

@@ -1,66 +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.
+# 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

@@ -1,135 +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.
+# 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.