feed-the-machine 1.5.0 → 1.6.0

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

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

package/ftm-audit/references/templates/REPORT-FORMAT.md

@@ -1,96 +1,96 @@
-# Audit Report Format
-
-The final output structure for a completed ftm-audit run.
-
----
-
-## Summary Report
-
-```
-## FTM Audit Report — [YYYY-MM-DD HH:MM]
-
-### Layer 1: Static Analysis (knip)
-- Findings: [N]
-- [FINDING_TYPE] file:line — description
-- [FINDING_TYPE] file:line — description
-
-### Layer 2: Adversarial Audit
-- Findings: [N]
-- [FINDING_TYPE] file:line — description (Dimension N FAIL)
-- [FINDING_TYPE] file:line — description (Dimension N FAIL)
-
-### Layer 3: Auto-Fix Results
-- Fixed: [N]
-- Manual intervention needed: [N]
-- [list each fix applied with result]
-
-### Final Status: PASS / FAIL
-- Remaining issues: [list if any]
-```
-
----
-
-## Detailed Changelog
-
-Produced alongside the summary report when Layer 3 runs.
-
-```
-### 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)
-```
-
----
-
-## Layer-by-Layer Finding Format
-
-### Layer 1 (knip) Finding Format
-
-```
-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
-```
-
-### Layer 2 (Adversarial) Finding Format
-
-```
-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)
-```
-
-**Requirement:** Every finding must include file:line evidence. "I think this might be unused" is not acceptable — show the grep results or the missing link in the chain.
-
-### Phase 3 (Runtime) Finding Format
-
-When runtime-only findings are present (passed Layers 1-2 but failed Phase 3):
-
-```
-Phase 3 (Runtime) findings:
-- [RUNTIME_FAIL] /analytics — page returns 404 despite route registered in router.tsx:18
-- [RUNTIME_WARN] /settings — route renders but <UserPreferences /> missing from ARIA tree
-```
-
-Label these as `runtime-only` so developers know they won't be caught by future static checks alone.
+# Audit Report Format
+
+The final output structure for a completed ftm-audit run.
+
+---
+
+## Summary Report
+
+```
+## FTM Audit Report — [YYYY-MM-DD HH:MM]
+
+### Layer 1: Static Analysis (knip)
+- Findings: [N]
+- [FINDING_TYPE] file:line — description
+- [FINDING_TYPE] file:line — description
+
+### Layer 2: Adversarial Audit
+- Findings: [N]
+- [FINDING_TYPE] file:line — description (Dimension N FAIL)
+- [FINDING_TYPE] file:line — description (Dimension N FAIL)
+
+### Layer 3: Auto-Fix Results
+- Fixed: [N]
+- Manual intervention needed: [N]
+- [list each fix applied with result]
+
+### Final Status: PASS / FAIL
+- Remaining issues: [list if any]
+```
+
+---
+
+## Detailed Changelog
+
+Produced alongside the summary report when Layer 3 runs.
+
+```
+### 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)
+```
+
+---
+
+## Layer-by-Layer Finding Format
+
+### Layer 1 (knip) Finding Format
+
+```
+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
+```
+
+### Layer 2 (Adversarial) Finding Format
+
+```
+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)
+```
+
+**Requirement:** Every finding must include file:line evidence. "I think this might be unused" is not acceptable — show the grep results or the missing link in the chain.
+
+### Phase 3 (Runtime) Finding Format
+
+When runtime-only findings are present (passed Layers 1-2 but failed Phase 3):
+
+```
+Phase 3 (Runtime) findings:
+- [RUNTIME_FAIL] /analytics — page returns 404 despite route registered in router.tsx:18
+- [RUNTIME_WARN] /settings — route renders but <UserPreferences /> missing from ARIA tree
+```
+
+Label these as `runtime-only` so developers know they won't be caught by future static checks alone.

package/ftm-audit/scripts/run-knip.sh

@@ -1,23 +1,23 @@
-#!/usr/bin/env bash
-# run-knip.sh — Run knip and return structured findings
-# Exit 0 if clean, 1 if findings exist
-
-set -euo pipefail
-
-# Check for package.json
-if [ ! -f "package.json" ]; then
-  echo '{"skipped": true, "reason": "No package.json found"}'
-  exit 0
-fi
-
-# Run knip with JSON reporter
-OUTPUT=$(npx knip --reporter json 2>/dev/null || true)
-
-# Check if output is empty or just '{}'
-if [ -z "$OUTPUT" ] || [ "$OUTPUT" = "{}" ] || [ "$OUTPUT" = '{"files":[],"issues":[]}' ]; then
-  echo '{"clean": true, "files": [], "issues": []}'
-  exit 0
-fi
-
-echo "$OUTPUT"
-exit 1
+#!/usr/bin/env bash
+# run-knip.sh — Run knip and return structured findings
+# Exit 0 if clean, 1 if findings exist
+
+set -euo pipefail
+
+# Check for package.json
+if [ ! -f "package.json" ]; then
+  echo '{"skipped": true, "reason": "No package.json found"}'
+  exit 0
+fi
+
+# Run knip with JSON reporter
+OUTPUT=$(npx knip --reporter json 2>/dev/null || true)
+
+# Check if output is empty or just '{}'
+if [ -z "$OUTPUT" ] || [ "$OUTPUT" = "{}" ] || [ "$OUTPUT" = '{"files":[],"issues":[]}' ]; then
+  echo '{"clean": true, "files": [], "issues": []}'
+  exit 0
+fi
+
+echo "$OUTPUT"
+exit 1

package/ftm-audit.yml

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