@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

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

@@ -26,8 +26,9 @@ decision, proposed before it runs.
 
 ## When to use it
 
-- **A verify-gated file transform:** a mechanical refactor, a history-comment cleanup, or a unit test
-  added, where a verify command can prove the edit green or have it rolled back.
+- **A verify-gated file transform longer than one short parent Edit:** a mechanical refactor or a
+  history-comment cleanup across a file, or a unit test the parent would otherwise iterate red→green,
+  where a verify command can prove the edit green or have it rolled back.
 - **An explicitly selected candidate research digest:** reading a long file or log so only a short digest enters the parent context.
 - **An explicitly selected candidate librarian or handoff draft:** compressing a handoff under its byte cap, or drafting a `codify` or
   `consolidate` candidate for human review.
@@ -35,6 +36,29 @@ decision, proposed before it runs.
 Not for multi-file architectural planning, ambiguous requirements (`clarify`), or pre-merge verdicts
 (`reviewer`).
 
+## When it pays
+
+Each call is itself one parent request: the parent writes the instruction, waits and reads the receipt,
+and that request re-reads the whole context like any other. In 0038's `m_r × (F·T + g·T²/2)`, a call that
+replaces one parent Edit leaves `T` as it was and lowers `g` only by the output it saves, the difference
+between writing the instruction and writing the code. A miss, a call that keeps nothing or a kept edit the
+parent then touches up, adds a whole request. So:
+
+- **Keep an edit the parent can write in one short Edit in the parent.** Delegate only where one call
+  replaces more parent work than the request it costs.
+- **Whether a call pays turns on its miss rate and the context's size.** With `s` the output a kept call
+  saves, priced at 0038's five times input, and `c` a miss's re-read of the context `C` at the tenth of
+  input that `cli/ledger.mjs` takes for a cache read, a call pays only while its miss rate stays under
+  `s / (s + c)`, and under less once a miss's own output is counted. One run in
+  [#583](https://github.com/sleepy-panda-srl/portulan/issues/583) measured a 20% miss rate at a median `C`
+  of 236k. The output a kept call saved, derived from the parent's output on the edits it wrote itself, was
+  250–650 tokens and is overstated, since the parent kept its larger edits. That puts break-even at 5–12%,
+  a net loss, from one run, one local model and one parent model, and the verdict rests on the tenth: at
+  0038's fortieth, break-even is 17–35%.
+- **Where a call should pay is reasoning, not measurement:** a red→green loop the parent would otherwise
+  iterate, a batch of calls inside one tool request, and a long mechanical replacement the parent would
+  otherwise write out.
+
 ## The pass
 
 1. **Scope the input first.** Outline a file of 300 lines or more with

package/spec/README.md

@@ -228,15 +228,40 @@ number governing both would make a bump in either mean a change in the other:
 
 | Schema | Manifest key | Current | What it governs |
 |---|---|---|---|
-| [`workspace.schema.json`](workspace.schema.json) | `portulan.spec` | **2.13** | the Workspace Definition — the manifest at a workspace root |
-| [`pack.schema.json`](pack.schema.json) | `portulan.pack` | **1.0** | the Pack Definition — the manifest at a pack root. |
+| [`workspace.schema.json`](workspace.schema.json) | `portulan.spec` | **2.16** | the Workspace Definition — the manifest at a workspace root |
+| [`pack.schema.json`](pack.schema.json) | `portulan.pack` | **1.1** | the Pack Definition — the manifest at a pack root. |
 
 The rules below apply to each train independently. `portulan.spec` is `MAJOR.MINOR`, and the current
-Workspace Definition version is **2.13**. It did **not** move when the Pack Definition arrived, because
+Workspace Definition version is **2.16**. It did **not** move when the Pack Definition arrived, because
 `workspace.schema.json` was byte-identical across that change: `packs` already existed as an array of
 strings and was deliberately left that way, since tightening its items to the canonical `category/name`
 form would be a constraint an existing manifest could newly fail, which is a MAJOR.
 
+**2.16 adds optional `spend.resume.tokens`**, from [#503](https://github.com/sleepy-panda-srl/portulan/issues/503).
+It prices additional restart expense in uncached-input-token equivalents. Doctor
+checks its finite nonnegative bound by hand and gates it to 2.16; compile refuses
+older declarations before writing. Index and librarian recognize the new minor.
+Existing manifests need no change: unknown resume cost or a default horizon now
+permits a conditional report only, including for an existing `restart: "block"`.
+No estimate is installed automatically, and init gains no question.
+
+**2.15 adds optional handoff budgets**, accepted proposal 0037: a per-record token cap with a required
+cutoff, and a generated index window with a token budget. Existing manifests need no changes. Both
+budgets require an explicit context ratio; doctor checks their positive integer bounds and real cutoff,
+and direct index calls independently refuse malformed declarations. Doctor gates the keys to 2.15;
+index and librarian add that supported version. Init opts into 2.15 only when a budget is accepted;
+upgrade installs no cap or ratio unasked. This workspace defers its proposed 3000/3000 adoption until
+it has a measured ratio. The series remains unbudgeted and the Stop-gate checks no length.
+
+**2.14 adds optional `verify.stopTimeout`.** The workspace may declare the Stop
+recipe's deadline in whole seconds; absent, it remains ninety seconds. `doctor`,
+`compile` and the runner share its range and version check, and compile gives
+that hook sixty additional seconds. No existing declaration is tightened or
+rewritten. `KNOWN_SPECS` in index and librarian gains `2.14` by addition; writers
+retain the oldest version their actual fields require. The schema subset types
+this field as `number`; the shared reader checks the integer/range constraint.
+This adds one hand-check to 2.12's fifteen, without expanding the schema subset.
+
 **2.13 is a MINOR on 2.8's terms: optional keys only.** `spend.restart` is the last piece of item 5 of
 proposal `0038`'s order of work, the declared block its ruling 3 allows: `"advise"` is the restart advisory as
 it was, and `"block"` also holds a turn's end once, at the first stop at or past the threshold that no block
@@ -434,7 +459,7 @@ workspace with no constitution slot and a green report.
 | A declared pack **resolves** | `doctor` | **Built**. Roots are derived from `tree`, and named roots may be given with `--pack-root`, which **replace** the derived one rather than preceding it, so a from-a-feed demonstration cannot be satisfied by a copy in the local tree at all. A workspace with no `tree` and no named root has its packs reported *unverifiable* rather than failed. Resolution **from a feed is demonstrated**: the checkpoint ritual pack installed from the private `portulan-internal` marketplace and resolved from the install root, which is the same code path the derived one takes. **Discovery is built** ([#123](https://github.com/sleepy-panda-srl/portulan/issues/123)): `--pack-root auto` reads the host's installed-plugin record — in **both** shapes a plugin lands in, packs under `packs/` for a repository-shaped one and categories at the install root for a flat one, which is what this project's own feed ships. Asked-for discovery is **unioned** with the tree-derived root, discovered first, so a workspace composing a cache-installed pack *and* one of its own resolves both. The **named**-root property above is untouched: a named root still replaces the derived one, so a from-a-feed demonstration given one cannot be satisfied by a local copy. What the union trades is the weaker guarantee that `auto` *alone* implied provenance; it no longer does, and each pack's resolution states which root answered instead. Asking for a named root **and** `auto` together is refused (exit 2) rather than silently resolved to one of them. Discovery runs on the **unasked** path too, because `--pack-root` is *optional where discovery finds a root*. `auto` now selects the strict degrade (asked-and-could-not-look is exit 2) rather than unlocking discovery. Two things bound it, and neither makes a bare run host-independent — `doctor` is a per-host capability report and a bare verdict does move with the machine. First, every **required** check **names** its root, which replaces every other source, so it cannot consult the host at all. Second, `doctor`'s note-vs-fail keying is on a root's **origin**, so discovery can turn a note into a **resolution** and never a **miss** into a failure — a miss under a root the workspace or the caller claimed stays a FAIL whatever is installed. It softens nothing: a discovered copy that resolves and is *invalid* still fails, with its origin named. |
 | A pack manifest conforms to the Pack Definition | `doctor` | **Built**. Same validator, same subset, a different schema and version train. |
 | A pack's skills and personas are opened and validated | `doctor` | **Built**, on the maintainer's ruling that row 7's validation reads broad. A skill's frontmatter (`name` kebab-case, `description` non-empty — the two a host reads before loading a body); a persona against the five-part contract, **including the memory scope** `core/operating/memory.md` promised would be validated at this milestone; and the tier no role may claim. Containment is checked **after resolution**, because opening these paths is what made an escaping value stop being inert. Three honest limits, each measured rather than assumed. The skills walk stops **three levels down**, matching `cli/plugin-lint.mjs`'s bound so two walkers over the same key cannot disagree, and it **reports the directories it did not descend into** rather than counting a root it never opened as empty. The Prohibited check is a prose heuristic defeated by any negation **in the same block** — a bullet list counts as one block — and the structural fix is a declared reach *field*, a contract change that is not built. And the five-part check is **presence**, not content: a persona whose sections are all empty passes, so a declared memory scope is read and not honoured. |
-| A persona's declared context fields — `model`, `effort`, `omitClaudeMd`, `cacheLifetime` | `doctor` · `compile` | **Built** for a persona a composed pack ships, with no schema version moved, since no persona file is governed by either schema: the fields belong to the persona contract [`../core/personas/README.md`](../core/personas/README.md) fixes, and are optional. `doctor` fails a malformed value and `compile` refuses one; neither defaults any. `compile` writes the declared fields into the role's hand-written binding, `agents/<name>.md` in the tree, byte-compared under `--check`, and prints a degradation line for each field a host cannot express. Claude Code loads `agents/` only from a plugin root, so in a tree that is not one the compiled block is loaded by nothing, and that degradation line says so; in one that is, it loads only while the plugin is installed and enabled, which `compile` cannot see. **Not built**: writing `.claude/agents/`, where a repository that is not a plugin loads its agents; a binding where none exists, which is reported unbound; and the compiling of a core persona's binding. |
+| A persona's declared context fields — `model`, `effort`, `omitClaudeMd`, `cacheLifetime` | `doctor` · `compile` | **Built** for composed personas and the core personas in this engine's own declared tree, with no schema version change. The optional fields belong to [`../core/personas/README.md`](../core/personas/README.md); neither reader defaults them. Compiler and doctor select existing `agents/<name>.md` bindings for plugins and `.claude/agents/<name>.md` for ordinary projects. `--check` byte-compares declared fields, including in a persona-only project. Missing adopter bindings remain unbound and are not created; malformed/nonregular/escaping marker and binding inputs are refused. A degradation line names each field an AGENTS.md host cannot express. This establishes source-derived files and selected locations, not host enablement or runtime honoring of a key. |
 | Pack gate fragments merge **tighten-only** | [`../cli/compile.mjs`](../cli/compile.mjs) | **Built**. Two layers and two axes: `auto` is absent from the Pack Definition's tier enum, so a demotion to unattended is unexpressible; the comparison against the composed base is the compiler's, and both a weakened **tier** and a changed **action** throw rather than being dropped. The action half is the one a tier-only check misses — raising the tier while swapping the matcher removes the gate and still reads as a tightening. |
 | A pack declaring a version ahead of `doctor` | `doctor` | **Built**. Refused rather than graded, symmetric with the workspace train, and on the Pack Definition's own `$id`. |
 | Path slots resolve to real files | `doctor` | **Built.** File-versus-directory too; a slot resolving outside the workspace is reported, never failed. |
@@ -501,3 +526,11 @@ repositories are *not present* is what exposed that the claims lint had no way t
 
 Illustrative fragments in [`slots.md`](slots.md) use `{braces}` for placeholders, the same convention as
 [`../core/templates/`](../core/templates/).
+
+Pack Definition 1.1 adds optional ritual `contributes.contexts` with
+`max_concurrent_subagents`. Doctor and compiler require a positive safe integer
+and the 1.1 contract; the schema subset expresses only its numeric shape.
+Counts compose by minimum and compile to Claude project settings, with the
+[admission scope and exceptions](../packs/rituals/checkpoints/README.md#context-admission)
+stated separately from the ledger's actual lifetime count. Workspace Definition
+is unchanged; rituals remain packs, as recorded in [slots](slots.md).

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

@@ -1,13 +1,29 @@
 // A form step — each section a team marks in its own instruction file moves to an on-read unit.
 
 import { ESTIMATED_BYTES_PER_TOKEN, alwaysTier, declaredContext, tokensOf } from "../../cli/context.mjs";
+import { previewMigration } from "../../cli/init-preview.mjs";
 import { notYetForm } from "../../cli/form.mjs";
-import { INSTRUCTION_FILES, contextDir, grouped, instructionReader, linkRefusal, marksOf, planSplit, splitLines } from "../../cli/instructions.mjs";
+import {
+    INSTRUCTION_FILES,
+    contextDir,
+    grouped,
+    instructionReader,
+    linkRefusal,
+    marksOf,
+    planSplit,
+    splitLines,
+} from "../../cli/instructions.mjs";
 
 function splitOf(ws) {
     const tree = ws.repository.dir;
     const context = contextDir(tree, ws.dir, ws.manifest);
-    const taken = context === null ? [] : ws.repository.names(context).filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -3));
+    const taken =
+        context === null
+            ? []
+            : ws.repository
+                  .names(context)
+                  .filter((name) => name.endsWith(".md"))
+                  .map((name) => name.slice(0, -3));
     return planSplit({ tree, context, taken, read: instructionReader(tree, ws.repository.read) });
 }
 
@@ -26,29 +42,62 @@ export const step = {
     owed(ws, ctx) {
         const behind = notYetForm(ws, ctx);
         if (behind) return { owed: false, because: behind };
-        if (!ws.repository) return { owed: false, because: "this workspace declares no tree, so there is no instruction file of its own" };
+        if (!ws.repository)
+            return {
+                owed: false,
+                because: "this workspace declares no tree, so there is no instruction file of its own",
+            };
         const read = instructionReader(ws.repository.dir, ws.repository.read);
         const marked = INSTRUCTION_FILES.filter((rel) => marksOf(read(rel) ?? "").marks.length > 0);
-        if (marked.length === 0) return { owed: false, because: "no section of CLAUDE.md or .claude/CLAUDE.md is marked `<!-- portulan: on-read -->`" };
+        if (marked.length === 0)
+            return {
+                owed: false,
+                because: "no section of CLAUDE.md or .claude/CLAUDE.md is marked `<!-- portulan: on-read -->`",
+            };
         if (typeof ws.manifest?.slots?.context !== "string") {
-            return { owed: false, because: `${marked.join(" and ")} marks a section, and \`slots.context\` is undeclared: \`0006\` declares it, and this step is asked again then` };
+            return {
+                owed: false,
+                because: `${marked.join(" and ")} marks a section, and \`slots.context\` is undeclared: \`0006\` declares it, and this step is asked again then`,
+            };
         }
         const linked = marked.map((rel) => linkRefusal(ws.repository.dir, rel)).filter((refusal) => refusal !== null);
-        if (linked.length) return { owed: true, hand: true, because: `a marked section cannot move, so none is moved — ${linked.join("; ")}, or take the marks out, then upgrade again` };
+        if (linked.length)
+            return {
+                owed: true,
+                hand: true,
+                because: `a marked section cannot move, so none is moved — ${linked.join("; ")}, or take the marks out, then upgrade again`,
+            };
         const split = splitOf(ws);
-        if (split.refusals.length) return { owed: true, because: `a marked section cannot move — ${split.refusals.join("; ")}` };
+        if (split.refusals.length)
+            return { owed: true, because: `a marked section cannot move — ${split.refusals.join("; ")}` };
         const ratio = declaredContext(ws.manifest).ratio ?? ESTIMATED_BYTES_PER_TOKEN;
-        const before = alwaysTier(ws.repository.dir).entries.reduce((n, e) => n + e.bytes, 0);
-        const after = before - split.files.reduce((n, f) => n + f.removed, 0) + split.index;
+        const projected = previewMigration(ws.repository.dir, ws.dir, [
+            ...split.files.map((f) => ({ file: f.rel, next: f.after })),
+            ...split.units.map((u) => ({ file: u.source, next: u.text })),
+        ]);
+        const before = projected.before[0],
+            after = projected.after?.[0];
         return {
             owed: true,
-            because: `${splitLines(split).join("; ")}; the always tier goes from ~${grouped(tokensOf(before, ratio))} to ~${grouped(tokensOf(after, ratio))} tokens`,
+            because: `${splitLines(split).join("; ")}; ${after === undefined ? "the after forecast is unavailable because native imports cannot be projected exactly" : `the always tier goes from ~${grouped(tokensOf(before, ratio))} to ~${grouped(tokensOf(after, ratio))} tokens`}`,
         };
     },
 
     plan(ws) {
         const split = splitOf(ws);
-        if (split.refusals.length) return { ok: false, reason: `a marked section cannot move, so none is moved — ${split.refusals.join("; ")}` };
+        if (split.refusals.length)
+            return {
+                ok: false,
+                reason: `a marked section cannot move, so none is moved — ${split.refusals.join("; ")}`,
+            };
+        try {
+            previewMigration(ws.repository.dir, ws.dir, [
+                ...split.files.map((f) => ({ file: f.rel, next: f.after })),
+                ...split.units.map((u) => ({ file: u.source, next: u.text })),
+            ]);
+        } catch (error) {
+            return { ok: false, reason: `prospective guidance refuses — ${error.message}` };
+        }
         return {
             ok: true,
             edits: [

package/spec/migrations/0011-persona-bindings-compiled.mjs

@@ -0,0 +1,23 @@
+// Refresh existing persona context fields through the compiler's ownership planner.
+import { personaEdits } from "../../cli/compile.mjs";
+import { notYetForm } from "../../cli/form.mjs";
+
+export const step = {
+    id: "0011-persona-bindings-compiled", kind: "form", from: null, to: null,
+    title: "existing eligible persona bindings carry the shipped context declarations",
+    why: "The shipped persona route and its A/B evidence must arrive on upgrade. Refresh existing compiler-owned context fields; never create a binding, widen core source selection, or write gate settings.",
+    owed(ws, ctx) {
+        const behind = notYetForm(ws, ctx);
+        if (behind) return { owed: false, because: behind };
+        if (!ws.repository) return { owed: false, because: "no declared repository tree holds persona bindings" };
+        const planned = personaEdits(ws.dir);
+        return {
+            owed: planned.edits.length > 0,
+            because: planned.edits.length ? `${planned.edits.map(edit => edit.file).join(", ")} differ from their persona declarations` :
+                planned.compared ? "existing eligible persona bindings agree with their declarations" : "no existing eligible binding is selected; missing or foreign core bindings are not installed",
+        };
+    },
+    plan(ws) {
+        return { ok: true, edits: personaEdits(ws.dir).edits.map(edit => ({ root: "tree", ...edit })) };
+    },
+};

package/spec/migrations/README.md

@@ -107,6 +107,7 @@ is a question that could not be answered.
 | [`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. |
+| [`0011-persona-bindings-compiled.mjs`](0011-persona-bindings-compiled.mjs) | `form` | Refresh existing eligible persona bindings through the compiler's ownership planner. Core sources participate only in the installed engine's own tree; composed pack sources retain their existing boundary. Missing bindings are not created and gate settings are untouched. |
 
 **`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
@@ -118,6 +119,11 @@ either, since this repository keeps no `CLAUDE.md`, and is exercised against suc
 instruction file the suite marks; `0010` against one `init` drafted where git listed no files, then
 committed.
 
+`0011` is exercised against exact v0.2.0 core bindings in a copy of the engine and against
+foreign trees and absent bindings. The command-level demonstration holds unrelated bytes,
+modes and settings constant, checks idempotence, and forces a staging collision after one
+replacement to demonstrate rollback while preserving the unowned collision file.
+
 ## Adding one
 
 Drop a module in, named `NNNN-slug.mjs`. `cli/upgrade.mjs` reads the directory and orders by filename,

package/spec/pack.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://portulan.dev/spec/pack/1.0/pack.schema.json",
-  "title": "Portulan Pack Definition v1.0",
+  "$id": "https://portulan.dev/spec/pack/1.1/pack.schema.json",
+  "title": "Portulan Pack Definition v1.1",
   "description": "The manifest at the root of a pack. A pack is the cascade's middle layer — core < pack < workspace < repo card < task — and this manifest declares what it contributes to that cascade: skills, personas, verify recipes, and gate-policy fragments. It is an index, not a container, for the same reason the Workspace Definition is: the content lives in the files the paths point at. Written in the same deliberately small subset of JSON Schema 2020-12 — see spec/README.md for the subset, for what validates this, and for why a pack carries its own version train rather than the Workspace Definition's.",
   "type": "object",
   "additionalProperties": false,
@@ -49,7 +49,7 @@
     },
 
     "contributes": {
-      "description": "What this pack adds to the cascade. Every key is optional and an absent key contributes nothing of that kind — but the object itself is required, because a pack contributing nothing is a plugin, not a pack, and the manifest should say which it is rather than leaving it to be inferred from four absences.",
+      "description": "What this pack adds to the cascade. Every key is optional and an absent key contributes nothing of that kind — but the object itself is required, because a pack contributing nothing is a plugin, not a pack, and the manifest should say which it is rather than leaving it to be inferred from optional absences.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
@@ -74,6 +74,15 @@
           "minItems": 1,
           "items": { "$ref": "#/$defs/recipe" }
         },
+        "contexts": {
+          "description": "Since Pack Definition 1.1, ritual packs only: ordinary fresh native Agent admission within one session. Positive safe integer checked by doctor and compiler; number is the schema subset's numeric type. Multiple packs compose by minimum. Claude env compiles even without a gate policy. Parent, lifetime totals, resumes/forks and independent agent systems are outside the bound; see packs/rituals/checkpoints/README.md.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["max_concurrent_subagents"],
+          "properties": {
+            "max_concurrent_subagents": { "type": "number" }
+          }
+        },
         "gates": {
           "description": "Gate-policy fragments — the cascade's missing middle, and the contribution that needs care, because an installed pack reaching the gate map means a dependency can change what an agent is allowed to do. The floor is the maintainer's ruling of 2026-07-27 recorded in .portulan/proposals/0010-prohibited-as-a-fourth-universal-tier.md: a pack may raise a tier or add a prohibition, and may NEVER demote another layer's classification. Enforcement is split between this schema and the merge step, and the split is stated rather than implied — see `$defs/fragment`. READ TODAY, like `personas` and unlike `skills` and `verify`: cli/compile.mjs is the merge step, and it resolves this key when a pack root is given.",
           "type": "array",