@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

package/packs/tools/local-llm/skills/delegate-local/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: delegate-local
+description: Offload a verify-gated one-file edit, a file digest or a draft to a local model. Use only where the workspace composes tools/local-llm and a server answers on loopback.
+---
+
+# Skill — Delegate Local
+
+> Every turn in a frontier session re-reads its whole context (`m_r × (F·T + g·T²/2)`, proposal
+> [`0038`](../../../../../.portulan/proposals/0038-what-a-change-spends-is-measured.md)). This skill moves a
+> bounded, high-turn or read-heavy sub-task off that context and onto a local model on loopback, through
+> [`runner/local-llm.mjs`](../../runner/local-llm.mjs) and under a verify command.
+
+## Before you start
+
+`<runner>` below is `runner/local-llm.mjs` in this pack's directory, two levels above this file:
+`<plugin root>/packs/tools/local-llm/runner/local-llm.mjs` where the plugin is the repository root, and
+`<plugin root>/tools/local-llm/runner/local-llm.mjs` where it is the `packs/` payload.
+
+The runner talks to an OpenAI-compatible server on loopback: LM Studio on `127.0.0.1:1234` by default,
+or `--base-url` (or `PORTULAN_LOCAL_LLM_URL`) for another loopback port such as Ollama's `11434`. Run
+`node <runner> status` first. Exit `0` lists the models the server holds; exit `1` is an endpoint
+refused as off loopback; exit `2` is could-not-run — no server answered, it answered with an HTTP
+error, or `--base-url` is not a URL. On anything but `0`, do the work in the parent session. Never pass
+`--allow-remote` on your own authority: an endpoint off loopback is the `local-llm-off-loopback`
+decision, proposed before it runs.
+
+## When to use it
+
+- **A verify-gated file transform:** a mechanical refactor, a history-comment cleanup, or a unit test
+  added, where a verify command can prove the edit green or have it rolled back.
+- **An explicitly selected candidate research digest:** reading a long file or log so only a short digest enters the parent context.
+- **An explicitly selected candidate librarian or handoff draft:** compressing a handoff under its byte cap, or drafting a `codify` or
+  `consolidate` candidate for human review.
+
+Not for multi-file architectural planning, ambiguous requirements (`clarify`), or pre-merge verdicts
+(`reviewer`).
+
+## The pass
+
+1. **Scope the input first.** Outline a file of 300 lines or more with
+   `node <plugin root>/cli/symbols.mjs <file>` and pass `--file <file> --lines <start>-<end>` (to
+   `transform`, `chat` and `summarize` alike) rather than the whole file. `cli/` ships with the
+   repository-root plugin and not in the `packs/` payload; there, find the span's line numbers with
+   `grep -n`. Prefill scales with prompt bytes: proposal 0039 measured prompts of about 400–470 tokens
+   prefilling in 0.85–1.88 s, and the `32 KB` default of `--max-input-bytes` (about 8k tokens) is a
+   ceiling, not a measured latency.
+2. **Use an earned role.** Code transforms and strict syntax use `--role code`
+   (`qwen/qwen3.8-27b`) at `--effort low`, supported by the
+   [captured A/B](../../../../../evals/ab/local-worker.md)'s L5/H5 code cell. Shared `--role prose`
+   (`google/gemma-4-31b`) is disabled: codify scored L0/H3, despite handoff's L5/H5. Keep digests and
+   librarian drafts in the parent session. `summarize` defaults to prose and refuses; explicit roles,
+   model overrides and environment mismatches cannot bypass the guard. An operator can select a
+   candidate with `--model <id>` and no `--role`; that is deliberate evaluation, not earned routing.
+   Screen a candidate with `node <runner> eval --model <id>`; it needs `cli/` beside `packs/` and exits
+   `2` without it. Passing a screen never enables a role.
+3. **Gate every edit.** `node <runner> transform --file <path> --verify "<cmd>" --prompt "<instruction>"`,
+   where `--verify` is required. The runner applies the edit, runs `<cmd>`, retries with the end of its
+   output on exit `1`, and keeps the edit only on exit `0`; any other exit, and SIGINT, SIGTERM or
+   SIGHUP, restores the file byte for byte. It is a rollback, not an atomic write: any other signal that
+   ends the runner, SIGKILL and SIGQUIT among them, or a power loss between the edit and its verdict
+   leaves the edit in place.
+4. **Read only the receipt back.** On exit `0`, take the one-line receipt and do not re-read the file
+   unless a later edit depends on its new line numbers. On exit `1` or `2`, escalate to the frontier
+   implementer rather than looping locally again.

