planrails 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 0.4.0 — 2026-09-13
+
+A review of 0.3.0 against a real multi-session plan, the Claude Code docs, and
+the planning systems that came before it found where the promise leaked, and this
+release closes the leaks. Two of them are behaviour changes in the checker; the
+rest is method. Everything stays a prompt plus one script, and `init` still writes
+nothing but its two files.
+
+- **Evidence must record the proof's exit code, and it must be 0.** A command
+  proof's evidence cell now needs `exit 0` (or `exit code 0`, `exited 0`); a bare
+  word such as "done" or "✅", or a pasted `exit 1`, fails the build. This is the
+  format `PLANNER.md` always prescribed; the checker now checks it, and every
+  `exit N` in the cell counts. A proof cell must be exactly one backticked command
+  or the word `owner`, not prose with a span in it; an owner-closed task records
+  the owner's words with the date. **This is the one change that can fail a plan
+  that passed before** — and only a plan the method already called not done.
+  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
+  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
+  `CLAUDE.md`, every active plan must be reloaded by
+  `@.project-management/plans/<id>/PLAN.md` on its own line, outside backticks and
+  fences, 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, so a stale NOW is
+  caught. Both are skipped for a retired plan, so retiring a plan now means
+  setting `status: done` and then backticking its line; a plan with no status
+  line counts as active, the safe direction; the reload check is skipped when
+  there is no `CLAUDE.md`.
+- **`--verify` has a timeout** (10 minutes per proof) and reports the last line a
+  failing proof printed, instead of hanging or saying nothing.
+- **The checker can no longer silently exit 0.** Its entry guard compared paths
+  textually, so run through a symlink, or through `/tmp` on macOS, it printed
+  nothing and passed. It now compares real paths, and a test runs it as a command,
+  and through a symlink, on a plan with a known problem. The same fix went into
+  the CLI, which npm installs as a symlink.
+- **The plan carries its own loop.** The PLAN.md template's HTML comments became a
+  "How to work this plan" block: set doing, run the proof now with the time from
+  `date`, paste `exit N`, done only on 0, update NOW, append a LOG entry, record a
+  learning, say where a blocked reason goes, run `git status --short` after a
+  compaction, and how to brief a sub-agent. A fresh session with only `CLAUDE.md`
+  and the plan completed a two-task plan by the loop and retired it correctly.
+- **The method (PLANNER.md) gained:** the project-root `CLAUDE.md` named as the
+  always-loaded file; "check the plan before the first task"; a task per sitting,
+  permanent task ids and `dropped` rows; phase-end end-to-end tasks; one active
+  plan per repo; a ~2,000-word budget that trims prose before Learnings; "delegate
+  a self-contained task" with a five-line brief, one writer per file, output to a
+  named file, and the main session running the proof; the engineering standards
+  (fix the cause, a red test starts an investigation, never weaken an assertion);
+  a fresh-context review at close; retiring a plan by backticking its line, never
+  by moving it under a "Finished" heading, which still imports; and the evidence
+  behind each rule. A test pins the template inside `PLANNER.md` to the checker,
+  so the two cannot drift apart.
+- **`init` updates the tool and never the plans.** Both copied files carry
+  `planrails X.Y.Z` near the top. A re-run replaces an older or unstamped copy
+  under `.project-management/planrails/` and says what it replaced, keeps a
+  same-version copy you edited unless `--force`, never writes into `plans/`, and
+  points out 0.2.x files left at the `.project-management/` root. `--root` and
+  `--dir` are accepted everywhere. The CLI runs correctly through npm's bin
+  symlink.
+- The `/plan` skill reads the project's own copy of `PLANNER.md` and says to run
+  `init` if it is missing, so there is one copy per project, not three. The README
+  says plainly that automatic reload is Claude Code's; other agents open the plan
+  by hand. The worked example carries the new block and a `CLAUDE.md` with the
+  reload line, so it exercises all three rails, and its log agrees with its
+  learnings. The README, the CLI's next steps and `PLANNER.md` use one start
+  sentence, the one that makes the agent report ready and wait. This repo's own plan for this release lives in
+  `.project-management/plans/self-sufficient-plan/` and is gated by the checker it
+  ships, in CI. 70 tests.
+
 ## 0.3.0 — 2026-09-12
 
 Two changes, both asked for by a user planning a long, multi-session feature:

package/PLANNER.md

@@ -1,3 +1,4 @@
+<!-- planrails 0.4.0 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -7,9 +8,10 @@ This file is the whole method. You, the model, do the setup by following the
 steps below: make the folders, write the plan, wire the reload line, and — if the
 project runs Node — copy in one small checker.
 
-**How a person starts you.** They say something like *"Familiarise yourself with
-these instructions and tell me when you are ready to plan the next feature with
-me."* When they do, run **§1 Get ready**, give the eight-line report, and stop.
+**How a person starts you.** They say something like *"Follow
+`.project-management/planrails/PLANNER.md` and tell me when you are ready to plan
+the next feature with me."* When they do, run **§1 Get ready**, give the
+eight-line report, and stop.
 Do not start planning until they answer.
 
 ---
@@ -20,21 +22,21 @@ Two files per plan, under `.project-management/plans/<id>/`:
 
 - **PLAN.md** — the map and the tracker. What we are building, the tasks, and the
   proof each task is done. A fresh session reads this and knows the whole state.
-- **LOG.md** — append-only history. One dated line per landed piece of work.
+- **LOG.md** — append-only history. One dated entry per landed piece of work.
 
 The plan is written for an **executor who never saw this prompt** — maybe a fresh
 session of you after the chat is gone. So everything the executor needs goes in
-the plan. If it is not in the plan, it does not exist.
+the plan, including how to work it. If it is not in the plan, it does not exist.
 
 Three rules make the plan trustworthy. They are the whole point of this system:
 
-1. **The reload line.** One line in the project's always-loaded file re-opens the
+1. **The reload line.** One line in the project-root `CLAUDE.md` re-opens the
    plan after every compaction, so the state is never lost.
 2. **Proof before work.** Every task names the command that will prove it done
    *before* the work starts. No command, no way to fake it later.
 3. **Evidence at close.** A task is done only when its proof was run and its exit
    code and last line are pasted into the plan. An empty evidence cell is not
-   done, whatever the status column says.
+   done, whatever the status column says. Exit 0, or it is not done.
 
 The plan is also the project's memory. Besides the tasks, PLAN.md carries the
 **Rules** you must not break, the **Decisions** you made and why, and the
@@ -50,13 +52,14 @@ struggle. That is how you stop paying for the same mistake twice.
 Do this before you ask the person anything. Read the project; do not make them
 tell you what the repo already says.
 
