@sleepy_panda_srl/portulan 0.1.2 → 0.2.0

package/cli/version-carriers.mjs

@@ -1,50 +1,5 @@
 #!/usr/bin/env node
-// Portulan — every prose statement of the CURRENT version agrees with `package.json`.
-//
-// ## The defect this exists for
-//
-// `README.md` and `.portulan/products/portulan/product.md` both said the newest release entry was
-// `0.2.0` while `package.json`, both plugin manifests and the registry said `0.1.0`. They were fixed
-// together — and then, one release later, the SAME PAIR drifted again: `README.md` still read
-// "Current release: `0.1.0`" inside the change that cut `0.1.1`. Twice, with the pairing already
-// written down in `docs/plan.md` both times.
-//
-// **A sibling list in prose is not a rail.** This is the rail.
-//
-// It matters more than a tidy number because `README.md` is in `package.json`'s `files`, and npm
-// FREEZES a README per published version: a wrong current-version sentence that reaches a publish
-// cannot be corrected by any edit to `main`, only by cutting another release. That is exactly what
-// `0.1.1` was for.
-//
-// ## Why the record layer is excluded, which is the whole design
-//
-// This repository writes about its own defects, so the retired sentences are QUOTED in the files that
-// record fixing them: `CHANGELOG.md` carries *"The newest release entry is `0.2.0`"* inside the entry
-// explaining that it was retired, and two handoffs plus `docs/plan.md` do the same. A matcher over
-// everything reds on the repository's own account of the repair — the failure mode #286 measured,
-// where both arms it proposed died on this repository's own review corpus.
-//
-// So the scan is scoped to LIVE prose and the record layer is excluded BY PATH. The exclusion is not
-// a convenience: a dated record is supposed to preserve a sentence that is no longer true, and a rail
-// that forbids that would forbid the record.
-//
-// ## What it cannot do, stated rather than discovered
-//
-// A current-version claim spelled a NEW way, in any file, is invisible to it. There is no way to tell
-// "this prose asserts the current version" from "this prose mentions a version" without a matcher, and
-// a matcher only knows the spellings it was given. The accepted practice for that residual is #286's,
-// ruled by the maintainer: **a new spelling gets a pattern here and a fixture first.**
-//
-// The half that IS closed beyond drift: every file in MUST_CARRY has to produce at least one match, so
-// deleting or rewording a known carrier reds instead of silently shrinking the rail's reach.
-//
-// Three further residuals, named because an unstated limit is the one a reader assumes away:
-//   · A live claim placed UNDER an excluded prefix is invisible. `.portulan/memory/` in particular
-//     holds doctrine-shaped notes rather than only dated records, so a current-version sentence
-//     written there would not be checked.
-//   · An UNTRACKED carrier is invisible: enumeration is `git ls-files`, deliberately, because a rail
-//     that reads the working tree grades files no commit will ever contain.
-//   · A NON-MARKDOWN carrier is invisible: the pathspec is `*.md`.
+// Every prose statement of the current version agrees with `package.json`.
 //
 // Exit 0 green · 1 a finding · 2 could not run.
 
@@ -53,23 +8,22 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { execFileSync } from "node:child_process";
 
-/** Raised when a precondition fails. Always exit 2 — never a finding about the prose. */
 export class CouldNotRun extends Error {}
 