package/packs/tools/local-llm/verify/README.md

@@ -0,0 +1,18 @@
+# `runner-rails` — what it checks, and what it cannot
+
+One recipe: `node ${PACK_ROOT}/runner/local-llm.mjs --verify-offline`, run from the adopting repository's root.
+
+## The three exits
+
+| Exit | Means |
+|---|---|
+| `0` | all offline runner rails hold: non-loopback URLs are refused without `--allow-remote`, oversized inputs above `--max-input-bytes` are refused before network I/O, a verify command ending in any exit but `0` or `1` is could-not-run with the file restored, a green verify command keeps the edit with a one-line receipt, transform rollback restores original file bytes on a red verify command, and `dedup` refuses a non-loopback endpoint and a file over the ceiling before any request |
+| `1` | at least one runner rail failed to fire (a forced-red check passed when it should have been refused, rollback left modified bytes behind, a green verify did not keep its edit with a one-line receipt, or `dedup` reached its request) |
+| `2` | **could not run** — [`runner/local-llm.mjs`](../runner/local-llm.mjs) or the Node.js runtime could not be executed |
+
+## Why `--verify-offline` makes no network or loopback call
+
+A verify recipe in Portulan may never make a network call, and a local LLM server (`localhost:1234`) is
+machine-specific state that is absent in CI. `--verify-offline` exercises the runner's guards against
+in-process synthetic fixtures and three temporary-file transform drills (red, no verdict, green) and a `dedup` drill over two temporary files, proving the rails hold without
+touching a socket. Live model health checks and role grading use `status` or `eval` outside recipes.

package/spec/README.md

@@ -114,7 +114,9 @@ carries, applied to the handoff series — `slots.handoffs` when `handoffs` is d
 either counted as a handoff by the `record` check's correspondence or failed by it for carrying no
 date; and, as of 2.6, that same pair a third time over the per-persona scope layer — `slots.personas`
 when `personas` is declared, and `personas.index.path` resolving **outside** `slots.personas`, since
-`index`'s orphan sweep would examine a file sited there as an undeclared persona location.
+`index`'s orphan sweep would examine a file sited there as an undeclared persona location; and, as of
+2.11, `memory.store.budget.record_kilobytes` when `memory.store.budget.cutoff` is declared, since a
+cutoff says which records that cap binds and alone configures nothing.
 Everything else is optional.
 
 _The 2.6 pair was enforced in `doctor` from the day the keys landed and was missing from this list until
@@ -139,7 +141,7 @@ a manifest in *another repository*, and no contract over a single document can s
 join the list, and the reason is what keeps that list meaningful: every entry there is a dependency
 between two keys **of one manifest**, which is the thing a reader of the schema alone would expect to find
 and does not. A check that needs a second repository is not in that category, and folding it in would make
-the count measure two different things at once. **The count stays at nine**, and it counts what it always
+the count measure two different things at once. **The count stays at ten**, and it counts what it always
 counted.
 
 [`slots.md`](slots.md) argues each one.
@@ -150,8 +152,8 @@ defect [#77](https://github.com/sleepy-panda-srl/portulan/issues/77) is filed ab
 and adding to the list at 2.5 is exactly the edit that would have left it stale again — which is how
 this one was noticed._
 
-That the count went from one to three in a single MINOR, then to five, then to seven, and now stands at
-**nine**, is worth noticing rather than absorbing. Each is a genuine dependency between two keys and none
+That the count went from one to three in a single MINOR, then to five, then to seven, then to nine, and
+now stands at **ten**, is worth noticing rather than absorbing. Each is a genuine dependency between two keys and none
 can be written in the declared subset, so the gap between *what the schema says* and *what a conforming
 manifest must satisfy* is widening — and a constraint invisible to someone reading the schema alone is a
 real cost, stated here rather than discovered. The subset earns its narrowness by being implementable
@@ -179,6 +181,38 @@ subset can say, and `doctor` returns at *the manifest must conform first* before
 runs. It is a live hole for `cli/index.mjs` alone, which validates against no schema by design and
 therefore refuses the string itself.)_
 
