cad-health

Presence. .planning/ exists with PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md. A missing core doc is an issue (if the dir itself is absent, point at /cad-new-project for a blank page and /cad-adopt for a repo that already has code and history).

• The run record stays out of git. Run node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" trace ignore --root . --check and report an issue when ignored is false or tracked is true. Silent when the record is ignored and untracked. A project scaffolded before that seam existed has no line of its own; --check writes nothing and this step never edits the user's .gitignore. The two flags are separate facts and take DIFFERENT remedies, so name the one that applies rather than one command for both: ignored:false is a missing rule, fixed by the same command without --check; tracked:true means the record is in the index ALREADY, where no ignore rule reaches it, and the fix is git rm --cached .planning/trace.jsonl. Both can be true at once, and then both steps are needed - adding the rule alone leaves a tracked file that keeps getting committed.
• The capture queue, in two calls - a census of the file's sections, and a verdict on the walked queue itself: node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" capture-sections node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" capture-check From capture-sections, print one line per section whose in_walk is false, naming its heading and its bullet count, then what the number MEANS in one clause: those bullets are invisible to /cad-plan's recall. Silent when exists is false or every section is in the walk. It is a NAMED NOTE, not an issue, the way step 7's manifest clause is a distinct lower note: ## Debt markers is written wholesale by debt-harvest and is not a queue, so calling every out-of-walk section an issue trains the user to skim past exactly the line this is here to make readable. What is worth their attention is a count that MOVED, which they can only see because the steady-state number is printed too. From capture-check, print three things, and these ARE issues. .planning/CAPTURE.md holds the phase in flight and nothing else, so each one says that stopped being true:
  • substantive against bound, naming the crossing when over_bound is true. A crossed bound means a filing path stopped filing - the queue is carrying work that belongs on the tracker.
  • every annotations[] entry with its section, line and text. An annotation is an item adjudicated the WRONG WAY: an item is resolved by REMOVAL, so re-verifying one in place made the bullet longer instead of making it leave.
  • archive.heading with archive.bullets when archive.present is true. That heading has LEFT this file's contract - moving settled items to a section of the same document changes nothing about the bytes. Print both readings EVERY run, never filtered against a list of sections or items you expect. That allowlist is precisely what would have hidden the incident this check exists for - all five lost bullets sat under ## Archive, the section any allowlist would have named first.

STATE cursor. Exactly the 4-line schema (Phase / Status / Next / Updated - references/conventions.md). Status is one of the lifecycle values (ready to plan | context gathered | planned | executed | phase complete | paused). Phase: N of M parses with N <= M (except in the closed-milestone case rule 5 states). Updated is a date. Flag a 5th line, an unknown status, or an unparseable phase.