-// The spellings that assert a current version. Each must capture the version in group 1.
+// Each captures the version in group 1; a claim spelled any other way goes unseen until it gets a pattern here.
 export const PATTERNS = [
     { id: "current-release", re: /\*\*Current release:\s*`([^`]+)`\*\*/g },
     { id: "newest-entry", re: /newest release entry is\s*`([^`]+)`/g },
     { id: "supported-current", re: /\|\s*`([^`]+)`\s*\|\s*Yes\s*—\s*the current release\s*\|/g },
 ];
 
-// Files that MUST carry at least one claim. Losing one is a finding: it means a carrier was deleted
-// or reworded, which is how this rail would otherwise quietly stop covering what it was built for.
 export const MUST_CARRY = ["README.md", "SECURITY.md", ".portulan/products/portulan/product.md"];
 
 // The record layer. These files preserve sentences that are no longer true, on purpose.
 export const RECORD_PREFIXES = [
     "CHANGELOG.md",
+    "changes/",
+    "evals/releases/",
     "docs/plan.md",
     "docs/milestones/",
     ".portulan/handoffs/",
@@ -80,7 +34,6 @@ export const RECORD_PREFIXES = [
 
 export const isRecord = (p) => RECORD_PREFIXES.some((r) => (r.endsWith("/") ? p.startsWith(r) : p === r));
 
-/** Every tracked Markdown file that is not part of the record layer. Derived, never a written list. */
 export function liveProseFiles(root) {
     let out;
     try {
@@ -96,11 +49,7 @@ export function liveProseFiles(root) {
 export function declaredVersion(root) {
     let raw;
     try {
-        // From the INDEX, like the prose it is compared against. Reading the version from the
-        // worktree while reading carriers from the index compares two different trees: a staged
-        // version bump with an unchanged worktree would grade staged prose against the OLD version,
-        // reporting drift that is not there — or, reversed, greening drift that is. Half a fix is
-        // how this rail's own index change first shipped.
+        // From the index, like the prose: a version read from the worktree would grade staged prose against another tree.
         raw = execFileSync("git", ["-C", root, "show", ":package.json"], { encoding: "utf8" });
     } catch (e) {
         throw new CouldNotRun(`could not read package.json from the index: ${e.message}`);
@@ -115,7 +64,6 @@ export function declaredVersion(root) {
     return v;
 }
 
-/** Every current-version claim in one file's text, with the line it sits on. */
 export function claimsIn(text) {
     const found = [];
     for (const { id, re } of PATTERNS) {
@@ -139,15 +87,10 @@ export function inspect(root) {
     for (const rel of files) {
         let text;
         try {
-            // The INDEX, not the working tree — `pack-identity` reads the same way and for the same
-            // reason. Enumerating from the index and then reading the worktree lets a staged drift
-            // with a reverted worktree copy report green while the commit ships the drift.
+            // The index, not the worktree: a reverted worktree copy would hide a staged drift the commit ships.
             text = execFileSync("git", ["-C", root, "show", `:${rel}`], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
         } catch (e) {
-            // NOT `continue`. `git ls-files` just named this path, so failing to read its blob means
-            // the rail could not examine live prose it is responsible for — and skipping it would
-            // report GREEN over a file never looked at. That is this session's defect class exactly,
-            // and it was sitting inside the rail built against it. Could-not-run, never a green.
+            // Not `continue`: skipping a file git just listed would report green over prose never read.
             throw new CouldNotRun(`could not read ${rel} from the index: ${e.message}`);
         }
         for (const c of claimsIn(text)) {
@@ -187,12 +130,7 @@ export function main(argv, stdout = process.stdout, stderr = process.stderr) {
     return 0;
 }
 
-// The entry guard, in the ONE form `cli/rule-carriers.mjs` designates after this repository got it
-// wrong twice. `file://${argv[1]}` is NOT that form: `import.meta.url` percent-encodes, this working
-// copy lives under a path with spaces, and the comparison failed — so the tool exited 0 having run
-// nothing. **A green that is the tool never starting**, shipped inside the rail built against exactly
-// that. The realpath fallback covers the symlink case an npm `bin` produces, in a `try` because a
-// missing path must answer no rather than throw.
+// URLs on both sides, since `import.meta.url` percent-encodes; the realpath covers a symlinked npm `bin`.
 function isMain() {
     const invoked = process.argv[1];
     if (!invoked) return false;
@@ -204,8 +142,5 @@ function isMain() {
     }
 }
 
-// `process.exitCode` rather than `process.exit`, which `cli/control-chars.mjs:540` settled for this
-// repository: exiting outright can truncate a pipe that has not drained. It matters more here than
-// stylistically — a truncated `ok` line IS exit 0 with no output, which is the precise shape of the
-// false green this file's entry guard was fixed for. The same defect, one door along.
+// `exitCode`, not `exit()`, so a pipe that has not drained is not cut short.
 if (isMain()) process.exitCode = main(process.argv.slice(2));

package/core/README.md

@@ -13,7 +13,7 @@ loads on demand.
 | Path | What lives here |
 |---|---|
 | [`engine.md`](engine.md) | The kernel: cascade, loop, non-negotiable gates, and the map. Always loaded. |
-| [`operating/`](operating/) | The doctrine, one concern per file: loop · autonomy · verification · memory · evolution · safety. |
+| [`operating/`](operating/) | The doctrine, one concern per file: loop · autonomy · verification · memory · evolution · safety · context · sessions. |
 | [`templates/`](templates/) | The artifacts the doctrine references: repo-card · task · handoff · proposal · memory-entry. |
 | [`personas/`](personas/) | Roles an agent takes, as context firewalls — each with a `tools:` allow-list. |
 | [`skills/`](skills/) | Progressive-disclosure procedures in `SKILL.md` form. |

package/core/engine.md

@@ -1,12 +1,7 @@
 # Portulan engine
 
 > The always-loaded kernel: the invariants every agent carries, and the map to the doctrine behind
-> them. Kept small on purpose — everything here is load-bearing; everything else loads on demand. This
-> file is the core's source contribution to the always-loaded layer; `portulan vendor --host` inlines it
-> verbatim into a vendored `AGENTS.md` beside the workspace's own layer, for a host that cannot install
-> the plugin. The **pack** layer is named in that file rather than composed into it — a pack resolves
-> from a feed at a pinned version and **vendoring resolves nothing**, which is unchanged. Pack-cache
-> discovery landed at milestone 7: the CLI reads the host's record, a vendored file cannot.
+> them. Kept small on purpose — everything here is load-bearing; everything else loads on demand.
 
 ## Resolution cascade
 
