planrails 0.6.0 → 0.7.0

package/CHANGELOG.md

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

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.6.0 -->
+<!-- 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.
@@ -120,22 +123,29 @@ 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:
+- **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
@@ -153,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,
@@ -208,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`
@@ -298,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.
 
 ---
 
@@ -317,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
@@ -392,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,9 +160,13 @@ 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
 
@@ -173,7 +179,7 @@ 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: 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 +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.
@@ -215,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.
@@ -234,6 +255,8 @@ 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. 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, 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;
@@ -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;
 }
 
@@ -110,7 +117,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.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.6.0
+// planrails 0.7.0
 /**
  * check-plans — the machine-checked rails of the planner.
  *
@@ -8,9 +8,13 @@
  *    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.
@@ -40,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";
 
@@ -274,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");
@@ -316,22 +333,34 @@ export function planNotes({ id, text }) {
 /** 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`);
+    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 +389,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);
 }