+**2.9 adds nothing to that list either**: `context` requires `ratio`, and `ratio` requires its two
+fields, in the schema itself, because `required` is in the subset. It adds **two** keys to the hand-check,
+so it covers **nine**. `context.always.budget.tokens` is the fifth budget the subset can only type as
+`number`. `context.ratio.bytes_per_token` is the first key held to something other than a positive
+integer: 2.99 bytes per token is a real figure, so the check is *at least 1*, since a token covers at
+least one byte and a smaller figure is tokens per byte entered inverted. For that key `minimum` alone
+would close the gap.
+
+**2.10 adds nothing to either list.** `slots.context` is a directory path, which the schema types in full,
+and what a unit's frontmatter may say is `compile`'s to refuse, because the subset cannot see inside a
+file. `doctor` checks the slot as it checks every directory slot, and gates it to 2.10.
+
+**2.11 adds one to each list.** `memory.store.budget.cutoff` needs `record_kilobytes` beside it, the
+tenth conditional requirement; and its `pattern` admits a day that does not exist, such as `2026-02-30`,
+so `doctor` and `cli/index.mjs` refuse one by hand, and the hand-check covers **ten**.
+`sessions` adds nothing to either: every field of it is a boolean or one of two strings, which the
+schema types in full with `type` and `enum`, so `doctor` only gates the key to 2.11.
+
+**2.12 adds five to the hand-check and nothing to the conditional requirements.** `required` holds both
+halves of `spend.multipliers` and both lifetimes of its `write` in the schema itself, and the subset types
+the four figures only as `number`, the horizon included, since it cannot say `integer`, so `doctor` holds
+the read in (0, 1], each write at least 1 and the horizon to a positive integer by hand, and refuses a write
+the read divides past the largest number, since the restart threshold divides one by the other; the
+hand-check covers **fifteen**. For the two writes `minimum` alone would close the gap, as it would for the
+ratio; the read is the first figure bounded above, so it would need `exclusiveMinimum` and `maximum`, and
+the horizon the budgets' `minimum` and `integer`; no keyword in the subset relates two figures, so the
+quotient stays by hand.
+
+**2.13 adds nothing to either list.** `spend.restart` is one of two strings, which the subset types in full
+with `type` and `enum`, so the key needs no hand-check, only the gate to 2.13, which `doctor` and `compile`
+both hold.
+
 _These figures are history rather than state: what 2.3 and 2.4 added cannot change, so they do not go
 stale the way the removed count did. The one forward-looking sentence is the growth rate, and it is
 dated by the version it names._
@@ -194,15 +228,87 @@ number governing both would make a bump in either mean a change in the other:
 
 | Schema | Manifest key | Current | What it governs |
 |---|---|---|---|
-| [`workspace.schema.json`](workspace.schema.json) | `portulan.spec` | **2.8** | the Workspace Definition — the manifest at a workspace root |
+| [`workspace.schema.json`](workspace.schema.json) | `portulan.spec` | **2.13** | the Workspace Definition — the manifest at a workspace root |
 | [`pack.schema.json`](pack.schema.json) | `portulan.pack` | **1.0** | the Pack Definition — the manifest at a pack root. |
 
 The rules below apply to each train independently. `portulan.spec` is `MAJOR.MINOR`, and the current
-Workspace Definition version is **2.8**. It did **not** move when the Pack Definition arrived, because
+Workspace Definition version is **2.13**. It did **not** move when the Pack Definition arrived, because
 `workspace.schema.json` was byte-identical across that change: `packs` already existed as an array of
 strings and was deliberately left that way, since tightening its items to the canonical `category/name`
 form would be a constraint an existing manifest could newly fail, which is a MAJOR.
 
