planrails 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.5.0 — 2026-09-13
+
+One method change, paid for by a real collision. The reload line loads an active
+plan into every session opened in a checkout, and on 2026-09-13 a second session
+in one repo read the reloaded plan, was told "continue", committed, and was
+starting the next task while the first session was mid-edit on the same files and
+the same PLAN.md. The checker is unchanged apart from its stamp; `init` still
+writes only its two files.
+
+- **A plan names the session working it.** NOW gains a fourth line,
+  `session: <name> · <first 8 characters of the session id> · since <date>`, or
+  `session: none` — written when the plan is written, when a task goes `doing`,
+  and on a takeover; cleared at close. It is a lead, not a lock: whether that
+  session is alive is decided by the live listing (`claude agents --json`, which
+  is documented and lists headless runs too; `ListAgents` inside Claude Code), so
+  a stale line from a closed terminal blocks nobody.
+- **The plan's block runs the check.** "How to work this plan" now tells a
+  session, before any task goes `doing` and even when the person asked it to
+  continue: re-read NOW from disk, list the live sessions, run
+  `git status --short`, and — if the line names a live session that is not you,
+  or says `none` while a peer in the checkout is busy or plan files are dirty —
+  stop, report and ask before writing to the plan, its files, or a commit.
+  Several reloaded plans: work only the one assigned in this session, and say
+  which.
+- **One plan per session, one session per plan** replaces "one active plan per
+  repo". Several plans may be active, each with its own reload line and one
+  holder; keep them few, since every session reloads all of them. The "Active
+  plans" heading in `CLAUDE.md` carries one line saying so.
+- **PLANNER.md** §3 has the rule and "name the session"; §4 the check, the listing
+  and the decision rules (busy, idle, waiting, stale, a plan with no line, a
+  worktree, a sub-agent), and how to stop and ask; §5 clears the line at close;
+  "Why it is shaped this way" records the incident.
+- **Existing plans: update by hand.** `init` never touches a plan. Add the
+  `session:` line to NOW, change "NOW is three lines" to four, and append the
+  block's last paragraph from the template. A plan without them still passes the
+  checker, which ignores the line; a test pins that.
+- Field-tested with headless sessions in a scratch project: told only "Continue
+  the active plan.", a second session stopped, reported and asked while the
+  holder was live (idle with a clean tree; busy with a dirty PLAN.md and no
+  line), and wrote nothing; took over a stale claim and finished the plan by the
+  loop; and, told to continue the second of two plans, wrote its claim on that
+  one and left the held plan byte-identical. One wording gap found and fixed: the
+  id is the session id, not the ref `ListAgents` prints. 73 tests.
+
+## 0.4.1 — 2026-09-13
+
+- The Claude Code skill is `/planrails`, not `/plan`, because Claude Code has a
+  `/plan` of its own. Install it at `~/.claude/skills/planrails/`; the README and
+  the sentence `init` prints say so. Nothing else changed.
+
 ## 0.4.0 — 2026-09-13
 
 A review of 0.3.0 against a real multi-session plan, the Claude Code docs, and

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.4.0 -->
+<!-- planrails 0.5.0 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -125,10 +125,26 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   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. One active plan per repo at a time; to pause another, set its
-  header to `status: paused` and wrap its line in backticks. (For a tool that
+  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.)
+- **One plan per session, one session per plan.** A repo may hold several active
+  plans, each with its own reload line and each held by one session, named on its
+  NOW `session:` line. Every session reloads all of them, so keep them few; a plan
+  nobody is working is paused (`status: paused`, its line in backticks). A session
+  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;
+  Claude Code gives a second live session with that name a variant suffix.
+- **Name the session.** NOW's `session:` line names the session that will execute
+  the plan: yours, if that is you. In Claude Code the name is what `ListAgents`
+  prints after "This session is", and the id is the first eight characters of
+  `$CLAUDE_CODE_SESSION_ID` — the `sessionId` that `claude agents --json` prints,
+  not the bracketed ref `ListAgents` shows. The id survives a resume when the name
+  may not. Elsewhere, write anything a reader can tell apart (`codex@mbp tty003`);
+  `none` when handing the plan to someone else.
 - **Wire the checker, if the project runs Node and has a check command.**
   `npx planrails init` already put it at `.project-management/planrails/check-plans.mjs`;
   if you did not run init, copy `tools/check-plans.mjs` from
@@ -154,9 +170,46 @@ for — read them and you skip the struggle instead of repeating it. After a
 compaction, also run `git status --short`: it is the journal of in-flight work
 that NOW may not mention yet.
 
