planrails 0.5.2 → 0.6.0

package/CHANGELOG.md

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

package/PLANNER.md

@@ -1,4 +1,4 @@
-<!-- planrails 0.5.2 -->
+<!-- planrails 0.6.0 -->
 # The Planner
 
 You are about to plan a piece of work with a person, then help execute it so the
@@ -116,8 +116,10 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   checks, run end to end, the way a user would.
 - **Use repo-relative paths** (`lib/digest/query.ts`), never absolute ones. They
   are clickable and they survive a move to another machine.
-- **Keep PLAN.md under ~2,000 words.** Trim prose before Learnings or Decisions.
-  History goes in LOG.md, not here.
+- **Keep PLAN.md under ~3,000 words.** It reloads into every session, so every
+  word is paid for again and again. Trim prose before Learnings or Decisions.
+  History goes in LOG.md, not here. Past the line, the checker prints a `note:` —
+  advice, not a failure: the run still exits 0, and you decide what to trim.
 - **Add the reload line.** In the project-root `CLAUDE.md`, under a short
   "Active plans" spot, add:
   ```
@@ -332,6 +334,12 @@ Each line here was paid for by a real failure in earlier planning systems:
   fixes.
 - **History stays out of the plan.** One plan grew a 16,000-word progress section,
   stamped two hours behind its own log. NOW is four lines; LOG.md is the history.
+- **The checker's notes advise; they never block.** A script can verify an exit
+  code, so that is a problem and fails the build. It can only suspect that a plan
+  is too long, so that is a note, and you judge. Four of four real plans had
+  outgrown the word line with nothing saying so. The check command already runs
+  before every commit and its output is already read, so a reminder there needs
+  no hook. A note needs a real failure behind it, or it is noise.
 - **Sub-agent findings are leads** because four spot-checked findings were each
   right in direction and wrong in number, and a wrong number becomes a wrong plan.
   Delegation is method, not machinery: a brief of one unit and nothing else worked.

package/README.md

@@ -164,6 +164,18 @@ structural check, biased toward catching a faked "done":
 - an active plan keeps its `RESUME` line, and that line must name a task that
   is still open
 
+The checker also **advises without blocking**. What a script can only suspect, it
+prints as a `note:` before its final line; the run still exits 0, and the agent
+that ran the check decides. There is one today: an active `PLAN.md` over ~3,000
+words, because the plan reloads into every session and nothing else says when it
+has grown. Reminders ride on the check your agent already runs before every
+commit, so they need no hook.
+
+```
+check-plans: note: weekly-digest: PLAN.md is 3,588 words, over the ~3,000 line — it reloads into every session; move history to LOG.md and trim prose before Learnings or Decisions
+check-plans: 1 plan(s) ok — every completion claim has a proof and exit 0 evidence, active plans reload, NOW is current
+```
+
 `--verify` goes further and **runs** each proof again, with a timeout, and shows
 the last line a failing proof printed. Because it executes the commands written in
 the plan, use it only on plans you trust — run the default structural check in CI
@@ -220,6 +232,8 @@ installed files under `.project-management/planrails/`. 0.4.0 makes the plan
 carry its own loop, makes the checker demand `exit 0` and check the reload line,
 and teaches the executor to brief sub-agents from the plan. 0.5.0 names the
 session working a plan and has every session check for a live holder before it
-touches the plan. See [`CHANGELOG.md`](CHANGELOG.md).
+touches the plan. 0.6.0 lets the checker advise without blocking: a `note:` for
+what a script can only suspect, starting with a plan that has outgrown its word
+line. See [`CHANGELOG.md`](CHANGELOG.md).
 
 MIT.

package/bin/planrails.mjs

@@ -18,7 +18,7 @@
 import { readFileSync, copyFileSync, mkdirSync, existsSync, writeFileSync, realpathSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkPlans, isActive } from "../tools/check-plans.mjs";
+import { checkPlans, isActive, formatNotes } from "../tools/check-plans.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const version = () => JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
@@ -103,7 +103,8 @@ function check(args) {
   const root = dirArg(args);
   if (!existsSync(root)) { console.error(`planrails check: --dir path does not exist: ${root}`); return 2; }
   const verify = args.includes("--verify");
-  const { plans, problems } = checkPlans({ root, verify });
+  const { plans, problems, notes } = checkPlans({ root, verify });
+  process.stdout.write(formatNotes(notes));
   if (!plans.length && !problems.length) { console.log("check-plans: no plans under .project-management/plans/ — nothing to check"); return 0; }
   if (problems.length) {
     console.error(`check-plans: ${problems.length} problem(s):\n${problems.map((p) => `  - ${p}`).join("\n")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Plans that survive a lost session, and \"done\" that means done. A planner prompt and a tiny checker.",
   "type": "module",
   "license": "MIT",

package/tools/check-plans.mjs

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