-1. **Read the always-loaded file** — `CLAUDE.md`, else `AGENTS.md`, else
-   `README.md`. Find the stack, the package manager, the **check command** (the
-   one run before every commit), and the **test command**.
+1. **Read the always-loaded file** — the project-root `CLAUDE.md`, else
+   `AGENTS.md`, else `README.md`. Find the stack, the package manager, the
+   **check command** (the one run before every commit), and the **test command**.
 2. **List `docs/`** and read the ones this feature touches. Use sub-agents for
    long files so your own context stays clear. Record each relevant doc's path
    and one line of what it holds.
-3. **Read `.project-management/`** — existing plans and prose. Note the active one.
+3. **Read `.project-management/`.** Read the active plan in full; list the
+   finished ones by id only.
 4. **Read the last ~20 commits** (`git log --oneline -20`) for how the code moves.
 
 **A sub-agent's finding is a lead, not a fact.** If it names a file and line, you
@@ -99,29 +102,46 @@ Create `.project-management/plans/<id>/PLAN.md` and `LOG.md` from the two
 templates at the end of this file (§ Template — PLAN.md, § Template — LOG.md).
 Pick a short kebab-case `<id>` (`weekly-digest`). Then:
 
+- **Write for a senior engineer.** Decisions and context, not obvious steps.
 - **Name the proof for every task before any work.** The proof is the command
   that shows the task is done: a test, a build, a check. A task that no command
   can prove is proven by the person's word — write `owner` in the proof column
-  and record their words and the date in evidence when they give it.
+  and record their words and the date in evidence when they give it (the checker
+  wants the date there). The proof cell is exactly one `command`, or `owner`.
+- **A task is one sitting's work with one proof.** Longer than that is two tasks.
+  Task ids are permanent: never renumber, and a task you will not do keeps its
+  row with status `dropped`.
+- **A plan with phases ends each phase with a task** whose proof is the Done-when
+  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 ~1,500 words.** History goes in LOG.md, not here.
-- **Add the reload line.** In the always-loaded file, under a short "Active plans"
-  spot, add:
+- **Keep PLAN.md under ~2,000 words.** Trim prose before Learnings or Decisions.
+  History goes in LOG.md, not here.
+- **Add the reload line.** In the project-root `CLAUDE.md`, under a short
+  "Active plans" spot, add:
   ```
   @.project-management/plans/<id>/PLAN.md
   ```
   Put it on its own line, outside any code block — an `@` import wrapped in
   backticks does not load. Claude Code re-reads that file, and everything it
   imports, at every session start and after every compaction, so the plan comes
-  back on its own. (For a tool that does not do `@`-imports, put the plan's path
-  in `AGENTS.md` and open it by hand at the start of each session.)
+  back on its own. One active plan per repo at a time; to pause another, set its
+  header to `status: paused` and wrap its line in backticks. (For a tool that
+  does not do `@`-imports, put the plan's path in `AGENTS.md` and open it by hand
+  at the start of each session.)
 - **Wire the checker, if the project runs Node and has a check command.**
   `npx planrails init` already put it at `.project-management/planrails/check-plans.mjs`;
-  if you did not run init, copy this repo's `tools/check-plans.mjs` there. Add
+  if you did not run init, copy `tools/check-plans.mjs` from
+  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 the project is not Node,
+  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,
   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,
+  confirm the reload line loads and the checker passes, and log what you changed.
+  A plan can name a file that does not exist, or a proof that proves nothing;
+  ten minutes here saves an hour later.
 
 ---
 
@@ -130,18 +150,21 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
 **At the start of every session, read the plan back first.** The reload line has
 already loaded PLAN.md. Read **NOW**, then the **Rules** and the **Learnings**,
 before you touch anything. The Learnings are mistakes a past session already paid
-for — read them and you skip the struggle instead of repeating it.
+for — read them and you skip the struggle instead of repeating it. After a
+compaction, also run `git status --short`: it is the journal of in-flight work
+that NOW may not mention yet.
 
 The loop for each task:
 
 1. **Set it doing.** Change the status cell to `doing`. Update **NOW**.
-2. **Do the work.**
+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.
+   line of output. Take the time from `date`, never from memory.
 4. **Paste the evidence.** Into the task's evidence cell:
-   `2026-09-12 14:20 · exit 0 · "6 passed"`.
+   `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.
-6. **Append one line to LOG.md** — what landed, what is next, anything learned,
+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
    hour lost before you found the cause — add it to PLAN.md under **Learnings** as
@@ -149,8 +172,35 @@ The loop for each task:
    the rule, because Learnings reloads every session and the log does not.
 
 **Update NOW before you end any turn.** NOW is the first thing a fresh session
-reads. If it is stale, the next session repeats your work or starts in the wrong
-place.
+reads, so write it for a stranger. On a long task, note the sub-step in NOW at
+each checkpoint. If a task cannot proceed, set it `blocked`, put the reason in its
+evidence cell, and say so in NOW. If NOW is stale, the next session repeats your
+work or starts in the wrong place.
+
+**A red test starts an investigation**, not an edit: is the product wrong, the
+test stale, or the environment wrong? Decide which before changing anything, and
+never weaken an assertion to get green.
+
+**Edit the plan through the editor tool** or a quoted heredoc. An unquoted shell
+string eats backticks and quotes, and takes your evidence with them.
+
+**Delegate a self-contained task.** When a task's row, plus the Rules, Decisions,
+Learnings and its Context lines, is enough to do it, hand it to a sub-agent with
+exactly that brief and nothing else:
+
+```
+Task <id> of <plan path>: <the row's task text>
+Rules / Decisions / Learnings: <the plan's, verbatim>   Context: <the lines this task touches>
+Write your output to <file>. One writer per file; do not edit PLAN.md or LOG.md.
+Proof: <the command>. Report: exit code, last line, files touched, anything learned.
+```
+
+Validate one unit before you scale to many. Reconcile the report against the
+files it wrote, not against its reply. Its result is a lead: run the proof
+yourself before you paste evidence. Bulk reading or bulk processing always goes
+to sub-agents that write to disk and report a few lines; the main session never
+holds bulk output, because everything it holds rides along on every later call.
+Keep in the main session only the tasks that need the whole picture.
 
 **Your judgement outranks the gate.** The gate is a proposal from a script that
 cannot see the screen. You can.
@@ -169,14 +219,21 @@ the task `blocked` with the reason, and stop. Do not hand-fix state to look done
 
 1. **Re-run every proof.** A plan closes on what the checks say now, not on their
    last recorded run. Paste fresh evidence.
-2. **Update the docs** the work changed — in the same step, per the project's
+2. **Fresh-context review.** A sub-agent, or a new session, with the plan and
+   nothing from the chat, checks the work against **Done when** and reports what
+   it cannot see passing. Fix what it finds. Two such reviews once found 26
+   defects the self-tests had passed.
+3. **Update the docs** the work changed — in the same step, per the project's
    documentation guide if it has one.
-3. **Retire the plan.** Move its reload line out of "Active plans" into a
-   "Finished" list (or delete the line). The plan files stay on disk; they are the
-   record.
-4. **Graduate any lasting learning.** A learning that is true beyond this feature
+4. **Retire the plan.** Set its header to `status: done`, then wrap its reload
+   line in backticks, or delete it. Do not move a bare `@` line under a
+   "Finished" heading: it still imports, and every retired plan would reload
+   forever. The status comes first: the checker holds an `active` plan to its
+   reload line. The plan files stay on disk; they are the record.
+5. **Graduate any lasting learning.** A learning that is true beyond this feature
    moves to the always-loaded file (`CLAUDE.md` / `AGENTS.md`), so it outlives the
-   plan you are retiring. One that was only about this work retires with it.
+   plan you are retiring. A learning that a check could enforce becomes a test.
+   One that was only about this work retires with it.
 
 ---
 
@@ -185,19 +242,29 @@ the task `blocked` with the reason, and stop. Do not hand-fix state to look done
 Each line here was paid for by a real failure in earlier planning systems:
 
 - **The reload line** replaces a whole SessionStart hook. Re-reading the
-  always-loaded file after compaction is something the tool already does.
+  always-loaded file after compaction is something the tool already does. Hooks
+  that tried to do more misfired: a crashing pre-tool hook blocks the very call,
+  a read guard was wrong twice about sub-agents, a compaction journal came out as
+  command stubs.
 - **Proof before work** exists because a checkbox lies. One project marked a phase
   "done" three times while it was not; nothing in a status column could catch it.
   A named command that must be run and pasted can.
 - **Evidence at close** is the one machine-checkable rail worth keeping. The
-  checker enforces exactly this and nothing else.
+  checker enforces it — exit 0, not a word — plus two integrity checks that keep
+  the reload honest: the reload line exists, and NOW names a live task. Both
+  failures were silent in real plans.
+- **The plan carries its own loop** because a session that never saw this file
+  gets only PLAN.md back. It knew where it was; it did not know how to work.
 - **Learnings live in the plan, not only the log.** The log is history a fresh
   session does not re-read; the plan is reloaded every session. A mistake written
   as a rule, where the next session will see it, is the only kind that stops being
   repeated. The same struggle coming back in a new chat is the exact failure this
   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 three lines; LOG.md is the history.
 - **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.
 - **Repo-relative paths** because absolute paths break on the next machine, and a
   path a reader cannot open is worse than none.
 - **Nothing the method needs is installed.** `npx planrails init` only copies two
@@ -216,7 +283,8 @@ Learnings are plain sections of the plan, not new machinery.)
 
 Create `.project-management/plans/<id>/PLAN.md` with this shape. Keep the column
 names exactly as shown. The checker reads `id`, `status`, `proof` and `evidence`
-by name, in any order; `task` is there for you to read.
+by name, in any order; `task` is there for you to read. Keep the "How to work this
+plan" block as it is: it is what a session that never saw this file will follow.
 
 ````markdown
 # <Feature> — plan
@@ -224,25 +292,31 @@ by name, in any order; `task` is there for you to read.
 status: active · opened <YYYY-MM-DD> · id: <kebab-id>
 
 ## NOW
-RESUME: <the one thing to do next, with the file — e.g. "T2: render the digest (lib/digest/render.ts)">
+RESUME: <T2 — the one thing to do next, with the file; written for a stranger>
 NEXT: <T3 · T4 · …>
-updated: <YYYY-MM-DD HH:MM>
+updated: <YYYY-MM-DD HH:MM, from `date`>
+
+## 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.
+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.
+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 three 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.
 
 ## Goal
-<4–5 sentences: what we are building and why. What is true when it ships.>
-<!-- If the architecture is non-trivial, add a mermaid diagram here. Skip it for a simple change. -->
+<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.>
 
 ## Done when
-- <a command or check that must pass — e.g. `npm run check` exits 0>
+- <a command that must exit 0 — e.g. `npm run check`>
 - <a real-world check — e.g. a digest email arrives for a test user with 5 posts>
 
 ## Must not change
 - <the rails, data, or public shape this work must not break>
 
 ## Tasks
-<!-- status: todo | doing | done | blocked. proof: a `command` in backticks, or `owner`
-     for a task only the owner's word can close. evidence: pasted after the proof runs —
-     required for a done task. -->
 | id | task | status | proof | evidence |
 |----|------|--------|-------|----------|
 | T1 | <what to do> (<path>) | todo | `<command that proves it>` | |
@@ -250,7 +324,6 @@ updated: <YYYY-MM-DD HH:MM>
 | T3 | update the docs this work changed | todo | owner | |
 
 ## Rules for this plan
-<!-- Short. These stay in the executor's context the whole time. Max ~15 lines. -->
 - <a rule that governs this area — e.g. "every email goes through lib/email, never a bare send">
 
 ## Decisions
@@ -259,15 +332,10 @@ updated: <YYYY-MM-DD HH:MM>
 | <YYYY-MM-DD> | <what was chosen> | <the reason and what it rules out> |
 
 ## Learnings
-<!-- Mistakes already paid for, so no later session repeats them. Each line: the
-     trap, then the rule it taught, with the real case. Not a Rule (a constraint
-     known up front) and not a Decision (a choice between options) — a learning is
-     what a failure taught you. Add one the moment a task fights back. This section
-     reloads with the plan every session; that is what makes the lesson stick. -->
 - <the trap you hit> → <the rule that avoids it> (<the real case, one line>)
 
 ## Context (read during planning — do not re-read)
-- <path> — <one line of what it holds>
+- <path> — <one line of what it holds; mark a sub-agent's unverified finding as a lead>
 ````
 
 ## Template — LOG.md

package/README.md

@@ -7,13 +7,17 @@ Long tasks lose their thread. A coding session compacts or ends, and the next on
 starts blind: it repeats work, or it trusts a status line that says "done" over
 work that is not. planrails fixes that with three plain rules and almost no code.
 
-1. **The plan reloads itself.** One line in the file your agent always reads
-   re-opens the plan after every compaction. The state is never lost.
+1. **The plan reloads itself.** One line in your project's root `CLAUDE.md`
+   re-opens the plan after every compaction, and the plan carries its own
+   operating loop, so a session that never saw the planner prompt still works it
+   correctly. (Claude Code reloads it for you; another agent opens it by hand.)
 2. **Every task names its proof before the work starts** — the command that will
    show it is done. No command, no way to fake it later.
-3. **A task is done only when its proof was run and pasted in.** An empty evidence
-   cell is not done, whatever the status says. A small, dependency-free checker
-   enforces this in your build.
+3. **A task is done only when its proof was run and its exit code pasted in.** An
+   empty evidence cell, a bare word, or a recorded `exit 1` is not done, whatever
+   the status says. A small, dependency-free checker enforces this in your build,
+   and also checks that every active plan has its reload line and that NOW points
+   at a task that is still open.
 
 It works in any project — Node, Python, Go, a monorepo, Windows — because it adds
 two files and changes nothing else.
@@ -30,15 +34,17 @@ npx planrails init
 
 That copies two files into `.project-management/planrails/` and makes the
 `plans/` folder. It writes **nothing else** — no `package.json`, no `npm install`,
-no hooks, no edits to your `CLAUDE.md`. Run it again any time; it skips files that
-already exist. What lands:
+no hooks, no edits to your `CLAUDE.md`. Run it again any time to update: it brings
+the two planner files up to the package version and tells you what it replaced,
+keeps a same-version copy you edited unless you pass `--force`, and never touches
+your plans. What lands:
 
 ```
 .project-management/
   planrails/
     PLANNER.md        the prompt your agent follows to plan and execute
     check-plans.mjs   the checker (the one machine-enforced rail)
