planrails 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 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.
+
+- **Notes.** A problem is what a script can verify, and it still fails the build.
+  A note is what a script can only suspect: it prints as `check-plans: note: …`
+  on stdout before the final line, the exit code and the final line do not
+  change, and the agent that ran the check decides. `checkPlans` returns `notes`
+  beside `problems`; `npx planrails check` prints the same ones. On a plan with
+  no note the output is byte-for-byte what 0.5.2 printed.
+- **One note ships: an active `PLAN.md` over ~3,000 words.** The plan reloads
+  into every session, and nothing said when it had grown: four of four real plans
+  were past the stated line, one at 9,123 words. A retired plan gets no note; it
+  does not reload.
+- **The word line moves from ~2,000 to ~3,000.** The line was written before the
+  plan carried its own ~480-word block; two carefully kept plans measure ~2,800.
+  The doc was stale, not the plans.
+- **Why not hooks.** The idea began as advisory Claude Code hooks. Checked against
+  the hooks reference: a PreCompact hook cannot add context, no event fires at a
+  context threshold, a Stop hook's advice forces another turn, and no event knows
+  a plan's task closed. The check command already runs before every commit and
+  its output is already read, in any agent. `CONTRIBUTING.md` sets the bar for a
+  new note: a recorded failure behind it, silent on a healthy plan. A LOG-entry
+  reminder was tested on four real plans, never fired, and was not built.
+
+To update: `npx planrails@latest init`. No plan needs editing.
+
 ## 0.5.2 — 2026-09-13
 
 A second field test of 0.5.1, four scratch projects and seven fresh sessions, and

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.5.2 -->
+<!-- planrails 0.7.0 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -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,8 +55,9 @@ 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.
@@ -116,24 +119,33 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   checks, run end to end, the way a user would.
 - **Use repo-relative paths** (`lib/digest/query.ts`), never absolute ones. They
   are clickable and they survive a move to another machine.
-- **Keep PLAN.md under ~2,000 words.** Trim prose before Learnings or Decisions.
-  History goes in LOG.md, not here.
-- **Add the reload line.** In the project-root `CLAUDE.md`, under a short
-  "Active plans" spot, add:
+- **Keep PLAN.md under ~3,000 words.** It reloads into every session, so every
+  word is paid for again and again. Trim prose before Learnings or Decisions.
+  History goes in LOG.md, not here. Past the line, the checker prints a `note:` —
+  advice, not a failure: the run still exits 0, and you decide what to trim.
+- **Add the reload line.** In the project-root `CLAUDE.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
+  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
   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
@@ -151,9 +163,9 @@ 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 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,
@@ -206,8 +218,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`
@@ -296,14 +309,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.
 
 ---
 
@@ -315,14 +331,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
@@ -332,6 +350,12 @@ Each line here was paid for by a real failure in earlier planning systems:
   fixes.
 - **History stays out of the plan.** One plan grew a 16,000-word progress section,
   stamped two hours behind its own log. NOW is four lines; LOG.md is the history.
+- **The checker's notes advise; they never block.** A script can verify an exit
+  code, so that is a problem and fails the build. It can only suspect that a plan
+  is too long, so that is a note, and you judge. Four of four real plans had
+  outgrown the word line with nothing saying so. The check command already runs
+  before every commit and its output is already read, so a reminder there needs
+  no hook. A note needs a real failure behind it, or it is noise.
 - **Sub-agent findings are leads** because four spot-checked findings were each
   right in direction and wrong in number, and a wrong number becomes a wrong plan.
   Delegation is method, not machinery: a brief of one unit and nothing else worked.
@@ -384,7 +408,7 @@ Read NOW, then Rules and Learnings; do not re-read Context. One task at a time:
 4. `done` only if N is 0. A proof of `owner` is closed only by the person's words with the date, never by you: until then the row is `blocked`, the reason in its evidence cell, and RESUME says so. Point NOW at the next task; append an entry to LOG.md: did, files, proof, next, learned.
 5. If it fought back, add a Learning: the trap, then the rule. A verified fact goes in Context, a choice in Decisions.
 
-NOW is 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` 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.
 
 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.

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/
@@ -111,7 +113,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,12 +160,28 @@ 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.
+
+```
+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, this session's plan reloads, NOW is current
+```
+
 `--verify` goes further and **runs** each proof again, with a timeout, and shows
 the last line a failing proof printed. Because it executes the commands written in
 the plan, use it only on plans you trust — run the default structural check in CI
@@ -175,9 +193,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.
@@ -203,7 +235,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.
@@ -220,6 +253,10 @@ installed files under `.project-management/planrails/`. 0.4.0 makes the plan
 carry its own loop, makes the checker demand `exit 0` and check the reload line,
 and teaches the executor to brief sub-agents from the plan. 0.5.0 names the
 session working a plan and has every session check for a live holder before it
-touches the plan. See [`CHANGELOG.md`](CHANGELOG.md).
+touches the plan. 0.6.0 lets the checker advise without blocking: a `note:` for
+what a script can only suspect, starting with a plan that has outgrown its word
+line. 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
+[`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.
  *
