planrails 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.3.0 — 2026-09-12
+
+Two changes, both asked for by a user planning a long, multi-session feature:
+carry learnings forward so a mistake is not re-paid in the next chat, and tidy the
+installed files into one folder.
+
+- **Learnings are now a first-class, reloaded part of a plan.** `PLAN.md` gains a
+  `## Learnings` section: each line is the trap and the rule it taught. It reloads
+  with the plan at the start of every session — and after every compaction —
+  through the same reload line, so the next session reads the lesson before it
+  repeats the struggle. A learning is distinct from a `Rule` (a constraint known
+  up front) and a `Decision` (a choice and why). `PLANNER.md` makes capturing a
+  learning a step of the execute loop, written the moment a task fights back; tells
+  a resuming session to read the Learnings first; and graduates a learning that
+  outlives the plan to the always-loaded file. Until now the only place for a
+  lesson was a `LOG.md` line, and the log is neither reloaded nor re-read — which
+  is exactly why the same struggle returned in each new session.
+- **The two installed files move into `.project-management/planrails/`.** `init`
+  now writes `.project-management/planrails/PLANNER.md` and
+  `.project-management/planrails/check-plans.mjs`, leaving `.project-management/`
+  holding just two folders: `planrails/` (the tool) and `plans/` (your plans). The
+  reload line is unchanged — `@.project-management/plans/<id>/PLAN.md`. If you ran
+  an older `init`, point your check command at the new path
+  (`node .project-management/planrails/check-plans.mjs`) and remove the two loose
+  files left at the `.project-management/` root.
+- The checker's behaviour is unchanged: learnings are prose, enforced by the
+  method, not the gate, and a plan with no `Learnings` section still validates. A
+  test pins that a `Learnings` section does not confuse the parser. 34 tests.
+
+## 0.2.1 — 2026-09-12
+
+A careful post-release review, including an end-to-end test of the published
+package, found one robustness gap in the checker and fixed it.
+
+- The checker finds a task table by its columns (`id`, `status`, `proof`,
+  `evidence`), not by a `## Tasks` heading. So tasks under `## Phase 2 Tasks`,
+  `## Backlog`, any heading, or none at all are all gated — a phased plan is no
+  longer rejected with a confusing "no readable Tasks table". A table under a
+  literal `## Tasks` heading that is missing a column still names which one.
+- Verified against the live 0.2.0 package: `npx planrails init` copies only into
+  `.project-management/`, leaves `package.json` and a pnpm lockfile untouched,
+  writes no `node_modules` and no `CLAUDE.md`, and the checker catches every
+  faked-"done" bypass. 33 tests.
+
 ## 0.2.0 — 2026-09-12
 
 Rebuilt as a planner prompt and one checker, with a two-command CLI that only

package/PLANNER.md

@@ -36,6 +36,13 @@ Three rules make the plan trustworthy. They are the whole point of this system:
    code and last line are pasted into the plan. An empty evidence cell is not
    done, whatever the status column says.
 
+The plan is also the project's memory. Besides the tasks, PLAN.md carries the
+**Rules** you must not break, the **Decisions** you made and why, and the
+**Learnings** — a mistake or dead end, written as the rule that avoids it next
+time. The reload line brings all of it back at the start of every session, so a
+lesson learned in one chat is read by the next one *before* it repeats the
+struggle. That is how you stop paying for the same mistake twice.
+
 ---
 
 ## §1 Get ready
@@ -110,16 +117,21 @@ Pick a short kebab-case `<id>` (`weekly-digest`). Then:
   back on its own. (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.)
 - **Wire the checker, if the project runs Node and has a check command.**
-  `npx planrails init` already put it at `.project-management/check-plans.mjs`; if
-  you did not run init, copy this repo's `tools/check-plans.mjs` there. Add
-  `node .project-management/check-plans.mjs` to the check command. Now the build
-  fails if a task is marked done with no evidence. If the project is not Node,
+  `npx planrails init` already put it at `.project-management/planrails/check-plans.mjs`;
+  if you did not run init, copy this repo's `tools/check-plans.mjs` 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 the project is not Node,
   skip this; the plan still works, and you enforce the gate yourself.
 
 ---
 
 ## §4 Execute — one task at a time
 
