planrails 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # 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.

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.7.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.
 
 ---
@@ -63,14 +63,17 @@ tell you what the repo already says.
    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>
@@ -78,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">
@@ -107,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
@@ -123,6 +136,26 @@ 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.
+- **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:
   ```
@@ -146,7 +179,7 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
 - **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 in this checkout reloads all of them, so keep them few; a plan
-  nobody is working is paused (`status: paused`, its line in backticks). A session
+  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;
@@ -167,8 +200,21 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   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.
@@ -238,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
@@ -254,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.
@@ -293,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
@@ -352,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
@@ -401,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 deleted from CLAUDE.local.md. 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.
@@ -430,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">
@@ -445,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

@@ -58,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
@@ -103,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
@@ -172,13 +239,24 @@ structural check, biased toward catching a faked "done":
 
 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: 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
 ```
 
@@ -256,7 +334,10 @@ 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. 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. See
+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

@@ -18,6 +18,7 @@
  */
 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, reloadLines } from "../tools/check-plans.mjs";
 
@@ -49,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");
@@ -91,6 +127,8 @@ function init(args) {
   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`);
 
@@ -102,7 +140,10 @@ Next:
        node .project-management/planrails/check-plans.mjs
   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`);
+       @.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;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.7.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.7.0
+// planrails 0.8.0
 /**
  * check-plans — the machine-checked rails of the planner.
  *
@@ -16,12 +16,15 @@
  *    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
@@ -254,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])));
@@ -323,11 +326,33 @@ 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. */
@@ -356,6 +381,8 @@ export function checkPlans({ root = ".", verify = false, verifyTimeoutMs = 10 *
     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 (!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`);