planrails 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.5.2 — 2026-09-13
+
+A second field test of 0.5.1, four scratch projects and seven fresh sessions, and
+a newcomer's pass over the docs. The published behaviour held: a stale claim was
+taken over by id, a live holder stopped a second session, a session assigned one
+of two plans touched only that one. Four gaps in the plan's block, and one in the
+worked example, are closed here.
+
+- **Two sessions can work two plans in one checkout.** The block's rule for an
+  unheld plan (`session: none`, or no line) said stop whenever any session in the
+  checkout was busy or any plan file was dirty, so the second of two sessions
+  always had to ask. Now a session assigned an unheld plan writes its line and
+  goes on, unless *that plan's* files are dirty or a busy session in the checkout
+  has its id on no plan's `session:` line. The same-plan rule is unchanged: a
+  live holder, matched by id, stops you.
+- **An `owner` proof is closed only by the person.** A field session closed an
+  owner task with a check of its own and an invented exit code; the checker cannot
+  see that. The block and §4 now say: the row stays `blocked` with the reason in
+  its evidence cell, and RESUME says so.
+- **NOW keeps its shape, and the block says how a plan closes.** A session
+  renamed RESUME to DONE, wrote the `session:` line twice and left a finished plan
+  active. The block says NOW is exactly the four lines, and points at §5 for the
+  close. The checker now fails an active plan whose NOW section has no RESUME
+  line, the one hole a renamed line opened in the NOW rule.
+- **The session rule is a list.** Its paragraph fell from 197 words to four
+  bullets; the whole block is about 480 words, up from 443, with the owner and
+  close clauses added.
+- **Existing 0.5.0 and 0.5.1 plans:** replace the block with the template's, so
+  they carry the unheld-plan rule and the owner clause; `init` cannot tell them
+  from 0.5.2 plans, since they already have a `session:` line.
+- **The worked example carries the template's block, byte for byte**, pinned by a
+  test. It had shipped the 0.5.0 paragraph that matched holders by name.
+- **`init` points out plans that predate 0.5**: an active plan with no `session:`
+  line is named, with the by-hand steps from 0.5.0. `init` still never touches a
+  plan.
+- Timestamps come from the shell clock: `date`, or `Get-Date` on Windows, where
+  `date` prompts. The README no longer suggests `ListAgents` can do the id match.
+  The 0.4.0 entry no longer overstates the stray-backtick fix. 77 tests.
+
 ## 0.5.1 — 2026-09-13
 
 A fresh-context review of 0.5.0, run the same day, found the block — the one copy
@@ -103,8 +142,8 @@ nothing but its two files.
   Re-run the proof and paste its exit code.
 - **The checker fails closed on a row it cannot read.** The cell splitter follows
   the CommonMark rule for backtick runs, so a stray backtick or three backticks in
-  prose no longer shift the columns; a row whose cell count still differs from the
-  header's is a problem instead of a silent pass. A task table inside a code fence
+  prose are read the way CommonMark reads them; a row whose cell count still
+  differs from the header's is a problem instead of a silent pass. A task table inside a code fence
   is ignored, a table right after the task table with no heading between is no
   longer read as tasks, and `**id**` in a header is read.
 - **Two integrity checks keep the reload honest.** When the project has a

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.5.1 -->
+<!-- planrails 0.5.2 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -152,7 +152,8 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   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, or if NOW points at a finished task. If the project is not Node,
+  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,
@@ -196,9 +197,11 @@ decide:
 - 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.
+- `none`, or no line (an older plan): say what you saw in one line, write your
+  claim, go on — unless this plan's files are dirty in `git status`, or a busy
+  session in this checkout has its id on no plan's `session:` line; then stop
+  and ask. A busy peer whose id is on another plan's line is working that plan,
+  so two sessions can work two plans in one checkout side by side.
 - 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.
@@ -217,14 +220,20 @@ The loop for each task:
 
 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).
