@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

package/spec/migrations/0005-session-log-retired.mjs

@@ -0,0 +1,69 @@
+// A form step — a change's record is its commit message, and the Session log is retired to a pointer.
+
+import { notYetForm, retireSessionLogs, sessionLogPointer, sessionLogSections } from "../../cli/form.mjs";
+
+function logsIn(ws) {
+    if (!ws.repository) return { skip: "this workspace declares no tree, so no repository holds a Session log" };
+    const git = ws.repository.git;
+    if (git === null) return { skip: "no git work tree answers here, and a retired log points at the commit that holds its entries" };
+    const listed = git("ls-files", "-z", "--", "*.md");
+    if (listed.status !== 0) return { unknown: `git ls-files could not list the tracked Markdown — ${listed.stderr.trim() || `exit ${listed.status}`}` };
+    const files = [];
+    for (const rel of listed.stdout.split("\0").filter(Boolean)) {
+        let text;
+        try {
+            text = ws.repository.read(rel);
+        } catch {
+            // A link, or a path the disk cannot give: a link's target is read in its own right where git tracks it.
+            continue;
+        }
+        if (text === null || !text.includes("Session log")) continue;
+        if (sessionLogSections(text).some((s) => s.entries)) files.push({ rel, text });
+    }
+    return { git, files };
+}
+
+export const step = {
+    id: "0005-session-log-retired",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "the Session log is retired to a pointer at the commit that holds it",
+    why:
+        "A log every change appends to conflicts on every merge and repeats what the commit messages say. " +
+        "Each `Session log` section with entries keeps its heading and two lines: the date it retired, and " +
+        "`git show <sha>:<file>`, the last commit holding its entries.",
+
+    owed(ws, ctx) {
+        const behind = notYetForm(ws, ctx);
+        if (behind) return { owed: false, because: behind };
+        const found = logsIn(ws);
+        if (found.skip) return { owed: false, because: found.skip };
+        if (found.unknown) return { owed: null, because: found.unknown };
+        if (found.files.length === 0) return { owed: false, because: "no tracked Markdown holds a Session log with entries" };
+        return { owed: true, because: `a Session log with entries in ${found.files.map((f) => f.rel).join(", ")}` };
+    },
+
+    plan(ws, ctx) {
+        const found = logsIn(ws);
+        if (found.skip) return { ok: true, edits: [] };
+        if (found.unknown) return { ok: false, reason: found.unknown };
+        const { git } = found;
+        // `git show <sha>:<path>` reads a path from the repository's top, and the tree may sit below it.
+        const prefix = git("rev-parse", "--show-prefix");
+        if (prefix.status !== 0) return { ok: false, reason: `git rev-parse could not name the tree's place in its repository — ${prefix.stderr.trim()}` };
+        const edits = [];
+        for (const { rel, text } of found.files) {
+            const status = git("status", "--porcelain", "--", rel);
+            if (status.status !== 0) return { ok: false, reason: `git status could not answer for ${rel} — ${status.stderr.trim() || `exit ${status.status}`}` };
+            if (status.stdout.trim() !== "") {
+                return { ok: false, reason: `${rel} has changes not committed, and its retired log would point at a commit that lacks them — commit or stash them, then upgrade` };
+            }
+            const sha = git("log", "-1", "--format=%h", "--", rel);
+            if (sha.status !== 0 || sha.stdout.trim() === "") return { ok: false, reason: `git names no commit holding ${rel}, so its retired log would point at nothing` };
+            const pointer = sessionLogPointer({ date: ctx.today, sha: sha.stdout.trim(), file: `${prefix.stdout.trim()}${rel}` });
+            edits.push({ root: "tree", file: rel, next: retireSessionLogs(text, pointer) });
+        }
+        return { ok: true, edits };
+    },
+};

package/spec/migrations/0006-boot-card.mjs

