feed-the-machine 1.5.0 → 1.5.1

package/ftm-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Triple-layer wiring audit that verifies all code is actually connected to the running application and documented in INTENT.md. Combines static analysis (knip), documentation coverage checking (INTENT.md entries for every changed function), and adversarial LLM audit — auto-fixes anything it finds. Use when user says "audit", "wiring check", "verify wiring", "dead code", "check imports", "unused code", "find dead code", "audit wiring", "check docs", or "documentation coverage". Also auto-invoked by ftm-executor after each task.
 ---
 
 ## Events
@@ -121,6 +121,79 @@ Layer 1 findings:
 
 **Helper script:** `scripts/run-knip.sh` handles execution and returns structured JSON output.
 
+## Layer 1.5: Documentation Coverage Check
+
+**Purpose:** Verify that every new or changed function has a corresponding INTENT.md entry. This catches the most common documentation skip — agents write code and tests but forget to update INTENT.md, leaving the documentation layer stale.
+
+**When to run:** After Layer 1, before Layer 2. Only runs if the project has an INTENT.md documentation layer (root INTENT.md exists). If no INTENT.md exists anywhere in the project, skip this layer silently — it's not a documentation-first project.
+
+**Scope:** Analyze the current git diff to find new or changed functions/classes/methods.
+
+**Check protocol:**
+
+1. **Find changed files:** `git diff HEAD~1 --name-only -- '*.py' '*.ts' '*.tsx' '*.js' '*.jsx'` (or equivalent for the project's language)
+2. **For each changed source file:**
+   - Identify the module directory (e.g., `src/risk/` for `src/risk/position_sizer.py`)
+   - Check if `[module_dir]/INTENT.md` exists
+   - If it exists, read it and extract all documented function signatures
+   - Parse the changed file for public function/class/method definitions
+   - Compare: flag any public function that exists in code but has NO entry in INTENT.md
+3. **For new module directories** (directories created in this diff):
+   - Check if `[new_module_dir]/INTENT.md` was created
+   - Check if root INTENT.md module map has a row for the new module
+   - Flag if either is missing
+
+**Finding types:**
+
+| Finding | Severity | Auto-fixable? |
+|---------|----------|---------------|
+| `MISSING_INTENT_ENTRY` — function exists in code but no INTENT.md entry | HARD FAIL | Yes — generate entry from code |
+| `STALE_INTENT_ENTRY` — INTENT.md entry for a function that no longer exists | WARN | Yes — remove entry |
+| `MISSING_MODULE_INTENT` — new module directory has no INTENT.md file | HARD FAIL | Yes — create from template |
+| `MISSING_MODULE_MAP_ROW` — new module not in root INTENT.md module map | HARD FAIL | Yes — add row |
+
+**Output format:**
+```
+Layer 1.5 findings:
+- [MISSING_INTENT_ENTRY] src/risk/position_sizer.py:45 — `calculate_dynamic_size()` has no entry in src/risk/INTENT.md
+- [STALE_INTENT_ENTRY] src/risk/INTENT.md — entry for `old_function()` but function no longer exists in code
+- [MISSING_MODULE_INTENT] src/newmodule/ — directory created but no INTENT.md file
+- [MISSING_MODULE_MAP_ROW] src/newmodule/ — not listed in root INTENT.md module map
+```
+
+**Auto-fix strategy for `MISSING_INTENT_ENTRY`:**
+
+Generate the entry from the function's code. Read the function body and produce:
+```markdown
+### function_name(param1: Type, param2: Type) -> ReturnType
+- **Does**: [infer from function body — one sentence]
+- **Why**: [infer from context and callers — one sentence, or "Why unknown — inferred from usage: [inference]"]
+- **Relationships**: [grep for callers/callees — one sentence]
+- **Decisions**: [note any non-obvious choices, or "None"]
+```
+
+Append the entry to the module's INTENT.md under the `## Functions` section.
+
+**Auto-fix strategy for `MISSING_MODULE_INTENT`:**
+
+Create `[module_dir]/INTENT.md` with:
+```markdown
+# [Module Name] — Intent
+
+## Functions
+
+[generate entries for all public functions in the module]
+```
+
+**Auto-fix strategy for `MISSING_MODULE_MAP_ROW`:**
+
+Append a row to the root INTENT.md module map table:
+```markdown
+| [module_path] | [infer purpose from code] | [infer relationships from imports] |
+```
+
+---
+
 ## Layer 2: LLM Adversarial Audit
 
 **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.
@@ -192,6 +265,10 @@ Layer 2 findings:
 | `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 |
+| `MISSING_INTENT_ENTRY` | Generate INTENT.md entry from function code (Does/Why/Relationships/Decisions). Append to module's INTENT.md. | Flag if function purpose is ambiguous |
+| `STALE_INTENT_ENTRY` | Remove the entry from INTENT.md. | Flag if unsure whether function was renamed vs deleted |
+| `MISSING_MODULE_INTENT` | Create module INTENT.md with entries for all public functions. | Flag if module has no clear public API |
+| `MISSING_MODULE_MAP_ROW` | Add row to root INTENT.md module map table. | Flag if module purpose is unclear |
 
 **Fix Protocol (for each finding):**
 
@@ -430,12 +507,13 @@ 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
+3. Run Layer 1.5 (documentation coverage check — INTENT.md entries for changed functions)
+4. Run Layer 2 (LLM adversarial audit, calibrated to detected patterns)
+5. Combine findings, deduplicate
+6. Run Layer 3 (auto-fix) for each finding (including missing INTENT.md entries)
+7. Re-verify (re-run Layers 1+1.5+2)
+8. Run Phase 3 (runtime wiring via ftm-browse, if prerequisites met)
+9. Produce final changelog report
 
 ## Blackboard Write
 
@@ -458,6 +536,10 @@ After completing, update the blackboard:
 - Findings: [N]
 - [list each finding with file:line]
 
+### Layer 1.5: Documentation Coverage
+- Findings: [N]
+- [list each finding — missing entries, stale entries, missing module docs]
+
 ### Layer 2: Adversarial Audit
 - Findings: [N]
 - [list each finding with file:line and evidence]

package/ftm-executor/SKILL.md

@@ -128,7 +128,7 @@ For FAIL findings, suggest specific fixes.
 ```
 
 **Interpret the result:**
-- **PASS**: Proceed to Phase 1
+- **PASS**: Proceed to Phase 0.7 → Phase 1 → Phase 1.5 (documentation bootstrap) → Phase 2
 - **WARN**: Show warnings to user, proceed unless they object
 - **FAIL**: Present blockers and suggested fixes. Ask user: fix the plan and re-run, or override and execute anyway?
 
@@ -174,6 +174,10 @@ Parallel waves:
   Final: Task [N] (integration/cleanup)
 ```
 
+**After outputting the summary, proceed IMMEDIATELY to Phase 1.5.** Do NOT skip to Phase 2. The documentation bootstrap must run before any agents are dispatched.
+
+---
+
 ### Phase 1.5: Documentation Layer Bootstrap (MANDATORY)
 
 **This phase is non-skippable.** The documentation layer is required for ftm-verify to assess plan completion, for ftm-codex-gate to detect intent conflicts, and for agents to update docs as they work. Without it, every downstream verification step is degraded.
@@ -204,6 +208,10 @@ Cannot proceed without documentation layer. Fix manually or re-run.
 ```
 Do NOT proceed to Phase 2 with missing documentation files.
 
+**Phase 1.5 complete.** All documentation files verified. Proceed to Phase 2.
+
+**CRITICAL FLOW REMINDER: The execution sequence is Phase 0 → 0.5 → 0.7 → 1 → 1.5 → 2 → 3 → 3.5 → 4. Phase 1.5 MUST execute between Phase 1 and Phase 2. If you are reading this and have not yet created/verified the documentation layer, STOP and do it now before dispatching any agents.**
+
 ---
 
 ### Phase 2: Assemble the Agent Team

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feed-the-machine",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "A unified intelligence layer for Claude Code — 22 skills with OODA-based reasoning, persistent memory, multi-model deliberation, and optional operator cockpit inbox",
   "license": "MIT",
   "author": "kkudumu",