+   (`since` from the shell clock 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
-   line of output. Take the time from `date`, never from memory.
+   line of output. Take the time from the shell clock (`date`; on Windows
+   `Get-Date`), never from memory.
 4. **Paste the evidence.** Into the task's evidence cell:
    `2026-09-12 14:20 · exit 0 · "6 passed"`. Exit 0, or the task is not done.
-5. **Set it done.** Only now. Update **NOW** to point at the next task.
+5. **Set it done.** Only now. 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.
+   Update **NOW** to point at the next task; NOW keeps its four lines and their
+   names, RESUME included, until the plan is retired.
 6. **Append an entry to LOG.md** — what landed, what is next, anything learned,
    any decision made.
 7. **If the task fought back, record the learning.** An error, a wrong turn, an
@@ -364,20 +373,25 @@ status: active · opened <YYYY-MM-DD> · id: <kebab-id>
 ## NOW
 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`>
+updated: <YYYY-MM-DD HH:MM, from the shell clock>
 session: <none, or the session working this plan: name · the first 8 characters of its session id · since YYYY-MM-DD HH:MM>
 
 ## How to work this plan
 Read NOW, then Rules and Learnings; do not re-read Context. One task at a time:
-1. Set it `doing`; point NOW at it; put your session on its `session:` line.
+1. Check who holds the plan (below); set it `doing`; point NOW at it; put your session on its `session:` line.
 2. Do the work: fix causes, not symptoms; the simplest change that works end to end.
-3. Run the proof now. Paste `YYYY-MM-DD HH:MM · exit N · "last line"` into evidence. Every stamp comes from `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.
+3. Run the proof now. Paste `YYYY-MM-DD HH:MM · exit N · "last line"` into evidence. Every stamp comes from the shell clock (`date`; on Windows `Get-Date`), never typed from memory.
+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 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.
+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.
 
-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.
+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.
+- the id is live and not yours: stop, report what you found, ask; write nothing.
+- the id is not listed: stale if no other session in this checkout is live; say so, take over, write your line. Else stop and ask.
+- `none`, or no line: write your line and go on, unless this plan's PLAN.md, LOG.md or the files its tasks name are dirty, or a busy session in this checkout has its id on no plan's `session:` line; then stop and ask.
+Work only the plan assigned in this session; other reloaded plans are context. Without a `claude` command, git is the record: pull first, and ask about a fresh `doing` row.
 
 ## 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

@@ -161,7 +161,8 @@ structural check, biased toward catching a faked "done":
 - 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
-- an active plan's `RESUME` line must name a task that is still open
+- an active plan keeps its `RESUME` line, and that line must name a task that
+  is still open
 
 `--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
@@ -192,11 +193,16 @@ directory, so a second session can read the plan and start the task the first on
 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
+sessions (`claude agents --json`, matching the line's id; `ListAgents` inside
+Claude Code names sessions but shows no id) 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. A session assigned an
+unheld plan claims it and goes on, unless that plan's files are dirty or a busy
+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
 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

package/bin/planrails.mjs

@@ -15,10 +15,10 @@
  *
  *   planrails --version | --help
  */
-import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync, realpathSync } from "node:fs";
+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 } from "../tools/check-plans.mjs";
+import { checkPlans, isActive } from "../tools/check-plans.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const version = () => JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
@@ -77,6 +77,14 @@ function init(args) {
   const keep = join(plans, ".gitkeep");
   if (!existsSync(keep)) { writeFileSync(keep, ""); console.log("  + .project-management/plans/"); }
   else console.log("  = .project-management/plans/ (your plans are never touched)");
+  // A plan written before 0.5 has no session: line and an older block. init never
+  // touches a plan, so say which ones need the by-hand update from CHANGELOG 0.5.0.
+  for (const name of existsSync(plans) ? readdirSync(plans) : []) {
+    const pf = join(plans, name, "PLAN.md");
+    if (!existsSync(pf)) continue;
+    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`);
+  }
   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`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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.1
+// planrails 0.5.2
 /**
  * check-plans — the machine-checked rails of the planner.
  *
@@ -11,8 +11,8 @@
  *  - 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.)
- *  - NOW must be current: the RESUME line of an active plan may not name only
- *    finished tasks. A retired plan says `status: done` (or paused) and is exempt
+ *  - 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.
  *
  * The rule is biased toward catching a faked "done": a task counts as a
@@ -229,8 +229,11 @@ export function checkPlan({ id, text, verify = false, run = null }) {
       if (code !== 0) problems.push(`${id} ${t.id}: proof re-run failed — \`${cmd}\` exited ${code}${r.last ? ` — ${r.last}` : ""}`);
     }
   }
-  // NOW must point somewhere live: a RESUME line that names only finished tasks is stale.
+  // NOW must point somewhere live: an active plan keeps its RESUME line, and a
+  // RESUME line that names only finished tasks is stale.
   if (isActive(text)) {
+    const ls = text.split(/\r?\n/), fm = fenceMask(ls);
+    if (ls.some((l, k) => !fm[k] && /^#{1,6}\s+NOW\b/.test(l)) && !ls.some((l, k) => !fm[k] && /^\s*RESUME:/.test(l))) problems.push(`${id}: NOW has no RESUME line — an active plan keeps RESUME, NEXT, updated and session; a finished plan says status: done`);
     const named = resumeIds(text, tasks.map((t) => t.id).filter(Boolean));
     if (named.length && named.every((n) => tasks.some((t) => t.id === n && isCompletionClaim(t.status))))
       problems.push(`${id}: NOW is stale — RESUME names ${named.map((n) => n.replace(/[`*_]/g, "")).join(", ")}, which ${named.length === 1 ? "is" : "are all"} done; point it at the next open task, or set the plan's status to done`);