-  plans/              your plans will live here, one folder each
+  plans/              your plans live here, one folder each (a .gitkeep holds the folder)
 ```
 
 Then, two steps:
@@ -71,8 +77,8 @@ The command is the same; the difference is what your agent sees.
 - **Existing project:** the agent first reads your `CLAUDE.md`/`README`, your
   `docs/`, and recent commits, and reports what it found before planning — so the
   plan fits how your code already works. `init` is safe to run in a project that
-  already has files or its own `.project-management/`; it only adds, never
-  overwrites (without `--force`).
+  already has files or its own `.project-management/`: it only writes its two
+  planner files, updating an older copy, and never touches a plan.
 
 ### Without npm, or a non-Node project
 
@@ -88,51 +94,76 @@ planner method does not depend on any language.
 
 ### As a `/plan` command in Claude Code
 
-Copy [`skill/`](skill) to `~/.claude/skills/plan/`, and put a copy of `PLANNER.md`
-beside it in the same folder. Then `/plan` starts the same flow in any project.
+Copy [`skill/`](skill) to `~/.claude/skills/plan/`. Then `/plan` starts the same
+flow in any project that has run `npx planrails init` — the skill reads the
+project's own copy of `PLANNER.md`, so every project follows the version it has.
 
 ## How a plan works
 
 Each plan is two files: `PLAN.md` (the map and tracker) and `LOG.md` (append-only
-history). `PLAN.md` also carries the plan's memory — the rules to keep, the
-decisions made, and the **learnings** (a mistake, written as the rule that avoids
-it). Because the reload line brings `PLAN.md` back at the start of every session, a
-lesson from one chat is read by the next one before it repeats the struggle. The
-top of `PLAN.md` is what a fresh session reads first:
+history). `PLAN.md` carries a short "How to work this plan" block — the loop a
+session follows even if it never saw the planner prompt — and the plan's memory:
+the rules to keep, the decisions made, and the **learnings** (a mistake, written
+as the rule that avoids it). Because the reload line brings `PLAN.md` back at the
+start of every session, a lesson from one chat is read by the next one before it
+repeats the struggle. The top of `PLAN.md` is what a fresh session reads first. Abridged from
+[`examples/weekly-digest/`](examples/weekly-digest), which also shows the
+`CLAUDE.md` line that reloads it:
 
 ```
+# Weekly digest email — plan
+
+status: active · opened 2026-09-12 · id: weekly-digest
+
 ## NOW
-RESUME: T2 — render the digest through lib/email (lib/digest/render.ts)
-NEXT: T3 schedule · T4 docs
+RESUME: T2 — render the digest through the email seam (lib/digest/render.ts)
+NEXT: T3 schedule the Monday send · T4 docs
 updated: 2026-09-12 14:20
 
+## How to work this plan
+(the loop a session follows: set doing, run the proof, paste exit N, done on 0, update NOW, log it)
+
 ## Tasks
 | id | task | status | proof | evidence |
 |----|------|--------|-------|----------|
-| T1 | the digest query (lib/digest/query.ts) | done  | `npx vitest run tests/digest.test.ts` | 2026-09-12 14:05 · exit 0 · "6 passed" |
-| T2 | render through the email seam       | doing | `npx vitest run tests/render.test.ts` | |
+| T1 | the digest query (lib/digest/query.ts) | done  | `npx vitest run tests/digest/query.test.ts` | 2026-09-12 14:05 · exit 0 · "6 passed" |
+| T2 | render through the email seam       | doing | `npx vitest run tests/digest/render.test.ts` | |
 ```
 
-The full method — how the agent gets ready, interviews you, writes the plan, and
-runs one task at a time — is in [`PLANNER.md`](PLANNER.md). A complete worked plan
-is in [`examples/weekly-digest/`](examples/weekly-digest).
+The full method — how the agent gets ready, interviews you, writes the plan,
+checks it before the first task, runs one task at a time, briefs a sub-agent with
+just a task's row and the plan's rules, and closes with a fresh-context review —
+is in [`PLANNER.md`](PLANNER.md). A complete worked plan is in
+[`examples/weekly-digest/`](examples/weekly-digest).
 
 ## The checker
 
 ```bash
-node .project-management/planrails/check-plans.mjs          # done tasks must name a proof and carry evidence
-node .project-management/planrails/check-plans.mjs --verify # also re-run each done task's proof, expect exit 0
-npx planrails check                                         # the same, using the latest published checker
+node .project-management/planrails/check-plans.mjs            # done needs a proof and exit 0 evidence; the plan reloads; NOW is current
+node .project-management/planrails/check-plans.mjs --verify   # also re-run each done task's proof, expect exit 0
+node .project-management/planrails/check-plans.mjs --root DIR # check another folder (--dir works too)
+npx planrails check                                           # the same, with the published package's checker, which may be newer than your copy
 ```
 
 No dependencies. Node 20+, any OS (Windows included). The default is a fast
-structural check: every task that claims to be finished must name a proof and
-carry pasted evidence, and no spelling of "done" can slip past it.
-
-`--verify` goes further and **runs** each proof again. Because it executes the
-commands written in the plan, use it only on plans you trust — run the default
-structural check in CI that builds untrusted pull requests, and keep `--verify`
-for your own branch or a trusted pipeline.
+structural check, biased toward catching a faked "done":
+
+- every task that claims to be finished must name a proof — exactly one
+  `command` in backticks, or the word `owner` — and its evidence must record the
+  command's exit code, which must be 0; a bare word, an empty cell, or `exit 1`
+  fails. An owner-closed task records the owner's words with the date
+- no spelling of "done" slips past it, and a table row it cannot read (a stray
+  pipe or backtick) fails closed instead of passing
+- 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
+
+`--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
+the plan, use it only on plans you trust — run the default structural check in CI
+that builds untrusted pull requests, and keep `--verify` for your own branch or a
+trusted pipeline.
 
 ## On a team
 
@@ -140,7 +171,8 @@ for your own branch or a trusted pipeline.
   exits 0 when there are no plans, so a teammate who never uses planrails is
   unaffected.
 - **The reload line is a plain file include.** `@.project-management/plans/…` in
