@sleepy_panda_srl/portulan 0.1.2 → 0.2.0

package/spec/migrations/0010-comment-rail.mjs

@@ -0,0 +1,57 @@
+// A form step — a `comments` recipe holds the comment lines that record a change's history.
+
+import path from "node:path";
+
+import { historyCount } from "../../cli/comments.mjs";
+import { COMMENTS_RECIPE, commentsRecipe, commentsRecipeEntry, commentsRecipeOf, notYetForm } from "../../cli/form.mjs";
+
+const RECIPE_FILE = "verify/comments.sh";
+
+const posix = (p) => p.split(path.sep).join("/");
+
+export const step = {
+    id: "0010-comment-rail",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "a `comments` recipe holds the comment lines that record a change's history",
+    why:
+        "A comment is paid for on every read of its file, and a change's history belongs in its commit " +
+        "message. `verify/comments.sh` counts the comment lines that record one, and holds them at the count " +
+        "the tree has today, so it starts green and the count only falls. It is declared as the `comments` recipe.",
+
+    owed(ws, ctx) {
+        const behind = notYetForm(ws, ctx);
+        if (behind) return { owed: false, because: behind };
+        if (ws.manifest?.kind !== "repository") return { owed: false, because: `a \`${ws.manifest?.kind}\` workspace has no repository of its own to count` };
+        if (!ws.repository) return { owed: false, because: "this workspace declares no tree to count" };
+        if (ws.repository.git === null) return { owed: false, because: "no git work tree answers here, so no files are listed to count" };
+        const recipe = commentsRecipeOf(ws.manifest);
+        if (recipe?.drafted) return { owed: false, because: "a `comments` recipe is declared" };
+        if (recipe) return { owed: null, because: `the \`${COMMENTS_RECIPE}\` recipe runs ${recipe.run}, not a \`${RECIPE_FILE}\`: rename it, then upgrade` };
+        return { owed: true, because: "no `comments` recipe counts the comment lines that record a change's history: one is drafted at the tree's count" };
+    },
+
+    plan(ws, ctx) {
+        if (ws.list().includes(RECIPE_FILE)) {
+            return { ok: false, reason: `\`${RECIPE_FILE}\` is in the workspace and no recipe declares it: declare it as \`${COMMENTS_RECIPE}\`, or rename it, then upgrade` };
+        }
+        const tree = ws.repository.dir;
+        let limit;
+        try {
+            limit = historyCount(tree);
+        } catch (error) {
+            return { ok: false, reason: `the tree's comments could not be counted — ${error.message}` };
+        }
+        const entry = commentsRecipeEntry(posix(path.relative(tree, ws.dir)) || ".");
+        const manifest = { ...ws.manifest, verify: { ...ws.manifest.verify, recipes: [...ws.manifest.verify.recipes, entry] } };
+        const toTree = posix(path.relative(path.join(ws.dir, "verify"), tree));
+        return {
+            ok: true,
+            edits: [
+                { file: RECIPE_FILE, next: commentsRecipe({ bundle: ctx.bundle, limit, toTree }), mode: 0o755 },
+                { file: "workspace.json", next: `${JSON.stringify(manifest, null, 2)}\n` },
+            ],
+        };
+    },
+};

package/spec/migrations/README.md

@@ -5,7 +5,7 @@
 > stated condition: a migration needed code. The runner is
 > [`../../cli/upgrade.mjs`](../../cli/upgrade.mjs).
 
-## A step, and the two kinds
+## A step, and the three kinds
 
 A migration is not one act. It is an ordered set of **steps**, each a zero-dependency ESM module
 exporting a single `step` object, and each of exactly one kind:
@@ -14,6 +14,7 @@ exporting a single `step` object, and each of exactly one kind:
 |---|---|---|
 | `version` | A Workspace Definition MAJOR migration. `spec/README.md`'s rule stands: **MINORs are additive and owe no migration**, so there is no such thing as a MINOR step and nothing here restamps one. | `from` → `to` |
 | `repair` | Something a rewriter owes a workspace it touches, independent of any version — a value that was true where it was written and is not true where the workspace now is. | the workspace's own state |
