@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/evals/ab/personas/reviewer.md

@@ -0,0 +1,22 @@
+# reviewer — acquired routing comparison
+
+Host: 2.1.321 (Claude Code). Concrete model: claude-sonnet-5-5.
+
+A uses the shipped inherited model and undeclared child effort (observed high). B requests medium through the native child tool. Each case has one attempt per arm.
+
+| Arm | Semantic passes | Observed cost index | Cold-normalized cost index |
+|---|---:|---:|---:|
+| A | 3/3 | 150520.60 | 426477.60 |
+| B | 3/3 | 161948.05 | 426186.55 |
+
+Medium wins this observed corpus: **yes**. The shipped policy remains inherited model, undeclared effort, instruction floor retained and five-minute cache lifetime.
+
+These are three observations, not a reliability estimate. A result on this concrete model does not establish medium effort for other inherited models. Cost indexes use the frozen declared vector, include parent and child requests, and are not subscription bills. First-request input is normalized separately in each fresh parent and child context.
+
+| Case | A | B |
+|---|---|---|
+| reviewer-verdict | PASS | PASS |
+| reviewer-clean | PASS | PASS |
+| reviewer-boundaries | PASS | PASS |
+
+The common acquisition record accounts for both mechanism probes and discloses the one retained-answer decoder repair after the first outcome. The original failed decode score and the repaired score are both retained; that child was never rerun.

package/evals/releases/0.3.0.json

@@ -0,0 +1,150 @@
+{
+    "portulan": {
+        "releaseEval": "1"
+    },
+    "version": "0.3.0",
+    "captured": "2026-11-03",
+    "source": {
+        "commit": "c08515fee0693cb0fc07fc6077fb152aa46bc28b",
+        "clean": false
+    },
+    "host": {
+        "node": "v26.12.1",
+        "platform": "darwin"
+    },
+    "recipes": [
+        {
+            "id": "docs",
+            "exit": 0
+        },
+        {
+            "id": "json",
+            "exit": 0
+        },
+        {
+            "id": "doctor",
+            "exit": 0
+        },
+        {
+            "id": "tests",
+            "exit": 0
+        },
+        {
+            "id": "plugin",
+            "exit": 0
+        },
+        {
+            "id": "compile",
+            "exit": 0
+        },
+        {
+            "id": "workflow-filters",
+            "exit": 0
+        },
+        {
+            "id": "index",
+            "exit": 0
+        },
+        {
+            "id": "context",
+            "exit": 0
+        },
+        {
+            "id": "ledger",
+            "exit": 0
+        },
+        {
+            "id": "control-chars",
+            "exit": 0
+        },
+        {
+            "id": "comments",
+            "exit": 0
+        },
+        {
+            "id": "rule-carriers",
+            "exit": 0
+        },
+        {
+            "id": "pack-version",
+            "exit": 0
+        },
+        {
+            "id": "pack-identity",
+            "exit": 0
+        },
+        {
+            "id": "payload",
+            "exit": 0
+        },
+        {
+            "id": "eval-bundle",
+            "exit": 0
+        },
+        {
+            "id": "goldens",
+            "exit": 0
+        },
+        {
+            "id": "mutants",
+            "exit": 0
+        },
+        {
+            "id": "fuzz-shell",
+            "exit": 0
+        },
+        {
+            "id": "version-carriers",
+            "exit": 0
+        },
+        {
+            "id": "skill-goldens",
+            "exit": 0
+        },
+        {
+            "id": "review-loop",
+            "exit": 0
+        },
+        {
+            "id": "telemetry",
+            "exit": 0
+        },
+        {
+            "id": "drills",
+            "exit": 0
+        },
+        {
+            "id": "ab",
+            "exit": 0
+        },
+        {
+            "id": "ab-grade",
+            "exit": 0
+        },
+        {
+            "id": "ab-run",
+            "exit": 0
+        },
+        {
+            "id": "tools/github:actions-pinned",
+            "exit": 0
+        },
+        {
+            "id": "tools/local-llm:runner-rails",
+            "exit": 0
+        }
+    ],
+    "excluded": [
+        {
+            "id": "release-eval",
+            "why": "a capture cannot be accurate about the record it is inside — captured before the record is written it is red for the record's absence, and captured after it is stale the moment the register is rendered. Its verdict for this release is the rail's own run on the pull request carrying this file."
+        }
+    ],
+    "abBaseline": {
+        "snapshot": "evals/ab/baseline.json",
+        "register": "evals/ab/baseline.md",
+        "captured": "2026-08-31T09:05:32.699Z",
+        "commit": "a642d551eec6c146c67ef0acfe3f8ba535c5ce6e",
+        "clean": false
+    }
+}