@@ -18,7 +19,7 @@
 import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync, realpathSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkPlans, isActive } 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;
@@ -85,6 +86,11 @@ 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 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 +100,9 @@ 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`);
   return 0;
 }
 
@@ -103,13 +110,14 @@ function check(args) {
   const root = dirArg(args);
   if (!existsSync(root)) { console.error(`planrails check: --dir path does not exist: ${root}`); return 2; }
   const verify = args.includes("--verify");
-  const { plans, problems } = checkPlans({ root, verify });
+  const { plans, problems, notes } = checkPlans({ root, verify });
+  process.stdout.write(formatNotes(notes));
   if (!plans.length && !problems.length) { console.log("check-plans: no plans under .project-management/plans/ — nothing to check"); return 0; }
   if (problems.length) {
     console.error(`check-plans: ${problems.length} problem(s):\n${problems.map((p) => `  - ${p}`).join("\n")}`);
     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.5.2",
+  "version": "0.7.0",
   "description": "Plans that survive a lost session, and \"done\" that means done. A planner prompt and a tiny checker.",
   "type": "module",
   "license": "MIT",

package/tools/check-plans.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// planrails 0.5.2
+// planrails 0.7.0
 /**
  * check-plans — the machine-checked rails of the planner.
  *
@@ -8,13 +8,21 @@
  *    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.
  *
+ * It also prints notes: what a script can only suspect (an active PLAN.md over
+ * ~3,000 words, which reloads into every session). A note goes to stdout before
+ * the final line and never changes the exit code; whoever ran the check decides.
+ *
  * The rule is biased toward catching a faked "done": a task counts as a
  * completion claim UNLESS its status is blank or an explicit not-done word
  * (todo, doing, blocked, …). So no spelling of "done" — done, completed, ✅,
@@ -36,7 +44,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";
 
@@ -270,6 +278,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");
@@ -295,21 +316,52 @@ export function runProof(cmd, root, timeoutMs) {
   return { code: r.status ?? 1, last };
 }
 
-/** Check every plan under root. Returns { plans, problems }. `--verify` re-runs proofs, each with a timeout (10 min by default). */
-export function checkPlans({ root = ".", verify = false, verifyTimeoutMs = 10 * 60 * 1000 } = {}) {
+/**
+ * Notes on one plan: what a script can only suspect. A note prints and the run
+ * still exits 0; whoever ran the check decides. Only an active plan gets one —
+ * a retired plan does not reload, so its size costs nothing.
+ */
+export const WORD_LINE = 3000;
+const commas = (n) => String(n).replace(/\B(?=(\d{3})+$)/g, ","); // no Intl: a Node built without it would drop the comma
+export function planNotes({ id, text }) {
+  const notes = [];
+  if (!isActive(text)) return notes;
+  const words = text.split(/\s+/).filter(Boolean).length;
+  if (words > WORD_LINE) notes.push(`${id}: PLAN.md is ${commas(words)} words, over the ~${commas(WORD_LINE)} line — it reloads into every session; move history to LOG.md and trim prose before Learnings or Decisions`);
+  return notes;
+}
+/** The notes as printed: one "note:" line each, newline-terminated, or "" when there are none. */
+export const formatNotes = (notes) => notes.map((n) => `check-plans: note: ${n}\n`).join("");
+
+/**
+ * Check every plan under root. Returns { plans, problems, notes }. `--verify` re-runs proofs, each with a timeout (10 min by default).
+ * `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 }));
-    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`);
+    notes.push(...planNotes({ id, text }));
+    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`);
-  return { plans, problems };
+  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 };
 }
 
 // --- CLI ----------------------------------------------------------------------
@@ -330,12 +382,13 @@ if (isMain) {
   const verify = args.includes("--verify");
   const root = flagValue(args, "--root") || flagValue(args, "--dir") || ".";
   if (!existsSync(root)) { process.stderr.write(`check-plans: --root path does not exist: ${root}\n`); process.exit(2); }
-  const { plans, problems } = checkPlans({ root, verify });
+  const { plans, problems, notes } = checkPlans({ root, verify });
+  process.stdout.write(formatNotes(notes));
   if (!plans.length && !problems.length) { process.stdout.write("check-plans: no plans under .project-management/plans/ — nothing to check\n"); process.exit(0); }
   if (problems.length) {
     process.stderr.write(`check-plans: ${problems.length} problem(s):\n${problems.map((p) => `  - ${p}`).join("\n")}\n`);
     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);
 }