+| `form` | A move of a consumer's records or boot to the form Portulan moved its own to, in the repository beside the workspace as well as in it (2026-09-24). Today's form stays legitimate and boots as it did, so a form step is owed only where the new form is not there yet, and `doctor` reports the form without failing it. | the workspace's and its tree's own state |
 
 The second kind exists by the maintainer's ruling of 2026-08-12. Without it this directory would hold
 one step (`1.0 → 2.0`) with **no subject in this repository and none in any tree we have seen** —
@@ -22,19 +23,37 @@ machinery demonstrable only on a fixture. What actually bites an adopter is a wo
 ```js
 export const step = {
     id: "0002-bundle-fallback-path",   // stable, sortable; the id IS the chain's order
-    kind: "repair",                    // "version" | "repair"
-    from: null, to: null,              // version steps only; null on a repair
+    kind: "repair",                    // "version" | "repair" | "form"
+    from: null, to: null,              // version steps only; null on a repair or a form step
     title: "…",                        // one line, printed in the plan
     why: "…",                          // why it is owed at all, printed under -v
-    owed(ws),                          // → { owed: true | false | null, because }
+    owed(ws, ctx),                     // → { owed: true | false | null, because, hand? }
     plan(ws, ctx),                     // → { ok: true, edits } | { ok: false, reason }
 };
 ```
 
-`ws` is a read view of the workspace — `{ dir, manifest, manifestText, list(), read(rel) }`. `ctx`
-carries `{ bundle, spec, tree }`: the CLI root this run is executing from, the Workspace Definition
-version **this bundle implements**, and the `--tree` a step may need and must never invent. An `edit`
-is `{ file, next }` — a relative path and its whole next contents.
+`ws` is a read view of the workspace — `{ dir, manifest, manifestText, list(), read(rel), repository }`,
+`repository` being a read view of the tree the manifest declares, `{ dir, read(rel), names(rel), git }`,
+or `null` where it declares none; `git` runs git in the tree, and is `null` where no work tree answers
+there. `ctx` carries `{ bundle, spec, tree, today }`: the CLI root this run is executing from, the
+Workspace Definition version **this bundle implements**, the `--tree` a step may need and must never
+invent, and the date a record written today carries. An `edit` is `{ file, next }` — a relative path
+and its whole next contents — relative to the workspace, or to the tree where it says `root: "tree"`;
+a `next` of `null` deletes the file, and a `mode` is the mode of a file the edit creates, as a recipe
+must be executable. Rollback puts back what each edit replaced or deleted, in either
+root, and the report names each file as its root names it.
+
+**After each step applied, the steps after it are asked again.** A step owed only once an earlier one
+has landed, `0007` compiling the card `0006` drafts, is applied in the same run rather than the next.
+**And after a pass that applied a step, the whole chain is asked again** until a pass applies nothing
+(2026-09-24), so a later step can make an earlier one owed, as `0008` does `0007` by editing the card;
+a chain still applying after as many passes as it has steps is refused and rolled back.
+**A step owed where it does not place its edits answers `hand: true`** (2026-09-24), its `because` naming
+what a person adds: `upgrade --write` applies the rest of the chain, reports that step as owed and not
+placed once `doctor` is green, and exits 1, as `--check` does over a step owed.
+A form step reads a workspace at this bundle's MAJOR only (`notYetForm` in
+[`../../cli/form.mjs`](../../cli/form.mjs)): one a MAJOR behind is moved by a version step first, and
+the form steps are then asked again, so a workspace no version step reaches is still refused.
 
 ## Three properties, and what each one replaces
 
@@ -69,7 +88,10 @@ is a question that could not be answered.
   claiming the migration caused it.
 - **Nothing here restamps a MINOR.** A manifest declares the version its content needs, not the newest
   one — `spec/README.md`'s own rule, the one that keeps `examples/` at 2.4 as live compatibility