package/evals/releases/0.3.0.md

@@ -0,0 +1,68 @@
+# Eval result — Portulan 0.3.0
+
+> **Generated. Do not edit.** Rendered from [`evals/releases/0.3.0.json`](0.3.0.json) by [`cli/release-eval.mjs`](../../cli/release-eval.mjs) and byte-compared by the `release-eval` verify recipe. This is the eval result milestone 8 requires a release to carry — `docs/plan.md`, Protocol → Versioning.
+
+## What this release was measured at
+
+| | |
+|---|---|
+| Version | `0.3.0` |
+| Captured | 2026-11-03 |
+| Commit | `c08515fee0693cb0fc07fc6077fb152aa46bc28b` |
+| Tree at capture | **not clean** |
+| Node | `v26.12.1` |
+| Platform | `darwin` |
+
+## The rails, and what each returned
+
+30 of the 31 recipes this workspace yielded at capture. The set is derived from [`cli/recipe-set.mjs`](../../cli/recipe-set.mjs) and never listed by hand.
+
+| Recipe | Verdict |
+|---|---|
+| `docs` | green |
+| `json` | green |
+| `doctor` | green |
+| `tests` | green |
+| `plugin` | green |
+| `compile` | green |
+| `workflow-filters` | green |
+| `index` | green |
+| `context` | green |
+| `ledger` | green |
+| `control-chars` | green |
+| `comments` | green |
+| `rule-carriers` | green |
+| `pack-version` | green |
+| `pack-identity` | green |
+| `payload` | green |
+| `eval-bundle` | green |
+| `goldens` | green |
+| `mutants` | green |
+| `fuzz-shell` | green |
+| `version-carriers` | green |
+| `skill-goldens` | green |
+| `review-loop` | green |
+| `telemetry` | green |
+| `drills` | green |
+| `ab` | green |
+| `ab-grade` | green |
+| `ab-run` | green |
+| `tools/github:actions-pinned` | green |
+| `tools/local-llm:runner-rails` | green |
+
+**`release-eval` is excluded**, and the reason is printed rather than the row silently dropped: a capture cannot be accurate about the record it is inside — captured before the record is written it is red for the record's absence, and captured after it is stale the moment the register is rendered. Its verdict for this release is the rail's own run on the pull request carrying this file.
+
+## The A/B baseline this release ships against
+
+[`evals/ab/baseline.md`](https://github.com/sleepy-panda-srl/portulan/blob/v0.3.0/evals/ab/baseline.md), rendered from `evals/ab/baseline.json` — captured 2026-08-31T09:05:32.699Z at `a642d551eec6c146c67ef0acfe3f8ba535c5ce6e`, over a tree that was **not clean**.
+
+**Its figures are not repeated here.** They have one carrier and this is not it.
+
+## What this record does not establish
+
+- **A green says this record agrees with its own capture — never that the release is good.** Every line below is what the recipes returned at one commit, and a recipe's own green establishes only what that recipe's documentation says it establishes.
+- **The recipes were not run at the tag.** They ran at `c08515fee0693cb0fc07fc6077fb152aa46bc28b`, and this record is committed *in* the cut change — so the tagged tree is this commit plus whatever that change still adds after the capture, the record itself at minimum. A record cannot be captured at a commit that does not exist yet, and printing the one it was captured at is the only honest form.
+- **`release-eval` is excluded from the rows above**, because a capture cannot be accurate about the record it is inside. Its verdict for this release is the rail's own run on the pull request that carries this file.
+- **This record measures the Portulan repository's own build**, at the commit named above — never the workspace, project or package this release is installed into. Nothing here has looked at your tree.
+- **The tree was NOT clean at capture** — the diff of the cut change is the only record of what was uncommitted, which is weaker than a sha and is printed rather than hidden.
+- **The A/B baseline's figures are NOT restated here.** This record names which baseline the release ships against; the figures and everything that may not be concluded from them live in that register alone.

package/evals/releases/0.4.0.json

@@ -0,0 +1,154 @@
+{
+    "portulan": {
+        "releaseEval": "1"
+    },
+    "version": "0.4.0",
+    "captured": "2026-11-11",
+    "source": {
+        "commit": "660cbbfd7c9a4cf234e5a85d82d2ae21d248d3b1",
+        "clean": true
+    },
+    "host": {
+        "node": "v26.13.0",
+        "platform": "darwin"
+    },
+    "recipes": [
+        {
+            "id": "cache-stability",
+            "exit": 0
+        },
+        {
+            "id": "docs",
+            "exit": 0
+        },
+        {
+            "id": "json",
+            "exit": 0
+        },
+        {
+            "id": "doctor",
+            "exit": 0
+        },
+        {
+            "id": "tests",
+            "exit": 0
+        },
+        {
+            "id": "plugin",
+            "exit": 0
+        },
+        {
+            "id": "compile",
+            "exit": 0
+        },
+        {
+            "id": "workflow-filters",
+            "exit": 0
+        },
+        {
+            "id": "index",
+            "exit": 0
+        },
+        {
+            "id": "context",
+            "exit": 0
+        },
+        {
+            "id": "ledger",
+            "exit": 0
+        },
+        {
+            "id": "control-chars",
+            "exit": 0
+        },
+        {
+            "id": "comments",
+            "exit": 0
+        },
+        {
+            "id": "rule-carriers",
+            "exit": 0
+        },
+        {
+            "id": "pack-version",
+            "exit": 0
+        },
+        {
+            "id": "pack-identity",
+            "exit": 0
+        },
+        {
+            "id": "payload",
+            "exit": 0
+        },
+        {
+            "id": "eval-bundle",
+            "exit": 0
+        },
+        {
+            "id": "goldens",
+            "exit": 0
+        },
+        {
+            "id": "mutants",
+            "exit": 0
+        },
+        {
+            "id": "fuzz-shell",
+            "exit": 0
+        },
+        {
+            "id": "version-carriers",
+            "exit": 0
+        },
+        {
+            "id": "skill-goldens",
+            "exit": 0
+        },
+        {
+            "id": "review-loop",
+            "exit": 0
+        },
+        {
+            "id": "telemetry",
+            "exit": 0
+        },
+        {
+            "id": "drills",
+            "exit": 0
+        },
+        {
+            "id": "ab",
+            "exit": 0
+        },
+        {
+            "id": "ab-grade",
+            "exit": 0
+        },
+        {
+            "id": "ab-run",
+            "exit": 0
+        },
+        {
+            "id": "tools/github:actions-pinned",
+            "exit": 0
+        },
+        {
+            "id": "tools/local-llm:runner-rails",
+            "exit": 0
+        }
+    ],
+    "excluded": [
+        {
+            "id": "release-eval",
+            "why": "a capture cannot be accurate about the record it is inside — captured before the record is written it is red for the record's absence, and captured after it is stale the moment the register is rendered. Its verdict for this release is the rail's own run on the pull request carrying this file."
+        }
+    ],
+    "abBaseline": {
+        "snapshot": "evals/ab/baseline.json",
+        "register": "evals/ab/baseline.md",
+        "captured": "2026-08-31T09:05:32.699Z",
+        "commit": "a642d551eec6c146c67ef0acfe3f8ba535c5ce6e",
+        "clean": false
+    }
+}

package/evals/releases/0.4.0.md

@@ -0,0 +1,69 @@
+# Eval result — Portulan 0.4.0
+
+> **Generated. Do not edit.** Rendered from [`evals/releases/0.4.0.json`](0.4.0.json) by [`cli/release-eval.mjs`](../../cli/release-eval.mjs) and byte-compared by the `release-eval` verify recipe. This is the eval result milestone 8 requires a release to carry — `docs/plan.md`, Protocol → Versioning.
+
+## What this release was measured at
+
+| | |
+|---|---|
+| Version | `0.4.0` |
+| Captured | 2026-11-11 |
+| Commit | `660cbbfd7c9a4cf234e5a85d82d2ae21d248d3b1` |
+| Tree at capture | clean |
+| Node | `v26.13.0` |
+| Platform | `darwin` |
+
+## The rails, and what each returned
+
+31 of the 32 recipes this workspace yielded at capture. The set is derived from [`cli/recipe-set.mjs`](../../cli/recipe-set.mjs) and never listed by hand.
+
+| Recipe | Verdict |
+|---|---|
+| `cache-stability` | green |
+| `docs` | green |
+| `json` | green |
+| `doctor` | green |
+| `tests` | green |
+| `plugin` | green |
+| `compile` | green |
+| `workflow-filters` | green |
+| `index` | green |
+| `context` | green |
+| `ledger` | green |
+| `control-chars` | green |
+| `comments` | green |
+| `rule-carriers` | green |
+| `pack-version` | green |
+| `pack-identity` | green |
+| `payload` | green |
+| `eval-bundle` | green |
+| `goldens` | green |
+| `mutants` | green |
+| `fuzz-shell` | green |
+| `version-carriers` | green |
+| `skill-goldens` | green |
+| `review-loop` | green |
+| `telemetry` | green |
+| `drills` | green |
+| `ab` | green |
+| `ab-grade` | green |
+| `ab-run` | green |
+| `tools/github:actions-pinned` | green |
+| `tools/local-llm:runner-rails` | green |
+
+**`release-eval` is excluded**, and the reason is printed rather than the row silently dropped: a capture cannot be accurate about the record it is inside — captured before the record is written it is red for the record's absence, and captured after it is stale the moment the register is rendered. Its verdict for this release is the rail's own run on the pull request carrying this file.
+
+## The A/B baseline this release ships against
+
+[`evals/ab/baseline.md`](https://github.com/sleepy-panda-srl/portulan/blob/v0.4.0/evals/ab/baseline.md), rendered from `evals/ab/baseline.json` — captured 2026-08-31T09:05:32.699Z at `a642d551eec6c146c67ef0acfe3f8ba535c5ce6e`, over a tree that was **not clean**.
+
+**Its figures are not repeated here.** They have one carrier and this is not it.
+
+## What this record does not establish
+
+- **A green says this record agrees with its own capture — never that the release is good.** Every line below is what the recipes returned at one commit, and a recipe's own green establishes only what that recipe's documentation says it establishes.
+- **The recipes were not run at the tag.** They ran at `660cbbfd7c9a4cf234e5a85d82d2ae21d248d3b1`, and this record is committed *in* the cut change — so the tagged tree is this commit plus whatever that change still adds after the capture, the record itself at minimum. A record cannot be captured at a commit that does not exist yet, and printing the one it was captured at is the only honest form.
+- **`release-eval` is excluded from the rows above**, because a capture cannot be accurate about the record it is inside. Its verdict for this release is the rail's own run on the pull request that carries this file.
+- **This record measures the Portulan repository's own build**, at the commit named above — never the workspace, project or package this release is installed into. Nothing here has looked at your tree.
+- **The tree was clean at capture**, so the commit named above is what was measured.
+- **The A/B baseline's figures are NOT restated here.** This record names which baseline the release ships against; the figures and everything that may not be concluded from them live in that register alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleepy_panda_srl/portulan",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Portulan — an agentic-engineering framework whose product is its files. The CLI wraps the file-based mechanics for hosts beyond Claude Code.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,6 +16,7 @@
     "spec/",
     "packs/",
     "evals/releases/",
+    "evals/ab/personas/",
     "README.md",
     "LICENSE",
     "NOTICE",
@@ -26,9 +27,13 @@
     "!cli/ab.mjs",
     "!cli/ab-run.mjs",
     "!cli/ab-grade.mjs",
+    "!cli/local-routing.mjs",
+    "!cli/acquire-personas.mjs",
+    "!cli/normalize-personas.mjs",
     "!cli/warm.mjs",
     "!cli/payload.mjs",
-    "!cli/roster.mjs"
+    "!cli/roster.mjs",
+    "!cli/cache-stability.mjs"
   ],
   "repository": {
     "type": "git",

package/packs/.claude-plugin/plugin.json

@@ -17,6 +17,7 @@
     "supervision"
   ],
   "skills": [
-    "./rituals/checkpoints/skills/"
+    "./rituals/checkpoints/skills/",
+    "./tools/local-llm/skills/"
   ]
 }

