@sleepy_panda_srl/portulan 0.1.3 → 0.2.0

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

package/spec/slots.md

@@ -50,8 +50,9 @@ experience a failure. *(Binding non-goal: no ceremony that can't scale down.)*
 | `slots.memory` | path | no | constitution — thesis 1 *(memory)*; [`memory.md`](../core/operating/memory.md) |
 | `slots.repos` | path | no | constitution — thesis 1 *(repo cards)*; [`repo-card.md`](../core/templates/repo-card.md) |
 | `slots.tasks` | path | no | content — [`tasks/`](../.portulan/tasks/); constitution — BMAD, the story file as atomic context unit |
-| `slots.handoffs` | path | no | content — [`handoffs/`](../.portulan/handoffs/); [`loop.md`](../core/operating/loop.md) — every session ends with one |
+| `slots.handoffs` | path | no | content — [`handoffs/`](../.portulan/handoffs/); [`loop.md`](../core/operating/loop.md) — a session ending with work not committed and pushed ends with one |
 | `slots.proposals` | path | no | content — [`proposals/`](../.portulan/proposals/); [`evolution.md`](../core/operating/evolution.md) |
+| `slots.context` | path | no | criterion — milestone 12, *`compile` emits Claude Code's on-path and on-invoke targets*; [`context.md`](../core/operating/context.md) — the four load tiers |
 | `verify` | structured | **for a governing kind** | criterion — *verify recipes*; [`verification.md`](../core/operating/verification.md) — the workspace sets the default |
 | `governed_by` | manifest | **for `kind: pointer`** | the maintainer's residence ruling, 2026-07-30 — [proposal 0017](../.portulan/proposals/0017-one-repository-one-governing-workspace.md); one repository, one governing workspace |
 | `products[]` | structured | no | criterion — *product-layer slot … portfolio-aware*; content — [`identity.md`](../.portulan/identity.md) |
@@ -60,6 +61,9 @@ experience a failure. *(Binding non-goal: no ceremony that can't scale down.)*
 | `packs` | structured | no | constitution — thesis 1's cascade, `core < pack < workspace` |
 | `memory` | structured | no | criterion — milestone 5, *generated size-budgeted index whose budget is a rail*; [`memory.md`](../core/operating/memory.md) — the Index and Consolidate states of the lifecycle |
 | `handoffs` | structured | no | criterion — milestone 5 as amended, *a generated index over the handoff series*; [`loop.md`](../core/operating/loop.md) — the librarian that mines the series |
+| `context` | structured | no | criterion — milestone 12, *what a host loads into every context is measured, budgeted and demoted*; [`context.md`](../core/operating/context.md) — the always tier, budgeted in tokens |
+| `sessions` | structured | no | criterion — milestone 13, *the prefix stays stable* and *earned by an A/B run*; [`sessions.md`](../core/operating/sessions.md) — which sessions start warm, and the switches that change the prefix |
+| `spend` | structured | no | criterion — milestone 13, *the manifest declares the multipliers and the horizon*; [proposal 0038](../.portulan/proposals/0038-what-a-change-spends-is-measured.md), rulings 2 and 3 — the figures the restart threshold is computed at |
 | `provenance` | record field | **on every rule** | criterion — *provenance slot*; [proposal 0002](../.portulan/proposals/0002-sealed-provenance.md), adopted |
 
 ## `kind` — which of the four workspace kinds this is, and which of them govern
@@ -234,8 +238,8 @@ held then.
 
 `auto` · `propose` · `gated` · **`prohibited`**. The fourth is not a stronger `gated` — it is a different
 answer. Gated means *approvable per action* and compiles to a prompt; prohibited means *no approval
-exists* and compiles to a refusal. A three-class policy would file "no agent edits the constitution" under
-Gated, and the compiler would then emit a prompt — turning *never* into *unless someone clicks yes*.
+exists* and compiles to a refusal. A three-class policy would file "no session certifies its own checkpoint"
+under Gated, and the compiler would then emit a prompt — turning *never* into *unless someone clicks yes*.
 
 ### What a compiler must do with it
 
@@ -323,9 +327,10 @@ at someone else's workspace.
 
 ## `products[]` — repeated, even though customer zero has one
 
-The criterion says *portfolio-aware: many products per workspace*, and the vision's Reference workspaces
-bullet describes a Sleepy Panda SRL workspace covering **all** Sleepy Panda SRL products. So the product layer is
-per-product from the start, not a workspace-level field that a later milestone has to unpick.
+The criterion says *portfolio-aware: many products per workspace*, and
+[`vision.md`](../docs/vision.md) § *Reference workspaces* gives the Sleepy Panda SRL workspace **all**
+its products. So the product layer is per-product from the start, not a workspace-level field that a
+later milestone has to unpick.
 
 This is the schema's most deliberate act of resisting its own evidence. Derived faithfully from the only
 available sample, `products` would be a singular object — customer zero has exactly one product, and a
@@ -350,9 +355,10 @@ claim it cannot check is whether the mission written there is still true.
 
 ## `affordances` — what the product offers an agent
 
-The unclaimed niche in the influence map: *agent-legibility, repo affordances scored by `doctor`*. The
-slot holds what an agent can rely on — entry points, contracts, budgets, commands — **and** what it must
-not assume, which is the half that makes the document worth reading. Customer zero's
+The unclaimed niche [`vision.md`](../docs/vision.md) § *Agent-native / AX* names: agent legibility,
+the repository's affordances scored by `doctor`. The slot holds what an agent can rely on — entry
+points, contracts, budgets, commands — **and** what it must not assume, which is the half that makes
+the document worth reading. Customer zero's
 [affordances document](../.portulan/products/portulan/affordances.md) is a filled example.
 
 It resolves down the cascade *inside* the workspace: a workspace-level `affordances` is the default, and
@@ -412,7 +418,7 @@ dependency between two keys needs `if`/`then` or `dependentRequired`, and neithe
 to anyone reading the schema alone. Stated loudly rather than hidden, because "read the schema to know
 the contract" is otherwise false in these places, and an unmarked exception is worse than a marked one.
 
-**It is now one of nine**, and [`README.md`](README.md) keeps the running count because the number is
+**It is now one of ten**, and [`README.md`](README.md) keeps the running count because the number is
 the thing to watch. Two arrived with `memory` at 2.3 — a declared `memory` object needs a
 `slots.memory` store to index, and `memory.index.path` must resolve *outside* it — two more with
 `librarian` at 2.4, and then that same store-and-siting pair twice again: over the handoff series at 2.5
@@ -505,6 +511,7 @@ the store is the single source, committed so a change to what is always loaded i
 | `index.budget.columns` | The most columns one line may hold — refused, never truncated. |
 | `store.budget.kilobytes` | The most the store's records may total, in 1024-byte KB. |
 | `store.budget.record_kilobytes` | Added at 2.8. The most any **one** record may hold. |
+| `store.budget.cutoff` | Added at 2.11, beside `record_kilobytes` only. The day after which that cap binds; forward only. |
 
 **Four numbers rather than one, because they are different axes — and each pairs with a per-unit cap
 that closes the hole the aggregate has.** The index is what gets loaded to decide what else to load,
@@ -526,6 +533,17 @@ workspace declares `record_kilobytes` alone, and [`../examples/workspace.json`](
 declares `kilobytes`, so both rails have a live carrier in the tree rather than one of them being a
 key the schema accepts and nothing exercises.
 
+**The per-record cap can bind forward only, since 2.11**, in proposal `0037`'s shape for a handoff. With
+`store.budget.cutoff` declared, the cap binds the records dated after the cutoff, and a record dated on or
+before it is reported, never railed. A record's date is its `**dated:**` line, the day its text last
+changed, because a verify rail may not read git; an edit re-dates a record, so an old one meets the cap
+in the change that next rewrites it, and a cap lowered today does not turn a whole store red with no
+change to the records. A missing or unreal date is refused, and so is one more than a day after the UTC
+date the check runs on. The cutoff is the declaring change's date or the newest record's, whichever is
+later; it moves only in a change that tightens the cap, and never earlier, which no checker
+establishes (below). The cutoff requires
+`record_kilobytes` beside it, one more conditional requirement the subset cannot write.
+
 **Nothing is defaulted**, on the `floor` object's rule from 2.2: a default here would be this
 specification setting a policy for every workspace that ever adopts it, in a key nobody typed. An
 undeclared number is not checked. A number that is declared and is not a positive integer is
@@ -548,13 +566,18 @@ not in the design; it was in the containment test.
 That rule is [`memory.md`](../core/operating/memory.md)'s and the human gate's — refusing a raise needs
 a check that reads git history, which produces false reds in a shallow CI checkout. The limit is
 recorded in [`../.portulan/verify/README.md`](../.portulan/verify/README.md) with the measurement
-behind it, rather than left for a reader to assume the rail covers both halves.
+behind it, rather than left for a reader to assume the rail covers both halves. A `cutoff` moved
+earlier, or later without a tighter cap, is the same hand edit, since it unbinds what the cap bound,
+and the same gate holds it for the same reason.
 
 ## `handoffs` — an index over a series nobody can consolidate
 
 Added at 2.5, and it is deliberately one key. `slots.handoffs` is the series; this object says where
-its generated index goes. The same split as `memory` above, built by the same generator, byte-compared
-by the same recipe.
+its generated index goes. The same split as `memory` above, built by the same generator. A workspace
+keeps its index or not, and a copy on disk says which: a kept copy is byte-compared by the same recipe
+and regenerated by a write; with none, `index --check` renders the series, which proves every handoff
+yields a line, and nothing is written. This repository keeps none since 2026-09-23: a committed copy
+conflicted on every merge that added a handoff.
 
 | Field | What it is |
 |---|---|
@@ -584,19 +607,16 @@ filename: a generated line whose title the generator invented is the one thing a
 not contain. The date is derived from the filename, which is where the cadence rule already puts it.
 
 **Its siting rule has two enforcers rather than one, and neither is redundant.** An index inside
-`slots.handoffs` is either counted as a handoff by `docs.sh`'s date-correspondence check — inflating
-one side of a count the Session log is held to — or, carrying no date, failed by the same check for
-exactly that. `index` refuses the siting outright, because it cannot render a series it would then be
+`slots.handoffs` is either a dated handoff to `docs.sh`'s `record` check or, carrying no date, failed
+by that check for exactly that. `index` refuses the siting outright, because it cannot render a series it would then be
 a member of. The second enforcer is not a second opinion: the generator physically cannot proceed,
 while the recipe is what catches a hand-placed file the generator never saw.
 
 **There is no budget here, and the absence is the argued half.** A budget's only permitted remedy is
 consolidation — merge, compress, split, retire ([`memory.md`](../core/operating/memory.md)) — and a
-handoff series is append-only by construction: one per session, dated, held to the Session log by a
-count-based correspondence. Retiring a handoff to buy headroom would either red that check or destroy
-the record it exists to keep; **splitting one** — the move 2.8 added for the per-record rail — would
-put two dated handoffs against a single session and red the same correspondence from the other side;
-and raising the budget in the change that breached it is the one repair that doctrine rules out. Every
+handoff series is append-only by construction. Retiring a handoff to buy headroom destroys the record
+it exists to keep; **splitting one** — the move 2.8 added for the per-record rail — leaves the series
+no smaller; and raising the budget in the change that breached it is the one repair that doctrine rules out. Every
 remedy such a budget could ask for is barred, which makes it a rail designed to be broken — and a rail
 that fires with no legal repair is how a whole recipe gets switched off.
 
@@ -680,6 +700,298 @@ heading still holds. There is no budget for the same reason:
 there is nothing yet to budget, and the axis such a rail should use is per-persona rather than
 per-workspace, which belongs to the row where something finally reads these locations.
 
+## `context` — what the always tier may cost, and the ratio it is counted at
+
+Added at **2.9**, with proposal `0036`. [`context.md`](../core/operating/context.md) is the doctrine and the
+one source for what each load tier holds; this object is its machine half, as `memory` is
+[`memory.md`](../core/operating/memory.md)'s.
+
+| Field | What it is |
+|---|---|
+| `always.budget.tokens` | The most tokens the always tier may load, counted at the ratio below. |
+| `ratio.bytes_per_token` | Bytes per token, as a host's exact count measured them. At least 1. |
+| `ratio.calibrated_by` | The host whose exact count calibrated the ratio, by the id `compile` gives it: `claude-code`. |
+
+```json
+"context": {
+  "always": { "budget": { "tokens": 8000 } },
+  "ratio": { "bytes_per_token": 2.99, "calibrated_by": "claude-code" }
+}
+```
+
+**The ratio is required and the budget is not.** A token budget with nothing to count it by is not a
+budget, so the schema refuses `context` without `ratio`, and a ratio without the host that calibrated
+it. Those are dependencies the subset can state, so they are the schema's and join no list of `doctor`'s
+conditionals. A ratio alone is a legitimate shape: it is what a report in tokens needs, and the default
+is the report.
+
+**Declared, not measured per run.** The exact count asks the host, which is a network call no verify
+recipe may make, and a ratio that moved between runs would make one tree red on one run and green on the
+next. So the ratio is measured exactly on demand and declared, with the host that measured it. There is no
+date field, because the commit that changes the ratio dates it, and one ratio rather than one per host,
+because nothing yet reads a second.
+
+**Named for its tier.** Only the always tier is budgeted, and the budget sits under `always` so a budget
+on a later tier would sit beside it rather than force a rename, which would be a MAJOR.
+
+**Nothing is defaulted**, on memory's rule: an undeclared budget is not checked. `doctor` refuses a
+declared token budget that is not a positive integer, as it refuses the memory budgets, and a ratio under
+1, because a token covers at least one byte and a smaller figure is tokens per byte entered inverted.
+Both are `doctor`'s because the subset has no `minimum` and cannot say `integer`. `doctor` also refuses
+`context` in a manifest declaring a version before 2.9, whose own validator refuses it as unknown: the
+key is gated from birth, when no manifest can newly fail the check.
+
+**What checks the budget itself.** `doctor` measures the always tier of every workspace that declares
+a `tree`, through [`../cli/context.mjs`](../cli/context.mjs), and fails it over a declared budget, or
+where a declared budget cannot be judged; with none declared it reports the figure. _(This paragraph read
+*"What nothing checks yet: the budget itself"* until that report landed, and it was true then:
+[`a-mandate-nothing-checks-is-already-broken.md`](../.portulan/memory/a-mandate-nothing-checks-is-already-broken.md)
+is why no workspace here declared the key before something checked it.)_ No workspace in this tree
+declares it now either: Portulan's own contribution is railed by this repository's recipes, not by a
+budget in its manifest. And, as with memory, no checker establishes that a budget was not raised in the
+change that breached it.
+
+## `sessions` — the host switches that change what a fresh session writes
+
+Added at **2.11**, from `0038`'s rules 3 and 4 and row 12's cache-lifetime compile target.
+[`sessions.md`](../core/operating/sessions.md) is the doctrine; this object is its machine half.
+
+| Field | What it is |
+|---|---|
+| `git_instructions` | `false` drops the host's git instructions from every session in the repository: on Claude Code, the startup git snapshot and the commit and pull-request instructions, compiled as `includeGitInstructions`. |
+| `cache_lifetime` | `"5m"` or `"1h"`: the main conversation's cache lifetime, compiled as Claude Code's `promptCacheTtl`. |
+| `headless.git_instructions` | The same switch, for the sessions Portulan's own runners start. |
+| `headless.cache_lifetime` | The same lifetime, for those sessions. |
+| `headless.exclude_dynamic_sections` | `true` starts those sessions with the per-machine sections moved from the system prompt into the first message, so runs in different directories or on different machines share the system prompt. |
+
+```json
+"sessions": {
+  "headless": { "cache_lifetime": "5m", "exclude_dynamic_sections": true }
+}
+```
+
+**Nothing is defaulted.** An undeclared switch is the host's own default and `compile` emits nothing for
+it, so a manifest without the key compiles byte for byte as before. A switch is declared once an A/B run
+has shown that it cuts spend with no loss, and [`sessions.md`](../core/operating/sessions.md) says which
+sessions keep what a switch removes.
+
+**Two scopes, because the host has two.** `git_instructions` and `cache_lifetime` are project settings on
+Claude Code, so `compile` writes them into the settings it already generates from `gates`, and they reach
+every session there, interactive or not. The exclusion is no setting at all: Claude Code 2.1.281 takes it
+only as a command-line flag or an SDK option, so only whatever starts a session can ask for it. `headless`
+is therefore read by Portulan's own runners that start sessions, today [`../cli/warm.mjs`](../cli/warm.mjs),
+which the package does not ship, and never compiled. A workspace with no gate policy has no settings
+for the first two to ride, and `compile` says that it compiled neither.
+
+**Offered to an adopter, and still never defaulted** (2026-09-24). `init` offers `cache_lifetime` `"5m"`
+with what it saves and what a pause costs, asking once at a terminal or taking `--cache-lifetime`, and on
+a yes drafts the key at 2.11 for `compile` to write; `upgrade` prints the same offer to a `repository`
+workspace that declares no lifetime, and writes nothing; `doctor` reports where every switch stands in one
+line. Only the lifetime is offered: the git instructions and the exclusion wait on their rows of
+[`../evals/ab/warm.md`](../evals/ab/warm.md).
+
+**Checked by the schema, and gated by `doctor`.** Every field is a boolean or one of two strings, which the
+subset types in full, so nothing joins `doctor`'s hand-check. `doctor` refuses the key in a manifest
+declaring a version before 2.11, gated from birth as `context` was.
+
+## `spend` — the figures the restart threshold is computed at
+
+Added at **2.12**, from [proposal 0038](../.portulan/proposals/0038-what-a-change-spends-is-measured.md)'s
+ruling 2, *the manifest declares the multipliers*, and its ruling 3's horizon; `restart` at **2.13**, from
+the same ruling's block by declaration. The proposal carries the arithmetic; this object holds the figures a
+workspace computes it at, and what a crossed threshold does.
+
+| Field | What it is |
+|---|---|
+| `multipliers.read` | What a cache read costs, as a multiple of an uncached input token. Above 0 and at most 1. |
+| `multipliers.write["5m"]` | What a five-minute cache write costs, as the same multiple. At least 1. |
+| `multipliers.write["1h"]` | What a one-hour cache write costs, as the same multiple. At least 1. |
+| `horizon.requests` | The requests still to go at which the restart threshold is judged. A positive integer. |
+| `restart` | `"advise"` or `"block"`: what a crossed threshold does. Undeclared, `"advise"`. |
+
+```json
+"spend": {
+  "multipliers": { "read": 0.05, "write": { "5m": 1.25, "1h": 2 } },
+  "horizon": { "requests": 30 },
+  "restart": "block"
+}
+```
+
+**What reads it.** A session is told to end into a handoff once its context passes
+`C* ≈ F × (1 + m_w / (n × m_r))`: `F` the fresh context, `m_r` the read multiplier, `m_w` the write multiplier
+at the lifetime the host recorded for the session's writes (the five-minute one where the records do not say),
+and `n` the horizon. [`../cli/ledger.mjs`](../cli/ledger.mjs) reads the key from `<dir>/workspace.json` when
+run with `--workspace <dir>`, and computes every threshold its report states at it. The restart advisory,
+[`../cli/advisory.mjs`](../cli/advisory.mjs), is handed its command and the host's payload and nothing else,
+so `compile` writes the figures onto each of its commands, the `PostToolUse` and `UserPromptSubmit` hooks, the
+status line and, where `restart` declares it, the block, as `--read`, `--write-5m`, `--write-1h` and
+`--horizon`, and its drift check holds them to the manifest: an edit to `spend` is drift until recompiled. A
+workspace with no gate policy has no settings for them to ride, and `compile` says that it compiled nothing.
+Every threshold the ledger or the advisory prints says whether its multipliers are declared, and so does a
+ledger report with no threshold to judge.
+
+**Declared, not defaulted.** Undeclared, both price at the general multipliers, a read at a tenth and writes
+at 1.25× and 2×, over a horizon of 20 requests, and say `undeclared`. That is ruling 2's answer to a spread no
+one figure fits: a model's cache reads cost between a fortieth and a tenth of an uncached input token. The
+general tenth puts the restart line early, which is the cheaper way to err, since a restart that comes too
+soon costs a fresh write and a handoff, and erring the other way, where reads cost a tenth, costs about four
+times more in excess reads over 20 requests. A declaration makes a team's contracted rates and its host's real
+prices one value. Either half may be declared alone, and the other keeps its general figures. The three
+multipliers are one set, because a threshold priced by one declared figure and two general ones would be
+priced by nobody's.
+
+**`restart`: a block, only where declared.** `"advise"` is the advisory every workspace has: the line once,
+with a tool result or at a prompt. `"block"` keeps that line and adds a block at the end of a turn: at the
+first stop whose last recorded request is at or past the threshold and that no block provoked, the advisory's
+own `stop` command, which `compile` writes as a second `Stop` command beside the Stop-gate's, holds the turn's
+end with the line as its reason, once in a session and again after each compaction, and the turn goes on. A
+stop that a block provoked is never held, since a host that gives that retry a new session id would find no
+record of the hold and hold it again. It is the advisory's command rather than a reason inside the Stop-gate,
+so the gate's counters and caps stay about the recipe and the handoff; and nothing ends the session, which
+stays the agent's or the human's act. `0038`'s *Enforcement* says the block comes *instead* of the line, and
+it is read here as *added*, because the line is what reaches an agent mid-stretch and a headless run's only
+stop is its last (the coordinator session's delegated call of 2026-09-24); where the agent already acted on
+the line, the block costs one request. Ruling 3 makes the block a workspace's own choice, so `init` asks
+nothing about it and `upgrade` offers nothing: the threshold is an estimate, and one priced at the general
+multipliers comes early for a model whose cache reads cost less than a tenth, where a block would hold a turn
+short of its real line. Undeclared or `"advise"`, the settings compile byte for byte as before; where
+`"block"` writes the command, `compile` says so on every run.
+
+**What is not here.** Ruling 2 has `init` offer the declaration from the host's own pricing setting where the
+host exposes one, else from a dated per-host table in the engine. Both are keyed by the model a host records,
+so both wait for their own change: until then `init` offers no figures, and a workspace writes its own by
+hand. Nothing checks a declared figure against what the workspace is billed; keeping it true is the declaring
+workspace's work.
+
+**Checked by the schema and by `doctor`, and refused by every reader.** The schema holds the shape: both
+halves of `multipliers`, both lifetimes of `write`, and no key it does not name. The subset types the four
+figures only as `number`, so `doctor` holds the read above 0 and at most 1, each write at least 1 and the
+horizon to a positive integer by hand: a token read from cache costs something and never more than the same
+token sent uncached, and writing one costs at least what sending it uncached does. Figures each in range can
+still give no threshold, since it divides each write by the read, so `doctor` also refuses a write the read
+divides past the largest number, which would put the restart line at Infinity, where no session reaches it.
+The ledger, `compile` and the advisory hold the same ranges themselves rather than trusting that `doctor` ran.
+The first two stop with exit 2; the advisory, whose exit 2 would erase the person's prompt, says once on
+stderr what it could not use and prices that half at the general figures. A threshold that a session's fresh
+context still carries past the largest number is none: the ledger stops with exit 2, and the advisory says it
+is not known. `doctor` refuses the key in a manifest declaring a version before 2.12, gated from birth as
+`sessions` was, and `restart` in one before 2.13. `compile` refuses `restart` there too, with exit 2 and
+nothing written, so that no block is compiled from a declaration its own version's validator refuses.
+`restart` is one of two strings, which the subset types in full, and the ledger and `compile` refuse any other
+with exit 2.
+
+## `slots.context` — the guidance a host loads, each unit in its tier
+
+Added at **2.10**, with proposal `0036`'s compile targets. [`context.md`](../core/operating/context.md)
+defines the four tiers. This slot's pair is `context` above: the slot holds the guidance and the key its
+budget, as `slots.memory` holds the records and `memory` their configuration.
+
+A directory of Markdown files, one unit of guidance each; only the `.md` files at its top level are units,
+and anything else in it is left alone. The file's name, less `.md`, is the unit's name and must be a slug,
+because a host names a skill by it. Each file opens with frontmatter naming its tier:
+
+```markdown
+---
+tier: on-path
+paths: ["api/**", "migrations/*.sql"]
+description: How this team writes an API handler and a migration.
+---
+
+The guidance itself, which is what the host loads.
+```
+
+| Key | What it is |
+|---|---|
+| `tier` | `always`, `on-path`, `on-invoke` or `on-read`: `0036`'s four tiers, spelled as that proposal spells them. |
+| `paths` | On-path only, and required there: globs, relative to the repository the workspace governs, that load the unit when the agent first touches a match. A list, in flow form as above or as a block list of `- ` items. |
+| `description` | Every tier but `always`, and one line: what an agent reads to decide whether to open the unit. It is a skill's description on a host that lists skills, and the pointer line wherever the unit degrades to one. |
+
+**The tier is declared, never inferred**, and a unit sits in one tier, so what a unit costs is what its
+tier costs and nothing has to read the file to find out where it belongs.
+
+**`compile` emits it, per host.** For Claude Code, an `always` unit is an unscoped rule, loaded into every
+context; an `on-path` unit is a rule scoped by `paths:`; an `on-invoke` unit is a project skill, whose
+description is always loaded and whose body loads when it is invoked; and an `on-read` unit is one line in
+an unscoped index of pointers, naming its file, its size in whole KB and its description (the size since
+2026-09-24, so a session knows what it passes over), while its file stays where it is for the agent to
+open. **A tier a host cannot express degrades to an on-read pointer, never to nothing**: the vendored
+`AGENTS.md` carries the `always` units inline and every other unit as a pointer, one level deep. The
+compiled files are committed and byte-compared against this slot, as the compiled settings are against
+`gates`, so a desktop session's fresh worktree has them. `compile` shows which rules in
+`.claude/rules/portulan/` are its own with a marker there, `.compiled`, a file no host loads that lists
+each rule it wrote: it rewrites or removes only a rule the marker lists, stops with exit 2 rather than
+replace one it does not list, and stops too where the directory holds Markdown files and no marker in its
+form. It writes and removes nothing through a link.
+
+**Checked by `compile`, not by the schema or `doctor`.** The subset cannot see inside a file, so the
+frontmatter is its consumer's to refuse: an unknown key, a tier outside the four, `paths` on a unit that is
+not on-path or reaching outside the repository, a missing `description` or one on an `always` unit, a unit
+with no guidance under its frontmatter, a link out of the workspace or into a directory `compile` writes into,
+a slot in one of those (`.claude/`, or the workspace's `compile/`, neither of which `vendor` carries), a name
+that is not a slug or is `on-read`, which the index takes, or a unit that would replace a skill written by
+hand or compiled from another unit stops `compile` with exit 2, *could not compile*. `doctor` checks what it
+checks of every directory slot, that the path resolves, and refuses the slot in a manifest declaring a version
+before 2.10, gated from birth as `context` was.
+
+**A unit named `boot` is the workspace's boot card**, reserved within 2.10, with no key and no version
+bump (decided 2026-09-23). It is an `always` unit whose first line
+under the frontmatter is `# Portulan boot card`, and the boot skill reads it in place of the slots when
+that line is in its context. `compile` refuses a `boot` unit in another tier or opening with another line,
+and a unit of another name opening with that one, which the skill would take for the card.
+
+**A section of a project instruction file can become an on-read unit**, with no key and no version bump
+(2026-09-24). A team marks it with a line `<!-- portulan: on-read -->` directly under its heading in
+`CLAUDE.md` or `.claude/CLAUDE.md`, and `upgrade`'s form step `0009` moves the section, heading and all
+and byte for byte, into a unit of this slot named by the heading, whose `description` is the heading's own
+text, leaving `<!-- portulan: on-read <unit> <digest> -->` where it was, the digest the moved section's.
+The file must reassemble from its units byte for byte, or nothing moves. Claude Code drops both comments
+before it loads the file, so neither costs a context. The unit's text is not rewritten, so a relative link
+in it still reads from the repository root, as it did in `CLAUDE.md`.
+[`../cli/instructions.mjs`](../cli/instructions.mjs) is the same split on the command line, and `--join`
+puts every section back as it stands, saying which one the digest shows edited since, and refusing a unit
+re-tiered since, or a file not at the top of this slot, rather than undo its tier or remove it.
+
+**An `always` unit may import whole files and write out another file's lead sentences or a gate policy's
+gates**, so a card carries a fact without holding a second copy of it:
+
+- **An import is `@` and a path, alone on its line, relative to the unit's own file.** Claude Code 2.1.281
+  loads a rule as it loads `CLAUDE.md`: it resolves an import against the file making it, follows it only
+  inside the project, skips code blocks, skips code spans and HTML comments except in a list item's text,
+  which it reads whole (2026-09-24), and loads nothing five imports below the rule. A rule scoped by
+  `paths:` loads on its path, and the files it imports load into every context, since an
+  imported file carries no `paths:` of its own (read in the program text, and seen on a fixture). So
+  `compile` spells each import again from the rule it compiles to, and refuses one that is a home or an
+  absolute path, leaves or links out of the tree it compiles, names no file, shares its line, or sits five
+  imports down; in a unit of any other tier it refuses an import naming a file, which would not load as
+  its unit does. `context.mjs` counts an imported file in the always tier at the depth the host loads it,
+  a path-scoped rule's included. The vendored `AGENTS.md` carries each import as a pointer line to the
+  file in the vendored tree, and one for each file that file imports in turn, to the depth the host would
+  load (2026-09-24), and `vendor` refuses an import leaving the workspace, which is all that tree holds.
+- **A line `<!-- leads: <path> -->`, alone on its line, is replaced by the first sentence of each item in
+  the first list of the file it names**, each item opening with a bold lead. The file stays the one
+  source of those sentences, so a change there is drift until the unit is recompiled. `compile` refuses
+  a file with no list, an item with no bold lead, a lead carrying a link, which would not resolve from
+  the compiled rule, and a line of text with no indent straight under an item, which CommonMark reads as
+  more of that item (2026-09-24). **The path may end `#<heading>`**, for the first list under that
+  heading, found as `cli/symbols.mjs` finds a section: by the anchor GitHub gives it, which its outline
+  prints, or by its text or a `Parent>Child` path where either holds no space, since the line's path holds
+  none; a heading that none or several answer is refused (2026-09-24).
+- **A line `<!-- engine: <path> -->`, alone on its line, writes out the leads of a file in the engine
+  `compile` ships with**, its path relative to that engine's `core/`, and refused outside it or naming no
+  file, with a `#<heading>` read as above (2026-09-24, within 2.10). Portulan's own card and each
+  consumer's name the same file, so they carry one text, and an upgrade of Portulan that changes it is
+  drift until the card is recompiled. `<plugin root>/` in a lead is the directory the plugin is installed
+  in, and is written as nothing where that engine is the tree compiled, as in Portulan's own repository.
+- **A line `<!-- gates: <path> -->`, alone on its line, is replaced by the gate ids of the policy it
+  names, one line per tier** in core's order, each id as the policy spells it and in its order there, a
+  tier holding none saying so, and a line naming the packs the manifest composes, whose gates only a
+  compile resolving them can list (2026-09-24). The policy is read by the reader every compiled gate goes
+  through, so `compile` refuses here what it refuses there, and an edit to the policy is drift until the
+  unit is recompiled. `init` and `upgrade` draft a consumer's card with one.
+
+**Nothing is defaulted.** A workspace that declares no slot compiles no guidance, and no directory in an
+adopter's workspace is chosen by a key nobody typed.
+
 ## `provenance` — a record field, not a manifest key
 
 The criterion lists a provenance slot beside the others, but it does not belong in the manifest, and