@@ -0,0 +1,77 @@
+// A form step — the boot is a card, drafted from the workspace's own slots.
+
+import path from "node:path";
+
+import { claudeRulesUnignore, draftCard, notYetForm, withIgnoreLines } from "../../cli/form.mjs";
+
+/** The Workspace Definition version `slots.context` arrived in, which a manifest declaring it needs. */
+const CONTEXT_SPEC = "2.10";
+
+const posix = (p) => p.split(path.sep).join("/");
+
+function atLeastContextSpec(declared) {
+    const [major, minor] = String(declared).split(".").map(Number);
+    const [needMajor, needMinor] = CONTEXT_SPEC.split(".").map(Number);
+    return major > needMajor || (major === needMajor && minor >= needMinor) ? declared : CONTEXT_SPEC;
+}
+
+export const step = {
+    id: "0006-boot-card",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "the boot is a card, drafted from the workspace's own slots",
+    why:
+        "A boot through the slots reads the skill's steps and every slot file in full; a card carries the " +
+        "same, compiled into the rules the host loads, and a session reads no slot to boot. `context/boot.md` " +
+        "is drafted, `slots.context` declared at 2.10, and `0007` compiles it. Delete the card to boot as before.",
+
+    owed(ws, ctx) {
+        const behind = notYetForm(ws, ctx);
+        if (behind) return { owed: false, because: behind };
+        const kind = ws.manifest?.kind;
+        if (kind !== "repository") return { owed: false, because: `a \`${kind}\` workspace has no repository of its own whose host would load a card` };
+        if (!ws.repository) return { owed: false, because: "this workspace declares no tree for a card to load in" };
+        if (typeof ws.manifest?.slots?.context === "string") {
+            return { owed: false, because: "`slots.context` is declared: a `boot` unit in it is the card, and a slot without one boots through the slots" };
+        }
+        return { owed: true, because: "`slots.context` is undeclared, so a session boots by reading every slot; the card is drafted from them, and `0007` then compiles it" };
+    },
+
+    plan(ws) {
+        if (ws.list().some((rel) => rel === "context" || rel.startsWith("context/"))) {
+            return { ok: false, reason: "`context/` is already in the workspace and is no declared slot — rename it, or declare `slots.context` yourself, then upgrade" };
+        }
+        const manifest = {
+            ...ws.manifest,
+            portulan: { ...ws.manifest.portulan, spec: atLeastContextSpec(ws.manifest.portulan?.spec) },
+            slots: { ...ws.manifest.slots, context: "context/" },
+        };
+        const tree = ws.repository.dir;
+        const workspace = posix(path.relative(tree, ws.dir)) || ".";
+        const inTree = (rel) => {
+            const at = path.relative(tree, path.resolve(ws.dir, rel));
+            return at !== "" && !at.startsWith("..") && !path.isAbsolute(at);
+        };
+        const read = (rel) => {
+            try {
+                return ws.read(rel);
+            } catch {
+                return null;
+            }
+        };
+        const repos = typeof manifest.slots.repos === "string" ? manifest.slots.repos.replace(/\/?$/, "/") : null;
+        const repoCards = repos === null
+            ? []
+            : ws.list().filter((rel) => rel.startsWith(repos) && rel.endsWith(".md") && !rel.slice(repos.length).includes("/") && path.posix.basename(rel) !== "README.md").map((rel) => path.posix.basename(rel, ".md"));
+
+        const edits = [
+            { file: "workspace.json", next: `${JSON.stringify(manifest, null, 2)}\n` },
+            { file: "context/boot.md", next: draftCard(manifest, read, { workspace, inTree, repoCards }) },
+        ];
+        // A `.gitignore` hiding `.claude/` would keep the compiled card out of review and every fresh checkout.
+        const { lines } = claudeRulesUnignore(tree, ws.repository.git);
+        if (lines.length) edits.push({ root: "tree", file: ".gitignore", next: withIgnoreLines(ws.repository.read(".gitignore"), lines) });
+        return { ok: true, edits };
+    },
+};

package/spec/migrations/0007-guidance-compiled.mjs

