planrails 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.6.0 — 2026-09-19
+
+The checker can now advise without blocking.
+
+- **Notes.** A problem is what a script can verify, and it still fails the build.
+  A note is what a script can only suspect: it prints as `check-plans: note: …`
+  on stdout before the final line, the exit code and the final line do not
+  change, and the agent that ran the check decides. `checkPlans` returns `notes`
+  beside `problems`; `npx planrails check` prints the same ones. On a plan with
+  no note the output is byte-for-byte what 0.5.2 printed.
+- **One note ships: an active `PLAN.md` over ~3,000 words.** The plan reloads
+  into every session, and nothing said when it had grown: four of four real plans
+  were past the stated line, one at 9,123 words. A retired plan gets no note; it
+  does not reload.
+- **The word line moves from ~2,000 to ~3,000.** The line was written before the
+  plan carried its own ~480-word block; two carefully kept plans measure ~2,800.
+  The doc was stale, not the plans.
+- **Why not hooks.** The idea began as advisory Claude Code hooks. Checked against
+  the hooks reference: a PreCompact hook cannot add context, no event fires at a
+  context threshold, a Stop hook's advice forces another turn, and no event knows
+  a plan's task closed. The check command already runs before every commit and
+  its output is already read, in any agent. `CONTRIBUTING.md` sets the bar for a
+  new note: a recorded failure behind it, silent on a healthy plan. A LOG-entry
+  reminder was tested on four real plans, never fired, and was not built.
+
+To update: `npx planrails@latest init`. No plan needs editing.
+
+## 0.5.2 — 2026-09-13
+
+A second field test of 0.5.1, four scratch projects and seven fresh sessions, and
+a newcomer's pass over the docs. The published behaviour held: a stale claim was
+taken over by id, a live holder stopped a second session, a session assigned one
+of two plans touched only that one. Four gaps in the plan's block, and one in the
+worked example, are closed here.
+
+- **Two sessions can work two plans in one checkout.** The block's rule for an
+  unheld plan (`session: none`, or no line) said stop whenever any session in the
+  checkout was busy or any plan file was dirty, so the second of two sessions
+  always had to ask. Now a session assigned an unheld plan writes its line and
+  goes on, unless *that plan's* files are dirty or a busy session in the checkout
+  has its id on no plan's `session:` line. The same-plan rule is unchanged: a
+  live holder, matched by id, stops you.
+- **An `owner` proof is closed only by the person.** A field session closed an
+  owner task with a check of its own and an invented exit code; the checker cannot
+  see that. The block and §4 now say: the row stays `blocked` with the reason in
+  its evidence cell, and RESUME says so.
+- **NOW keeps its shape, and the block says how a plan closes.** A session
+  renamed RESUME to DONE, wrote the `session:` line twice and left a finished plan
+  active. The block says NOW is exactly the four lines, and points at §5 for the
+  close. The checker now fails an active plan whose NOW section has no RESUME
+  line, the one hole a renamed line opened in the NOW rule.
+- **The session rule is a list.** Its paragraph fell from 197 words to four
+  bullets; the whole block is about 480 words, up from 443, with the owner and
+  close clauses added.
+- **Existing 0.5.0 and 0.5.1 plans:** replace the block with the template's, so
+  they carry the unheld-plan rule and the owner clause; `init` cannot tell them
+  from 0.5.2 plans, since they already have a `session:` line.
+- **The worked example carries the template's block, byte for byte**, pinned by a
+  test. It had shipped the 0.5.0 paragraph that matched holders by name.
+- **`init` points out plans that predate 0.5**: an active plan with no `session:`
+  line is named, with the by-hand steps from 0.5.0. `init` still never touches a
+  plan.
+- Timestamps come from the shell clock: `date`, or `Get-Date` on Windows, where
+  `date` prompts. The README no longer suggests `ListAgents` can do the id match.
+  The 0.4.0 entry no longer overstates the stray-backtick fix. 77 tests.
+
 ## 0.5.1 — 2026-09-13
 
 A fresh-context review of 0.5.0, run the same day, found the block — the one copy
@@ -103,8 +169,8 @@ nothing but its two files.
   Re-run the proof and paste its exit code.
 - **The checker fails closed on a row it cannot read.** The cell splitter follows
   the CommonMark rule for backtick runs, so a stray backtick or three backticks in