+**2.13 is a MINOR on 2.8's terms: optional keys only.** `spend.restart` is the last piece of item 5 of
+proposal `0038`'s order of work, the declared block its ruling 3 allows: `"advise"` is the restart advisory as
+it was, and `"block"` also holds a turn's end once, at the first stop at or past the threshold that no block
+provoked, with the advisory's line as the reason; [`slots.md`](slots.md) argues it. Nothing is removed,
+renamed, tightened or defaulted: without the key, or with `"advise"`, the settings compile byte for byte as
+before, so every 2.12 manifest is a valid 2.13 manifest unchanged. This repository's own workspace stays on
+2.11 and declares no block: it declares no multipliers either, and at the general ones the line comes early
+for a model whose cache reads cost less than a tenth, so a block would hold its sessions short of their real
+line. Nothing writes 2.13 unasked: `init` asks nothing about the key and `upgrade` offers nothing, since
+ruling 3 makes a block a workspace's own choice. `KNOWN_SPECS` in [`../cli/index.mjs`](../cli/index.mjs) and
+[`../cli/librarian.mjs`](../cli/librarian.mjs) gains `"2.13"` by addition, and `doctor` and `compile` both
+refuse the key in a manifest that declares an earlier MINOR.
+
+**2.12 is a MINOR on 2.8's terms: optional keys only.** `spend` is item 4 of proposal `0038`'s order of
+work: the multipliers the restart threshold is computed at, which its ruling 2 has the manifest declare, and
+the horizon the threshold is judged over, 20 requests under ruling 3 until the manifest declares another;
+[`slots.md`](slots.md) argues it. Nothing is removed, renamed, tightened or defaulted: without `spend`,
+[`../cli/ledger.mjs`](../cli/ledger.mjs) and the restart advisory price at the general multipliers as before
+and say `undeclared`, and the settings compile byte for byte as before, so every 2.11 manifest is a valid
+2.12 manifest unchanged. This repository's own workspace stays on 2.11 and declares no `spend`; it now
+declares `sessions.headless.cache_lifetime` `"5m"`, a 2.11 key. `examples/` stays on 2.4. `init` writes 2.11
+where a person takes the five-minute cache lifetime it now offers, since `sessions` is 2.11's key, and 2.10
+otherwise. `KNOWN_SPECS` in [`../cli/index.mjs`](../cli/index.mjs) and
+[`../cli/librarian.mjs`](../cli/librarian.mjs) gains `"2.12"` by addition, and `doctor` gates the key to
+2.12. `0038`'s third key, the declared Stop-gate block, takes the next free MINOR, 2.13, in its own change,
+and `0034`'s keys take the next free MINOR when they are drafted.
+
+**2.11 is a MINOR on 2.8's terms: optional keys only.** `memory.store.budget.cutoff`
+makes the per-record cap forward-only, in proposal `0037`'s shape for a handoff, and [`slots.md`](slots.md)
+argues it. `sessions` is the machine half of [`../core/operating/sessions.md`](../core/operating/sessions.md),
+from `0038`'s rules 3 and 4: the host switches that change what a fresh session writes into the prompt cache,
+two of which `compile` writes into the settings it already generates and one of which only a runner can apply;
+[`slots.md`](slots.md) argues it too. Nothing is removed, renamed, tightened or defaulted: without the cutoff,
+`record_kilobytes` binds every record as it did, and without `sessions` the settings compile byte for byte as
+before, so every 2.10 manifest is a valid 2.11 manifest unchanged. This repository's own workspace moves from
+2.10 to 2.11 to declare the cutoff, with the cap lowered from 8 KB to 2 and the cutoff 2026-09-24, and declares
+no `sessions`; `examples/` stays on 2.4. `KNOWN_SPECS` in [`../cli/index.mjs`](../cli/index.mjs) and
+[`../cli/librarian.mjs`](../cli/librarian.mjs) gains `"2.11"` by addition, `doctor` gates both keys to 2.11,
+and the four writers stay at `2.7`, since nothing they scaffold declares either. `0034`'s key and the rest of
+`0038`'s still take the next free MINOR when they are drafted.
+
+**2.10 is a MINOR on 2.9's terms: one optional slot and nothing else.** `slots.context` is the content
+half of [`../core/operating/context.md`](../core/operating/context.md), from proposal `0036`'s compile
+targets: a directory of guidance, each file declaring in its frontmatter the load tier it belongs in, which
+`compile` emits in each host's own form. Nothing is removed, renamed, tightened or defaulted, so every 2.9
+manifest is a valid 2.10 manifest unchanged, and [`slots.md`](slots.md) argues the slot. It is the first
+MINOR with two digits, and every reader compares the MINOR as a number or matches the string whole, so
+`2.10` sorts after `2.9`. `0034`'s and `0038`'s keys still take the next free MINOR when they are drafted.
+
+**Measured across the bump:** `node cli/doctor.mjs .portulan examples` is GREEN, with `.portulan` on 2.8
+and `examples/` on 2.4, both untouched: the demo stays six MINORs behind for the reason given under 2.8,
+and no workspace here declares the slot, because moving guidance between tiers in this repository's own
+curated layer is its maintainer's change to make. `KNOWN_SPECS` in [`../cli/index.mjs`](../cli/index.mjs)
+and [`../cli/librarian.mjs`](../cli/librarian.mjs) gains `"2.10"` by addition, and the four writers stay at
+`2.7`, since nothing they scaffold declares the slot.
+
+**2.9 is a MINOR on 2.8's terms: one optional key and nothing else.** `context` is the machine half of
+[`../core/operating/context.md`](../core/operating/context.md), from proposal `0036`: an always-tier
+budget in tokens and the bytes-per-token ratio it is counted at, with the host whose exact count
+calibrated it. Nothing is removed, renamed, tightened or defaulted, so every 2.8 manifest is a valid 2.9
+manifest unchanged. [`slots.md`](slots.md) argues the key. **It carries `context` alone.** Proposals
+`0034` (`evals` and `telemetry`) and `0038` (its spend keys) each say their keys ride the MINOR this key
+needs and that neither waits for the other; none of them is drafted, and `0034`'s accepted text names no
+version number, so they take the next free MINOR when they are drafted.
+
+**Measured across the bump, as for 2.7 and 2.8:** `node cli/doctor.mjs .portulan examples` is GREEN, with
+`.portulan` still on 2.8 and `examples/` on 2.4, both untouched. Neither declares the key, because
+nothing measures the always tier yet and a budget nothing checks reads as a rail. What it costs:
+`KNOWN_SPECS` in [`../cli/index.mjs`](../cli/index.mjs) and [`../cli/librarian.mjs`](../cli/librarian.mjs)
+gains `"2.9"` by addition, and the four writers stay at `2.7`, since nothing they scaffold declares the
+key.
+
 **2.8 is a MINOR on the plainest terms in this train's history: one optional key and nothing else.**
 `memory.store.budget.record_kilobytes` — the most bytes any single record may hold — joins the sibling
 `kilobytes` it does not replace. Nothing is removed, renamed, tightened or defaulted, so every 2.7
