planrails 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 0.5.1 — 2026-09-13
+
+A fresh-context review of 0.5.0, run the same day, found the block — the one copy
+of the rule that survives into a real plan — weaker than §4, and wrong in one
+case: it matched a holder by name, and a name changes (accepting a plan in Claude
+Code's plan mode retitles the session; `claude -n` and a resume can rename it), so
+a live holder could read as stale and be taken over. This repo's own plan hit it
+within the hour.
+
+- **The block matches by session id.** Its paragraph now says what the line holds
+  (name · first 8 characters of the session id · since), that the id is what to
+  match, which listing to run and what it shows, the three outcomes — stop; stale
+  only when the id is unlisted *and* no other session in the checkout is live;
+  write your own line on `doing` and on a takeover — and what to do without a
+  listing: git is the record. Step 1 of the loop puts the session on the line.
+- **§4** matches the id over the whole listing before any directory filter (a
+  session can hold a plan from another directory), drops the last-activity
+  advice, and adds the no-listing rule and "a plan you wrote in this session
+  already names you"; §1 speaks of plans in the plural and who holds each; the
+  "Why" bullet names no private repository.
+- The skill puts the listing first and no longer says "or plausibly does"; the
+  worked example's `CLAUDE.md` carries the held-by sentence; the template pin now
+  fails when the NOW line is lost or the paragraph leaves the block. 74 tests.
+- **Existing 0.5.0 plans:** replace the block's last paragraph and its step 1 with
+  the template's.
+- Field-tested on these files, with PLAN.md hashes recorded and each case's start
+  state committed: a holder renamed after the claim was written was recognised
+  by its id and left alone; a plan with no line, a dirty PLAN.md and a busy peer
+  stopped the newcomer; told to continue the second of two plans, a session
+  claimed only that one and left the held plan byte-identical; a stale claim
+  with nothing else live was taken over with a correctly written line, and the
+  plan finished by the loop. 0.5.0's field test ran the block pasted into a 0.4.1
+  planner: the block was tested, §4 was not; this one runs the shipped bytes.
+
+## 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

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.4.1 -->
+<!-- planrails 0.5.1 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -58,8 +58,9 @@ tell you what the repo already says.
 2. **List `docs/`** and read the ones this feature touches. Use sub-agents for
    long files so your own context stays clear. Record each relevant doc's path
    and one line of what it holds.
-3. **Read `.project-management/`.** Read the active plan in full; list the
-   finished ones by id only.
+3. **Read `.project-management/`.** Read in full the plan this session is
+   assigned — the person names it; if one plan is active, that one — and list
+   the others by id, with who holds each (NOW's `session:` line).
 4. **Read the last ~20 commits** (`git log --oneline -20`) for how the code moves.
 
 **A sub-agent's finding is a lead, not a fact.** If it names a file and line, you
@@ -73,7 +74,7 @@ READY — <project name>
 Stack:      <language, framework, package manager>
 Always-on:  <CLAUDE.md | AGENTS.md | README.md>
 Check:      <the check command>   Test: <the test command>
-Plans:      <existing plan ids; which is active, or "none">
+Plans:      <existing plan ids; which are active and who holds each, or "none">
 Docs:       <relevant doc paths, or "none">
 Touches:    <the folders this feature will change>
 Questions:  <up to 4 things the repo did not answer, or "none">
@@ -125,10 +126,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 +171,53 @@ 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 — an interactive one with `name`, `sessionId`, `cwd`,
+`pid`, `status` (`busy`, `idle`, or `waiting` for the person) and `startedAt`; a
+background one with `state` — and a headless `claude -p` run is listed too. Match
+the line's id against `sessionId` over the whole listing; `cwd` then tells which
+peers are in this checkout. Never filter by directory before matching the id: a
+session can hold a plan from another directory. Names are for people: accepting
+a plan in Claude Code's plan mode retitles the session, `claude -n` and a resume
+can rename it. 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`. Then
+decide:
+
+- The line's id is yours, whatever your name is now: go on. A plan you wrote in
+  this session already names you.
+- Its id is live and not yours: stop. Busy is mid-task; idle is between turns
+  and still the holder; waiting means it needs the person — tell them.
+- Its id is not listed: the claim is stale only when no other session in this
+  checkout is live — then say so, take over, write your claim. When one is live,
+  stop and ask; it may be the holder under a new id, after a branch or a fork.
+- `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.
+- No `claude` command (another agent), or a plan shared across machines: there is
+  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.
+
+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,10 +286,10 @@ 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
-   "Finished" heading: it still imports, and every retired plan would reload
-   forever. The status comes first: the checker holds an `active` plan to its
+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.
 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
@@ -261,12 +322,21 @@ 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, a second session in one repo, opened for a tool
+  upgrade, read the reloaded plan, was told to 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 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 — and it is matched by session id,
+  because the same day a session's name changed within the hour.
 - **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,16 +365,19 @@ 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:
-1. Set it `doing`; point NOW at it.
+1. Set it `doing`; point NOW at it; put your session on its `session:` line.
 2. Do the work: fix causes, not symptoms; the simplest change that works end to end.
 3. Run the proof now. Paste `YYYY-MM-DD HH:MM · exit N · "last line"` into evidence. Every stamp comes from `date` run at that moment, never typed from memory.
 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: name · first 8 characters of its session id · since. Match by id; names change. `claude agents --json` lists every live session on this machine with `sessionId`, `cwd` and `status`; in Claude Code your id is `$CLAUDE_CODE_SESSION_ID`. Before any task goes `doing`, even when asked to continue: re-read NOW from disk, run that listing and `git status --short`. Stop, report what you found, and ask before writing to the plan, its files, or a commit if the line's id is live and not yours, or if the line is `none` or missing while another session in this checkout is busy or plan files are dirty. If the id is not listed and no other session in this checkout is live, the claim is stale: say so, take over. On `doing` and on a takeover, write your own name · id · since, from `date`. Without a `claude` command, or on another machine, git is the record: pull first, treat a fresh `doing` row as someone's work in flight, and ask. 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
@@ -94,7 +96,7 @@ planner method does not depend on any language.
 
 ### As a `/planrails` command in Claude Code
 
-Copy [`skill/`](skill) to `~/.claude/skills/planrails/`. Then `/planrails` starts
+Copy [`skill/`](https://github.com/vivmagarwal/planrails/tree/main/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.)
@@ -120,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 |
@@ -177,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 — 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.
 
 ## History
 
@@ -188,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/package.json

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