-  prose no longer shift the columns; a row whose cell count still differs from the
-  header's is a problem instead of a silent pass. A task table inside a code fence
+  prose are read the way CommonMark reads them; a row whose cell count still
+  differs from the header's is a problem instead of a silent pass. A task table inside a code fence
   is ignored, a table right after the task table with no heading between is no
   longer read as tasks, and `**id**` in a header is read.
 - **Two integrity checks keep the reload honest.** When the project has a

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.5.1 -->
+<!-- planrails 0.6.0 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -116,8 +116,10 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   checks, run end to end, the way a user would.
 - **Use repo-relative paths** (`lib/digest/query.ts`), never absolute ones. They
   are clickable and they survive a move to another machine.
-- **Keep PLAN.md under ~2,000 words.** Trim prose before Learnings or Decisions.
-  History goes in LOG.md, not here.
+- **Keep PLAN.md under ~3,000 words.** It reloads into every session, so every
+  word is paid for again and again. Trim prose before Learnings or Decisions.
+  History goes in LOG.md, not here. Past the line, the checker prints a `note:` —
+  advice, not a failure: the run still exits 0, and you decide what to trim.
 - **Add the reload line.** In the project-root `CLAUDE.md`, under a short
   "Active plans" spot, add:
   ```
@@ -152,7 +154,8 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   https://github.com/vivmagarwal/planrails there. Add
   `node .project-management/planrails/check-plans.mjs` to the check command. Now the
   build fails if a task is marked done with no evidence, if an active plan has no
-  reload line, or if NOW points at a finished task. If the project is not Node,
+  reload line, if its NOW lost its RESUME line, or if NOW points at a finished
+  task. If the project is not Node,
   skip this; the plan still works, and you enforce the gate yourself.
 - **Check the plan before the first task.** You, or a fresh sub-agent with no
   chat context: open every path the plan names, start every proof command,
@@ -196,9 +199,11 @@ decide:
 - Its id is not listed: the claim is stale only when no other session in this
   checkout is live — then say so, take over, write your claim. When one is live,
   stop and ask; it may be the holder under a new id, after a branch or a fork.
-- `none`, or no line (an older plan): a busy session in this checkout, or plan
-  files dirty in `git status`: stop. Otherwise say what you saw in one line, write
-  your claim, go on.
+- `none`, or no line (an older plan): say what you saw in one line, write your
+  claim, go on — unless this plan's files are dirty in `git status`, or a busy
+  session in this checkout has its id on no plan's `session:` line; then stop
+  and ask. A busy peer whose id is on another plan's line is working that plan,
+  so two sessions can work two plans in one checkout side by side.
 - No `claude` command (another agent), or a plan shared across machines: there is
   no listing to consult. Git is the record: pull first, read a `doing` row with a
   fresh `updated:` stamp as someone's work in flight, and ask.
@@ -217,14 +222,20 @@ The loop for each task:
 
 1. **Check who holds the plan** (above), then **set it doing.** Change the status
    cell to `doing`. Update **NOW**, and put your session on its `session:` line
-   (`since` from `date` on a takeover; unchanged when it already names you).
+   (`since` from the shell clock on a takeover; unchanged when it already names
+   you).
 2. **Do the work.** Fix the cause, not the symptom. The simplest change that
    works, end to end.
 3. **Run the proof.** Right now, not from memory. Copy the exit code and the last
-   line of output. Take the time from `date`, never from memory.
+   line of output. Take the time from the shell clock (`date`; on Windows
+   `Get-Date`), never from memory.
 4. **Paste the evidence.** Into the task's evidence cell:
    `2026-09-12 14:20 · exit 0 · "6 passed"`. Exit 0, or the task is not done.
-5. **Set it done.** Only now. Update **NOW** to point at the next task.
+5. **Set it done.** Only now. A proof of `owner` is closed only by the person's
+   words with the date, never by you: until then the row is `blocked`, the
+   reason in its evidence cell, and RESUME says so.
+   Update **NOW** to point at the next task; NOW keeps its four lines and their
+   names, RESUME included, until the plan is retired.
 6. **Append an entry to LOG.md** — what landed, what is next, anything learned,
    any decision made.
 7. **If the task fought back, record the learning.** An error, a wrong turn, an
@@ -323,6 +334,12 @@ Each line here was paid for by a real failure in earlier planning systems:
   fixes.
 - **History stays out of the plan.** One plan grew a 16,000-word progress section,
   stamped two hours behind its own log. NOW is four lines; LOG.md is the history.
+- **The checker's notes advise; they never block.** A script can verify an exit
+  code, so that is a problem and fails the build. It can only suspect that a plan
+  is too long, so that is a note, and you judge. Four of four real plans had
+  outgrown the word line with nothing saying so. The check command already runs
+  before every commit and its output is already read, so a reminder there needs
+  no hook. A note needs a real failure behind it, or it is noise.
 - **Sub-agent findings are leads** because four spot-checked findings were each
   right in direction and wrong in number, and a wrong number becomes a wrong plan.
   Delegation is method, not machinery: a brief of one unit and nothing else worked.
@@ -364,20 +381,25 @@ status: active · opened <YYYY-MM-DD> · id: <kebab-id>
 ## NOW
 RESUME: <T2 — the one thing to do next, with the file; written for a stranger>
 NEXT: <T3 · T4 · …>
-updated: <YYYY-MM-DD HH:MM, from `date`>
+updated: <YYYY-MM-DD HH:MM, from the shell clock>
 session: <none, or the session working this plan: name · the first 8 characters of its session id · since YYYY-MM-DD HH:MM>
 
 ## How to work this plan
 Read NOW, then Rules and Learnings; do not re-read Context. One task at a time:
-1. Set it `doing`; point NOW at it; put your session on its `session:` line.
+1. Check who holds the plan (below); set it `doing`; point NOW at it; put your session on its `session:` line.
 2. Do the work: fix causes, not symptoms; the simplest change that works end to end.
-3. Run the proof now. Paste `YYYY-MM-DD HH:MM · exit N · "last line"` into evidence. Every stamp comes from `date` run at that moment, never typed from memory.
-4. `done` only if N is 0. Point NOW at the next task; append an entry to LOG.md: did, files, proof, next, learned.
+3. Run the proof now. Paste `YYYY-MM-DD HH:MM · exit N · "last line"` into evidence. Every stamp comes from the shell clock (`date`; on Windows `Get-Date`), never typed from memory.
+4. `done` only if N is 0. A proof of `owner` is closed only by the person's words with the date, never by you: until then the row is `blocked`, the reason in its evidence cell, and RESUME says so. Point NOW at the next task; append an entry to LOG.md: did, files, proof, next, learned.
 5. If it fought back, add a Learning: the trap, then the rule. A verified fact goes in Context, a choice in Decisions.
 
-NOW is four lines for a stranger; on a long task note the sub-step, and update it before any turn ends. Blocked: say so in NOW, reason in the evidence cell. A task you will not do is `dropped`; its row stays. After a compaction, `git status --short` shows the in-flight work. Edit this file with the editor or a quoted heredoc; an unquoted shell string eats backticks. A self-contained task may go to a sub-agent briefed with its row, Rules, Decisions, Learnings and Context; it writes to a named file and reports a few lines, which are leads; you run the proof before pasting evidence. If the project runs Node, `node .project-management/planrails/check-plans.mjs` must pass. Full method: `.project-management/planrails/PLANNER.md` §4.
+NOW is exactly these four lines, RESUME, NEXT, updated and session, written for a stranger; on a long task note the sub-step in RESUME, and update NOW before any turn ends. Blocked: say so in RESUME, reason in the evidence cell. A task you will not do is `dropped`; its row stays. After a compaction, `git status --short` shows the in-flight work. Edit this file with the editor tool; an unquoted shell string eats backticks. A self-contained task may go to a sub-agent briefed with its row, Rules, Decisions, Learnings and Context; it writes to a named file and reports a few lines, which are leads; you run the proof before pasting evidence. If the project runs Node, `node .project-management/planrails/check-plans.mjs` must pass. When no row is left open, done or dropped, close by PLANNER.md §5: proofs re-run, a fresh-context review, `status: done`, `session: none`, the reload line in CLAUDE.md wrapped in backticks. Full method: `.project-management/planrails/PLANNER.md` §4.
 
-The `session:` line names the one session working this plan: name · first 8 characters of its session id · since. Match by id; names change. `claude agents --json` lists every live session on this machine with `sessionId`, `cwd` and `status`; in Claude Code your id is `$CLAUDE_CODE_SESSION_ID`. Before any task goes `doing`, even when asked to continue: re-read NOW from disk, run that listing and `git status --short`. Stop, report what you found, and ask before writing to the plan, its files, or a commit if the line's id is live and not yours, or if the line is `none` or missing while another session in this checkout is busy or plan files are dirty. If the id is not listed and no other session in this checkout is live, the claim is stale: say so, take over. On `doing` and on a takeover, write your own name · id · since, from `date`. Without a `claude` command, or on another machine, git is the record: pull first, treat a fresh `doing` row as someone's work in flight, and ask. Other reloaded plans are context; work only the one assigned in this session, and say which.
+Who holds the plan. `session:` names the one session working it: `name · first 8 characters of its session id · since YYYY-MM-DD HH:MM`. Match by id, never by name: the line's 8 characters start a `sessionId` in the listing. Before any task goes `doing`, even when asked to continue: re-read NOW from disk, run `claude agents --json` (your own id is `$CLAUDE_CODE_SESSION_ID`) and `git status --short`, then:
+- the id is yours: go on.
+- the id is live and not yours: stop, report what you found, ask; write nothing.
+- the id is not listed: stale if no other session in this checkout is live; say so, take over, write your line. Else stop and ask.
+- `none`, or no line: write your line and go on, unless this plan's PLAN.md, LOG.md or the files its tasks name are dirty, or a busy session in this checkout has its id on no plan's `session:` line; then stop and ask.
+Work only the plan assigned in this session; other reloaded plans are context. Without a `claude` command, git is the record: pull first, and ask about a fresh `doing` row.
 
 ## Goal
 <4–5 sentences: what we are building and why. What is true when it ships. A mermaid diagram only if the architecture is non-trivial.>

package/README.md

@@ -161,7 +161,20 @@ structural check, biased toward catching a faked "done":
 - when the project has a `CLAUDE.md`, every active plan must be reloaded by
   `@.project-management/plans/<id>/PLAN.md` on its own line, and no such line may
   point at a plan that does not exist
-- an active plan's `RESUME` line must name a task that is still open
+- an active plan keeps its `RESUME` line, and that line must name a task that
+  is still open
+
+The checker also **advises without blocking**. What a script can only suspect, it
+prints as a `note:` before its final line; the run still exits 0, and the agent
+that ran the check decides. There is one today: an active `PLAN.md` over ~3,000
+words, because the plan reloads into every session and nothing else says when it
+has grown. Reminders ride on the check your agent already runs before every
+commit, so they need no hook.
+
+```
+check-plans: note: weekly-digest: PLAN.md is 3,588 words, over the ~3,000 line — it reloads into every session; move history to LOG.md and trim prose before Learnings or Decisions
+check-plans: 1 plan(s) ok — every completion claim has a proof and exit 0 evidence, active plans reload, NOW is current
+```
 
 `--verify` goes further and **runs** each proof again, with a timeout, and shows
 the last line a failing proof printed. Because it executes the commands written in
@@ -192,11 +205,16 @@ directory, so a second session can read the plan and start the task the first on
 is on. A plan's NOW names the session working it
 (`session: app-3f · 7c1d2e9a · since 2026-09-12 14:05`), and the plan's block tells
 every session, before it sets a task `doing`, to re-read that line, list the live
-sessions (`claude agents --json`; `ListAgents` inside Claude Code) and run
-`git status --short`, and to stop and ask when another live session holds the plan
-— even when you asked it to continue, because you can forget which window owns
-it. One plan per session, one session per plan; the other reloaded plans are
-context. The claim is a lead, not a lock: a line left by a closed terminal blocks
+sessions (`claude agents --json`, matching the line's id; `ListAgents` inside
+Claude Code names sessions but shows no id) and run `git status --short`, and to
+stop and ask when another live session holds the plan — even when you asked it to
+continue, because you can forget which window owns it. One plan per session, one
+session per plan; the other reloaded plans are context. A session assigned an
+unheld plan claims it and goes on, unless that plan's files are dirty or a busy
+peer in this checkout holds no plan, so two sessions can work two plans side by
+side. A plan
+written before 0.5 has no `session:` line; `init` points it out, and the
+changelog says what to add by hand. The claim is a lead, not a lock: a line left by a closed terminal blocks
 nobody, and the checker ignores the line. Field-tested with headless sessions: a
 second session told "Continue the active plan." stopped and asked while the first
 was live — by its id, after the first had been renamed — took over when it was
@@ -214,6 +232,8 @@ installed files under `.project-management/planrails/`. 0.4.0 makes the plan
 carry its own loop, makes the checker demand `exit 0` and check the reload line,
 and teaches the executor to brief sub-agents from the plan. 0.5.0 names the
 session working a plan and has every session check for a live holder before it
-touches the plan. See [`CHANGELOG.md`](CHANGELOG.md).
+touches the plan. 0.6.0 lets the checker advise without blocking: a `note:` for
+what a script can only suspect, starting with a plan that has outgrown its word
+line. See [`CHANGELOG.md`](CHANGELOG.md).
 
 MIT.

package/bin/planrails.mjs

@@ -15,10 +15,10 @@
  *
  *   planrails --version | --help
  */
-import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync, realpathSync } from "node:fs";
+import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync, realpathSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkPlans } from "../tools/check-plans.mjs";
+import { checkPlans, isActive, formatNotes } from "../tools/check-plans.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const version = () => JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
@@ -77,6 +77,14 @@ function init(args) {
   const keep = join(plans, ".gitkeep");
   if (!existsSync(keep)) { writeFileSync(keep, ""); console.log("  + .project-management/plans/"); }
   else console.log("  = .project-management/plans/ (your plans are never touched)");
+  // A plan written before 0.5 has no session: line and an older block. init never
+  // touches a plan, so say which ones need the by-hand update from CHANGELOG 0.5.0.
+  for (const name of existsSync(plans) ? readdirSync(plans) : []) {
+    const pf = join(plans, name, "PLAN.md");
+    if (!existsSync(pf)) continue;
+    const text = readFileSync(pf, "utf8");
+    if (isActive(text) && !/^session:/m.test(text)) console.log(`  ! plan ${name} predates 0.5: add a session: line to its NOW and replace its "How to work this plan" block with the template's in .project-management/planrails/PLANNER.md; until then a second session cannot tell who holds it`);
+  }
   const loose = ["PLANNER.md", "check-plans.mjs"].filter((f) => existsSync(join(pm, f)));
   if (loose.length) console.log(`  ! 0.2.x files at .project-management/ root: ${loose.join(", ")} — the copies now live in planrails/; delete the loose ones and point your check command at .project-management/planrails/check-plans.mjs`);
 