+**At the start of every session, read the plan back first.** The reload line has
+already loaded PLAN.md. Read **NOW**, then the **Rules** and the **Learnings**,
+before you touch anything. The Learnings are mistakes a past session already paid
+for — read them and you skip the struggle instead of repeating it.
+
 The loop for each task:
 
 1. **Set it doing.** Change the status cell to `doing`. Update **NOW**.
@@ -131,6 +143,10 @@ The loop for each task:
 5. **Set it done.** Only now. Update **NOW** to point at the next task.
 6. **Append one line 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
+   hour lost before you found the cause — add it to PLAN.md under **Learnings** as
+   "trap → rule", with the real case. LOG.md holds what happened; Learnings holds
+   the rule, because Learnings reloads every session and the log does not.
 
 **Update NOW before you end any turn.** NOW is the first thing a fresh session
 reads. If it is stale, the next session repeats your work or starts in the wrong
@@ -158,6 +174,9 @@ the task `blocked` with the reason, and stop. Do not hand-fix state to look done
 3. **Retire the plan.** Move its reload line out of "Active plans" into a
    "Finished" list (or delete the line). The plan files stay on disk; they are the
    record.
+4. **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. One that was only about this work retires with it.
 
 ---
 
@@ -172,6 +191,11 @@ Each line here was paid for by a real failure in earlier planning systems:
   A named command that must be run and pasted can.
 - **Evidence at close** is the one machine-checkable rail worth keeping. The
   checker enforces exactly this and nothing else.
+- **Learnings live in the plan, not only the log.** The log is history a fresh
+  session does not re-read; the plan is reloaded every session. A mistake written
+  as a rule, where the next session will see it, is the only kind that stops being
+  repeated. The same struggle coming back in a new chat is the exact failure this
+  fixes.
 - **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.
 - **Repo-relative paths** because absolute paths break on the next machine, and a
@@ -181,8 +205,10 @@ Each line here was paid for by a real failure in earlier planning systems:
   package, and that is what broke on the projects that were not npm — Python,
   pnpm, bun, monorepos, Windows. A prompt and a copied script work everywhere.
 
-Keep it this simple. If you are tempted to add a config file, a second script, or
-a fourth rule, you are rebuilding the thing this replaced.
+Keep it this simple. The three rails — reload, proof, evidence — are the whole
+machine-checked core. If you are tempted to add a config file, a second script, or
+a fourth rail, you are rebuilding the thing this replaced. (Rules, Decisions and
+Learnings are plain sections of the plan, not new machinery.)
 
 ---
 
@@ -232,6 +258,14 @@ updated: <YYYY-MM-DD HH:MM>
 |------|----------|-----|
 | <YYYY-MM-DD> | <what was chosen> | <the reason and what it rules out> |
 
+## Learnings
+<!-- Mistakes already paid for, so no later session repeats them. Each line: the
+     trap, then the rule it taught, with the real case. Not a Rule (a constraint
+     known up front) and not a Decision (a choice between options) — a learning is
+     what a failure taught you. Add one the moment a task fights back. This section
+     reloads with the plan every session; that is what makes the lesson stick. -->
+- <the trap you hit> → <the rule that avoids it> (<the real case, one line>)
+
 ## Context (read during planning — do not re-read)
 - <path> — <one line of what it holds>
 ````
@@ -251,5 +285,6 @@ Append-only. One entry per landed piece of work, newest at the bottom.
 - files: <repo-relative paths touched>
 - proof: <the command and its result — e.g. `npx vitest run tests/digest.test.ts` → exit 0, "6 passed">
 - next: <what comes next; where you stopped if you paused>
-- learned / decided: <anything a second reader needs; omit if nothing>
+- learned / decided: <anything a second reader needs; omit if nothing. A durable
+  trap also goes to PLAN.md § Learnings, which reloads every session>
 ````

package/README.md

@@ -28,15 +28,16 @@ From the root of your project:
 npx planrails init
 ```
 
-That copies two files into `.project-management/` 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; it skips files that already
-exist. What lands:
+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; it skips files that
+already exist. What lands:
 
 ```
 .project-management/