-  `CLAUDE.md` just tells Claude Code to load that file; it commits like any doc.
+  the root `CLAUDE.md` just tells Claude Code to load that file; it commits like
+  any doc. Other agents do not import it: open the plan by hand at session start.
 - **Decide whether to commit `.project-management/`.** Committing it shares plans
   and lets CI run the checker. If your repo gitignores it, the checker still runs
   locally and the plan still reloads for whoever has the files.
@@ -153,7 +185,9 @@ review found ten data-loss and silent-failure paths in that surface, and the
 monorepos and Windows. 0.2.0 keeps the idea and drops the weight: the same three
 rails, as a prompt plus one checker, with a two-command CLI that only copies
 files. 0.3.0 makes learnings a reloaded part of every plan and groups the two
-installed files under `.project-management/planrails/`. See
+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. See
 [`CHANGELOG.md`](CHANGELOG.md).
 
 MIT.

package/bin/planrails.mjs

@@ -3,10 +3,11 @@
  * planrails — a planner prompt and one checker. Two commands, both safe:
  *
  *   npx planrails init [--dir DIR] [--force]
- *       Copies PLANNER.md and the checker into <project>/.project-management/planrails/
+ *       Puts PLANNER.md and the checker in <project>/.project-management/planrails/
  *       and makes the plans/ folder. It writes nothing else — no package.json, no npm
- *       install, no hooks, no edits to your CLAUDE.md. Idempotent: it skips files
- *       that already exist unless you pass --force.
+ *       install, no hooks, no edits to your CLAUDE.md. Run it again to update: a copy
+ *       older than this package (or unstamped, 0.3.x) is replaced and you are told;
+ *       a copy of this version is left alone unless --force; plans/ is never touched.
  *
  *   npx planrails check [--dir DIR] [--verify]
  *       Runs the checker over the project's plans. --verify re-runs each done
@@ -14,7 +15,7 @@
  *
  *   planrails --version | --help
  */
-import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync } from "node:fs";
+import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync, realpathSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { checkPlans } from "../tools/check-plans.mjs";
@@ -24,11 +25,11 @@ const version = () => JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"
 
 const HELP = `planrails ${version()} — a planner prompt and one checker.
 
-  npx planrails init [--dir DIR] [--force]   set a project up (copies 2 files, writes nothing else)
+  npx planrails init [--dir DIR] [--force]   set a project up, or update its copy of the planner (2 files, nothing else)
   npx planrails check [--dir DIR] [--verify] check the project's plans
   planrails --version | --help
 
-After init, tell your agent:  Follow .project-management/planrails/PLANNER.md and plan <the feature> with me.
+After init, tell your agent:  Follow .project-management/planrails/PLANNER.md and tell me when you are ready to plan <the feature> with me.
 Add to the command you run before every commit:  node .project-management/planrails/check-plans.mjs
 Full guide: https://github.com/vivmagarwal/planrails#readme`;
 
@@ -38,31 +39,50 @@ function flag(args, name) {
   const i = args.indexOf(name);
   return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
 }
+const dirArg = (args) => resolve(flag(args, "--dir") || flag(args, "--root") || ".");
+
+/** The version a copied file carries near its top (`planrails X.Y.Z`), or null for a 0.3.x copy. */
+export function stampOf(text) {
+  const m = text.slice(0, 400).match(/planrails (\d+\.\d+\.\d+)/);
+  return m ? m[1] : null;
+}
+const newer = (a, b) => { const [x, y] = [a, b].map((v) => v.split(".").map(Number)); for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i]; return false; };
 
 function init(args) {
-  const target = resolve(flag(args, "--dir") || ".");
+  const target = dirArg(args);
   const force = args.includes("--force");
+  const ver = version();
   const pm = join(target, ".project-management");
   const sys = join(pm, "planrails");
   const plans = join(pm, "plans");
   mkdirSync(sys, { recursive: true });
   mkdirSync(plans, { recursive: true });
+  console.log(`planrails ${ver} → ${target}`);
 
-  const copy = (from, to, label) => {
-    if (existsSync(to) && !force) { console.log(`  · ${label} already present (use --force to overwrite)`); return; }
+  // The two copied files are the tool. A re-run brings them up to this package's
+  // version; it never writes into plans/, and never touches anything else.
+  const place = (from, to, label) => {
+    const src = readFileSync(from, "utf8");
+    if (!existsSync(to)) { copyFileSync(from, to); console.log(`  + ${label}`); return; }
+    const cur = readFileSync(to, "utf8");
+    if (cur === src) { console.log(`  = ${label} up to date (${ver})`); return; }
+    const have = stampOf(cur);
+    if (!force && have && newer(have, ver)) { console.log(`  · ${label} is ${have}, newer than this package (${ver}) — kept; use --force to replace`); return; }
+    if (!force && have === ver) { console.log(`  · ${label} is ${ver} but edited — kept; use --force to replace`); return; }
     copyFileSync(from, to);
-    console.log(`  + ${label}`);
+    console.log(`  ↑ ${label} updated ${have || "unstamped (0.3.x or older)"} → ${ver}${force ? " (--force)" : ""}`);
   };
-  console.log(`planrails ${version()} → ${target}`);
-  copy(join(ROOT, "PLANNER.md"), join(sys, "PLANNER.md"), ".project-management/planrails/PLANNER.md");
-  copy(join(ROOT, "tools", "check-plans.mjs"), join(sys, "check-plans.mjs"), ".project-management/planrails/check-plans.mjs");
+  place(join(ROOT, "PLANNER.md"), join(sys, "PLANNER.md"), ".project-management/planrails/PLANNER.md");
+  place(join(ROOT, "tools", "check-plans.mjs"), join(sys, "check-plans.mjs"), ".project-management/planrails/check-plans.mjs");
   const keep = join(plans, ".gitkeep");
   if (!existsSync(keep)) { writeFileSync(keep, ""); console.log("  + .project-management/plans/"); }
-  else console.log("  · .project-management/plans/ already present");
+  else console.log("  = .project-management/plans/ (your plans are never touched)");
+  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`);
 
   console.log(`
 Next:
-  1. Tell your agent:  Follow .project-management/planrails/PLANNER.md and plan <the feature> with me.
+  1. Tell your agent:  Follow .project-management/planrails/PLANNER.md and tell me when you are ready to plan <the feature> with me.
      (Or, in Claude Code, use /plan if you installed the skill.)
   2. Add to the command you run before every commit:
        node .project-management/planrails/check-plans.mjs
@@ -72,7 +92,7 @@ Next:
 }
 
 function check(args) {
-  const root = resolve(flag(args, "--dir") || ".");
+  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 });
@@ -81,14 +101,19 @@ function check(args) {
     console.error(`check-plans: ${problems.length} problem(s):\n${problems.map((p) => `  - ${p}`).join("\n")}`);
     return 1;
   }