@@ -95,7 +103,8 @@ function check(args) {
   const root = dirArg(args);
   if (!existsSync(root)) { console.error(`planrails check: --dir path does not exist: ${root}`); return 2; }
   const verify = args.includes("--verify");
-  const { plans, problems } = checkPlans({ root, verify });
+  const { plans, problems, notes } = checkPlans({ root, verify });
+  process.stdout.write(formatNotes(notes));
   if (!plans.length && !problems.length) { console.log("check-plans: no plans under .project-management/plans/ — nothing to check"); return 0; }
   if (problems.length) {
     console.error(`check-plans: ${problems.length} problem(s):\n${problems.map((p) => `  - ${p}`).join("\n")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Plans that survive a lost session, and \"done\" that means done. A planner prompt and a tiny checker.",
   "type": "module",
   "license": "MIT",

package/tools/check-plans.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// planrails 0.5.1
+// planrails 0.6.0
 /**
  * check-plans — the machine-checked rails of the planner.
  *
@@ -11,10 +11,14 @@
  *  - an active plan must reload: when the project has a CLAUDE.md, it must carry
  *    `@.project-management/plans/<id>/PLAN.md` on its own line, and no such line
  *    may point at a plan that does not exist. (Skipped when there is no CLAUDE.md.)
- *  - NOW must be current: the RESUME line of an active plan may not name only
- *    finished tasks. A retired plan says `status: done` (or paused) and is exempt
+ *  - NOW must be current: an active plan with a NOW section keeps its RESUME
+ *    line, and that line may not name only finished tasks. A retired plan says `status: done` (or paused) and is exempt
  *    from both; a plan with no status line counts as active.
  *
+ * It also prints notes: what a script can only suspect (an active PLAN.md over
+ * ~3,000 words, which reloads into every session). A note goes to stdout before
+ * the final line and never changes the exit code; whoever ran the check decides.
+ *
  * The rule is biased toward catching a faked "done": a task counts as a
  * completion claim UNLESS its status is blank or an explicit not-done word
  * (todo, doing, blocked, …). So no spelling of "done" — done, completed, ✅,
@@ -229,8 +233,11 @@ export function checkPlan({ id, text, verify = false, run = null }) {
       if (code !== 0) problems.push(`${id} ${t.id}: proof re-run failed — \`${cmd}\` exited ${code}${r.last ? ` — ${r.last}` : ""}`);
     }
   }
