planrails 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 0.8.0 — 2026-10-04
+
+Plans that run unattended, compact between tasks, and end instead of lingering.
+Every change below came from a test run or a real project's plans.
+
+- **An optional Claude Code plugin lets the model compact its own session
+  between tasks.** `claude plugin marketplace add vivmagarwal/planrails`, then
+  `claude plugin install planrails@planrails`. It gives the model two tools,
+  `context_usage` and `compact_after_turn`, and decides nothing: when a task is
+  recorded as done it puts the context reading (and the growth since the session
+  started or last compacted) beside the result, and step 6 of the plan's loop has
+  the model decide. The compaction runs once the turn ends, waits while a
+  sub-agent is still going (ask again later), keeps the session id, then resumes with "Continue the plan.";
+  a failure is reported to the model as text. Measured in CourseGen Lab on an
+  11-task plan run unattended on Opus, two pairs of runs: compactions only at
+  recorded boundaries; inside each plugin run its compactions saved about 30% and
+  50% of its bill; across pairs the plugin runs read 20% and 50% fewer tokens and
+  cost 1–32% less (runs vary: the two controls differed by 45%); blind reviews of
+  both pairs found no quality loss attributable to it.
+  Without the plugin, or headless, nothing changes. Installed per user (or per
+  project) from this repo's marketplace into `~/.claude/plugins/`; it adds
+  nothing measurable to a normal chat's start (3.3 s against 3.0 s). If an
+  `allowedMcpServers` list hides its tools, it stays idle (an earlier build
+  stalled every session start by ~8 s), and `npx planrails init` and the planner
+  warn and offer three choices: one entry in `~/.claude/settings.json`, the same
+  in a project's `.claude/settings.local.json`, or removing the list, with the
+  count of MCP servers that would also turn on. The plugin uses Claude Code's mods
+  API, which its own types call early access.
+- **Go on until the plan stops you.** Nothing told an unattended session to start
+  the next task. The loop now does, works around a blocked task, and lists when
+  to stop.
+- **Plans that only wait on the owner stop reloading.** A real project's three
+  active plans were 97–99% done, held open by one or two owner rows each, and
+  reloaded ~80,000 tokens into every call for days. New status `waiting`: §5
+  hands such a plan over (its reload line out, one line under "Waiting on you"
+  in `CLAUDE.local.md`); the checker notes an active plan in that state.
+- **Only the plans being worked reload.** The planner reports what reloads and
+  its size, and clears it before adding a line, with the person's yes.
+- **A plan is one feature of ~10–30 tasks**, ended at a phase boundary and
+  continued in a new plan that carries every Rule, Decision and Learning
+  forward. The size note says so when finished rows are most of the plan (the
+  0.6 note asked for a trim the method forbade, and was ignored for weeks), and
+  no longer counts the loop block every plan carries.
+- **Slices a stranger can pick up cold**: each row names its files and `after
+  Tn`; a proof fails until its task is done (a project-wide check goes after the
+  task's own test); irreversible steps are owner rows; Context is the living
+  "what exists"; before compacting, what the next task needs goes in the plan.
+- **The stamp is taken in the same command as the proof.** Typed timestamps were
+  the slip real plans recorded most.
+
+To update: `npx planrails@latest init`. Active plans keep working; to give one
+the new loop, replace its "How to work this plan" block with the template's.
+
+## 0.7.0 — 2026-10-03
+
+The reload line moves from `CLAUDE.md` to `CLAUDE.local.md`, which git ignores.
+A plan now reloads only for whoever works it, and a team's `CLAUDE.md` is left
+alone.
+
+- **Why.** Field feedback from teams: a team shares `CLAUDE.md`, so every plan
+  opened or closed changed the team's file, two branches' lines conflicted, and
+  every teammate's sessions reloaded everyone's plans.
+- **The line goes in `CLAUDE.local.md`**, and the agent adds that file to
+  `.gitignore` if git does not already ignore it. Claude Code loads it beside
+  `CLAUDE.md` and re-reads it, with its imports, after `/compact`. The docs say
+  so for `CLAUDE.md` only, so it was tested on Claude Code 2.1.288: a word
+  swapped on disk, never shown in the chat, came back after compaction, the same
+  as through `CLAUDE.md`. A teammate who takes a plan over adds the line to
+  their own file.
+- **The checker asks the holder.** Before, when a `CLAUDE.md` existed, every
+  active plan needed its line there. With the line in an ignored file, CI and a
+  teammate's checkout cannot see it, so that rule would fail them. Now the
+  active plan whose NOW `session:` id starts `$CLAUDE_CODE_SESSION_ID` must be
+  reloaded by a `CLAUDE.local.md` or `CLAUDE.md` in the project root or a folder
+  above it, which is what Claude Code loads; in CI, at a terminal, and for a
+  teammate's plan nothing is asked. The id is read in any case, from six hex
+  characters to a whole session id, never from a code fence. This also catches
+  a worktree outside the checkout, which has no copy of the ignored file. A `CLAUDE.md` line to a plan that does not exist
+  still fails; a `CLAUDE.local.md` one does not, because that file outlives a
+  checkout of a branch where the plan does not exist. The ok line says "this
+  session's plan reloads" in place of "active plans reload".
+- **`AGENTS.md` projects.** Once any `CLAUDE` file exists, Claude Code stops
+  reading `AGENTS.md` by itself. In a project with `AGENTS.md` and no
+  `CLAUDE.md`, `CLAUDE.local.md` starts with `@AGENTS.md`. Before 0.7 the
+  method wrote a `CLAUDE.md` in such a project, with the same silent effect.
+- **The close deletes the line.** A lasting learning still graduates to the
+  shared `CLAUDE.md`: it is the team's knowledge, added as a reviewed change.
+- **`init`** says the agent writes `CLAUDE.local.md`, and points out reload
+  lines still in `CLAUDE.md`. It writes neither file, nor `.gitignore`.
+
+To update: `npx planrails@latest init`. A reload line in `CLAUDE.md` keeps
+working. To move it, cut it from `CLAUDE.md`, paste it into `CLAUDE.local.md`,
+and add `CLAUDE.local.md` to `.gitignore`. Once it has moved, an active plan's
+block can say "the reload line deleted from CLAUDE.local.md" in place of "the
+reload line in CLAUDE.md wrapped in backticks"; until then, leave the block
+alone, or the close will look for the line in the wrong file.
+
 ## 0.6.0 — 2026-09-19
 
 The checker can now advise without blocking.

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.6.0 -->
+<!-- planrails 0.8.0 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -11,7 +11,7 @@ project runs Node — copy in one small checker.
 **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.
+nine-line report, and stop.
 Do not start planning until they answer.
 
 ---
@@ -30,8 +30,10 @@ 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-root `CLAUDE.md` re-opens the
-   plan after every compaction, so the state is never lost.
+1. **The reload line.** One line in the project-root `CLAUDE.local.md` re-opens
+   the plan after every compaction, so the state is never lost. Git ignores that
+   file, so the plan reloads for whoever works it, and the team's `CLAUDE.md` is
+   left alone.
 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
@@ -53,21 +55,25 @@ 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** — 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**.
+   `AGENTS.md`, else `README.md` — and `CLAUDE.local.md` if there is one. 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/`.** Read in full the plan this session is
    assigned — the person names it; if one plan is active, that one — and list
-   the others by id, with who holds each (NOW's `session:` line).
+   the others by id, with who holds each (NOW's `session:` line). Note what
+   reloads: each bare `@` plan line in `CLAUDE.local.md` and `CLAUDE.md`, and
+   its size (`wc -w`); and what waits on the person (the "Waiting on you" lines),
+   to remind them.
 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
 can check it. If it is only a number, re-derive it yourself or drop it. A wrong
 number in a plan becomes a wrong decision later.
 
-Then **report ready in eight lines** and stop:
+Then **report ready in nine lines** and stop:
 
 ```
 READY — <project name>
@@ -75,6 +81,7 @@ Stack:      <language, framework, package manager>
 Always-on:  <CLAUDE.md | AGENTS.md | README.md>
 Check:      <the check command>   Test: <the test command>
 Plans:      <existing plan ids; which are active and who holds each, or "none">
+Reloading:  <the plans on @ lines, with their words; or "none">
 Docs:       <relevant doc paths, or "none">
 Touches:    <the folders this feature will change>
 Questions:  <up to 4 things the repo did not answer, or "none">
@@ -104,12 +111,21 @@ templates at the end of this file (§ Template — PLAN.md, § Template — LOG.
 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
+- **Name the proof for every task before any work.** The proof is a command
+  that would fail if this task were not done. A project-wide check (`npm run
+  check`) shows only that nothing broke; when you use it, put the task's own test
+  first in the same cell: `npx vitest run tests/digest.test.ts && npm run check`.
+  Anything that cannot be undone or reaches beyond the repo (a deploy, a publish,
+  a push, a migration on shared data, a message to people) is its own task with
+  proof `owner`. 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 (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.
+- **A task is a slice a stranger can pick up cold.** Its row says what changes,
+  the files, and `after T3` when it needs an earlier task; the why is in
+  Decisions, the facts in Context. It fits in one stretch between compactions:
+  if it means reading more than a handful of files or changing two areas, it is
+  two tasks. One task, one proof.
   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
@@ -120,23 +136,50 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   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:
+- **A plan is one feature: about 10–30 tasks.** Finished rows stay in the plan
+  and reload with it, so a plan that keeps growing keeps costing. When the work
+  outgrows that, end the plan at a phase boundary (§5) and go on in a new plan.
+  Ending a plan must not lose what it knows: the new plan carries forward every
+  Rule, Decision and Learning that still holds, and its Context gets a short
+  "What exists" (what the last phase built, where) and a link to the old plan,
+  whose rows stay on disk to read when a task needs the detail. What stops
+  reloading is the finished rows' narrative, which is most of a big plan's
+  words and little of its guidance. An evidence cell holds the stamp, the exit
+  code and the last line; the story goes in LOG.md.
+- **Clear what reloads before you add to it.** Every plan on a bare `@` line
+  in `CLAUDE.local.md` or `CLAUDE.md` rides on every call of every session in
+  this checkout, whether that session works it or not. A session needs only the
+  plan it works: the hold check reads the others from disk. So, for each plan
+  that reloads: finished, close it (§5); only the owner can move it, hand it over
+  (§5); nobody works it now, pause it (`status: paused`, its line out); held by
+  a live session (§4's check), leave it. A line for someone else's plan belongs
+  in their own `CLAUDE.local.md`; one in the shared `CLAUDE.md` predates 0.7.
+  Say what you found, and change a plan only with the person's yes. The aim:
+  only the plans being worked right now reload.
+- **Add the reload line.** In the project-root `CLAUDE.local.md` (create it if
+  needed), under a short "Active plans" heading, 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. Under the same heading, one line says how the plans are held:
-  *Each plan below is held by one session — see its NOW `session:` line. Work one
-  only when asked in this session, after the check in its block.* (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.)
+  backticks does not load. Claude Code reads that file beside `CLAUDE.md`, and
+  re-reads both, with everything they import, at every session start and after
+  every compaction, so the plan comes back on its own. Under the same heading, one
+  line says how the plans are held: *Each plan below is held by one session — see
+  its NOW `session:` line. Work one only when asked in this session, after the
+  check in its block.*
+  The file is yours, not the team's: if `git check-ignore -q CLAUDE.local.md`
+  fails, add `CLAUDE.local.md` to `.gitignore` on its own line. Do not write the
+  reload line in `CLAUDE.md`; a team shares that file, and every teammate would
+  reload your plan. Someone who takes the plan over adds the line to their own
+  `CLAUDE.local.md`. If the project has `AGENTS.md` and no `CLAUDE.md`, make
+  `@AGENTS.md` the first line of `CLAUDE.local.md`: once any `CLAUDE` file
+  exists, Claude Code stops reading `AGENTS.md` by itself. (A tool that does not
+  do `@`-imports does not reload; open the plan by hand at each session start.)
 - **One plan per session, one session per plan.** A repo may hold several active
   plans, each with its own reload line and each held by one session, named on its
-  NOW `session:` line. Every session reloads all of them, so keep them few; a plan
-  nobody is working is paused (`status: paused`, its line in backticks). A session
+  NOW `session:` line. Every session in this checkout reloads all of them, so keep them few; a plan
+  nobody is working is paused (`status: paused`, its line out). A session
   works only the plan the person in that session assigned; the other reloaded
   plans are context, not work orders. Naming the session after the plan
   (`claude -n <id>`) shows the holder in every listing and in the terminal title;
@@ -153,12 +196,25 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   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 an active plan has no
-  reload line, if its NOW lost its RESUME line, or if NOW points at a finished
-  task. If the project is not Node,
+  build fails if a task is marked done with no evidence, if the plan your session
+  holds has no 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 compaction tools, if the planrails plugin is installed.** If you
+  lack `context_usage` although `claude plugin list` shows `planrails`, an
+  `allowedMcpServers` list in the settings hides them (the plugin then stays
+  idle and costs nothing). Tell the person, and offer the choices
+  (`npx planrails init` prints them too): `{ "serverName": "planrails" }` in
+  `allowedMcpServers` in `~/.claude/settings.json` (every project, every other
+  server still off); the same entry in `.claude/settings.local.json` (this
+  project only; make sure git ignores it); or removing the list, which also turns
+  on every MCP server it keeps off (count them in `~/.claude.json` and
+  `.mcp.json` first). Do what they pick; it applies from the next session. A
+  managed policy that locks the list (`allowManagedMcpServersOnly`) cannot be
+  widened: say who can, and carry on without.
 - **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,
+  chat context: open every path the plan names, start every proof command and
+  see it fail on work not yet built,
   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.
@@ -208,8 +264,9 @@ decide:
   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.
 - A worktree is another checkout with its own copy of the plan: a merge concern
-  later, not a clobber now. A sub-agent you briefed never runs this check; it
-  never writes the plan.
+  later, not a clobber now. Git does not copy `CLAUDE.local.md` into it, so add
+  the plan's reload line there too. A sub-agent you briefed never runs this
+  check; it never writes the plan.
 
 Stopping means: report the session's name, status and start, what NOW says and
 what `git status` shows, then ask — `AskUserQuestion` in Claude Code; a `claude -p`
@@ -227,8 +284,10 @@ The loop for each task:
 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 the shell clock (`date`; on Windows
-   `Get-Date`), never from memory.
+   line of output. Take the stamp in the same command, so it cannot be typed:
+   `npx vitest run x > /tmp/proof.out 2>&1; echo "exit $?"; date "+%Y-%m-%d %H:%M"; tail -1 /tmp/proof.out`
+   (on Windows, `Get-Date -Format "yyyy-MM-dd HH:mm"`). A stamp typed from memory
+   is the slip real plans recorded most.
 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. A proof of `owner` is closed only by the person's
@@ -243,12 +302,48 @@ The loop for each task:
    "trap → rule", with the real case. LOG.md holds what happened; Learnings holds
    the rule, because Learnings reloads every session and the log does not.
 
+**Go on until the plan stops you.** When the person asked you to work the plan,
+start the next task without ending your turn to report. A blocked task does not
+end the run: take the next one that does not wait on it. Stop only when every
+row is done or dropped (close, §5), only owner rows and the close are open (hand
+over, §5), every open task is blocked or waits on one, the hold check says stop,
+or something breaks that you cannot diagnose. Write NOW first, then report.
+
 **Update NOW before you end any turn.** NOW is the first thing a fresh session
 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.
 
+**Compact between tasks, if you have the tools.** The planrails plugin gives you
+`context_usage` and `compact_after_turn` (`mcp__planrails__…`; Claude Code may
+list them as deferred: load them with ToolSearch); without them, skip this, and Claude
+Code compacts on its own when the context fills. Every call re-reads the whole
+context, so a big one costs on every step that follows. When a task is done and
+recorded (evidence pasted, NOW updated, LOG appended, and in the plan whatever
+the next task needs: a person's words in Decisions with the date, a trap in
+Learnings, what you built in Context), call `context_usage` and decide:
+
+- Compact when the context has grown past about 50,000 tokens since the session
+  started or last compacted (`context_usage` reports it; a real project starts a
+  session at tens of thousands, which no compaction can drop), or past the line
+  the plan's Rules set, and tasks remain. The saving is roughly the tokens dropped
+  times the calls still to come.
+- Do not compact mid-task, near the end of the plan, or when the next task works
+  in the files you just read: re-reading them costs more than keeping them.
+
+To compact, first write into the plan what the next task needs: what you built,
+in Context; a trap, in Learnings; a person's words, in Decisions. The summary is
+rewritten at every compaction, so a fact that lives only there is lost at the
+next one; in a real run, facts left in the instructions ("not yet written down
+anywhere") were exactly that. Then call `compact_after_turn` with
+`instructions` naming the plan and the next task, and `resume: "Continue the
+plan."`, and end your turn. It compacts once the turn
+ends (it refuses while a sub-agent is still going: ask again once it is done),
+and the plan reloads with your session's
+claim intact. If `context_usage` reports the last compaction failed, carry on
+without it.
+
 **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.
@@ -282,13 +377,25 @@ cannot see the screen. You can.
 - Gate green, work wrong: refuse to close it. Say what the gate cannot see.
 - A green check is not proof the work is good. It is proof one command exited 0.
 
-**Never edit a plan the way a script would.** If something crashes, log it, set
-the task `blocked` with the reason, and stop. Do not hand-fix state to look done.
+**Never edit a plan the way a script would.** If something crashes, log it and set
+the task `blocked` with the reason; go on only with tasks that do not wait on it. Do not hand-fix state to look done.
 
 ---
 
 ## §5 Close
 
+**When only the owner can move the plan.** If every open row is an `owner` row
+or the close itself, the work is done and only the person's word is missing. Do
+not leave the plan `active`: it reloads into every session for nothing, and real
+plans have sat that way for days. Run steps 1–3 below now, then hand it over: set
+`status: waiting`, NOW's `session:` to `none` and RESUME to the owner rows; take
+its reload line out of `CLAUDE.local.md`, and add one line there under a
+"Waiting on you" heading: `<id> — T7: the owner tries the export and says it
+works (.project-management/plans/<id>/PLAN.md)`. Tell the person. When they give
+their word, a session sets the plan `active`, puts its reload line back, records
+their words and the date, re-runs every proof, and closes by steps 4–5. The checker notes an active plan
+in this state.
+
 1. **Re-run every proof.** A plan closes on what the checks say now, not on their
    last recorded run. Paste fresh evidence.
 2. **Fresh-context review.** A sub-agent, or a new session, with the plan and
@@ -298,14 +405,17 @@ the task `blocked` with the reason, and stop. Do not hand-fix state to look done
 3. **Update the docs** the work changed — in the same step, per the project's
    documentation guide if it has one.
 4. **Retire the plan.** Set its header to `status: done` and NOW's `session:` to
-   `none`, then wrap its reload line in backticks, or delete it. Do not move a
+   `none`, then delete its reload line (or wrap it in backticks). 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.
+   plan would reload forever. The status comes first: the checker holds the
+   `active` plan your session holds 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. A learning that a check could enforce becomes a test.
-   One that was only about this work retires with it.
+   moves to the shared always-loaded file (`CLAUDE.md` / `AGENTS.md`), not
+   `CLAUDE.local.md`: it is the team's knowledge, so it goes in as a change they
+   review, and it outlives the plan you are retiring. A learning that a check
+   could enforce becomes a test. One that was only about this work retires with
+   it.
 
 ---
 
@@ -317,14 +427,16 @@ Each line here was paid for by a real failure in earlier planning systems:
   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.
+  command stubs. It lives in `CLAUDE.local.md` because teams share `CLAUDE.md`:
+  there, every plan opened or closed changed the team's file, and every
+  teammate's sessions reloaded everyone's plans.
 - **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 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 reload honest: the plan your session holds has its reload line, 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
@@ -336,8 +448,11 @@ Each line here was paid for by a real failure in earlier planning systems:
   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
+  is too long, that only its owner can move it, or that a finished plan still
+  reloads, so those are notes, and you judge. Four of four real plans had
+  outgrown the word line with nothing saying so; three of three active plans in
+  one project were held open by owner rows. A note names an action the method
+  allows, or it is ignored. 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
@@ -385,14 +500,15 @@ 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:
+Read NOW, then Rules and Learnings; open a file Context lists only when your task touches it. One task at a time:
 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 the shell clock (`date`; on Windows `Get-Date`), never typed from memory.
+3. Run the proof now, with the stamp taken in the same command (`cmd > /tmp/proof.out 2>&1; echo "exit $?"; date "+%Y-%m-%d %H:%M"; tail -1 /tmp/proof.out`), never typed: `date`; in PowerShell `$LASTEXITCODE` and `Get-Date`. Paste `YYYY-MM-DD HH:MM · exit N · "last line"` into evidence, and only that; the story goes in LOG.md.
 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.
+5. If it fought back, add a Learning: the trap, then the rule. A verified fact, or what this task built that a later one uses, goes in Context (path — what it is); a choice, or a person's words with the date, in Decisions.
+6. If you have the planrails plugin's tools (`mcp__planrails__context_usage`; load it with ToolSearch if it is listed as deferred), call `context_usage` now: grown past ~50,000 tokens since the session started or last compacted, with tasks left and the next one in other files, first write into the plan what the next task needs (what you built, in Context; a trap, in Learnings), then call `compact_after_turn` (instructions: the plan and the next task; resume: "Continue the plan.") and end your turn. Otherwise go on to the next task without stopping to report; a blocked task does not end the run: take the next one that does not wait on it. Stop when no task can go ahead, the plan is ready to close or hand over, or the hold check says stop; write NOW first.
 
-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.
+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` and the last LOG.md entry show where you are. 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 deleted from CLAUDE.local.md. When only owner rows and the close are open, hand it over by §5: `status: waiting`, `session: none`, its reload line out, one line under "Waiting on you" in CLAUDE.local.md. Full method: `.project-management/planrails/PLANNER.md` §4.
 
 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.
@@ -414,9 +530,10 @@ Work only the plan assigned in this session; other reloaded plans are context. W
 ## Tasks
 | id | task | status | proof | evidence |
 |----|------|--------|-------|----------|
-| T1 | <what to do> (<path>) | todo | `<command that proves it>` | |
-| T2 | <what to do> (<path>) | todo | `<command>` | |
-| T3 | update the docs this work changed | todo | owner | |
+| T1 | <what changes> (<paths>) | todo | `<a command that fails until T1 is done>` | |
+| T2 | <what changes> (<paths>; after T1) | todo | `<its own test> && <the project check>` | |
+| T3 | the owner tries it on staging and says it works | todo | owner | |
+| T4 | close the plan by PLANNER.md §5 (after T1–T3) | todo | `<the Done-when checks>` | |
 
 ## Rules for this plan
 - <a rule that governs this area — e.g. "every email goes through lib/email, never a bare send">
@@ -429,8 +546,9 @@ Work only the plan assigned in this session; other reloaded plans are context. W
 ## Learnings
 - <the trap you hit> → <the rule that avoids it> (<the real case, one line>)
 
-## Context (read during planning — do not re-read)
+## Context (facts and what exists; open a listed file only when your task touches it)
 - <path> — <one line of what it holds; mark a sub-agent's unverified finding as a lead>
+- <path> — <what a task built here that a later task uses: the function, the table, the route>
 ````
 
 ## Template — LOG.md

package/README.md

@@ -7,8 +7,10 @@ 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 your project's root `CLAUDE.md`
-   re-opens the plan after every compaction, and the plan carries its own
+1. **The plan reloads itself.** One line in your project's root `CLAUDE.local.md`
+   re-opens the plan after every compaction. Git ignores that file, so the plan
+   reloads for whoever works it and your team's `CLAUDE.md` is never edited. The
+   plan carries its own
    operating loop and the name of the session working it, so a session that
    never saw the planner prompt still works it correctly — and a second session
    in the same checkout checks for the first before it touches the plan. (Claude
@@ -18,8 +20,8 @@ work that is not. planrails fixes that with three plain rules and almost no code
 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.
+   and also checks that the plan your session holds 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.
@@ -36,10 +38,10 @@ 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 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:
+no hooks, no edits to your `CLAUDE.md`, `CLAUDE.local.md` or `.gitignore`. 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/
@@ -56,7 +58,7 @@ Then, two steps:
    > Follow `.project-management/planrails/PLANNER.md` and tell me when you are
    > ready to plan the next feature with me.
 
-   It reads your repo, reports what it found in eight lines, and waits. Then you
+   It reads your repo, reports what it found in nine lines, and waits. Then you
    plan together, and it writes the plan and wires the reload line.
 
 2. **Wire the checker into your build.** Add this to the command you run before
@@ -101,6 +103,73 @@ the same flow in any project that has run `npx planrails init` — the skill rea
 the project's own copy of `PLANNER.md`, so every project follows the version it
 has. (It is not called `/plan`, because Claude Code has a `/plan` of its own.)
 
+### Optional: let the model compact between tasks (Claude Code plugin)
+
+Every model call re-reads the whole conversation, so a long plan pays for its
+early tasks again on every later step. Claude Code compacts on its own only when
+the context is nearly full, wherever that falls, mid-task included. The
+planrails plugin lets the model do it at a better moment: right after a task is
+done and recorded, when the plan already holds everything that matters.
+
+```bash
+claude plugin marketplace add vivmagarwal/planrails
+claude plugin install planrails@planrails
+```
+
+It adds two tools and decides nothing: `context_usage` (how full the context is,
+how much it has grown since the session started or last compacted, how many
+sub-agents run, how the last compaction went) and `compact_after_turn` (compact
+once this turn ends, then go on with "Continue the plan."). When a task is
+recorded as done in the plan, by whatever tool, the plugin puts that reading
+beside the result, and step 6 of the plan's loop has the model decide: after
+growth of about 50,000 tokens, with tasks left and the next one in other files,
+it writes what the next task needs into the plan and compacts. The compaction
+refuses while a sub-agent is still going, keeps the session's id (so the plan's `session:`
+claim holds), and the plan reloads afterwards. Without the plugin, or in a
+headless `claude -p` run, nothing changes.
+
+Measured on a real app (CourseGen Lab, an 11-task plan, unattended Opus
+sessions, two pairs of runs with and without the plugin): the sessions with it
+compacted only at recorded task boundaries; each run's own compactions saved
+about 30% and 50% of its bill, against the same run replayed without them. Across
+the pairs the plugin runs read 20% and 50% fewer tokens and cost 1–32% less, a
+wide range because runs vary: the two runs without the plugin differed by 45%.
+Blind reviews of both pairs found no quality loss attributable to compaction
+(one pair favoured each side, on the same bug). The runs, the method and the
+numbers are in `.project-management/research/auto-compact/`; the final wording
+of step 6 came after them.
+
+**Where it lives.** Not in the npm package: `claude plugin install` copies it
+into `~/.claude/plugins/cache/planrails/` and switches it on in the scope you
+choose (`--scope user`, the default: every project, for you; `project`: the
+shared `.claude/settings.json`, for the whole team; `local`: this project, for
+you). `claude plugin uninstall planrails@planrails` removes it.
+
+**What it costs a normal chat.** Nothing measurable. Sessions with it started as
+fast as without (median 3.3 s against 3.0 s, three runs each). Its two tools
+are listed by name only (Claude Code defers MCP tools until a model loads one),
+and it does nothing unless a plan under `.project-management/plans/` gains a
+done row or the model calls one of its tools. It never compacts on its own.
+
+**If an `allowedMcpServers` list hides it.** Such a list keeps every MCP server
+it does not name off, the plugin's included; the plugin notices, stays idle and
+costs nothing (an earlier build stalled every session start by ~8 s here).
+`npx planrails init` and the planner both say so, and offer three choices,
+each applied from the next session:
+
+| Choice | Effect |
+|---|---|
+| add `{ "serverName": "planrails" }` to `allowedMcpServers` in `~/.claude/settings.json` | every project; every other server stays off |
+| the same entry in a project's `.claude/settings.local.json` | that project only, for you |
+| remove the `allowedMcpServers` line | also turns on every MCP server it was keeping off (`init` counts them) |
+
+If managed settings set `allowManagedMcpServersOnly`, only whoever manages
+Claude Code can add the entry. Without the tools, planrails works as before.
+
+The plugin uses Claude Code's mods API, which its own types call early access:
+if a Claude Code update changes it, the tools go missing or report an error,
+and plans run as they do without the plugin.
+
 ## How a plan works
 
 Each plan is two files: `PLAN.md` (the map and tracker) and `LOG.md` (append-only
@@ -111,7 +180,7 @@ as the rule that avoids it). Because the reload line brings `PLAN.md` back at th
 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:
+`CLAUDE.local.md` line that reloads it:
 
 ```
 # Weekly digest email — plan
@@ -158,22 +227,37 @@ structural check, biased toward catching a faked "done":
   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
+- the plan your session holds (its NOW `session:` id starts
+  `$CLAUDE_CODE_SESSION_ID`) must be reloaded by
+  `@.project-management/plans/<id>/PLAN.md` on its own line in `CLAUDE.local.md`
+  (or `CLAUDE.md`, where plans before 0.7 put it), in the project root or a
+  folder above it, which is what Claude Code loads. In CI, at a terminal, and for
+  a teammate's plan it asks nothing: there the line lives in the holder's own
+  file. A `CLAUDE.md` line may not point at a plan that does not exist
 - 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.
+that ran the check decides. Each one names an action the method allows:
+
+- an active `PLAN.md` over ~3,000 words. When most of the words are finished
+  task rows, trimming prose cannot help, so the note says to end the plan at a
+  phase boundary and go on in a new one that carries the Rules, Decisions and
+  Learnings forward;
+- an active plan that only the owner can move: every open row is an `owner`
+  row or the close. It says to hand the plan over (`status: waiting`, its reload
+  line out, one line under "Waiting on you" in `CLAUDE.local.md`), so it stops
+  reloading until the owner's word reopens it.
+
+Both come from a real project's plans: three active plans there were 97–99%
+done, held open by one or two owner rows each, and reloaded about 59,000 words
+into every session. 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
+check-plans: note: weekly-digest: PLAN.md is 3,588 words besides its loop block, 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, this session's plan reloads, NOW is current
 ```
 
 `--verify` goes further and **runs** each proof again, with a timeout, and shows
@@ -187,9 +271,23 @@ trusted pipeline.
 - **It will not break teammates' builds.** The checker has no dependencies and
   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
-  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.
+- **Your plans stay out of the team's `CLAUDE.md`.** The reload line goes in
+  `CLAUDE.local.md`, which Claude Code loads beside `CLAUDE.md` and git ignores,
+  so opening or closing a plan changes no shared file, and a teammate's sessions
+  do not reload your plans. A teammate who takes a plan over adds its line to
+  their own `CLAUDE.local.md`. The one shared edit is a lasting learning, which
+  a plan's close graduates to `CLAUDE.md` as a normal, reviewed change. Other
+  agents do not import the line: open the plan by hand at session start.
+- **Moving from 0.6 or earlier.** A reload line already in `CLAUDE.md` keeps
+  working, and `npx planrails init` points it out. To move it, cut it from
+  `CLAUDE.md`, paste it into `CLAUDE.local.md`, and add `CLAUDE.local.md` to
+  `.gitignore`.
+- **Worktrees.** A git worktree has no copy of the ignored file. One under
+  `.claude/worktrees/`, where Claude Code makes them, still loads the main
+  checkout's `CLAUDE.local.md` from the folder above, but that line imports the
+  main checkout's copy of the plan. A session that works the plan in a worktree
+  adds the line to the worktree's own `CLAUDE.local.md`, or lists
+  `CLAUDE.local.md` in a `.worktreeinclude` file so Claude Code copies it in.
 - **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.
@@ -215,7 +313,8 @@ 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
+nobody, and the checker never judges it; it reads the line only to know which
+plan must reload for the session running the check. 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
 gone, and touched only the plan it was given when two were active.
@@ -234,6 +333,11 @@ 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. 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).
+line. 0.7.0 moves the reload line to `CLAUDE.local.md`, so a plan reloads
+only for whoever works it and a team's `CLAUDE.md` is left alone. 0.8.0 adds an
+optional Claude Code plugin that lets the model compact its session between
+tasks, a `waiting` state for plans only the owner can move, and plans that end
+at phase boundaries without losing what they know. See
+[`CHANGELOG.md`](CHANGELOG.md).
 
 MIT.

package/bin/planrails.mjs

@@ -5,7 +5,8 @@
  *   npx planrails init [--dir DIR] [--force]
  *       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. Run it again to update: a copy
+ *       install, no hooks, no edits to your CLAUDE.md, CLAUDE.local.md or .gitignore.
+ *       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.
  *
@@ -17,8 +18,9 @@
  */
 import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync, realpathSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { checkPlans, isActive, formatNotes } from "../tools/check-plans.mjs";
+import { checkPlans, isActive, formatNotes, reloadLines } from "../tools/check-plans.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const version = () => JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
@@ -48,6 +50,41 @@ export function stampOf(text) {
 }
 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; };
 
+/**
+ * Whether Claude Code's settings hide the planrails plugin's tools. Reads the
+ * settings files only (user, project, local, managed); writes nothing. Returns
+ * null when the plugin is not installed or the tools are allowed, else what hides
+ * them and the choices, as lines for init to print.
+ */
+export function pluginToolsCheck(project, { configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), platform = process.platform, managedPath } = {}) {
+  const read = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+  const managed = managedPath ?? ({ darwin: "/Library/Application Support/ClaudeCode/managed-settings.json", win32: "C:\\Program Files\\ClaudeCode\\managed-settings.json" }[platform] || "/etc/claude-code/managed-settings.json");
+  const sources = [
+    ["~/.claude/settings.json", join(configDir, "settings.json")],
+    [".claude/settings.json", join(project, ".claude", "settings.json")],
+    [".claude/settings.local.json", join(project, ".claude", "settings.local.json")],
+    ["managed settings", managed],
+  ].map(([label, path]) => ({ label, s: read(path) })).filter((x) => x.s);
+  const installed = sources.some(({ s }) => Object.entries(s.enabledPlugins || {}).some(([k, v]) => k.startsWith("planrails@") && v));
+  if (!installed) return null;
+  const lists = sources.filter(({ s }) => Array.isArray(s.allowedMcpServers));
+  if (!lists.length) return null;
+  const opens = (x) => x?.serverName === "planrails" || x?.serverUrl !== undefined || x?.serverCommand !== undefined;
+  const policy = sources.find((x) => x.label === "managed settings")?.s;
+  const locked = policy?.allowManagedMcpServersOnly === true;
+  const counted = locked ? [policy.allowedMcpServers || []] : lists.map(({ s }) => s.allowedMcpServers);
+  if (counted.some((l) => l.some(opens))) return null;
+  const where = lists.map((x) => x.label).join(" and ");
+  if (locked) return [`the planrails plugin is installed, but your organisation's managed settings lock allowedMcpServers (allowManagedMcpServersOnly), so its tools stay hidden and the model cannot compact between tasks. Ask whoever manages Claude Code to add { "serverName": "planrails" }. planrails works without it; the plugin stays idle.`];
+  const servers = Object.keys(read(existsSync(join(configDir, ".claude.json")) ? join(configDir, ".claude.json") : join(dirname(configDir), ".claude.json"))?.mcpServers || {}).length + Object.keys(read(join(project, ".mcp.json"))?.mcpServers || {}).length;
+  return [
+    `the planrails plugin is installed, but allowedMcpServers in ${where} hides its tools, so the model cannot compact between tasks. planrails works without them; the plugin stays idle and costs nothing. To turn them on, pick one; it applies from the next session:`,
+    `  a) every project, every other server still off: add { "serverName": "planrails" } to allowedMcpServers in ~/.claude/settings.json`,
+    `  b) this project only: add the same entry to .claude/settings.local.json (keep it out of git)`,
+    `  c) remove the allowedMcpServers line${servers ? `: it also turns on the ${servers} MCP server(s) configured in ~/.claude.json and .mcp.json that it now keeps off` : ""}`,
+  ];
+}
+
 function init(args) {
   const target = dirArg(args);
   const force = args.includes("--force");
@@ -85,6 +122,13 @@ function init(args) {
     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`);
   }
+  // Before 0.7 the reload line went in CLAUDE.md, which a team shares. It still
+  // works there; say where it goes now, and never move it.
+  const claudeMd = join(target, "CLAUDE.md");
+  const shared = existsSync(claudeMd) ? [...reloadLines(readFileSync(claudeMd, "utf8"))] : [];
+  if (shared.length) console.log(`  ! CLAUDE.md reloads ${shared.join(", ")}: since 0.7 the reload line goes in CLAUDE.local.md, which git ignores, so a plan reloads only for whoever works it and CLAUDE.md stays the team's. The line still works where it is; to move it, cut it from CLAUDE.md, paste it into CLAUDE.local.md, and add CLAUDE.local.md to .gitignore`);
+  const tools = pluginToolsCheck(target, process.env.PLANRAILS_MANAGED_SETTINGS ? { managedPath: process.env.PLANRAILS_MANAGED_SETTINGS } : {});
+  if (tools) console.log(`  ! ${tools.join("\n    ")}`);
   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`);
 
@@ -94,8 +138,12 @@ Next:
      (Or, in Claude Code, use /planrails if you installed the skill.)
   2. Add to the command you run before every commit:
        node .project-management/planrails/check-plans.mjs
-  3. When the agent writes a plan, it adds one line to your CLAUDE.md so the plan
-     reloads after every compaction:  @.project-management/plans/<id>/PLAN.md`);
+  3. When the agent writes a plan, it adds one line to CLAUDE.local.md, and that file
+     to .gitignore, so the plan reloads after every compaction, for you alone:
+       @.project-management/plans/<id>/PLAN.md
+  4. Optional, in Claude Code: let the model compact its session between tasks.
+       claude plugin marketplace add vivmagarwal/planrails
+       claude plugin install planrails@planrails`);
   return 0;
 }
 
@@ -110,7 +158,7 @@ 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 exit 0 evidence, active plans reload, NOW is current${verify ? " (proofs re-run)" : ""}`);
+  console.log(`check-plans: ${plans.length} plan(s) ok — every completion claim has a proof and exit 0 evidence, this session's plan reloads, NOW is current${verify ? " (proofs re-run)" : ""}`);
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.6.0",
+  "version": "0.8.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.6.0
+// planrails 0.8.0
 /**
  * check-plans — the machine-checked rails of the planner.
  *
@@ -8,16 +8,23 @@
  *    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.)
+ *  - the plan this session works must reload: when $CLAUDE_CODE_SESSION_ID starts
+ *    with the id on an active plan's NOW `session:` line, a CLAUDE.local.md or
+ *    CLAUDE.md in the root or a folder above it (what Claude Code loads) must carry `@.project-management/plans/<id>/PLAN.md` on its own
+ *    line. Elsewhere (CI, a terminal, a teammate's session) the line legitimately
+ *    lives in someone else's CLAUDE.local.md, so nothing is asked. A CLAUDE.md line
+ *    may not point at a plan that does not exist; a CLAUDE.local.md line is not
+ *    judged, because that file is untracked and outlives a branch switch.
  *  - 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.
+ *    line, and that line may not name only finished tasks. A plan that says
+ *    `status: done`, `paused` or `waiting` 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.
+ * It also prints notes: what a script can only suspect. An active PLAN.md over
+ * ~3,000 words of its own (the loop block not counted); an active plan only the
+ * owner can move; a plan that is no longer active but still reloads. 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
@@ -40,7 +47,7 @@
  * them without a real project.
  */
 import { readdirSync, readFileSync, existsSync, statSync, realpathSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve, dirname } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -250,7 +257,7 @@ export function checkPlan({ id, text, verify = false, run = null }) {
  * 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"]);
+const NOT_ACTIVE = new Set(["done", "paused", "retired", "closed", "shipped", "finished", "complete", "completed", "archived", "dropped", "cancelled", "canceled", "abandoned", "superseded", "onhold", "hold", "waiting"]);
 export function isActive(text) {
   const m = text.match(/^status:\s*([^\s·|]+)/im);
   return !(m && NOT_ACTIVE.has(norm(m[1])));
@@ -274,6 +281,19 @@ export function reloadLines(text) {
   return ids;
 }
 
+/**
+ * The session id on NOW's `session:` line (`name · id · since …`), lowercased, or
+ * null for none or a missing line. The id is the first field that is hex: six or
+ * more characters, or a whole session id. A line inside a code fence does not count.
+ */
+export function holderId(text) {
+  const lines = text.split(/\r?\n/), fenced = fenceMask(lines);
+  const k = lines.findIndex((l, i) => !fenced[i] && /^\s*session:/.test(l));
+  if (k < 0) return null;
+  const id = lines[k].replace(/^\s*session:/, "").split(/[·•|]/).map((f) => f.trim()).find((f) => /^[0-9a-f]{6,}(?:-[0-9a-f]+)*$/i.test(f));
+  return id ? id.toLowerCase() : null;
+}
+
 /** 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");
@@ -306,32 +326,68 @@ export function runProof(cmd, root, timeoutMs) {
  */
 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
+const countWords = (s) => s.split(/\s+/).filter(Boolean).length;
+// A row no one will finish: not a completion claim, and not waiting to be done.
+const SET_ASIDE = new Set(["dropped", "cancelled", "canceled", "wontfix", "wontdo", "abandoned", "skip", "skipped", "na"]);
+const isOpen = (t) => (EMPTY.test(t.status) || NOT_DONE.has(norm(t.status))) && !SET_ASIDE.has(norm(t.status));
+const isOwnerRow = (t) => norm(t.proof) === "owner";
+// The plan's own close: "close by PLANNER.md §5", "close the plan", "retire the plan" — not "close the dialog".
+const isCloseRow = (t) => /§\s*5|\bclose (?:by|per) planner\b|\b(?:close|retire) (?:the|this) plan\b/i.test(t.task);
 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`);
+  // The "How to work this plan" block is the method's, the same in every plan:
+  // count the plan's own words, which its author can trim.
+  const block = text.match(/^## How to work this plan[\s\S]*?(?=^## |(?![\s\S]))/m);
+  const words = countWords((block ? text.replace(block[0], "") : text).replace(/\|/g, " "));
+  const { tasks } = parseTasks(text);
+  if (words > WORD_LINE) {
+    // When the task rows are most of the plan, trimming prose cannot help, and the
+    // method keeps every row: ending the plan is the way to stop reloading them.
+    const rows = tasks.reduce((n, t) => n + countWords(`${t.id} ${t.task} ${t.status} ${t.proof} ${t.evidence}`), 0);
+    notes.push(rows * 2 > words
+      ? `${id}: PLAN.md is ${commas(words)} words besides its loop block, over the ~${commas(WORD_LINE)} line, and ${commas(rows)} are its task rows — it reloads into every session; end it at a phase boundary and go on in a new plan (its rows stay on disk as the record), and keep each evidence cell to the stamp, the exit code and the last line`
+      : `${id}: PLAN.md is ${commas(words)} words besides its loop block, over the ~${commas(WORD_LINE)} line — it reloads into every session; move history to LOG.md and trim prose before Learnings or Decisions`);
+  }
+  const open = tasks.filter(isOpen);
+  const owner = open.filter(isOwnerRow);
+  if (owner.length && open.every((t) => isOwnerRow(t) || isCloseRow(t)))
+    notes.push(`${id}: only the owner can move it now (${owner.map((t) => t.id).join(", ")}) — hand it over by PLANNER.md §5: status: waiting, session: none, its reload line out, and one line naming those rows under "Waiting on you" in CLAUDE.local.md; it stops reloading until their word reopens it`);
   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 } = {}) {
+/**
+ * Check every plan under root. Returns { plans, problems, notes }. `--verify` re-runs proofs, each with a timeout (10 min by default).
+ * `session` is the id of the session running the check; the plan it holds must reload.
+ */
+export function checkPlans({ root = ".", verify = false, verifyTimeoutMs = 10 * 60 * 1000, session = process.env.CLAUDE_CODE_SESSION_ID } = {}) {
   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;
+  const reloadsIn = (dir, name) => { const p = join(dir, name); return existsSync(p) ? reloadLines(readFileSync(p, "utf8")) : new Set(); };
+  const shared = reloadsIn(root, "CLAUDE.md");
+  // Claude Code loads both files from the root and every folder above it, so a
+  // worktree under .claude/worktrees/ also gets its checkout's. Read what it reads.
+  const loaded = new Set();
+  for (let d = resolve(root); ; d = dirname(d)) {
+    for (const name of ["CLAUDE.md", "CLAUDE.local.md"]) for (const id of reloadsIn(d, name)) loaded.add(id);
+    if (dirname(d) === d) break;
+  }
+  const me = (session || "").toLowerCase();
   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 }));
     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 (!isActive(text) && loaded.has(id))
+      notes.push(`${id}: it is no longer active but still reloads (a bare @ line in CLAUDE.local.md or CLAUDE.md) — take the line out, or wrap it in backticks; it costs every call of every session here`);
+    const holder = holderId(text);
+    if (me && holder && me.startsWith(holder) && isActive(text) && !loaded.has(id))
+      problems.push(`${id}: this session holds the plan but nothing reloads it here — add "@.project-management/plans/${id}/PLAN.md" on its own line, outside backticks, to CLAUDE.local.md, 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`);
+  for (const id of shared) 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, notes };
 }
 
@@ -360,6 +416,6 @@ if (isMain) {
     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 exit 0 evidence, active plans reload, NOW is current${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, this session's plan reloads, NOW is current${verify ? " (proofs re-run)" : ""}\n`);
   process.exit(0);
 }