@@ -38,10 +33,9 @@ scale down. → `operating/loop.md`
 
 ## The map
 
-- `operating/` — the doctrine: loop · autonomy · verification · memory · evolution · safety.
+- `operating/` — the doctrine: loop · autonomy · verification · memory · evolution · safety · context · sessions.
 - `templates/` — the artifacts: repo-card · task · handoff · proposal · memory-entry.
 - `personas/` — roles as context firewalls, each with a `tools:` allow-list.
 - `skills/` — progressive-disclosure procedures; a skill must enforce, measure, or earn its tokens.
 
-Every rule here carries its rationale and provenance in the doc it links to. Nothing in this kernel is
-prose for its own sake: when a line stops being load-bearing, it moves out of the kernel.
+Every rule here carries its rationale and provenance in the doc it links to.

package/core/operating/autonomy.md

@@ -54,7 +54,7 @@ else safe.)_
 by changing the rule itself through the evolution gate — never by runtime approval.
 
 That distinction is the whole reason the fourth tier exists rather than being folded into Gated, and it
-is not academic: a compiler with three tiers must file *"no agent edits the constitution"* under Gated,
+is not academic: a compiler with three tiers must file *"no session certifies its own checkpoint"* under Gated,
 and Gated compiles to a prompt. *Never* would become *unless somebody clicks yes* — a difference no
 reader of the gate map would see, produced entirely by the vocabulary being one word short. _(Found by
 building the compiler: milestone 4 needed a fourth class before it had a schema, and the workspace layer

package/core/operating/context.md

@@ -0,0 +1,183 @@
+# Context
+
+> Core doctrine — loaded on demand, which on this page's own terms is the on-read tier. What a host
+> loads into every context is paid for again by every fresh context: each session, subagent, checkpoint
+> and persona. So guidance sits in load tiers, the always tier is budgeted like memory, and a demotion
+> is measured before and after. `loop.md` manages the window while a task runs; this page governs what
+> the host loads into it, and when. _(Proposal
+> [`0036`](../../.portulan/proposals/0036-what-a-host-loads-into-every-context-is-budgeted.md).)_
+
+## Four load tiers
+
+**Every piece of guidance sits in a load tier, and belongs in the latest tier that still reaches the
+agent in time.** There are four:
+
+- **Always**: loaded into every context, which covers project instruction files and their imports,
+  unscoped rules, and skill and agent descriptions.
+- **On-path**: loaded when the agent first touches a matching path, which covers nested instruction files
+  and path-scoped rules.
+- **On-invoke**: loaded when a skill, persona or ritual runs.
+- **On-read**: loaded when the agent opens the file.
+
+The always tier is paid for by every context, whether or not its task needs what the tier holds; a later
+tier is paid for only by the contexts that reach it. *In time* is the limit: guidance that arrives after
+the moment it applies has not reached the agent.
+
+A workspace sets its own guidance in these tiers in `slots.context`, since Workspace Definition 2.10: one
+unit per file, each declaring its tier, and `compile` emits each unit in its host's form of that tier.
+_(See [`../../spec/slots.md`](../../spec/slots.md).)_
+
+## One level of index
+
+**One level of index only**: an always-tier line may point at content, and a pointer may not point at
+another pointer. A **pointer** is a line the agent reads to decide whether to open something; a file a
+procedure always reads is content loaded in that procedure's tier, not a pointer. So the kernel's map,
+whose lines point at directories of content, is one level, and so is the boot's path to a memory record:
+the boot always reads the memory index, and each index line is the one pointer to its record.
+
+_(Motivated, not established, by arXiv 2607.17598, *Is Progressive Disclosure All You Need for
+Long-Context Agents?* (He, Zhao, Wang and Chen, 2026), whose abstract finds that a second, deeper routing
+level never helps and sometimes breaks accuracy. It measured long-document question answering, not
+instruction files.)_
+
+## The always tier is budgeted in tokens
+
+**The budget is declared in the manifest and never defaulted**, as `context.always.budget.tokens`. A
+breach is repaired by **demotion** to a later tier, by **merge** or by **retirement**, and never by
+raising the budget in the change that breached it. The shape is memory's on purpose, its limit included:
+a budget is a rail, not an aim, and the no-raise half is a rule no checker establishes, for the reason
+[`memory.md`](memory.md) gives.
+
+**Bytes per token are declared too**, as `context.ratio`: measured exactly on demand, by asking the host
+for the true count, and recorded with the host whose exact count calibrated it. The exact measurement
+never runs inside a recipe, because no verify recipe may make a network call, and a ratio that moved
+between runs would make one tree red on one run and green on the next. The keys are argued in
+[`../../spec/slots.md`](../../spec/slots.md).
+
+**A report by default, a rail by declaration.** A workspace is failed only against a budget it declared.
+
+## Portulan budgets its own contribution
+
+**Portulan budgets its own contribution by default, because it owns it.** That is the kernel, the boot
+skill and the engine half of the boot read-set, skill and persona prompts, hook-injected text, and the
+vendored `AGENTS.md` skeleton. The default is a rail in this repository, not a budget in any adopter's
+manifest, so *never defaulted* holds. This is what lets every install benefit on upgrade without
+configuring anything.
+
+**The kernel, [`../engine.md`](../engine.md), is the core's source contribution to the always-loaded
+layer**; `portulan vendor --host` inlines it verbatim into a vendored `AGENTS.md` beside the workspace's
+own layer, for a host that cannot install the plugin. The **pack** layer is named in that file rather
+than composed into it — a pack resolves from a feed at a pinned version and **vendoring resolves
+nothing**, which is unchanged. Pack-cache discovery landed at milestone 7: the CLI reads the host's
+record, a vendored file cannot. Nothing in this kernel is prose for its own sake: when a line stops being
+load-bearing, it moves out of the kernel.
+
+## A fresh context is priced where it is created
+
+Whatever spawns one (a checkpoint, a persona, a ritual) states what it loads, and the compiled agent
+carries that. **Reviewers keep the conventions they grade against**: the remedy for an expensive always
+tier is a smaller always tier, never a blind reviewer.
+
+## No optimisation may lower context or code quality
+
+Prefer moving content to a later tier over deleting it, keep one source per fact, and measure before and
+after. **A demotion states both figures.**
+
+**What this does not ask for**: a defaulted workspace rail, lossy compression, a codebase vector index,
+switching model or effort mid-session, output-shortening tricks, or any change to a host. Portulan
+compiles to what hosts load and does not change how they load it.
+
+## Every request pays for what the session has read
+
+Each tool call ends a request, and the next request sends the whole context again: the host's own prefix,
+the always tier, and everything read and printed so far. The prompt cache makes the repeat cheaper, not
+free. In Claude Code 2.1.281 the main conversation's cache lives an hour on a subscription within its
+usage limits and five minutes on an API key or a cloud provider, a subagent's five minutes unless set
+(its settings `promptCacheTtl` and `subagentPromptCacheTtl`, read in its program text on 2026-09-24).
+So what a session adds, it pays for on every request after, and a task done in fewer requests re-sends
+less. `compile` writes the lead of each rule below onto every boot card, Portulan's and each consumer's:
+
+- **Send independent tool calls in one request.** Reads, searches and commands whose inputs do not wait
+  on each other's output cost one request together and one each apart, and each request re-sends the
+  context.
+- **Read a file once; reuse what your context holds.** A second read of an unchanged file adds a second
+  copy, paid for on every later request. After an Edit, do not read the file back to check it: the host
+  refuses an edit it cannot apply, and says so.
+- **Open a file only when the task needs it, and one of 300 lines or more only where it does:
+  `node <plugin root>/cli/symbols.mjs <file>` outlines it, and `<file>#<heading>` prints one section.**
+  The outline gives each part's lines, and a Markdown heading's anchor and size; it costs a line a part
+  where a doctrine page or an instruction file runs to thousands of tokens and a task needs one section.
+  A link to a heading names its section, so `<file>#<anchor>` reads what the link points at without an
+  outline. A shorter file the task changes is read whole, as below. Read a section you will edit with the
+  Read tool's `offset` and `limit`, which an Edit may follow. `<plugin root>` is where Portulan is
+  installed, the directory whose `core/engine.md` the boot reads; in Portulan's own repository it is the
+  repository, and `compile` writes the command as run from there.
+- **Ask for only the output you need: a range, a count, the failures.** Output enters the context as a
+  read does. A passing run needs its summary and a failing one the failing check and the fact to act on,
+  as [`loop.md`](loop.md)'s compacted error does; `git diff --stat`, `grep -c` and a line range ask for
+  less than a whole log, file or tree.
+- **The prompt cache lasts five minutes or an hour: a longer pause, or a fresh subagent where one could
+  be resumed, writes the whole context again.** A subagent's context is its own and starts with the
+  host's prefix, so start one only where the reads it keeps out of this context cost more than that
+  prefix, and resume one rather than start another; [`sessions.md`](sessions.md) holds both, and the
+  lifetime a workspace declares. The cost table in the same program text prices a cache write above
+  sending the tokens fresh and a cache read below it.
+- **Code should speak for itself: a comment is paid for on every read of its file, so add one only when
+  truly needed, concise, meaningful and valuable (less is more), and keep a change's history in its
+  commit message.** Claude Code 2.1.281's system prompt tells a model to match the surrounding code's
+  comment density, so what a file carries, the next change copies. Truly needed is what no name or
+  structure can show, in a line: a host's behaviour at its version, an ordering or a safety constraint the
+  code does not make obvious, a limit of the algorithm. A comment never carries a date, a proposal or
+  milestone number, a review round or a reviewer's credit, a pull request or issue number, or a narration
+  of what the code does; where the code needs one to be understood, rename or extract instead.
+  `node <plugin root>/cli/comments.mjs` counts the comment lines that record a change's history, in code
+  and in a Markdown file's HTML comments other than the lines a tool reads, and a workspace's `comments`
+  recipe holds that count at a limit that only falls.
+
+## Code is read by symbol
+
+A session outlines a code file of 300 lines or more before it opens it, then reads the spans it needs: in
+Claude Code, the Read tool with `offset` at a span's first line and `limit` its length. **A file under 300
+lines that the task changes is read whole**, since most of it is context for the change and the saving is
+smallest there, and so is any file whose outline cannot say where a change goes. A span read the host does
+not cut is a full read of those lines, so an Edit may follow it: in Claude Code 2.1.281 a Read is marked
+partial, and an Edit or a Write after it refused, only when the Read's token cap, 25,000 by default, cut it
+(read in its program text on 2026-09-24). [`cli/symbols.mjs`](../../cli/symbols.mjs) prints the outline,
+one line per symbol, and `--find <name>` locates a definition; it outlines Markdown by its headings, with
+each section's anchor and size, the same way. It prints from the file as it is, so no map is committed to
+go stale. Nothing checks that a session outlined first; what the rule saves is measured by rerunning a
+task, never by a recipe, which may not read the host's usage records.
+
+## What is machinery today, and what is not
+
+As of Workspace Definition 2.9 a workspace can declare the budget and the ratio, and both are checked
+for shape, by the schema and by `doctor`; the manifest key refuses a budget with no ratio to count it by.
+**The always tier is measured and reported.** [`cli/context.mjs`](../../cli/context.mjs) measures what
+Claude Code loads into every context from a workspace's `tree`; `doctor` reports that for every workspace
+and fails it only over a declared budget or where a declared budget cannot be judged; the boot closes
+with the same line; and this repository's `context` recipe rails Portulan's own footprint. **A boot can
+read a card instead of the slots**: the `boot` unit of `slots.context` (Workspace Definition 2.10) is
+compiled into every context, imports whole the files it needs, writes out the lead sentences of others,
+and names the file behind each line, so the rest loads when a rule's path or the card sends a session to
+it. **A team's own instruction file can be split the same way, section by section**: a line
+`<!-- portulan: on-read -->` under a heading of `CLAUDE.md` or `.claude/CLAUDE.md` is the team's word that
+the section may leave every context, and `portulan upgrade` moves it, byte for byte and proved to
+reassemble, into an on-read unit whose index line names the heading and its size in whole KB. `doctor`, the
+boot and `init` offer it where the file is over `0036`'s 8,000-token offer floor, and `doctor` and the boot
+wherever a declared budget is breached, naming there the command that splits while `upgrade` will not run;
+a section is never moved for its size alone. Claude Code 2.1.281 drops a comment standing on its own lines
+before it loads an instruction file or rule (read in its program text on 2026-09-24), so the mark and the
+marker left behind cost nothing. This repository's own card holds its boot under the 7,500-token line of
+2026-09-23, railed at today's figure plus 2% by the same recipe. A pointer's repository is not measured,
+because a pointer declares no tree. **Still to land**: the exact mode that
+calibrates a ratio, the degradation report that says which tiers a host can express, the Stop-gate's
+named demotion, persona frontmatter and the librarian pass, one change at a time, in `0036`'s order of work
+and under row 12 of [`../../docs/plan.md`](../../docs/plan.md).
+Until each lands, the rule it would enforce is held by the human gate, and saying so is the point: a rule
+nothing checks, presented as one that something does, is the failure this page exists to prevent.
+
+_(Provenance: proposal `0036`'s sealed incident, in which an adopting repository's always-loaded
+instruction files measured 130k tokens per fresh context, cache writes were most of the spend, and every
+subagent and checkpoint paid it again, because nothing measured, budgeted or demoted what the host
+loads. Host facts from the Claude Code documentation on costs, prompt caching and memory, checked
+2026-09-21.)_

package/core/operating/evolution.md

@@ -67,9 +67,9 @@ rather than a story about this repository. **Work is agent-drafted and fresh-con
 moments**: the plan before building starts, the diff before it goes outward, and the exit criteria at
 the close — where done is *demonstrated, not asserted* (`verification.md`). Two conditions hold the
 cycle up and neither is optional. The unit of work carries **hard exit criteria** fixed before it
-begins, so the close has a standard to grade rather than an impression. And **every session ends by
-writing the record** (`loop.md`), so the context arriving at the next moment inherits the reasoning
-instead of re-deriving it — a graded moment whose grader must first reconstruct what was decided is
+begins, so the close has a standard to grade rather than an impression. And **every change writes its
+record** (`loop.md`), its why in the commit and any open work in a handoff, so the context arriving at
+the next moment inherits the reasoning instead of re-deriving it — a graded moment whose grader must first reconstruct what was decided is
 grading its own reconstruction.
 
 The altitudes stay separate, and the separation is the part that travels. Core states that the three

package/core/operating/loop.md

@@ -26,26 +26,19 @@ The loop runs inside a finite attention window, so context is managed, not hoard
   next action — and drop the transcript. The loop is a stateless reducer over that state, so it resumes
   from the compaction without losing the thread. _(Provenance: HumanLayer ACE-FCA — the loop and
   compaction; 12-Factor Agents — stateless-reducer resumability.)_
-- **Handoffs record decisions and their why**, not just what changed, so the next agent — or the next
-  window — inherits the reasoning. **Every session ends with a dated handoff** — a *session* being one
-  bounded working stretch, however the host names it, from the moment work opens to the moment it closes.
-  Short is fine, absent is not, and an exception is a last resort. The rule is binary on purpose: a
-  discretionary one cannot be enforced, because no gate can judge whether skipping was warranted, and the
-  costs are asymmetric — an unnecessary handoff costs five lines, a skipped one loses the reasoning
-  permanently. Ceremony scales down *inside* the artifact, never by omitting it, so a gate on this checks
-  that one exists and is dated — never its structure or its length. **Dated** means the filename leads
-  with an ISO date: `YYYY-MM-DD-{slug}.md`. Naming the form matters, because a rule justified by being
-  checkable has to say what the checker looks at; a date buried in prose would need parsing and would be
-  read differently by every writer. It also makes the series sort chronologically for free. An unbroken
-  series is what makes the record machine-readable: the session-end gate arrived in milestone 4 — it
-  checks that a handoff dated today exists, never its length or its shape — and milestone 5 built the
-  librarian that **reads** the series, in three ways that only an unbroken one allows. It generates an
-  index over it, every field derived. It ages it from git. And it mines it: an incident nothing in the
-  curated layer points back at is a candidate for the `codify` skill, because a rule whose incident
-  cannot be traced can never be retired on evidence. The pass also **writes** to the series — a
-  scheduled pass is a session, so it ends with a dated handoff like any other — which is why nothing
-  regenerates that index until the pass's own record is on disk. _(Provenance: Cognition. See
-  `../templates/handoff.md`.)_
+- **A change's why goes in its commit; a handoff carries only the work still open.** A commit's subject
+  says what changed and its body says why, in a few lines: the reasoning the next agent cannot
+  reconstruct from the diff, kept beside the diff. A session (one bounded working stretch, however the
+  host names it) that ends with work not committed and pushed ends with a dated handoff: where things
+  stand, the open questions and the single next action, and nothing the diff or a commit already says.
+  **Dated** means the filename leads with an ISO date, `YYYY-MM-DD-{slug}.md`, because a rule justified by
+  being checkable has to say what the checker looks at, and the series then sorts chronologically for
+  free. The session-end gate (milestone 4) checks exactly that: while the tree holds uncommitted or
+  unpushed work, a handoff dated today exists, never its length or its shape. The librarian (milestone 5)
+  reads the series: it indexes it, ages it from git, and mines it, since an incident nothing in the
+  curated layer points back at is a candidate for the `codify` skill.
+  _(Provenance: Cognition — handoffs record decisions and their rationale; Git's own SubmittingPatches —
+  a commit's body explains the problem and justifies the change. See `../templates/handoff.md`.)_
 - **Subagents are context firewalls.** Fan work out to a persona with its own window and return only
   the conclusion; the parent's budget stays clean. Read in parallel, write from one place. _(See
   `../personas/`. Provenance: HumanLayer; Cognition — read-parallel / write-isolated.)_

