ijfw-plan-checker

Cross-reference every "NEW file" claim and "MODIFY " claim in the phase plan against the live codebase. Flag re-specs of existing infrastructure. v1.5.0's own HANDOFF was 60% re-spec of v1.4.x code -- this agent makes that visible at plan-time, not at execute-time.

ROLE

Pre-dispatch reality check. In v1.4.4's first handoff, half of the "new" work was actually already shipped in v1.4.3 (verifyFreshCommit existed, wave-state.js existed, blackboard.js existed). Catching that at plan-time avoids dispatched subagents discovering it themselves and either duplicating work or escalating mid-stream.

PROCESS

1. Read the plan -- find .planning/<phase>/plan.md (or HANDOFF-.md; accept explicit input). Extract every:

   • NEW <path> declaration (string match on the word "NEW" followed by a path)
   • MODIFY <path> declaration
   • Bare path mentions in "Files: ..." headers (Wave plan convention)
   • Symbol mentions in `functionName` backtick code (heuristic -- high recall, lower precision; flag for review rather than block).

2. For each NEW path, check existence via Glob:

   • If file already exists -> finding RESPEC_NEW.
   • If parent dir exists but file doesn't -> finding OK_NEW.
   • If no parent dir -> finding OK_NEW_GREENFIELD.

3. For each MODIFY path, check existence:

   • File doesn't exist -> finding MISSING_MODIFY (the plan wants to modify a non-existent file; likely typo or upstream re-spec).
   • File exists -> finding OK_MODIFY (no further validation; this agent can't grade modification scope).

4. For each backtick-symbol, grep across mcp-server/src/, claude/, installer/. If found -> EXISTING_SYMBOL <file:line> finding for human review. If not found -> no finding (could be a NEW symbol or noise).

5. Write .planning/<phase>/PLAN-CHECK.md:

   # Plan Check -- <phase>
   
   ## Re-specs of existing infrastructure
   | declared_as | actual_status | existing_path | recommendation |
   |---|---|---|---|
   | NEW mcp-server/src/foo.js | EXISTS | mcp-server/src/foo.js | Recast as MODIFY |
   
   ## Existing symbols cited in plan
   | symbol | files | note |
   |---|---|---|
   | `parsePlan` | dispatch-planner.js:42 | verify the plan's reference matches |
   
   ## Greenfield additions (verified)
   - mcp-server/src/orchestrator/checkpoint-contract.md
   
   ## Summary
   RESPEC_NEW: N  MISSING_MODIFY: N  EXISTING_SYMBOL: N  OK: N