@@ -0,0 +1,31 @@
+// A form step — the guidance the workspace declares is compiled into what the host loads.
+
+import { guidanceEdits } from "../../cli/compile.mjs";
+import { notYetForm } from "../../cli/form.mjs";
+
+export const step = {
+    id: "0007-guidance-compiled",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "the declared guidance is compiled into the rules the host loads",
+    why:
+        "A unit in `slots.context` reaches a session only as the rule `compile` writes for it. The rules are " +
+        "written through compile's own planner, as `portulan compile` writes them, and never " +
+        "`.claude/settings.json`.",
+
+    owed(ws, ctx) {
+        const behind = notYetForm(ws, ctx);
+        if (behind) return { owed: false, because: behind };
+        if (!ws.repository) return { owed: false, because: "this workspace declares no tree for compiled guidance to load in" };
+        if (typeof ws.manifest?.slots?.context !== "string") return { owed: false, because: "`slots.context` is undeclared, so there is no guidance to compile" };
+        const planned = guidanceEdits(ws.dir);
+        const left = planned.left.length ? `; ${planned.left.join(", ")} ${planned.left.length === 1 ? "is" : "are"} not compile's, and left as \`compile\` leaves ${planned.left.length === 1 ? "it" : "them"}` : "";
+        if (planned.edits.length === 0) return { owed: false, because: `the compiled guidance is what \`compile\` would write${left}` };
+        return { owed: true, because: `${planned.edits.map((e) => e.file).join(", ")} ${planned.edits.length === 1 ? "differs" : "differ"} from what \`compile\` would write${left}` };
+    },
+
+    plan(ws) {
+        return { ok: true, edits: guidanceEdits(ws.dir).edits.map((edit) => ({ root: "tree", file: edit.file, next: edit.next })) };
+    },
+};

package/spec/migrations/0008-card-reading.mjs

@@ -0,0 +1,55 @@
+// A form step — the card carries the engine's rules on reading and the cache.
+
+import path from "node:path";
+
+import { BOOT_CARD_UNIT } from "../../cli/compile.mjs";
+import { carriesReading, HEAD_BEFORE_READING_SHOWN, notYetForm, READING_LINE, withReading } from "../../cli/form.mjs";
+
+function cardOf(ws) {
+    const context = ws.manifest?.slots?.context;
+    if (typeof context !== "string") return { answer: { owed: false, because: "`slots.context` is undeclared, so there is no card; `0006` drafts one with the section" } };
+    const rel = path.posix.join(context, `${BOOT_CARD_UNIT}.md`);
+    try {
+        return { rel, card: ws.read(rel) };
+    } catch (error) {
+        if (error?.code === "ENOENT") return { answer: { owed: false, because: "`slots.context` holds no `boot` unit, so there is no card to carry the section" } };
+        return { answer: { owed: null, because: `${rel} could not be read: ${error.message}` } };
+    }
+}
+
+const unplaced = (rel) =>
+    `${rel} does not carry the engine's rules on reading and the cache, and its head is not one \`init\` drafted ` +
+    `before 2026-09-24, ${HEAD_BEFORE_READING_SHOWN}, so this step does not guess where they go: add a section ` +
+    `holding the line \`${READING_LINE}\` to the card, then upgrade again`;
+
+export const step = {
+    id: "0008-card-reading",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "the card carries the engine's rules on reading and the cache",
+    why:
+        "The card `init` drafts opens with the rules of Portulan's `core/operating/context.md` on what a " +
+        "session's reads, output and pauses cost on every request after them, written out by `compile`. A card " +
+        "drafted before them gets the section and `0007` compiles it; one under any other head is reported with " +
+        "the line to add by hand, and the rest of the chain runs.",
+
+    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 whose host would load a card` };
+        const { rel, card, answer } = cardOf(ws);
+        if (answer) return answer;
+        if (carriesReading(card)) return { owed: false, because: `${rel} carries the engine's rules on reading and the cache` };
+        if (withReading(card) === null) return { owed: true, hand: true, because: unplaced(rel) };
+        return { owed: true, because: `${rel} was drafted before the card carried the engine's rules on reading and the cache: they go under its head, and \`0007\` then compiles it` };
+    },
+
+    plan(ws) {
+        const { rel, card, answer } = cardOf(ws);
+        if (answer) return { ok: false, reason: answer.because };
+        const next = withReading(card);
+        if (next === null) return { ok: false, reason: unplaced(rel) };
+        return { ok: true, edits: [{ file: rel, next }] };
+    },
+};