package/core/operating/memory.md

@@ -46,6 +46,15 @@ which is worse than no check at all. So the breach is a rail and the *remedy* is
 gate holds. Written down rather than implied, because a rule nothing checks that is presented as one
 that does is the failure this page would otherwise be demonstrating.
 
+**The cap can bind forward only** (Workspace Definition 2.11): with `memory.store.budget.cutoff`
+declared beside it, it binds the records dated after the cutoff, and one dated on or before it is
+reported, never railed, in proposal `0037`'s shape for a handoff. 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 it, so
+an old record meets the cap in the change that next rewrites it, while compression is that change's
+to do. A record whose date cannot be read is refused. The cutoff never moves earlier, and moves later
+only with a cap that tightens: like the raise above, a rule the human gate holds, because a moved
+cutoff unbinds what the cap bound and only history shows the move.
+
 ## One fact per memory, with provenance
 
 A memory holds one fact and states where it came from. A rule links to the **incident** that created
@@ -62,8 +71,8 @@ curated context improves it, and the difference is measurable. So capture is age
 consolidation into the curated layer is a reviewed step. _(Provenance: ETH Zurich, arXiv:2602.11988 —
 generated context hurts, curated helps. The scheduled librarian arrived in milestone 5: a pass that
 regenerates each generated index, ages every record from git, nags a sealed stamp's owner, chases
-undecided proposals, drafts demotions, and **runs consolidation** — filed as a pull request nobody has
-to remember to open. What consolidation means on a schedule is bounded rather than claimed: the pass
+undecided proposals, drafts demotions, and **runs consolidation** — its report filed with a pull request
+nobody has to remember to open whenever the pass changed the tree. What consolidation means on a schedule is bounded rather than claimed: the pass
 reports how close each budget is to its rail, and surfaces records citing one incident as a
 **question**, because `../skills/consolidate/SKILL.md` merges records that are one *mechanism* and one
 incident routinely teaches several. Its steps 3 and 4 — surfacing contradictions and compressing what
@@ -145,7 +154,7 @@ where a reader already knows to look is stated at the narrowest carrier.
 was put to him twice and answered two different ways. The record of both, and of the third option that
 reconciles them, is
 [#98](https://github.com/sleepy-panda-srl/portulan/issues/98) and
-[`docs/milestones/m06.md`](../../docs/milestones/m06.md). Neither row needed a criterion edit to carry
+[`docs/milestones/m06.md`](https://github.com/sleepy-panda-srl/portulan/blob/8a33f9b/docs/milestones/m06.md). Neither row needed a criterion edit to carry
 this: both already demanded their half. Said plainly because the
 alternative is a page describing an enforcement that does not exist — the failure a workspace's
 definition of done exists to catch (`.portulan/dod.md` condition 4, in this repository): a document may

package/core/operating/sessions.md

@@ -0,0 +1,100 @@
+# Sessions
+
+> Core doctrine — on-read. Every fresh context pays for the host's own system prompt and tools, and for
+> the always tier, at the cache's write price, unless an earlier session left that prefix in the cache.
+> On Claude Code that prefix comes before any workspace file, and cache writes were most of what a task
+> cost on this repository ([`../../evals/ab/warm.md`](../../evals/ab/warm.md) has the figures). So a task
+> runs in as few fresh contexts as it can, each starts warm where it can, the cache lifetime fits the gap
+> between uses, and a host switch that changes the prefix is earned by an A/B run.
+> [`context.md`](context.md) governs what the host loads; this page governs how sessions start and end
+> around it. _(Proposal [`0038`](../../.portulan/proposals/0038-what-a-change-spends-is-measured.md), rules
+> 2 to 4, and row 12 of [`../../docs/plan.md`](../../docs/plan.md), whose compile targets carry the cache
+> lifetime.)_
+
+## A session starts warm, or it pays the prefix again
+
+**A fresh session starts warm when an earlier one left the same prefix in the cache**: the same host
+version, tools, model and effort, the same instruction files and rules, the same working directory, and
+nothing that varies per session ahead of the task, within the cache lifetime. A warm start reads the
+prefix at the read price; a cold one writes it again. Sessions running side by side in one checkout
+already share it. Sessions that follow one another share it only while nothing between them changed it,
+and on a local checkout the host's startup git snapshot changes with every commit.
+
+What moves the break earlier is anything per session in front of the task: a git snapshot, a date, a
+working directory made fresh for each run, a hook's per-session output, a session's own id. Rule 3 of
+`0038` keeps these out of Portulan's own always tier and hook text. A hosted session whose system prompt
+names the session itself starts cold whatever a workspace compiles; that is inferred from such a prompt,
+not documented.
+
+## Fewer fresh contexts per task
+
+- **Continue until the restart threshold, then restart.** `0038`'s threshold is computed from the multipliers,
+  the fresh context and a horizon, which a workspace declares in `spend` (Workspace Definition 2.12) and which
+  are the general ones where it does not, and [`../../cli/advisory.mjs`](../../cli/advisory.mjs) says it once.
+  A restart that finds its prefix still cached costs less than the threshold assumes.
+- **Resume a finished worker within its cache lifetime** rather than start a new one: its context is
+  read again rather than written again.
+- **A subagent is a fresh context**, on a five-minute cache unless set. Fan out when the reads it keeps
+  out of the parent cost more than the prefix it writes ([`loop.md`](loop.md)'s firewall), not for one
+  read.
+- A checkpoint, persona or ritual states what it loads ([`context.md`](context.md)), and the host's
+  prefix is part of that price.
+
+## The cache lifetime fits the gap
+
+**Five minutes where the next use of the prefix comes within five minutes**: bursts, and headless runs that
+follow one another. **An hour where sessions idle or the next one starts later.** A five-minute write costs
+1.25 times an uncached input token and an hour's 2, and every read renews either; a gap past the lifetime
+writes the whole context again. On this repository's own tasks, run straight through, five-minute writes cut a
+boot's cost by 22 to 30% and an edit's by about 18% against an hour's
+([`../../evals/ab/warm.md`](../../evals/ab/warm.md), row 2 and the measurement beside it); in a long session,
+one pause past five minutes, while a person reads or a review or CI runs, can cost more than every write the
+shorter lifetime saved. A subagent's lifetime is set apart from the session's.
+
+## A switch that changes the prefix is earned
+
+Claude Code has three switches that change what a session writes: the git instructions (the startup
+snapshot together with the commit and pull-request instructions), the cache lifetime, and, for a run
+started headless, moving the per-machine sections (working directory, platform, memory paths, the
+snapshot) out of the system prompt and into the first message, so runs in different directories or on
+different machines share the system prompt. **Each stays off until an A/B run shows it cuts spend with no
+loss**, which is `0038` rule 4's gate applied to sessions, and **a session that needs what a switch
+removes keeps it**:
+
+- **The git instructions are dropped only for sessions that neither commit nor open a pull request**, or
+  where the workspace's own guidance carries its commit and pull-request workflow. A session that needs
+  them is started with `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=0`, which outranks the compiled setting, and
+  a runner sets that per run.
+- **The per-machine sections are moved, never dropped**: the exclusion puts them in the first message. It
+  applies to headless runs only, because only whatever starts a session can ask for it.
+- **The cache lifetime removes nothing.** It trades the write price against the gap.
+
+## What a workspace declares
+
+**`sessions` in the manifest**, since Workspace Definition 2.11
+([`../../spec/slots.md`](../../spec/slots.md)): `git_instructions` and `cache_lifetime` compile into the
+host's project settings and reach every session in the repository; `headless` is what Portulan's own runners
+apply to the sessions they start. Nothing is defaulted: an undeclared switch is the host's own default. This
+repository declares one switch, five-minute writes for its headless runs, which row 2 of
+[`../../evals/ab/warm.md`](../../evals/ab/warm.md) earned. Its interactive sessions keep the host's default,
+because they commit and idle on reviews and CI; the git instructions wait on that page's row 3, and the
+per-machine sections on its row 4.
+
+## What is machinery today, and what is not
+
+`compile` emits the two interactive keys and says so on every run, and writes `spend`'s figures onto the
+restart advisory's commands; `doctor` checks the shape and version of `sessions` and `spend`, and reports
+every switch's state in one line; `init` offers an adopter's repository the five-minute lifetime with its
+reason and its trade-off, and writes the key on a yes for `compile` to carry, and `upgrade` prints the same
+offer and writes nothing. [`../../cli/warm.mjs`](../../cli/warm.mjs) runs fresh headless sessions in sequence
+and prices each from the host's own usage records, warm against cold, and
+[`../../evals/ab/warm.md`](../../evals/ab/warm.md) is its specification and its record. **Still to land**: the
+interactive A/B, which needs real local sessions and so runs on a maintainer's device; a report of how often
+sessions start warm, from the ledger's first request per context; an offer of the other switches, once their
+rows have run; and carrying the key through `vendor`. Until each lands, the rule it would enforce is held by
+the human gate.
+
+_(Provenance: the maintainer's five-run measurement of 2026-09-24, whose figures the record in
+[`../../evals/ab/warm.md`](../../evals/ab/warm.md) carries as its before, and the cache test of the same day,
+which ran its rows 1 and 2; the techniques survey before it, from Claude Code's documentation on prompt
+caching, settings and the CLI; and each switch read in Claude Code 2.1.281's program text on 2026-09-24.)_

package/core/personas/librarian.md

@@ -49,8 +49,8 @@ Re-expressed from public practice (Letta — consolidation; compounding engineer
 — curated beats generated). Invocable on demand, and **schedulable as of milestone 5**: `cli/librarian.mjs`
 runs reindex over both generated indexes, staleness (the sealed-stamp re-validation nag, and record age
 from git), proposal nagging, demotion drafts, **mining** and **consolidation**, and renders what it
-found as a record a workspace's scheduler files as a pull request — this persona is the contract it
-executes.
+found as a report, which a workspace's scheduler files with the pull request the pass opens when it
+changed the tree — this persona is the contract it executes.
 
 **Every subject in the charter above is now reached on a cadence, and one of them is reached less
 deeply than the charter describes — which is the distinction between this persona and that tool.** A

package/core/skills/consolidate/SKILL.md

@@ -18,8 +18,10 @@ description: Bring a memory store back under its budget by merging, compressing,
   decides which move applies**, and the finding names it: the index's `lines` (too many records —
   merge or retire; compressing removes no line and splitting adds one), the store's `kilobytes` (too
   much in total), or a record's `record_kilobytes` (one record too large — split, compress, or demote;
-  step 2 and step 4). A fourth red, the index's `columns`, is **not** this pass's work: one over-long
-  line is repaired by renaming the record, and nothing is consolidated.
+  step 2 and step 4), which binds only the records dated after a declared `cutoff`: one dated on or
+  before it is reported, never red, and meets the cap when its text next changes. A fourth red, the
+  index's `columns`, is **not** this pass's work: one over-long line is repaired by renaming the record,
+  and nothing is consolidated.
 - Two records say the same thing, or say opposite things.
 - A record's `Retire when:` condition has fired.
 - The librarian's scheduled pass runs.