@sleepy_panda_srl/portulan 0.1.2 → 0.2.0

package/spec/migrations/0001-repository-declares-its-tree.mjs

@@ -1,30 +1,11 @@
 // Workspace Definition 1.0 → 2.0 — a `repository` workspace declares its `tree`.
-//
-// The only MAJOR migration this train has, and `../README.md` records why it was taken while it cost
-// nothing: `tree` began optional, and optional was a hole — deleting one manifest line degraded the
-// whole claims-lint class from *checked* to *reported*, GREEN, exit 0.
-//
-// **This step has no subject in this repository and none in any tree we have seen.** Nothing here
-// declares 1.0. It is exercised against a fixture, which `../README.md` says out loud rather than
-// leaving a passing suite to imply otherwise.
 
 import fs from "node:fs";
 import path from "node:path";
 
-/** The version this step migrates FROM, as a MAJOR. One place, so the two readers below agree. */
 const FROM_MAJOR = 1;
 
-/**
- * Is `dir` a repository root? `.git` is the evidence, and it is **a file as often as a directory**.
- *
- * A worktree's `.git` is a FILE containing `gitdir: …`, and so is a submodule's. A directory-only
- * test passes every suite written on an ordinary clone and is wrong for every worktree user — the
- * shape this project keeps paying for, so it is guarded here rather than discovered. The repository
- * this step ships from is itself checked out as a worktree today.
- *
- * Three answers, not two: `yes`, `no`, and **`unknown`** — because only `ENOENT` means absent, and an
- * `EACCES` is a question nobody answered.
- */
+/** `.git` is a file in a worktree or a submodule, and only ENOENT means it is absent. */
 function repositoryRoot(dir) {
     try {
         fs.lstatSync(path.join(dir, ".git"));
@@ -63,16 +44,10 @@ export const step = {
     plan(ws, ctx) {
         const next = { ...ws.manifest, portulan: { ...ws.manifest.portulan, spec: this.to } };
 
-        // Only a `repository` needs `tree`. A `demo` or `portfolio` describes repositories that are
-        // not beside it, and giving one a tree would be inventing a claim the workspace never made.
         if (next.kind === "repository" && typeof next.tree !== "string") {
             if (typeof ctx.tree === "string" && ctx.tree !== "") {
                 next.tree = ctx.tree;
             } else {
-                // Derived only where it is derivable, and refused otherwise. A hopeful `../` is a
-                // claim about somebody's layout made by a tool that did not look — and `tree` is
-                // precisely the slot whose wrongness turns a check class into a lie rather than an
-                // error.
                 const parent = path.resolve(ws.dir, "..");
                 const verdict = repositoryRoot(parent);
                 if (verdict === "yes") {

package/spec/migrations/0002-bundle-fallback-path.mjs

@@ -1,84 +1,36 @@
 // A repair — the bundle path a rewriter owes a workspace it touches.
-//
-// Since milestone 7 session 7, `cli/init.mjs` drafts `verify/index.sh` with a third CLI location baked
-// in: the bundle `init` ran from, as an ABSOLUTE path that git cannot carry anywhere. It is a
-// deliberate convenience for the person who ran `init`, and it is true on exactly one machine.
-//
-// **The failure is quiet, which is why it needs a tool rather than a reminder.** `vendor --switch`
-// copies these files byte for byte into another residence; a clone lands on a machine that never had
-// that bundle. The rail then exits **2 — could not run**, which is the fail-closed direction and is
-// therefore easy to never notice: nothing goes red, the index simply stops being checked.
-//
-// **The marker is the contract.** `cli/init.mjs` writes `# portulan:bundle-fallback` on both lines
-// carrying the path precisely so a rewriter can FIND them rather than having to notice a comment, and
-// `cli/init.test.mjs` asserts the marker survives edits to the recipe. This step is the rewriter that
-// note was written for.
 
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** The token `cli/init.mjs` writes. One spelling, exported so a reader can grep for the pair. */
+/** The token `cli/init.mjs` writes on each line that carries the bundle path. */
 export const MARKER = "portulan:bundle-fallback";
 
-/** The entry point a marked line points at, relative to a bundle root. */
 const ENTRY = ["cli", "index.mjs"];
 
-/**
- * Is this file one the marker could be *marking*, as opposed to one that talks about the marker?
- *
- * **Found by running this step against this repository rather than against its own fixtures.** The
- * marker is a token, and a token appears in prose: `.portulan/handoffs/2026-08-11-…md` documents the
- * marker in a sentence, and the first cut of this step read that paragraph as a marked line of a
- * shape it did not recognise and refused to migrate the workspace at all — exit 2, on the one
- * workspace this repository actually owns. Every unit test passed, because no fixture here had ever
- * written about itself.
- *
- * What a repair fixes is a **runnable fallback**, so the scope is scripts: a shell shebang, or a
- * `.sh` name. That is narrower than "any file carrying the token" and it is the honest reading of
- * what `cli/init.mjs` writes — it is deliberately NOT narrowed to `verify/index.sh`, because keying
- * on the filename would make a second and narrower carrier of the rule the marker exists to be.
- */
+/** A script, by name or shebang: prose that mentions the marker marks nothing. */
 function couldCarryTheRail(rel, text) {
     if (rel.endsWith(".sh")) return true;
     const first = text.slice(0, text.indexOf("\n") + 1 || undefined);
     return first.startsWith("#!") && /\b(?:ba|da|k|z)?sh\b/.test(first);
 }
 
-/** This bundle, derived from where this module sits rather than passed in and trusted. */
+function isMarkedScript(rel, text) {
+    return text.includes(MARKER) && couldCarryTheRail(rel, text);
+}
+
 const OWN_BUNDLE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
-/** What a marked line should name, for a given bundle root. */
 function entryFor(bundle) {
     return `${bundle}/${ENTRY.join("/")}`;
 }
 
-/**
- * The one JSON string literal on a marked line that names a CLI entry point.
- *
- * Returns `null` when the line is not the shape `init` writes — which is a **refusal**, never a
- * best-effort rewrite. A marked line this step does not recognise is somebody's edit, and rewriting
- * around it by pattern would be exactly the guesswork `../README.md` says a repair may not do.
- */
 function quotedEntry(line) {
     const matches = [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].filter((m) => m[1].endsWith(`/${ENTRY.join("/")}`));
     return matches.length === 1 ? matches[0] : null;
 }
 
-/**
- * Every marked line in `text`, paired with the entry path it names — or a reason it is unreadable.
- *
- * **`quoted` is the DECODED path, not the source text between the quotes.** The regex captures what
- * is written in the file, which is still JSON-escaped: `init` emits `JSON.stringify(...)`, so a
- * bundle at `C:\Users\x` appears as `"C:\\Users\\x/cli/index.mjs"`. Comparing that raw capture to an
- * unescaped `want` never matches, and the step reports itself **perpetually owed** — rewriting the
- * same file on every run, forever.
- *
- * Invisible on POSIX, where an ordinary path contains nothing JSON escapes, which is why every test
- * and every live run here passed over it. Copilot's promoted note, round 4 on #231.
- *
- * A literal that will not decode is treated as unreadable rather than guessed at, which is the same
- * refusal an unrecognised marked line already gets.
- */
+/** Each marked line's entry path, JSON-decoded, since the raw capture keeps the escapes `init` wrote. */
 function marked(text) {
     const lines = text.split("\n");
     const hits = [];
@@ -92,7 +44,7 @@ function marked(text) {
         } catch {
             return { ok: false, line: n + 1, text: line };
         }
-        hits.push({ n, quoted: decoded, whole: found[0] });
+        hits.push({ n, entry: decoded, whole: found[0] });
     }
     return { ok: true, lines, hits };
 }
@@ -116,17 +68,14 @@ export const step = {
             try {
                 text = ws.read(rel);
             } catch (error) {
-                // *An empty set is two questions.* A file that could not be read has not answered
-                // anything, and reporting `not owed` here is "nothing looked" recorded as "nothing
-                // wrong" — in a step whose entire subject is a failure that is already silent.
                 return { owed: null, because: `${rel} could not be read — ${error.code ?? error.message}, so whether it carries a stale bundle path is unknown` };
             }
-            if (!text.includes(MARKER) || !couldCarryTheRail(rel, text)) continue;
+            if (!isMarkedScript(rel, text)) continue;
             const found = marked(text);
             if (!found.ok) {
                 return { owed: null, because: `${rel} line ${found.line} carries the marker in a shape this step does not recognise` };
             }
-            if (found.hits.some((h) => h.quoted !== want)) any = true;
+            if (found.hits.some((h) => h.entry !== want)) any = true;
         }
         return any
             ? { owed: true, because: `a marked line names a bundle other than ${want}` }
@@ -144,10 +93,7 @@ export const step = {
             } catch (error) {
                 return { ok: false, reason: `${rel} could not be read — ${error.code ?? error.message}` };
             }
-            // The same two conditions as `owed`, and they are spelled the same way on purpose: a
-            // scope that differed between asking and doing is `0020`'s class, and it would show up
-            // as a step reporting itself owed and then planning no edit.
-            if (!text.includes(MARKER) || !couldCarryTheRail(rel, text)) continue;
+            if (!isMarkedScript(rel, text)) continue;
             const found = marked(text);
             if (!found.ok) {
                 return {
@@ -158,18 +104,11 @@ export const step = {
                         `cannot read rather than guessing: ${found.text.trim()}`,
                 };
             }
-            if (!found.hits.some((h) => h.quoted !== want)) continue;
+            if (!found.hits.some((h) => h.entry !== want)) continue;
 
-            // Rewritten by SPLICING the one recognised literal, never by a replace over the line: a
-            // line may legitimately carry other quoted text, and a blanket substitution would edit it.
             const lines = [...found.lines];
             for (const hit of found.hits) {
-                // A **function** replacer, not a string one. `String.prototype.replace` reads `$&`,
-                // `` $` ``, `$'` and `$$` in the REPLACEMENT as patterns, so a checkout under a
-                // directory whose name contains one of them spliced the old path back in with broken
-                // quoting — producing a corrupted rail that `doctor` then grades GREEN, because
-                // `doctor` never runs shell. A function replacer is inserted verbatim.
-                // Found at the pre-commit checkpoint, by building the path rather than reading the line.
+                // A function replacer: a string one reads `$&`, `` $` ``, `$'` and `$$` in the path as patterns.
                 lines[hit.n] = lines[hit.n].replace(hit.whole, () => JSON.stringify(want));
             }
             edits.push({ file: rel, next: lines.join("\n") });

package/spec/migrations/0003-handoff-index-not-kept.mjs

@@ -0,0 +1,66 @@
+// A form step — the handoff index is printed on demand, and not kept.
+
+import path from "node:path";
+
+import { handoffIndexIgnore, notYetForm, withIgnoreLines } from "../../cli/form.mjs";
+
+const posix = (p) => p.split(path.sep).join("/");
+
+function located(ws) {
+    const declared = ws.manifest?.handoffs?.index?.path;
+    if (typeof declared !== "string") return { skip: "this workspace declares no handoff index" };
+    if (!ws.repository) return { skip: "this workspace declares no tree, so no repository's git keeps a copy" };
+    const rel = path.relative(ws.repository.dir, path.resolve(ws.dir, declared));
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return { skip: `the index at \`${declared}\` lies outside the tree` };
+    const git = ws.repository.git;
+    if (git === null) return { skip: "no git work tree answers here, so no copy is committed to stop keeping" };
+    return { rel: posix(rel), workspace: posix(path.relative(ws.repository.dir, ws.dir)) || ".", git };
+}
+
+/** `--no-index` asks the ignore rules alone, so a tracked path answers too. */
+function ignoredBy(at) {
+    const out = at.git("check-ignore", "-q", "--no-index", "--", at.rel);
+    if (out.status === 0) return { ignored: true };
+    if (out.status === 1) return { ignored: false };
+    return { ignored: null, why: `git check-ignore could not answer for ${at.rel} — ${out.stderr.trim() || `exit ${out.status}`}` };
+}
+
+export const step = {
+    id: "0003-handoff-index-not-kept",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "the handoff index is printed on demand, and not kept",
+    why:
+        "A committed handoff index conflicts on every merge that adds a handoff, and carries nothing the " +
+        "series does not: `portulan index --handoffs` prints it. The copy is deleted, so commit the deletion, " +
+        "and its path is git-ignored so none is committed again.",
+
+    owed(ws, ctx) {
+        const behind = notYetForm(ws, ctx);
+        if (behind) return { owed: false, because: behind };
+        const at = located(ws);
+        if (at.skip) return { owed: false, because: at.skip };
+        const rule = ignoredBy(at);
+        if (rule.ignored === null) return { owed: null, because: rule.why };
+        const kept = ws.repository.read(at.rel) !== null;
+        if (!rule.ignored) return { owed: true, because: `\`${at.rel}\` is not git-ignored${kept ? ", and a copy is kept" : ""}` };
+        const tracked = at.git("ls-files", "--error-unmatch", "--", at.rel).status === 0;
+        if (kept && tracked) return { owed: true, because: `\`${at.rel}\` is git-ignored and still tracked, so the committed copy conflicts on every merge that adds a handoff` };
+        return { owed: false, because: `\`${at.rel}\` is git-ignored${kept ? ", and the copy on disk is this machine's own" : ", and no copy is kept"}` };
+    },
+
+    plan(ws) {
+        const at = located(ws);
+        if (at.skip) return { ok: true, edits: [] };
+        const rule = ignoredBy(at);
+        if (rule.ignored === null) return { ok: false, reason: rule.why };
+        const edits = [];
+        if (ws.repository.read(at.rel) !== null) edits.push({ root: "tree", file: at.rel, next: null });
+        if (!rule.ignored) {
+            const before = ws.repository.read(".gitignore");
+            edits.push({ root: "tree", file: ".gitignore", next: withIgnoreLines(before, handoffIndexIgnore(at.rel, at.workspace)) });
+        }
+        return { ok: true, edits };
+    },
+};

package/spec/migrations/0004-changelog-fragments.mjs

@@ -0,0 +1,53 @@
+// A form step — a changelog entry is a fragment under `changes/`.
+
+import { CHANGELOG, CHANGES_DIR, CHANGES_README, changesReadme, notYetForm, unreleasedCount, unreleasedFragments, unreleasedRewrites } from "../../cli/form.mjs";
+
+function rewritten(changelog) {
+    const lines = unreleasedRewrites(changelog);
+    if (lines.length === 0) return "";
+    if (lines.length === 1) return ` (the one at line ${lines[0]} does not open \`- \`, which its fragment does, as the release cut accepts no other opening)`;
+    return ` (those at lines ${lines.slice(0, -1).join(", ")} and ${lines.at(-1)} do not open \`- \`, which their fragments do, as the release cut accepts no other opening)`;
+}
+
+export const step = {
+    id: "0004-changelog-fragments",
+    kind: "form",
+    from: null,
+    to: null,
+    title: "a changelog entry is a fragment under `changes/`",
+    why:
+        "Two open changes that each add a bullet under Unreleased conflict on merge; a file per entry never " +
+        "does. Each entry moves to `changes/<nn>-<slug>.<section>.md`, proved to print back as the changelog " +
+        "held it but for an entry that does not open `- `, whose fragment does and which the step names by its " +
+        "line, and `portulan index --changes changes` prints them as the cut pastes them.",
+
+    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 no changelog sits beside it" };
+        const changelog = ws.repository.read(CHANGELOG);
+        const readme = ws.repository.read(CHANGES_README) !== null;
+        if (changelog === null) {
+            return { owed: false, because: readme ? `${CHANGES_README} is here, and no ${CHANGELOG} yet` : `no ${CHANGELOG} here for fragments to feed` };
+        }
+        const entries = unreleasedCount(changelog) ?? 0;
+        const owed = [];
+        if (!readme) owed.push(`no ${CHANGES_README}`);
+        if (entries) owed.push(`${entries} entr${entries === 1 ? "y" : "ies"} under ${CHANGELOG}'s Unreleased${rewritten(changelog)}`);
+        if (owed.length === 0) return { owed: false, because: `the changelog's entries are fragments in ${CHANGES_DIR}/` };
+        return { owed: true, because: owed.join(", and ") };
+    },
+
+    plan(ws) {
+        const edits = [];
+        if (ws.repository.read(CHANGES_README) === null) edits.push({ root: "tree", file: CHANGES_README, next: changesReadme() });
+        const changelog = ws.repository.read(CHANGELOG);
+        const moved = changelog === null ? null : unreleasedFragments(changelog, new Set(ws.repository.names(CHANGES_DIR)));
+        if (moved?.refused) return { ok: false, reason: moved.refused };
+        if (moved && moved.fragments.length) {
+            for (const fragment of moved.fragments) edits.push({ root: "tree", file: `${CHANGES_DIR}/${fragment.name}`, next: fragment.text });
+            edits.push({ root: "tree", file: CHANGELOG, next: moved.next });
+        }
+        return { ok: true, edits };
+    },
+};

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 })),
+            ],
+        };
+    },
+};