-  PLANNER.md          the prompt your agent follows to plan and execute
-  check-plans.mjs     the checker (the one machine-enforced rail)
+  planrails/
+    PLANNER.md        the prompt your agent follows to plan and execute
+    check-plans.mjs   the checker (the one machine-enforced rail)
   plans/              your plans will live here, one folder each
 ```
 
@@ -44,8 +45,8 @@ Then, two steps:
 
 1. **Tell your agent to plan with you.** In any coding agent:
 
-   > Follow `.project-management/PLANNER.md` and tell me when you are ready to
-   > plan the next feature with me.
+   > Follow `.project-management/planrails/PLANNER.md` and tell me when you are
+   > ready to plan the next feature with me.
 
    It reads your repo, reports what it found in eight lines, and waits. Then you
    plan together, and it writes the plan and wires the reload line.
@@ -54,7 +55,7 @@ Then, two steps:
    every commit (your `check` / `lint` / CI script):
 
    ```bash
-   node .project-management/check-plans.mjs
+   node .project-management/planrails/check-plans.mjs
    ```
 
    Now the build fails if any task is marked done without pasted evidence.
@@ -76,9 +77,9 @@ The command is the same; the difference is what your agent sees.
 ### Without npm, or a non-Node project
 
 No npm? Copy the two files by hand from this repo:
-[`PLANNER.md`](PLANNER.md) → `.project-management/PLANNER.md`, and
+[`PLANNER.md`](PLANNER.md) → `.project-management/planrails/PLANNER.md`, and
 [`tools/check-plans.mjs`](tools/check-plans.mjs) →
-`.project-management/check-plans.mjs`. Make a `.project-management/plans/`
+`.project-management/planrails/check-plans.mjs`. Make a `.project-management/plans/`
 folder. Done.
 
 The checker needs Node to run. If your project has no Node at all, skip it — the
@@ -93,7 +94,11 @@ beside it in the same folder. Then `/plan` starts the same flow in any project.
 ## How a plan works
 
 Each plan is two files: `PLAN.md` (the map and tracker) and `LOG.md` (append-only
-history). The top of `PLAN.md` is what a fresh session reads first:
+history). `PLAN.md` also carries the plan's memory — the rules to keep, the
+decisions made, and the **learnings** (a mistake, written as the rule that avoids
+it). Because the reload line brings `PLAN.md` back at the 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:
 
 ```
 ## NOW
@@ -115,9 +120,9 @@ is in [`examples/weekly-digest/`](examples/weekly-digest).
 ## The checker
 
 ```bash
-node .project-management/check-plans.mjs            # done tasks must name a proof and carry evidence
-node .project-management/check-plans.mjs --verify   # also re-run each done task's proof, expect exit 0
-npx planrails check                                 # the same, using the latest published checker
+node .project-management/planrails/check-plans.mjs          # done tasks must name a proof and carry evidence
+node .project-management/planrails/check-plans.mjs --verify # also re-run each done task's proof, expect exit 0
+npx planrails check                                         # the same, using the latest published checker
 ```
 
 No dependencies. Node 20+, any OS (Windows included). The default is a fast
@@ -147,6 +152,8 @@ review found ten data-loss and silent-failure paths in that surface, and the
 "works with any project" promise broke on pnpm, bun, non-Node projects,
 monorepos and Windows. 0.2.0 keeps the idea and drops the weight: the same three
 rails, as a prompt plus one checker, with a two-command CLI that only copies
-files. See [`CHANGELOG.md`](CHANGELOG.md).
+files. 0.3.0 makes learnings a reloaded part of every plan and groups the two
+installed files under `.project-management/planrails/`. See
+[`CHANGELOG.md`](CHANGELOG.md).
 
 MIT.

package/bin/planrails.mjs

@@ -3,14 +3,14 @@
  * planrails — a planner prompt and one checker. Two commands, both safe:
  *
  *   npx planrails init [--dir DIR] [--force]
- *       Copies PLANNER.md and the checker into <project>/.project-management/ and
- *       makes the plans/ folder. It writes nothing else — no package.json, no npm
+ *       Copies PLANNER.md and the checker into <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. Idempotent: it skips files
  *       that already exist unless you pass --force.
  *
  *   npx planrails check [--dir DIR] [--verify]
  *       Runs the checker over the project's plans. --verify re-runs each done
- *       task's proof. Same as running the copied .project-management/check-plans.mjs.
+ *       task's proof. Same as running the copied .project-management/planrails/check-plans.mjs.
  *
  *   planrails --version | --help
  */