+**Find out who holds the plan before you touch it.** The reload line puts every
+active plan into every session opened in this checkout; a plan in your context is
+not a work order. At session start, read NOW's `session:` line and say in one line
+which plan you are on, or none. Before any task goes `doing` — even when the
+person just asked you to continue; they can forget which window holds the plan —
+re-read that line from disk (your reloaded copy may be older than the file), list
+the live sessions, and run `git status --short`. `claude agents --json` lists every
+live session on the machine: `name`, `sessionId`, `cwd`, `pid`, `status` (`busy`,
+`idle`, or `waiting` for the person) and `startedAt`; `--cwd <dir>` keeps those
+started under a directory, and a headless `claude -p` run is listed too. In Claude
+Code, `ListAgents` names you and the peers, but its bracketed ref is not the
+session id; the id is `$CLAUDE_CODE_SESSION_ID`. An entry changes on status, not
+on edits: last activity is the plan's `updated:` stamp or its transcript's mtime
+under `~/.claude/projects/`. Then decide:
+
+- The line names you: go on.
+- It names a live session that is not you: stop. Busy is mid-task; idle is between
+  turns and still the holder; waiting means it needs the person — tell them.
+- It names a session the listing lacks: say so. No other live session in this
+  checkout: take over, write your claim. One is: stop; the id tells whether it is
+  that conversation resumed under a new name.
+- `none`, or no line (an older plan): a busy session in this checkout, or plan
+  files dirty in `git status`: stop. Otherwise say what you saw in one line, write
+  your claim, go on.
+- 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.
+
+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`
+run ends its turn with the question — whether to leave the plan to that session,
+take it over here once they have stopped it, or work something else. Write nothing
+to the plan, its files, or a commit until they answer. Stage commits by path;
+another session's in-flight edits are not yours to sweep up.
+
 The loop for each task:
 
-1. **Set it doing.** Change the status cell to `doing`. Update **NOW**.
+1. **Check who holds the plan** (above), then **set it doing.** Change the status
+   cell to `doing`. Update **NOW**, and put your session on its `session:` line
+   (`since` from `date` on a takeover; unchanged when it already names you).
 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
@@ -225,8 +278,8 @@ the task `blocked` with the reason, and stop. Do not hand-fix state to look done
    defects the self-tests had passed.
 3. **Update the docs** the work changed — in the same step, per the project's
    documentation guide if it has one.
-4. **Retire the plan.** Set its header to `status: done`, then wrap its reload
-   line in backticks, or delete it. Do not move a bare `@` line under a
+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 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.
@@ -261,12 +314,20 @@ Each line here was paid for by a real failure in earlier planning systems:
   repeated. The same struggle coming back in a new chat is the exact failure this
   fixes.
 - **History stays out of the plan.** One plan grew a 16,000-word progress section,
-  stamped two hours behind its own log. NOW is three lines; LOG.md is the history.
+  stamped two hours behind its own log. NOW is four lines; LOG.md is the history.
 - **Sub-agent findings are leads** because four spot-checked findings were each
   right in direction and wrong in number, and a wrong number becomes a wrong plan.
   Delegation is method, not machinery: a brief of one unit and nothing else worked.
 - **Repo-relative paths** because absolute paths break on the next machine, and a
   path a reader cannot open is worse than none.
+- **The `session:` line and the check before `doing`** exist because the reload
+  line loads a plan into every session opened in a checkout, not only the one
+  working it. On 2026-09-13 in edodo-video, a second session, opened for a
+  planrails upgrade, read the reloaded plan, was told "continue with T5",
+  committed, and was starting T5b while the first session was mid-edit on the
+  same files and the same PLAN.md; the owner interrupted. The person had asked,
+  so the check runs even then. The claim is a lead and the live listing decides,
+  so a stale line from a closed terminal blocks nobody.
 - **Nothing the method needs is installed.** `npx planrails init` only copies two
   files, and you can copy them by hand instead. The old version was a heavy
   package, and that is what broke on the projects that were not npm — Python,
@@ -295,6 +356,7 @@ status: active · opened <YYYY-MM-DD> · id: <kebab-id>
 RESUME: <T2 — the one thing to do next, with the file; written for a stranger>
 NEXT: <T3 · T4 · …>
 updated: <YYYY-MM-DD HH:MM, from `date`>
+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:
@@ -304,7 +366,9 @@ Read NOW, then Rules and Learnings; do not re-read Context. One task at a time:
 4. `done` only if N is 0. Point NOW at the next task; append an entry to LOG.md: did, files, proof, next, learned.
 5. If it fought back, add a Learning: the trap, then the rule. A verified fact goes in Context, a choice in Decisions.
 
-NOW is three lines for a stranger; on a long task note the sub-step, and update it before any turn ends. Blocked: say so in NOW, reason in the evidence cell. A task you will not do is `dropped`; its row stays. After a compaction, `git status --short` shows the in-flight work. Edit this file with the editor or a quoted heredoc; an unquoted shell string eats backticks. A self-contained task may go to a sub-agent briefed with its row, Rules, Decisions, Learnings and Context; it writes to a named file and reports a few lines, which are leads; you run the proof before pasting evidence. If the project runs Node, `node .project-management/planrails/check-plans.mjs` must pass. Full method: `.project-management/planrails/PLANNER.md` §4.
+NOW is four lines for a stranger; on a long task note the sub-step, and update it before any turn ends. Blocked: say so in NOW, reason in the evidence cell. A task you will not do is `dropped`; its row stays. After a compaction, `git status --short` shows the in-flight work. Edit this file with the editor or a quoted heredoc; an unquoted shell string eats backticks. A self-contained task may go to a sub-agent briefed with its row, Rules, Decisions, Learnings and Context; it writes to a named file and reports a few lines, which are leads; you run the proof before pasting evidence. If the project runs Node, `node .project-management/planrails/check-plans.mjs` must pass. Full method: `.project-management/planrails/PLANNER.md` §4.
+
+The `session:` line names the one session working this plan. Before any task goes `doing`, even when asked to continue: re-read NOW from disk, run `claude agents --json` (in Claude Code, `ListAgents` names you) and `git status --short`. If the line names a live session that is not you, or says `none` while another session in this checkout is busy or plan files are dirty: stop, report what you found, and ask before writing to the plan, its files, or a commit. A named session the listing lacks is stale: say so, take over. Other reloaded plans are context; work only the one assigned in this session, and say which.
 
 ## Goal
 <4–5 sentences: what we are building and why. What is true when it ships. A mermaid diagram only if the architecture is non-trivial.>

package/README.md

@@ -9,8 +9,10 @@ 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
-   operating loop, so a session that never saw the planner prompt still works it
-   correctly. (Claude Code reloads it for you; another agent opens it by hand.)
+   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
+   Code reloads it for you; another agent opens it by hand.)
 2. **Every task names its proof before the work starts** — the command that will
    show it is done. No command, no way to fake it later.
 3. **A task is done only when its proof was run and its exit code pasted in.** An
@@ -92,11 +94,12 @@ The checker needs Node to run. If your project has no Node at all, skip it — t
 plan still works, and your agent enforces the gate the way `PLANNER.md` says. The
 planner method does not depend on any language.
 
-### As a `/plan` command in Claude Code
+### As a `/planrails` command in Claude Code
 
-Copy [`skill/`](skill) to `~/.claude/skills/plan/`. Then `/plan` starts the same
-flow in any project that has run `npx planrails init` — the skill reads the
-project's own copy of `PLANNER.md`, so every project follows the version it has.
+Copy [`skill/`](skill) to `~/.claude/skills/planrails/`. Then `/planrails` starts
+the same flow in any project that has run `npx planrails init` — the skill reads
+the project's own copy of `PLANNER.md`, so every project follows the version it
+has. (It is not called `/plan`, because Claude Code has a `/plan` of its own.)
 
 ## How a plan works
 
@@ -119,9 +122,10 @@ status: active · opened 2026-09-12 · id: weekly-digest
 RESUME: T2 — render the digest through the email seam (lib/digest/render.ts)
 NEXT: T3 schedule the Monday send · T4 docs
 updated: 2026-09-12 14:20
+session: app-3f · 7c1d2e9a · since 2026-09-12 14:05
 
 ## How to work this plan
-(the loop a session follows: set doing, run the proof, paste exit N, done on 0, update NOW, log it)
+(the loop a session follows: set doing, run the proof, paste exit N, done on 0, update NOW, log it — and, before any doing, the check that no other live session holds the plan)
 
 ## Tasks
 | id | task | status | proof | evidence |
@@ -176,6 +180,27 @@ trusted pipeline.
 - **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.
+- **Two machines, one plan.** The `session:` line names a session on the machine
+  that wrote it; another machine cannot list it. There, git is the record: pull
+  before you take a task, and read a `doing` row with a fresh `updated:` stamp as
+  someone's in-flight work.
+
+## Several sessions in one checkout
+
+The reload line puts an active plan into every Claude Code session opened in that
+directory, so a second session can read the plan and start the task the first one
+is on. A plan's NOW names the session working it
+(`session: app-3f · 7c1d2e9a · since 2026-09-12 14:05`), and the plan's block tells
+every session, before it sets a task `doing`, to re-read that line, list the live
+sessions (`claude agents --json`; `ListAgents` inside Claude Code) and run
+`git status --short`, and to stop and ask when another live session holds the plan
+— even when you asked it to continue, because you can forget which window owns
+it. One plan per session, one session per plan; the other reloaded plans are
+context. 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
+second session told "Continue the active plan." stopped and asked while the first
+was live, took over when it was gone, and touched only the plan it was given when
+two were active.
 
 ## History
 
@@ -187,7 +212,8 @@ rails, as a prompt plus one checker, with a two-command CLI that only copies
 files. 0.3.0 makes learnings a reloaded part of every plan and groups the two
 installed files under `.project-management/planrails/`. 0.4.0 makes the plan
 carry its own loop, makes the checker demand `exit 0` and check the reload line,
-and teaches the executor to brief sub-agents from the plan. See
-[`CHANGELOG.md`](CHANGELOG.md).
+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).
 
 MIT.

package/bin/planrails.mjs

@@ -83,7 +83,7 @@ function init(args) {
   console.log(`
 Next:
   1. Tell your agent:  Follow .project-management/planrails/PLANNER.md and tell me when you are ready to plan <the feature> with me.
-     (Or, in Claude Code, use /plan if you installed the skill.)
+     (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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.4.0",
+  "version": "0.5.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.4.0
+// planrails 0.5.0
 /**
  * check-plans — the machine-checked rails of the planner.
  *