-  evidence and keeps `init`, `new` and `vendor` writing `2.7`.
+  evidence and keeps `new` and `vendor` writing `2.7`. `0006` writes 2.10 into a manifest older than it
+  because the step declares `slots.context`, the key 2.10 added, which is the same rule; `init`
+  writes 2.10 for the same reason, and 2.11 where a person takes the cache lifetime it offers, which
+  `sessions`, 2.11's key, declares.
 
 ## The steps that exist
 
@@ -77,11 +99,24 @@ is a question that could not be answered.
 |---|---|---|
 | [`0001-repository-declares-its-tree.mjs`](0001-repository-declares-its-tree.mjs) | `version` 1.0 → 2.0 | The one migration `spec/README.md` documents: a `repository` workspace must declare `tree`. It **will not guess** the value — `"../"` only where the parent is verifiably the repository root, otherwise it refuses and names `--tree`. |
 | [`0002-bundle-fallback-path.mjs`](0002-bundle-fallback-path.mjs) | `repair` | `init` bakes the bundle it ran from into `verify/index.sh` as an absolute path, marked `# portulan:bundle-fallback`. `vendor --switch` copies it byte for byte. The rail then exits **2 — could not run**, which is fail-closed and therefore easy never to notice. This re-derives it. |
+| [`0003-handoff-index-not-kept.mjs`](0003-handoff-index-not-kept.mjs) | `form` | A kept handoff index is deleted and its path git-ignored, so none is committed again; `portulan index --handoffs` prints it. Owed by git's answer: a copy git ignores and does not track is one machine's own, and is left alone. |
+| [`0004-changelog-fragments.mjs`](0004-changelog-fragments.mjs) | `form` | Each entry under `CHANGELOG.md`'s Unreleased becomes a fragment under `changes/`, and the heading keeps a two-line pointer. **Proved before it is offered**: the fragments, rendered as the cut renders them, must print each section back as the changelog held it, or the step refuses; a heading naming none of the six sections is refused too. The one change is an entry that does not open `- `, a `*` or `+` marker or a tab after one, whose fragment does since the cut accepts no other, and the step names each such entry by its line. |
+| [`0005-session-log-retired.mjs`](0005-session-log-retired.mjs) | `form` | Each tracked Markdown file with a `Session log` holding entries keeps its heading and two lines naming the last commit that holds them. **Refused on a file with changes not committed**, since the pointer would name a commit that lacks them. |
+| [`0006-boot-card.mjs`](0006-boot-card.mjs) | `form` | Where `slots.context` is undeclared, a boot card is drafted from the workspace's own files, as `init` drafts one, and the slot declared at 2.10. A declared slot with no `boot` unit is a workspace that boots through its slots, and is owed nothing. |
+| [`0007-guidance-compiled.mjs`](0007-guidance-compiled.mjs) | `form` | The guidance half of `portulan compile` written where it drifted: the card and the rules the host loads, through `compile`'s own planner and refusals, and never `.claude/settings.json`, which enforces gates and is a person's to compile. |
+| [`0008-card-reading.mjs`](0008-card-reading.mjs) | `form` | A card drafted before it carried the engine's rules on reading and the cache gets that section, which `compile` writes out from the installed Portulan's `core/operating/context.md`, and `0007` compiles it. A card lacking the section under any other head is owed it by hand: the run names the head the step looks for and the line to add, applies the rest of the chain and exits 1, and `doctor` names the card until the line is there. |
+| [`0009-instruction-sections-on-read.mjs`](0009-instruction-sections-on-read.mjs) | `form` | Each section a team marks with a line `<!-- portulan: on-read -->` under its heading, in `CLAUDE.md` or `.claude/CLAUDE.md`, moves byte for byte into an on-read unit of `slots.context`, and a comment is left where it was. **Proved before it is offered**: the file must reassemble from its units byte for byte and each clause land once, or the step refuses; a section importing a file, a mark inside a marked section and a mark under no heading are refused too, and a mark in an instruction file that is a link is owed by hand while the rest of the chain runs. Owed only where a team marked a section, and put back by [`../../cli/instructions.mjs`](../../cli/instructions.mjs) `--join`. |
+| [`0010-comment-rail.mjs`](0010-comment-rail.mjs) | `form` | Where a `repository` workspace's tree is one git lists and no `comments` recipe is declared, `verify/comments.sh` is drafted as `init` drafts it, holding the comment lines that record a change's history at the count the tree has, and declared. **Refused where `verify/comments.sh` is already there undeclared**, rather than written over. |
 
 **`0001` has no subject in this tree** — nothing declares 1.0 — and is exercised against a fixture,
 which is said here rather than dressed up. **`0002` has no subject in this repository either**: this
 workspace's `verify/index.sh` was written by hand, not drafted by `init`, and carries no marker. It is