-  console.log(`check-plans: ${plans.length} plan(s) ok — every completion claim has a proof and pasted evidence${verify ? " (proofs re-run)" : ""}`);
+  console.log(`check-plans: ${plans.length} plan(s) ok — every completion claim has a proof and exit 0 evidence, active plans reload, NOW is current${verify ? " (proofs re-run)" : ""}`);
   return 0;
 }
 
-const [cmd, ...args] = process.argv.slice(2);
-if (cmd === "--version" || cmd === "-v") { console.log(version()); process.exit(0); }
-if (!cmd || cmd === "--help" || cmd === "-h") { console.log(HELP); process.exit(cmd ? 0 : 1); }
-if (cmd === "init") process.exit(init(args));
-if (cmd === "check") process.exit(check(args));
-console.error(`planrails: unknown command "${cmd}"\n\n${HELP}`);
-process.exit(2);
+// Run the CLI only when this file is the entry point. npm installs the bin as a
+// symlink, so compare real paths, or `npx planrails` would import and do nothing.
+const isMain = (() => { try { return process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (isMain) {
+  const [cmd, ...args] = process.argv.slice(2);
+  if (cmd === "--version" || cmd === "-v") { console.log(version()); process.exit(0); }
+  if (!cmd || cmd === "--help" || cmd === "-h") { console.log(HELP); process.exit(cmd ? 0 : 1); }
+  if (cmd === "init") process.exit(init(args));
+  if (cmd === "check") process.exit(check(args));
+  console.error(`planrails: unknown command "${cmd}"\n\n${HELP}`);
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Plans that survive a lost session, and \"done\" that means done. A planner prompt and a tiny checker.",
   "type": "module",
   "license": "MIT",
@@ -13,7 +13,7 @@
   "engines": { "node": ">=20" },
   "scripts": {
     "test": "node --test tools/check-plans.test.mjs bin/planrails.test.mjs",
-    "check": "node bin/planrails.mjs check --dir examples/weekly-digest && npm test",
+    "check": "node tools/check-plans.mjs && node bin/planrails.mjs check --dir examples/weekly-digest && npm test",
     "prepublishOnly": "npm test"
   }
 }

package/tools/check-plans.mjs

@@ -1,30 +1,41 @@
 #!/usr/bin/env node
+// planrails 0.4.0
 /**
- * check-plans — the one machine-checked rail of the planner.
+ * check-plans — the machine-checked rails of the planner.
  *
- * It reads every PLAN.md under .project-management/plans/<id>/ and enforces a
- * single rule: a task that claims to be finished must name a proof and carry
- * evidence that the proof was run. An empty evidence cell fails the build.
+ * It reads every PLAN.md under .project-management/plans/<id>/ and enforces:
+ *  - a task that claims to be finished must name a proof — a `command` in
+ *    backticks, or the word owner — and carry evidence that the proof was run.
+ *    For a command that means its exit code, pasted, and the code must be 0. An
+ *    empty evidence cell, a bare word, or a recorded failure is not done.
+ *  - 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
+ *    from both; a plan with no status line counts as active.
  *
  * 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, ✅,
- * shipped, a typo — can slip through unchecked.
+ * shipped, a typo — can slip through unchecked. A row the parser cannot read
+ * (its cell count differs from the header's) is a problem, never a pass.
  *
  * `npx planrails init` copies this file into a project's .project-management/planrails/;
  * add `node .project-management/planrails/check-plans.mjs` to the command you run before
  * every commit. No dependencies. Runs on Node 20+ on any OS.
  *
- *   node check-plans.mjs            # structural: completion claims need proof + evidence
- *   node check-plans.mjs --verify   # ALSO re-runs each claim's proof, expects exit 0.
+ *   node check-plans.mjs            # structural: completion claims need proof + exit 0 evidence
+ *   node check-plans.mjs --verify   # ALSO re-runs each claim's proof, expects exit 0; a proof that
+ *                                    #   fails shows its last output line, one that hangs times out.
  *                                    #   ⚠ --verify executes the proof commands. Only run it
  *                                    #   on plans you trust — never on an untrusted pull request.
- *   node check-plans.mjs --root DIR # check a project other than the current directory
+ *   node check-plans.mjs --root DIR # check a project other than the current directory (--dir works too)
  *
  * The functions are pure over their inputs, so check-plans.test.mjs exercises
  * them without a real project.
  */
-import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { readdirSync, readFileSync, existsSync, statSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -42,6 +53,10 @@ const NOT_DONE = new Set([
 ]);
 // A lone one of these in the evidence cell is a placeholder, not evidence.
 const NON_EVIDENCE = new Set(["tbd", "tba", "tbc", "todo", "pending", "later", "wip", "none", "na"]);
+// The exit codes inside an evidence cell: "exit 0", "exit code 1", "exit status 1", "exited 3", "exit=0".
+// Every occurrence counts, so "exit 0 … then exit 1" is a failure, not a pass.
+const EXIT_CODE = /\bexit(?:ed|[\s-]*(?:code|status))?\s*[:=]?\s*(-?\d+)/gi;
+const DATE = /\b\d{4}-\d{2}-\d{2}\b/;
 
 /** Normalise a status or a short token for matching: drop markup, spaces, hyphens, trailing punctuation. */
 function norm(s) {
@@ -57,64 +72,105 @@ function evidenceMissing(ev) {
 }
 
 /**
- * Split one markdown table row `| a | b |` into trimmed cells, respecting
- * backtick code spans and \| escapes — so a pipe inside a proof command
- * (`npm test | tail -1`) does not shift the columns.
+ * Split one markdown table row `| a | b |` into trimmed cells. A `|` inside a
+ * code span does not split (so `npm test | tail -1` stays one cell) and `\|` is
+ * a literal pipe. Code spans follow the CommonMark rule: a run of N backticks
+ * opens a span only if a run of exactly N closes it later in the row; otherwise
+ * the run is literal text. So a stray backtick, or three backticks written in
+ * prose, shifts nothing — and a row that still comes out short is reported.
  */
 function cells(line) {
   const s = line.trim().replace(/^\|/, "").replace(/\|$/, "");
   const out = [];
   let cur = "";
-  let inCode = false;
   for (let i = 0; i < s.length; i++) {
     const ch = s[i];
     if (ch === "\\" && s[i + 1] === "|") { cur += "|"; i++; continue; }
-    if (ch === "`") { inCode = !inCode; cur += ch; continue; }
-    if (ch === "|" && !inCode) { out.push(cur.trim()); cur = ""; continue; }
+    if (ch === "`") {
+      let n = 1;
+      while (s[i + n] === "`") n++;
+      const close = closingRun(s, i + n, n);
+      if (close === -1) { cur += s.slice(i, i + n); i += n - 1; continue; } // unmatched: literal backticks
+      cur += s.slice(i, close + n).replace(/\\\|/g, "|");
+      i = close + n - 1;
+      continue;
+    }
+    if (ch === "|") { out.push(cur.trim()); cur = ""; continue; }
     cur += ch;
   }
   out.push(cur.trim());
   return out;
 }
+/** The index of the next backtick run of exactly n characters in s at or after `from`, or -1. */
+function closingRun(s, from, n) {
+  for (let j = from; j < s.length;) {
+    if (s[j] !== "`") { j++; continue; }
+    let m = 1;
+    while (s[j + m] === "`") m++;
+    if (m === n) return j;
+    j += m;
+  }
+  return -1;
+}
 const isRow = (l) => l.trim().startsWith("|");
 const isHeading = (l) => /^#{1,6}\s/.test(l.trim());
 const isSeparator = (l) => /^\|[\s:|-]+\|?\s*$/.test(l.trim());
+/**
+ * True for every line inside a ``` or ~~~ fence, and for the fence lines themselves:
+ * never a table row. A fence closes only with a fence of the same character and at
+ * least the same length (CommonMark), so a ```` block can hold a ``` example.
+ */
+function fenceMask(lines) {
+  const m = new Array(lines.length);
+  let open = null; // { ch, len } of the fence we are inside
+  for (let k = 0; k < lines.length; k++) {
+    const f = lines[k].match(/^\s*(`{3,}|~{3,})/);
+    if (f && !open) { open = { ch: f[1][0], len: f[1].length }; m[k] = true; continue; }
+    if (f && open && f[1][0] === open.ch && f[1].length >= open.len && lines[k].trim() === f[1]) { open = null; m[k] = true; continue; }
+    m[k] = open !== null;
+  }
+  return m;
+}
 
 const REQUIRED = ["id", "status", "proof", "evidence"];
-/** The column indices of a row, and which required columns it is missing. */
+/** The column indices of a header row (markup like **id** ignored), which required columns it is missing, and its cell count. */
 function headerCols(rowText) {
-  const h = cells(rowText).map((c) => c.toLowerCase());
+  const h = cells(rowText).map((c) => c.replace(/[*_`]/g, "").trim().toLowerCase());
   const ci = { id: h.indexOf("id"), task: h.indexOf("task"), status: h.indexOf("status"), proof: h.indexOf("proof"), evidence: h.indexOf("evidence") };
-  return { ci, missing: REQUIRED.filter((k) => ci[k] === -1) };
+  return { ci, missing: REQUIRED.filter((k) => ci[k] === -1), count: h.length };
 }
 
 /**
  * Parse the task rows of a plan. A "task table" is any markdown table whose
  * header carries the four columns id, status, proof, evidence — found by its
  * columns, not by a heading, so tasks under "## Tasks", "## Phase 2 Tasks",
- * "## Backlog", or a second table are all read; blank lines inside a table are
- * tolerated. Returns { found, tasks, missingCols }.
+ * "## Backlog", or a second table are all read. Blank lines inside a table are
+ * tolerated; a heading, prose, a code fence, or another table's header ends it.
+ * Returns { found, tasks, missingCols }. Each task carries its cell count and
+ * the header's, so a row the splitter could not read is visible to the gate.
  */
 export function parseTasks(text) {
   const lines = text.split(/\r?\n/);
+  const fenced = fenceMask(lines);
   const tasks = [];
   let found = false;
   let i = 0;
   while (i < lines.length) {
-    if (!isRow(lines[i]) || isSeparator(lines[i]) || headerCols(lines[i]).missing.length) { i++; continue; }
+    if (fenced[i] || !isRow(lines[i]) || isSeparator(lines[i]) || headerCols(lines[i]).missing.length) { i++; continue; }
     found = true; // lines[i] is a task-table header (a | row naming all four columns)
-    const { ci } = headerCols(lines[i]);
+    const { ci, count } = headerCols(lines[i]);
     let j = i + 1;
     for (; j < lines.length; j++) {
       const l = lines[j];
-      if (isHeading(l)) break; // a heading ends the table
+      if (fenced[j] || isHeading(l)) break; // a fence or a heading ends the table
       if (l.trim() === "") continue; // a blank line inside the table does not
       if (!isRow(l)) break; // prose ends the table
       if (isSeparator(l)) continue;
-      if (headerCols(l).missing.length === 0) break; // the next table's header — reprocess it
+      if (headerCols(l).missing.length === 0) break; // the next task table's header — reprocess it
+      if (j + 1 < lines.length && isRow(lines[j + 1]) && isSeparator(lines[j + 1])) break; // any other table's header
       const c = cells(l);
       const at = (idx) => (idx >= 0 && idx < c.length ? c[idx] : "");
-      tasks.push({ id: at(ci.id), task: at(ci.task), status: at(ci.status), proof: at(ci.proof), evidence: at(ci.evidence), line: j + 1 });
+      tasks.push({ id: at(ci.id), task: at(ci.task), status: at(ci.status), proof: at(ci.proof), evidence: at(ci.evidence), line: j + 1, cellCount: c.length, headerCount: count });
     }
     i = j;
   }
@@ -122,7 +178,7 @@ export function parseTasks(text) {
   let missingCols = [];
   if (!found) {
     for (let k = 0; k < lines.length && !missingCols.length; k++) {
-      if (!/^#{1,6}\s+tasks\b/i.test(lines[k].trim())) continue;
+      if (fenced[k] || !/^#{1,6}\s+tasks\b/i.test(lines[k].trim())) continue;
       for (let m = k + 1; m < lines.length && !isHeading(lines[m]); m++) {
         if (isRow(lines[m]) && !isSeparator(lines[m])) { const miss = headerCols(lines[m]).missing; if (miss.length && miss.length < REQUIRED.length) missingCols = miss; break; }
       }
@@ -131,13 +187,13 @@ export function parseTasks(text) {
   return { found, tasks, missingCols };
 }
 
-/** The command inside a proof cell (backticks stripped), or null for `owner`/prose/empty. */
+/** The command in a proof cell that is exactly one `code span` (backticks stripped), or null for `owner`, prose, a span inside prose, or empty. */
 export function proofCommand(proof) {
-  const m = proof.match(/`([^`]+)`/);
+  const m = proof.trim().match(/^`([^`]+)`$/);
   return m ? m[1].trim() : null;
 }
 
-/** Problems with one plan's tasks. `run` (optional) executes a proof and returns its exit code. */
+/** Problems with one plan's tasks. `run` (optional) executes a proof and returns its exit code, or { code, last }. */
 export function checkPlan({ id, text, verify = false, run = null }) {
   const problems = [];
   const { found, tasks, missingCols } = parseTasks(text);
@@ -147,19 +203,70 @@ export function checkPlan({ id, text, verify = false, run = null }) {
     return problems;
   }
   for (const t of tasks) {
+    if (t.cellCount !== t.headerCount) {
+      problems.push(`${id} line ${t.line}: row has ${t.cellCount} cell(s) but the header has ${t.headerCount} — a stray | or backtick? A row the gate cannot read fails closed`);
+      continue;
+    }
     if (!isCompletionClaim(t.status)) continue;
     const noProof = EMPTY.test(t.proof);
+    const cmd = proofCommand(t.proof);
+    const owner = norm(t.proof) === "owner";
     const noEvidence = evidenceMissing(t.evidence);
     if (noProof) problems.push(`${id} ${t.id}: status "${t.status}" names no proof (line ${t.line})`);
+    else if (!cmd && !owner) problems.push(`${id} ${t.id}: the proof must be a \`command\` in backticks or the word owner, not "${t.proof}" (line ${t.line})`);
     if (noEvidence) problems.push(`${id} ${t.id}: status "${t.status}" but the evidence cell is empty — run the proof and paste its result (line ${t.line})`);
-    if (verify && !noProof && !noEvidence && run) {
-      const cmd = proofCommand(t.proof);
-      if (cmd) { const code = run(cmd); if (code !== 0) problems.push(`${id} ${t.id}: proof re-run failed — \`${cmd}\` exited ${code}`); }
+    else if (cmd) {
+      const codes = [...t.evidence.matchAll(EXIT_CODE)].map((m) => m[1]);
+      const bad = codes.find((x) => x !== "0");
+      if (!codes.length) problems.push(`${id} ${t.id}: evidence does not record the proof's exit code — run it and paste "exit 0" with the last line (line ${t.line})`);
+      else if (bad !== undefined) problems.push(`${id} ${t.id}: evidence records exit ${bad} — the proof failed, so the task is not done (line ${t.line})`);
+    } else if (owner && !DATE.test(t.evidence)) {
+      problems.push(`${id} ${t.id}: an owner-closed task records the owner's words with the date, e.g. "2026-09-13 owner: ship it" (line ${t.line})`);
     }
+    if (verify && cmd && !noEvidence && run) {
+      const r = run(cmd);
+      const code = typeof r === "number" ? r : r.code;
+      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.
+  if (isActive(text)) {
+    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`);
   }
   return problems;
 }
 
+/**
+ * Active unless the header says otherwise: `status: done`, `paused`, or another
+ * finished word exempts a plan from the reload and NOW rules. A plan with no
+ * status line counts as active — the safe direction for a gate.
+ */
+const NOT_ACTIVE = new Set(["done", "paused", "retired", "closed", "shipped", "finished", "complete", "completed", "archived", "dropped", "cancelled", "canceled", "abandoned", "superseded", "onhold", "hold"]);
+export function isActive(text) {
+  const m = text.match(/^status:\s*([^\s·|]+)/im);
+  return !(m && NOT_ACTIVE.has(norm(m[1])));
+}
+/** The task ids the RESUME line names, out of the plan's own ids (T1 does not match inside T12). */
+function resumeIds(text, ids) {
+  const m = text.match(/^\s*RESUME:(.*)$/m);
+  if (!m) return [];
+  const plain = (id) => id.replace(/[`*_\s]/g, "");
+  return ids.filter((id) => plain(id) && new RegExp(`(^|[^A-Za-z0-9])${plain(id).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![A-Za-z0-9])`).test(m[1]));
+}
+/** The plan ids a CLAUDE.md reloads: `@.project-management/plans/<id>/PLAN.md` on its own line, outside a fence. */
+export function reloadLines(text) {
+  const lines = text.split(/\r?\n/);
+  const fenced = fenceMask(lines);
+  const ids = new Set();
+  lines.forEach((l, k) => {
+    const m = !fenced[k] && l.match(/^\s*@\.project-management\/plans\/([^/\s]+)\/PLAN\.md\s*$/);
+    if (m) ids.add(m[1]);
+  });
+  return ids;
+}
+
 /** Plan folders under .project-management/plans/. A folder with no PLAN.md is a problem. */
 export function findPlans(root) {
   const dir = join(root, ".project-management", "plans");
@@ -177,15 +284,28 @@ export function findPlans(root) {
   return { plans, problems };
 }
 
-/** Check every plan under root. Returns { plans, problems }. */
-export function checkPlans({ root = ".", verify = false } = {}) {
+/** Run one proof command in root: its exit code (or "timeout after Ns") and the last line it printed. */
+export function runProof(cmd, root, timeoutMs) {
+  const r = spawnSync(cmd, { cwd: root, shell: true, encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  const last = `${r.stdout || ""}\n${r.stderr || ""}`.trim().split(/\r?\n/).filter(Boolean).pop() || "";
+  if (r.error && r.error.code === "ETIMEDOUT") return { code: `timeout after ${timeoutMs / 1000}s`, last };
+  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). */
+export function checkPlans({ root = ".", verify = false, verifyTimeoutMs = 10 * 60 * 1000 } = {}) {
   const { plans, problems } = findPlans(root);
-  const run = verify ? (cmd) => { const r = spawnSync(cmd, { cwd: root, shell: true, stdio: "ignore" }); return r.status ?? 1; } : null;
+  const run = verify ? (cmd) => runProof(cmd, root, verifyTimeoutMs) : null;
+  const claudeMd = join(root, "CLAUDE.md");
+  const reloads = existsSync(claudeMd) ? reloadLines(readFileSync(claudeMd, "utf8")) : null;
   for (const { id, path } of plans) {
     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 }));
+    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 };
 }
 
@@ -197,10 +317,15 @@ function flagValue(args, name) {
   return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
 }
 
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+// Run the CLI only when this file is the entry point. Compare real paths: through a
+// symlink, or /tmp vs /private/tmp on macOS, a textual comparison fails and a gate
+// that silently does nothing exits 0 — the one thing a gate must never do.
+const real = (p) => { try { return realpathSync.native(p); } catch { return realpathSync(p); } };
+const isMain = (() => { try { return Boolean(process.argv[1]) && real(process.argv[1]) === real(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (isMain) {
   const args = process.argv.slice(2);
   const verify = args.includes("--verify");
-  const root = flagValue(args, "--root") || ".";
+  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 });
   if (!plans.length && !problems.length) { process.stdout.write("check-plans: no plans under .project-management/plans/ — nothing to check\n"); process.exit(0); }
@@ -208,6 +333,6 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
     process.stderr.write(`check-plans: ${problems.length} problem(s):\n${problems.map((p) => `  - ${p}`).join("\n")}\n`);
     process.exit(1);
   }
-  process.stdout.write(`check-plans: ${plans.length} plan(s) ok — every completion claim has a proof and pasted evidence${verify ? " (proofs re-run)" : ""}\n`);
+  process.stdout.write(`check-plans: ${plans.length} plan(s) ok — every completion claim has a proof and exit 0 evidence, active plans reload, NOW is current${verify ? " (proofs re-run)" : ""}\n`);
   process.exit(0);
 }