-  // NOW must point somewhere live: a RESUME line that names only finished tasks is stale.
+  // NOW must point somewhere live: an active plan keeps its RESUME line, and a
+  // RESUME line that names only finished tasks is stale.
   if (isActive(text)) {
+    const ls = text.split(/\r?\n/), fm = fenceMask(ls);
+    if (ls.some((l, k) => !fm[k] && /^#{1,6}\s+NOW\b/.test(l)) && !ls.some((l, k) => !fm[k] && /^\s*RESUME:/.test(l))) problems.push(`${id}: NOW has no RESUME line — an active plan keeps RESUME, NEXT, updated and session; a finished plan says status: done`);
     const named = resumeIds(text, tasks.map((t) => t.id).filter(Boolean));
     if (named.length && named.every((n) => tasks.some((t) => t.id === n && isCompletionClaim(t.status))))
       problems.push(`${id}: NOW is stale — RESUME names ${named.map((n) => n.replace(/[`*_]/g, "")).join(", ")}, which ${named.length === 1 ? "is" : "are all"} done; point it at the next open task, or set the plan's status to done`);
@@ -292,9 +299,27 @@ export function runProof(cmd, root, timeoutMs) {
   return { code: r.status ?? 1, last };
 }
 
-/** Check every plan under root. Returns { plans, problems }. `--verify` re-runs proofs, each with a timeout (10 min by default). */
+/**
+ * Notes on one plan: what a script can only suspect. A note prints and the run
+ * still exits 0; whoever ran the check decides. Only an active plan gets one —
+ * a retired plan does not reload, so its size costs nothing.
+ */
+export const WORD_LINE = 3000;
+const commas = (n) => String(n).replace(/\B(?=(\d{3})+$)/g, ","); // no Intl: a Node built without it would drop the comma
+export function planNotes({ id, text }) {
+  const notes = [];
+  if (!isActive(text)) return notes;
+  const words = text.split(/\s+/).filter(Boolean).length;
+  if (words > WORD_LINE) notes.push(`${id}: PLAN.md is ${commas(words)} words, over the ~${commas(WORD_LINE)} line — it reloads into every session; move history to LOG.md and trim prose before Learnings or Decisions`);
+  return notes;
+}
+/** The notes as printed: one "note:" line each, newline-terminated, or "" when there are none. */
+export const formatNotes = (notes) => notes.map((n) => `check-plans: note: ${n}\n`).join("");
+
+/** Check every plan under root. Returns { plans, problems, notes }. `--verify` re-runs proofs, each with a timeout (10 min by default). */
 export function checkPlans({ root = ".", verify = false, verifyTimeoutMs = 10 * 60 * 1000 } = {}) {
   const { plans, problems } = findPlans(root);
+  const notes = [];
   const run = verify ? (cmd) => runProof(cmd, root, verifyTimeoutMs) : null;
   const claudeMd = join(root, "CLAUDE.md");
   const reloads = existsSync(claudeMd) ? reloadLines(readFileSync(claudeMd, "utf8")) : null;
@@ -302,11 +327,12 @@ export function checkPlans({ root = ".", verify = false, verifyTimeoutMs = 10 *
     let text = "";
     try { text = readFileSync(path, "utf8"); } catch (e) { problems.push(`${id}: cannot read ${path} (${e.code || e.message})`); continue; }
     problems.push(...checkPlan({ id, text, verify, run }));
+    notes.push(...planNotes({ id, text }));
     if (reloads && isActive(text) && !reloads.has(id))
       problems.push(`${id}: the plan is active but CLAUDE.md has no reload line — add "@.project-management/plans/${id}/PLAN.md" on its own line, outside backticks, or the plan will not survive a compaction`);
   }
   if (reloads) for (const id of reloads) if (!plans.some((p) => p.id === id)) problems.push(`CLAUDE.md reloads "${id}" but .project-management/plans/${id}/PLAN.md does not exist`);
-  return { plans, problems };
+  return { plans, problems, notes };
 }
 
 // --- CLI ----------------------------------------------------------------------
@@ -327,7 +353,8 @@ if (isMain) {
   const verify = args.includes("--verify");
   const root = flagValue(args, "--root") || flagValue(args, "--dir") || ".";
   if (!existsSync(root)) { process.stderr.write(`check-plans: --root path does not exist: ${root}\n`); process.exit(2); }
-  const { plans, problems } = checkPlans({ root, verify });
+  const { plans, problems, notes } = checkPlans({ root, verify });
+  process.stdout.write(formatNotes(notes));
   if (!plans.length && !problems.length) { process.stdout.write("check-plans: no plans under .project-management/plans/ — nothing to check\n"); process.exit(0); }
   if (problems.length) {
     process.stderr.write(`check-plans: ${problems.length} problem(s):\n${problems.map((p) => `  - ${p}`).join("\n")}\n`);