-exercised against workspaces the real `init` drafts.
+exercised against workspaces the real `init` drafts. **Neither have the form steps**: this repository
+moved its own records and boot by hand on 2026-09-23 and 24, and `0003`–`0008` are exercised against a
+consumer the real `init` drafts, put back in the form it drafted before, and committed. `0009` has none
+either, since this repository keeps no `CLAUDE.md`, and is exercised against such a consumer whose
+instruction file the suite marks; `0010` against one `init` drafted where git listed no files, then
+committed.
 
 ## Adding one
 

package/spec/pack.schema.json

@@ -132,7 +132,7 @@
     },
 
     "fragment": {
-      "description": "One gate-policy fragment: an id-addressed rule this pack contributes, in the same shape .portulan/gates.json already uses, because that policy was deliberately modelled as a list of id-addressed rules with no dependence on being the only source so that a merge step would be an addition rather than a redesign (.portulan/compile/README.md). WHERE THE TIGHTEN-ONLY RULE IS ENFORCED, stated plainly because a schema implying a guarantee it does not carry is what .portulan/dod.md condition 4 refuses: tightening is relative to what the same id already holds in the layer beneath, and a manifest cannot see that layer. So the shape forecloses what shape can — `auto` is not in the tier enum below, which makes demotion-to-unattended unexpressible in a pack at all — and the remaining comparisons are the merge step's. TIGHTENING HAS TWO AXES AND THE MERGE CHECKS BOTH. The tier may only rise. The `action` may not change at all: a fragment naming an existing id must carry that rule's action unaltered, because raising the tier while replacing the matcher passes every tier comparison, is reported as a tightening, and removes the gate — measured, on a real policy, as a fragment that took `git push --force` from gated to prohibited and deleted the emitted gate in the same move. A pack that wants to gate a different action contributes a NEW id; changing what an existing rule matches belongs to the workspace, which owns its policy. Neither layer is sufficient alone, and a release that consumes fragments without the merge's refusals would be trusting what it claims to check.",
+      "description": "One gate-policy fragment: an id-addressed rule this pack contributes, in the same shape .portulan/gates.json already uses, because that policy was deliberately modelled as a list of id-addressed rules with no dependence on being the only source so that a merge step would be an addition rather than a redesign (.portulan/gate-map/compiler.md). WHERE THE TIGHTEN-ONLY RULE IS ENFORCED, stated plainly because a schema implying a guarantee it does not carry is what .portulan/dod.md condition 4 refuses: tightening is relative to what the same id already holds in the layer beneath, and a manifest cannot see that layer. So the shape forecloses what shape can — `auto` is not in the tier enum below, which makes demotion-to-unattended unexpressible in a pack at all — and the remaining comparisons are the merge step's. TIGHTENING HAS TWO AXES AND THE MERGE CHECKS BOTH. The tier may only rise. The `action` may not change at all: a fragment naming an existing id must carry that rule's action unaltered, because raising the tier while replacing the matcher passes every tier comparison, is reported as a tightening, and removes the gate — measured, on a real policy, as a fragment that took `git push --force` from gated to prohibited and deleted the emitted gate in the same move. A pack that wants to gate a different action contributes a NEW id; changing what an existing rule matches belongs to the workspace, which owns its policy. Neither layer is sufficient alone, and a release that consumes fragments without the merge's refusals would be trusting what it claims to check.",
       "type": "object",
       "additionalProperties": false,
       "required": ["id", "tier", "action", "reason"],