package/spec/migrations/0009-instruction-sections-on-read.mjs

@@ -0,0 +1,60 @@
+// A form step — each section a team marks in its own instruction file moves to an on-read unit.
+
+import { ESTIMATED_BYTES_PER_TOKEN, alwaysTier, declaredContext, tokensOf } from "../../cli/context.mjs";
+import { notYetForm } from "../../cli/form.mjs";
+import { INSTRUCTION_FILES, contextDir, grouped, instructionReader, linkRefusal, marksOf, planSplit, splitLines } from "../../cli/instructions.mjs";
+
+function splitOf(ws) {
+    const tree = ws.repository.dir;
+    const context = contextDir(tree, ws.dir, ws.manifest);
+    const taken = context === null ? [] : ws.repository.names(context).filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -3));
+    return planSplit({ tree, context, taken, read: instructionReader(tree, ws.repository.read) });
+}
+
+export const step = {
+    id: "0009-instruction-sections-on-read",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "each section a team marks in its instruction file moves to an on-read unit",
+    why:
+        "`CLAUDE.md` and `.claude/CLAUDE.md` load whole into every context. A section marked " +
+        "`<!-- portulan: on-read -->` moves, byte for byte, to an on-read unit of `slots.context`, proved to " +
+        "reassemble, and every context loads one index line for it. " +
+        "`node <plugin root>/cli/instructions.mjs --workspace <dir> --join --write` puts it back.",
+
+    owed(ws, ctx) {
+        const behind = notYetForm(ws, ctx);
+        if (behind) return { owed: false, because: behind };
+        if (!ws.repository) return { owed: false, because: "this workspace declares no tree, so there is no instruction file of its own" };
+        const read = instructionReader(ws.repository.dir, ws.repository.read);
+        const marked = INSTRUCTION_FILES.filter((rel) => marksOf(read(rel) ?? "").marks.length > 0);
+        if (marked.length === 0) return { owed: false, because: "no section of CLAUDE.md or .claude/CLAUDE.md is marked `<!-- portulan: on-read -->`" };
+        if (typeof ws.manifest?.slots?.context !== "string") {
+            return { owed: false, because: `${marked.join(" and ")} marks a section, and \`slots.context\` is undeclared: \`0006\` declares it, and this step is asked again then` };
+        }
+        const linked = marked.map((rel) => linkRefusal(ws.repository.dir, rel)).filter((refusal) => refusal !== null);
+        if (linked.length) return { owed: true, hand: true, because: `a marked section cannot move, so none is moved — ${linked.join("; ")}, or take the marks out, then upgrade again` };
+        const split = splitOf(ws);
+        if (split.refusals.length) return { owed: true, because: `a marked section cannot move — ${split.refusals.join("; ")}` };
+        const ratio = declaredContext(ws.manifest).ratio ?? ESTIMATED_BYTES_PER_TOKEN;
+        const before = alwaysTier(ws.repository.dir).entries.reduce((n, e) => n + e.bytes, 0);
+        const after = before - split.files.reduce((n, f) => n + f.removed, 0) + split.index;
+        return {
+            owed: true,
+            because: `${splitLines(split).join("; ")}; the always tier goes from ~${grouped(tokensOf(before, ratio))} to ~${grouped(tokensOf(after, ratio))} tokens`,
+        };
+    },
+
+    plan(ws) {
+        const split = splitOf(ws);
+        if (split.refusals.length) return { ok: false, reason: `a marked section cannot move, so none is moved — ${split.refusals.join("; ")}` };
+        return {
+            ok: true,
+            edits: [
+                ...split.files.map((f) => ({ root: "tree", file: f.rel, next: f.after })),
+                ...split.units.map((u) => ({ root: "tree", file: u.source, next: u.text })),
+            ],
+        };
+    },
+};

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"],