@@ -328,6 +434,7 @@ workspace with no constitution slot and a green report.
 | A declared pack **resolves** | `doctor` | **Built**. Roots are derived from `tree`, and named roots may be given with `--pack-root`, which **replace** the derived one rather than preceding it, so a from-a-feed demonstration cannot be satisfied by a copy in the local tree at all. A workspace with no `tree` and no named root has its packs reported *unverifiable* rather than failed. Resolution **from a feed is demonstrated**: the checkpoint ritual pack installed from the private `portulan-internal` marketplace and resolved from the install root, which is the same code path the derived one takes. **Discovery is built** ([#123](https://github.com/sleepy-panda-srl/portulan/issues/123)): `--pack-root auto` reads the host's installed-plugin record — in **both** shapes a plugin lands in, packs under `packs/` for a repository-shaped one and categories at the install root for a flat one, which is what this project's own feed ships. Asked-for discovery is **unioned** with the tree-derived root, discovered first, so a workspace composing a cache-installed pack *and* one of its own resolves both. The **named**-root property above is untouched: a named root still replaces the derived one, so a from-a-feed demonstration given one cannot be satisfied by a local copy. What the union trades is the weaker guarantee that `auto` *alone* implied provenance; it no longer does, and each pack's resolution states which root answered instead. Asking for a named root **and** `auto` together is refused (exit 2) rather than silently resolved to one of them. Discovery runs on the **unasked** path too, because `--pack-root` is *optional where discovery finds a root*. `auto` now selects the strict degrade (asked-and-could-not-look is exit 2) rather than unlocking discovery. Two things bound it, and neither makes a bare run host-independent — `doctor` is a per-host capability report and a bare verdict does move with the machine. First, every **required** check **names** its root, which replaces every other source, so it cannot consult the host at all. Second, `doctor`'s note-vs-fail keying is on a root's **origin**, so discovery can turn a note into a **resolution** and never a **miss** into a failure — a miss under a root the workspace or the caller claimed stays a FAIL whatever is installed. It softens nothing: a discovered copy that resolves and is *invalid* still fails, with its origin named. |
 | A pack manifest conforms to the Pack Definition | `doctor` | **Built**. Same validator, same subset, a different schema and version train. |
 | A pack's skills and personas are opened and validated | `doctor` | **Built**, on the maintainer's ruling that row 7's validation reads broad. A skill's frontmatter (`name` kebab-case, `description` non-empty — the two a host reads before loading a body); a persona against the five-part contract, **including the memory scope** `core/operating/memory.md` promised would be validated at this milestone; and the tier no role may claim. Containment is checked **after resolution**, because opening these paths is what made an escaping value stop being inert. Three honest limits, each measured rather than assumed. The skills walk stops **three levels down**, matching `cli/plugin-lint.mjs`'s bound so two walkers over the same key cannot disagree, and it **reports the directories it did not descend into** rather than counting a root it never opened as empty. The Prohibited check is a prose heuristic defeated by any negation **in the same block** — a bullet list counts as one block — and the structural fix is a declared reach *field*, a contract change that is not built. And the five-part check is **presence**, not content: a persona whose sections are all empty passes, so a declared memory scope is read and not honoured. |
+| A persona's declared context fields — `model`, `effort`, `omitClaudeMd`, `cacheLifetime` | `doctor` · `compile` | **Built** for a persona a composed pack ships, with no schema version moved, since no persona file is governed by either schema: the fields belong to the persona contract [`../core/personas/README.md`](../core/personas/README.md) fixes, and are optional. `doctor` fails a malformed value and `compile` refuses one; neither defaults any. `compile` writes the declared fields into the role's hand-written binding, `agents/<name>.md` in the tree, byte-compared under `--check`, and prints a degradation line for each field a host cannot express. Claude Code loads `agents/` only from a plugin root, so in a tree that is not one the compiled block is loaded by nothing, and that degradation line says so; in one that is, it loads only while the plugin is installed and enabled, which `compile` cannot see. **Not built**: writing `.claude/agents/`, where a repository that is not a plugin loads its agents; a binding where none exists, which is reported unbound; and the compiling of a core persona's binding. |
 | Pack gate fragments merge **tighten-only** | [`../cli/compile.mjs`](../cli/compile.mjs) | **Built**. Two layers and two axes: `auto` is absent from the Pack Definition's tier enum, so a demotion to unattended is unexpressible; the comparison against the composed base is the compiler's, and both a weakened **tier** and a changed **action** throw rather than being dropped. The action half is the one a tier-only check misses — raising the tier while swapping the matcher removes the gate and still reads as a tightening. |
 | A pack declaring a version ahead of `doctor` | `doctor` | **Built**. Refused rather than graded, symmetric with the workspace train, and on the Pack Definition's own `$id`. |
 | Path slots resolve to real files | `doctor` | **Built.** File-versus-directory too; a slot resolving outside the workspace is reported, never failed. |

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