package/packs/README.md

@@ -31,7 +31,9 @@ registers nothing, silently, while a validator walking deeper counts three;
 manifests therefore sit in this tree and they answer different questions: the repository's own at
 [`../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json), which declares
 `./packs/rituals/checkpoints/skills/` because *its* root is the repository; and this one, whose root is
-`packs/`. Neither is redundant, and the paths differ by exactly the prefix their roots differ by.
+`packs/`. Neither is redundant, and the paths differ by exactly the prefix their roots differ by. Both
+also declare `tools/local-llm`'s `skills/` root, the same way, since this repository's workspace composes
+that pack too; the plugin's name and version here are the checkpoints pack's.
 
 **The version here mirrors the pack's own** — `portulan.version` in
 [`rituals/checkpoints/pack.json`](rituals/checkpoints/pack.json), which the Pack Definition names as how
@@ -45,7 +47,8 @@ observed through a *local* marketplace over a copy of this directory. The quoted
 exists and the feed's pin moves to it. Until then the green is demonstrated on the payload and inferred
 for the feed — a distinction this repository would rather write down than round off.
 
-> **Two packs exist.** [`rituals/checkpoints`](rituals/checkpoints/README.md), the supervised-build
-> ritual; and [`tools/github`](tools/github/README.md), one verify recipe. `stacks/` is still empty and
-> says why.
+> **Three packs exist.** [`rituals/checkpoints`](rituals/checkpoints/README.md), the supervised-build
+> ritual; [`tools/github`](tools/github/README.md), one verify recipe; and
+> [`tools/local-llm`](tools/local-llm/README.md), hybrid local-model execution under a zero-floor input
+> budget and a verify-gated rollback loop. `stacks/` is still empty and says why.
 

package/packs/rituals/checkpoints/README.md

@@ -18,8 +18,43 @@ sentence reads as a citation now and did not before.
 |---|---|
 | Skills | [`session-open`](skills/session-open/SKILL.md) · [`pre-commit`](skills/pre-commit/SKILL.md) · [`milestone-close`](skills/milestone-close/SKILL.md) |
 | Persona | [`supervisor`](personas/supervisor.md) — grades, never implements or merges |
+| Context admission | One ordinary fresh native Agent at a time per Claude session; see the scope below. |
 | Gate fragments | `commit-without-the-hooks` (gated) · `self-certify-a-checkpoint` (prohibited) |
 
+## Context admission
+
+Pack Definition 1.1 declares `contributes.contexts.max_concurrent_subagents: 1`.
+One supervisor at a time fits this sequential ritual; the three checkpoints can
+still open three or more contexts over the work's lifetime. The ledger reports
+actual contexts separately. Composed ritual counts tighten by minimum, independent
+of pack order. An unresolved pack beside a known cap refuses compilation because
+its contribution is unknown. No workspace `rituals` slot is introduced.
+
+Claude compilation writes project `env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, even
+without a gate policy. It applies across rituals within one session and excludes
+the parent. It governs **ordinary fresh native Agent admission**, not all child
+activity: completed-agent resumes and `/subtask` forks can exceed it; workflow
+agents and team teammates have independent limits. Higher-precedence settings,
+experimental flags and ultracode paths can bypass the guard. It bounds neither
+lifetime children nor requests, time or tokens. Other adapters report the count
+as not compiled; that is a limit of these adapters, not a claim about their hosts.
+
+The [native trace](../../../cli/fixtures/ritual-cap/README.md) tests Claude Code
+2.1.321 with synthetic loopback responses. The [current host documentation](https://code.claude.com/docs/en/sub-agents#concurrent-subagent-limit)
+was checked on 2026-11-11. Neither establishes a universal hard ceiling. The
+compiler composes caps with default restart advice in authored governing workspaces,
+independently of a gate policy. It owns this dedicated native settings artifact
+only while its complete payload, internal marker and digest remain intact; this
+is accidental-edit detection, not authentication. Foreign content, additions,
+links and old policy settings refuse before any output write. Formatting and key
+order may normalize. Exact legacy cap-only output can migrate after validating
+its shape and source/count consistency; it has no historical digest to authenticate
+plausible edits. Removing a cap leaves advice settings in place. Missing manifests
+and pointers do not adopt or remove those settings. The legacy internal cap-only
+path removes its own file when its cap disappears. Normal policy compilation
+retains its existing ownership. Removing both policy and cap while normal settings
+still carry a cap refuses in every mode and preserves the file for explicit resolution.
+
 ## The three checkpoints
 
 | Checkpoint | When | What it grades |

package/packs/rituals/checkpoints/pack.json

@@ -1,7 +1,7 @@
 {
   "portulan": {
-    "pack": "1.0",
-    "version": "0.3.0"
+    "pack": "1.1",
+    "version": "0.3.1"
   },
 
   "name": "checkpoints",
@@ -10,6 +10,7 @@
   "doc": "README.md",
 
   "contributes": {
+    "contexts": { "max_concurrent_subagents": 1 },
     "skills": ["skills/"],
 
     "personas": ["personas/supervisor.md"],

package/packs/tools/README.md

@@ -3,12 +3,12 @@
 Tool packs — integrations for the tools and MCP servers an agent drives (issue trackers, cloud
 CLIs, design tools, databases), with the how-to and the gate classification for each.
 
-> **One tool pack exists** — [`github/`](github/README.md). The machinery that reads one is a gate policy in a
-> host-neutral vocabulary, dispatched on by [`../../cli/compile.mjs`](../../cli/compile.mjs) — and the
-> cascade's missing middle (`core < pack < workspace`) is now bridged: a pack's `contributes.gates`
-> fragments are resolved and merged into the policy, **tighten-only**, by the same compiler.
+> **Two tool packs exist** — [`github/`](github/README.md) and [`local-llm/`](local-llm/README.md). The
+> machinery that reads one is a gate policy in a host-neutral vocabulary, dispatched on by
+> [`../../cli/compile.mjs`](../../cli/compile.mjs) — and the cascade's missing middle (`core < pack < workspace`)
+> is bridged: a pack's `contributes.gates` fragments are resolved and merged into the policy,
+> **tighten-only**, by the same compiler.
 >
-> The first pack to use it is a *ritual* one ([`../rituals/checkpoints/`](../rituals/checkpoints/)), so
-> the promise this file has carried since it was written — that a tool pack ships "with the gate
-> classification for each" — is now buildable and still unbuilt. A tool pack becomes worth writing when
-> a workspace here drives a tool that needs one.
+> [`local-llm/`](local-llm/README.md) is the first tool pack to ship a gate classification
+> (`local-llm-off-loopback` at `propose`) alongside a persona and an offline verify recipe,
+> fulfilling the promise this file has carried since it was written.