@@ -28,8 +28,8 @@ const HELP = `planrails ${version()} — a planner prompt and one checker.
   npx planrails check [--dir DIR] [--verify] check the project's plans
   planrails --version | --help
 
-After init, tell your agent:  Follow .project-management/PLANNER.md and plan <the feature> with me.
-Add to the command you run before every commit:  node .project-management/check-plans.mjs
+After init, tell your agent:  Follow .project-management/planrails/PLANNER.md and plan <the feature> with me.
+Add to the command you run before every commit:  node .project-management/planrails/check-plans.mjs
 Full guide: https://github.com/vivmagarwal/planrails#readme`;
 
 function flag(args, name) {
@@ -43,7 +43,9 @@ function init(args) {
   const target = resolve(flag(args, "--dir") || ".");
   const force = args.includes("--force");
   const pm = join(target, ".project-management");
+  const sys = join(pm, "planrails");
   const plans = join(pm, "plans");
+  mkdirSync(sys, { recursive: true });
   mkdirSync(plans, { recursive: true });
 
   const copy = (from, to, label) => {
@@ -52,18 +54,18 @@ function init(args) {
     console.log(`  + ${label}`);
   };
   console.log(`planrails ${version()} → ${target}`);
-  copy(join(ROOT, "PLANNER.md"), join(pm, "PLANNER.md"), ".project-management/PLANNER.md");
-  copy(join(ROOT, "tools", "check-plans.mjs"), join(pm, "check-plans.mjs"), ".project-management/check-plans.mjs");
+  copy(join(ROOT, "PLANNER.md"), join(sys, "PLANNER.md"), ".project-management/planrails/PLANNER.md");
+  copy(join(ROOT, "tools", "check-plans.mjs"), join(sys, "check-plans.mjs"), ".project-management/planrails/check-plans.mjs");
   const keep = join(plans, ".gitkeep");
   if (!existsSync(keep)) { writeFileSync(keep, ""); console.log("  + .project-management/plans/"); }
   else console.log("  · .project-management/plans/ already present");
 
   console.log(`
 Next:
-  1. Tell your agent:  Follow .project-management/PLANNER.md and plan <the feature> with me.
+  1. Tell your agent:  Follow .project-management/planrails/PLANNER.md and plan <the feature> with me.
      (Or, in Claude Code, use /plan if you installed the skill.)
   2. Add to the command you run before every commit:
-       node .project-management/check-plans.mjs
+       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`);
   return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planrails",
-  "version": "0.2.0",
+  "version": "0.3.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

@@ -11,8 +11,8 @@
  * (todo, doing, blocked, …). So no spelling of "done" — done, completed, ✅,
  * shipped, a typo — can slip through unchecked.
  *
- * `npx planrails init` copies this file into a project's .project-management/;
- * add `node .project-management/check-plans.mjs` to the command you run before
+ * `npx planrails init` copies this file into a project's .project-management/planrails/;
+ * add `node .project-management/planrails/check-plans.mjs` to the command you run before
  * every commit. No dependencies. Runs on Node 20+ on any OS.
  *
  *   node check-plans.mjs            # structural: completion claims need proof + evidence
@@ -80,41 +80,55 @@ const isRow = (l) => l.trim().startsWith("|");
 const isHeading = (l) => /^#{1,6}\s/.test(l.trim());
 const isSeparator = (l) => /^\|[\s:|-]+\|?\s*$/.test(l.trim());
 
+const REQUIRED = ["id", "status", "proof", "evidence"];
+/** The column indices of a row, and which required columns it is missing. */
+function headerCols(rowText) {
+  const h = cells(rowText).map((c) => c.toLowerCase());
+  const ci = { id: h.indexOf("id"), task: h.indexOf("task"), status: h.indexOf("status"), proof: h.indexOf("proof"), evidence: h.indexOf("evidence") };
+  return { ci, missing: REQUIRED.filter((k) => ci[k] === -1) };
+}
+
 /**
- * Parse the task rows of a plan. Scans EVERY "## Tasks" section; within a
- * section it collects all table rows to the next heading, so a blank line in the
- * middle does not end the table and a second table is not lost. Columns are
- * matched by name, in any order. Returns { found, tasks, missingCols }.
+ * Parse the task rows of a plan. A "task table" is any markdown table whose
+ * header carries the four columns id, status, proof, evidence — found by its
+ * columns, not by a heading, so tasks under "## Tasks", "## Phase 2 Tasks",
+ * "## Backlog", or a second table are all read; blank lines inside a table are
+ * tolerated. Returns { found, tasks, missingCols }.
  */
 export function parseTasks(text) {
   const lines = text.split(/\r?\n/);
-  let found = false;
   const tasks = [];
-  const missingCols = new Set();
-  for (let i = 0; i < lines.length; i++) {
-    if (!/^#{1,6}\s+tasks\b/i.test(lines[i].trim())) continue;
-    const rows = [];
+  let found = false;
+  let i = 0;
+  while (i < lines.length) {
+    if (!isRow(lines[i]) || isSeparator(lines[i]) || headerCols(lines[i]).missing.length) { i++; continue; }
+    found = true; // lines[i] is a task-table header (a | row naming all four columns)
+    const { ci } = headerCols(lines[i]);
     let j = i + 1;
     for (; j < lines.length; j++) {
-      if (isHeading(lines[j])) break;
-      if (isRow(lines[j])) rows.push({ text: lines[j], line: j + 1 });
-    }
-    i = j - 1;
-    if (!rows.length) continue;
-    const header = cells(rows[0].text).map((h) => h.toLowerCase());
-    const ci = { id: header.indexOf("id"), task: header.indexOf("task"), status: header.indexOf("status"), proof: header.indexOf("proof"), evidence: header.indexOf("evidence") };
-    const missing = ["id", "status", "proof", "evidence"].filter((k) => ci[k] === -1);
-    if (missing.length) { missing.forEach((m) => missingCols.add(m)); continue; }
-    found = true;
-    for (const row of rows.slice(1)) {
-      if (isSeparator(row.text)) continue;
-      const c = cells(row.text);
+      const l = lines[j];
+      if (isHeading(l)) break; // a heading ends the table
+      if (l.trim() === "") continue; // a blank line inside the table does not
+      if (!isRow(l)) break; // prose ends the table
+      if (isSeparator(l)) continue;
+      if (headerCols(l).missing.length === 0) break; // the next table's header — reprocess it
+      const c = cells(l);
       const at = (idx) => (idx >= 0 && idx < c.length ? c[idx] : "");
-      if (norm(at(ci.status)) === "status" && norm(at(ci.id)) === "id") continue; // a repeated header row
-      tasks.push({ id: at(ci.id), task: at(ci.task), status: at(ci.status), proof: at(ci.proof), evidence: at(ci.evidence), line: row.line });
+      tasks.push({ id: at(ci.id), task: at(ci.task), status: at(ci.status), proof: at(ci.proof), evidence: at(ci.evidence), line: j + 1 });
+    }
+    i = j;
+  }
+  // A helpful message for the common slip: a "## Tasks" table missing one column.
+  let missingCols = [];
+  if (!found) {
+    for (let k = 0; k < lines.length && !missingCols.length; k++) {
+      if (!/^#{1,6}\s+tasks\b/i.test(lines[k].trim())) continue;
+      for (let m = k + 1; m < lines.length && !isHeading(lines[m]); m++) {
+        if (isRow(lines[m]) && !isSeparator(lines[m])) { const miss = headerCols(lines[m]).missing; if (miss.length && miss.length < REQUIRED.length) missingCols = miss; break; }
+      }
     }
   }
-  return { found, tasks, missingCols: [...missingCols] };
+  return { found, tasks, missingCols };
 }
 
 /** The command inside a proof cell (backticks stripped), or null for `owner`/prose/empty. */
@@ -129,7 +143,7 @@ export function checkPlan({ id, text, verify = false, run = null }) {
   const { found, tasks, missingCols } = parseTasks(text);
   if (!found) {
     if (missingCols.length) problems.push(`${id}: the Tasks table is missing the ${missingCols.map((c) => `"${c}"`).join(", ")} column(s)`);
-    else problems.push(`${id}: no readable Tasks table (needs a | id | task | status | proof | evidence | table under a "## Tasks" heading)`);
+    else problems.push(`${id}: no readable Tasks table (needs a | id | task | status | proof | evidence | table)`);
     return problems;
   }
   for (const t of tasks) {