@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/core/personas/README.md

@@ -21,6 +21,81 @@ context firewalls; Cognition — read-parallel / write-isolated.)_
 - **Read / write posture** — most personas read in parallel; writes are isolated to one place so two
   agents never clobber the same file.
 
+## What a persona may declare about its context
+
+Four optional frontmatter fields say what a fresh context for the role should cost, per
+[`../operating/context.md`](../operating/context.md): `model`, one model name or alias as a single
+token; `effort`, one of `low`, `medium`, `high`, `xhigh` or `max`; `omitClaudeMd`, `true` or `false`
+unquoted, whether the role runs without the project's instruction files; and `cacheLifetime`, `5m` or
+`1h`. The effort levels and the name `omitClaudeMd` are adopted from Claude Code's vocabulary, the first
+host to express them. `effort` sets the host subagent's reasoning effort, and is not the thinking cap the
+`tools/local-llm` runner's `--effort` sends with each request it makes. `doctor` fails malformed values
+in composed pack personas; `compile` validates every persona source it compiles. Neither supplies a value
+the persona did not write. `compile` writes declared fields from composed pack personas into the
+frontmatter of the role's existing host binding: `agents/<name>.md` in a plugin tree and
+`.claude/agents/<name>.md` in an ordinary project. Compiler and doctor share that selection; a malformed,
+unreadable or escaping plugin marker is not treated as an ordinary project. When
+the declared tree resolves to this compiler's own engine root, including a canonical alias, the same
+pipeline also reads `core/personas/*.md` except this README. A foreign tree's matching files do not
+participate. A core source's declared name must match its filename. The compiler leaves every other line of
+that file as its author wrote it; `--check` byte-compares the result, and a line inside the compiled
+block that `compile` did not write is refused rather than removed. One it cannot catch: a line added inside
+the block in exactly the spelling and order `compile` writes reads as compiled, and is dropped once the
+persona no longer declares that field, since the two cannot be told apart. And once a persona declares any
+field, `compile` owns every top-level key it could write, so a hand-written `experimental:` is refused
+even for a key other than `cacheTtl`. A field a host cannot express is
+named, with the persona and the host, in the degradation report `compile` prints. Claude Code takes all
+four on an agent (`cacheLifetime` as `experimental.cacheTtl`), and a vendored `AGENTS.md` takes none.
+`compile` writes only existing bindings; an absent adopter binding remains unbound and is never
+created by compilation. A persona-only workspace can compile its declared fields without a gate
+policy or guidance. Nonregular, escaping and invalid UTF-8 inputs are refused before writes.
+Doctor checks the selected binding's name and declared tool grant, keeping an unread file distinct
+from an absent one. Plugin packaging checks core and actually composed charter owners in both
+directions, including personas declaring no context fields. File equality proves neither plugin
+enablement nor that a running host honored a field. _(Provenance:
+proposal `0036`'s order of work, item 7, and proposal `0039`'s first two rules. The host's keys, values
+and agent locations were read in Claude Code 2.1.317's program text on 2026-11-03.)_
+
+This product binds both composed roles. Supervisor still requires a fresh invocation for a checkpoint.
+Local-worker's host wrapper points to its existing loopback runner; loading that role does not itself
+invoke a local model or prove local execution.
+
+The three core sources explicitly declare `model: inherit`, `omitClaudeMd: false` and
+`cacheLifetime: 5m`, leaving effort undeclared. These are product-role policy choices: inherit the
+parent model, retain the instruction floor and request a five-minute cache lifetime. In Claude Code,
+explicit `inherit` outranks the ordinary `CLAUDE_CODE_SUBAGENT_MODEL` default; an invocation's model
+selection and `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` can override it. Cache lifetime remains subject to
+the host's precedence rules. Compilation proves the committed bytes, with no claim about quality,
+savings or live loading. _(Host precedence checked against the
+[official subagent documentation](https://code.claude.com/docs/en/sub-agents) on 2026-11-09.)_
+
+The acquired [implementer](../../evals/ab/personas/implementer.md),
+[reviewer](../../evals/ab/personas/reviewer.md) and
+[librarian](../../evals/ab/personas/librarian.md) comparisons each have three
+frozen artifact cases, one attempt per arm, through native children on Sonnet 5.5
+in Claude Code 2.1.321. Both arms pass all nine cases. Medium has a lower
+cold-normalized cost index in this observation; observed cache costs differ,
+and the reviewer arm's observed cost rises. These results support the retained
+policy on that corpus and model, with no global medium default earned for other
+inherited models. The [protocol](../../evals/ab/personas/README.md) discloses the
+small sample, both probes, full parent/child usage and one retained-answer
+decoder repair after the first outcome. The shipped offline checker regrades
+the records and checks routing and source bytes.
+
+A binding has one persona owner across core and composed pack sources, including an unbound persona or one declaring
+no fields; duplicate destinations are refused before any artifact is written. The binding must be a
+regular file whose real path stays in the real declared tree, including its parent directories.
+`omitClaudeMd` accepts only unquoted `true` or `false`, in both declarations and compiled blocks.
+
+`upgrade` refreshes existing eligible bindings through the same compiler planner,
+including normal host-cache pack discovery and its shadow refusals. It preserves
+unrelated binding text and modes, creates no absent binding, and writes no gate
+settings. Core sources still participate only in the installed engine's own
+declared tree; an ordinary adopter receives the baked core agents by updating the
+plugin, without installing a foreign core adapter. The command-level historical
+v0.2.0 demonstration is in
+[`../../cli/persona-upgrade.test.mjs`](../../cli/persona-upgrade.test.mjs).
+
 ## Status
 
 **Milestone 3 — contract, exemplars, and one host binding.** This README fixes the persona contract; the

package/core/personas/implementer.md

@@ -2,6 +2,9 @@
 name: implementer
 description: The default working persona. Takes one task through the full loop — research → plan → implement → verify → learn — and hands back a verified change plus what it learned. Delegate a unit of implementation work to it.
 tools: [read, search, edit-code, run-verify, draft-memory, open-pr]
+model: inherit
+omitClaudeMd: false
+cacheLifetime: 5m
 ---
 
 # Persona — Implementer

package/core/personas/librarian.md

@@ -2,6 +2,9 @@
 name: librarian
 description: The persona that tends the curated layer — consolidating memory, regenerating the size-budgeted index, drafting rule-change proposals from incidents and PR reviews, and chasing stale rules toward retirement. It drafts and files; it never accepts. Delegate a memory/evolution housekeeping pass to it.
 tools: [read, search, read-history, draft-memory, draft-proposal, write-index, open-pr]
+model: inherit
+omitClaudeMd: false
+cacheLifetime: 5m
 ---
 
 # Persona — Librarian

package/core/personas/reviewer.md

@@ -2,6 +2,9 @@
 name: reviewer
 description: The last-mile check on a change before it merges. Reads a proposed diff against the task's acceptance criteria and the definition of done, re-runs the verify recipe, and returns a verdict — it does not edit the code or merge. Delegate review of a completed change to it.
 tools: [read, search, run-verify, post-review]
+model: inherit
+omitClaudeMd: false
+cacheLifetime: 5m
 ---
 
 # Persona — Reviewer

package/core/skills/clarify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clarify
-description: Run a bounded clarification pass before planning a full-lane task whose intent is ambiguous or whose acceptance criteria are not yet testable. Use when the ask is underspecified, the constraints conflict, or the criteria can't be written as observable checks — surface the smallest set of decision-questions, get human answers, and fold them into EARS-shaped acceptance criteria before any code is planned.
+description: Run a bounded clarification pass before planning a full-lane task. Use when the ask is underspecified, the constraints conflict, or the criteria can't be written as observable checks — surface the smallest set of decision-questions, get human answers, and fold them into EARS-shaped acceptance criteria before any code is planned.
 ---
 
 # Skill — Clarify

package/core/skills/consolidate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: consolidate
-description: Bring a memory store back under its budget by merging, compressing, splitting, and retiring records — the repair a breached memory budget calls for. Use when the index verify recipe reports a breach, or on the librarian's scheduled pass. The output is drafts through the human gate; raising the budget is not one of the moves.
+description: Bring a memory store back under its budget by merging, compressing, splitting, and retiring records. Use when the index verify recipe reports a breach, or on the librarian's scheduled pass. The output is drafts through the human gate; raising the budget is not one of the moves.
 ---
 
 # Skill — Consolidate

package/core/templates/handoff.md

@@ -10,12 +10,16 @@
 > decisions and their rationale. When one is owed, and why the commit carries the rest:
 > `../operating/loop.md`.)_
 >
+> Link the records that own measured figures and durable rules. Keep each open decision and its why.
+> A declared token cap binds new handoffs; compress or move and link facts, never split or drop a why.
+> The heading names the outcome; the filename already carries the date. See `../operating/context.md`.
+>
 > **The commit a change lands in:** a subject that says what changed, in the present tense and under 72
 > characters; a blank line; a body of a few lines that says why, and what was rejected when that matters.
 
 ---
 
-# Handoff — {task / thread}
+# {outcome / open task}
 
 **State.** {where things stand: what is done and committed, what is in progress and uncommitted.}
 
@@ -30,7 +34,7 @@
 
 _A filled one, for a session that stopped mid-change:_
 
-# Handoff — retry the flaky upload test
+# Retry the flaky upload test
 
 **State.** The retry wrapper is written and its unit test passes; it is stashed, not committed, because
 the integration suite still fails once in about ten runs.

package/evals/README.md

@@ -122,6 +122,9 @@ node cli/review-meter.mjs --fetch --repo <owner/name> --out <file>        the on
 with `--register evals/review-loop/register.md --write` regenerates it, and the recipe byte-compares it.
 The criterion's *"rounds per pull request"* is **submissions** per pull request — its unit before *round*
 was redefined — and the tool prints that name, never the bare word.
+**The register is historical.** The loop it measures is Copilot's, and Copilot review left this
+repository's review path on 2026-10-30, by the maintainer's decision, so the capture is the record of that
+loop rather than a reading of a live one.
 What each figure is, at length, is in the header at `git show a31da46:cli/review-meter.mjs`.
 
 **What it does NOT establish:**
@@ -133,9 +136,9 @@ What each figure is, at length, is in the header at `git show a31da46:cli/review
   workspace-layer matcher the engine tool refused to copy, since two spellings of one rule on opposite
   sides of that boundary cannot see each other drift; the matcher left with its workflow on 2026-09-23
   ([#355](https://github.com/sleepy-panda-srl/portulan/issues/355)).
-- **A bound.** It is a meter: rule 4 of
-  [`a-review-loop-needs-a-bound.md`](../.portulan/memory/a-review-loop-needs-a-bound.md) stops a loop, and
-  nothing here stops anything.
+- **A bound.** It is a meter, and nothing here stops anything. The bound was rule 4 of
+  [`a-review-loop-needs-a-bound.md`](https://github.com/sleepy-panda-srl/portulan/blob/7d72356/.portulan/memory/a-review-loop-needs-a-bound.md),
+  retired on 2026-10-30.
 - **Current data.** The recipe compares the register to the snapshot, never the snapshot to the world, so a
   stale capture and a current one are the same green. Refreshing is `--fetch`, run by a person
   ([#356](https://github.com/sleepy-panda-srl/portulan/issues/356)).
@@ -232,12 +235,14 @@ is a new consent question rather than a covered one. It neither queues nor retri
   path. The send is proven only in the suite, against an injected transport, and no yielded recipe may
   ever exercise `--export`.
 - **A network mode reached indirectly.** The suite derives the set of network-capable modules from the
-  tree, and the offline audit matches a module as a path suffix and a flag as a token; a mode reached
-  through another script, or through a flag built at runtime, is invisible to it.
+  tree, and the offline audit matches a module as a path suffix and a flag as a token, or, for the
+  local-llm runner, any invocation but `--verify-offline` alone or `eval --verify` alone on its command; a mode reached through
+  another script, or through a flag built at runtime, is invisible to it.
 - **Scheduled emission.** Nothing fires when nobody runs it —
   [#344](https://github.com/sleepy-panda-srl/portulan/issues/344)'s silence again.
-- **Enforcement of the review-loop bound.** An emitter with no backend reading it is not the checker
-  [`a-review-loop-needs-a-bound.md`](../.portulan/memory/a-review-loop-needs-a-bound.md) lacks.
+- **Enforcement of the review-loop bound.** An emitter with no backend reading it was never the checker
+  [`a-review-loop-needs-a-bound.md`](https://github.com/sleepy-panda-srl/portulan/blob/7d72356/.portulan/memory/a-review-loop-needs-a-bound.md) lacked, and that record
+  retired on 2026-10-30.
 - **Traces.** Metrics only.
 
 ## The A/B baseline
@@ -262,6 +267,17 @@ capture. The recipes run no agent; the modes that do — `ab --stop-probe`, `ab-
 and the register cites it rather than restating it. **The baseline is scoped to the vendored-and-compiled
 tier** [`ab/arm.md`](ab/arm.md) specifies, and closes row 8 for no other configuration of *Portulan on*.
 
+## The local-worker routing capture — milestone 14
+
+[`ab/local-worker.json`](ab/local-worker.json) is the immutable acquired local/host capture;
+[`ab/local-worker.md`](ab/local-worker.md) is its generated register. The
+[acquisition note](ab/local-worker-acquisition.md) records conditions, recovery and limitations.
+`node packs/tools/local-llm/runner/local-llm.mjs eval --verify` regrades and byte-compares without a
+model. `node cli/local-routing.mjs` additionally compares the shipped role flags, model IDs and
+capture digest with an independent derivation. Both run beside the original baseline in `ab-run`.
+The acquired five-turn cells support code, while the shared prose role is disabled. These rates
+support no general quality claim, and CI cannot replay the events that produced them.
+
 ## A release carries an eval result
 
 ```

package/evals/ab/personas/README.md

@@ -0,0 +1,111 @@
+# Core persona routing comparisons
+
+This protocol addresses [#520](https://github.com/sleepy-panda-srl/portulan/issues/520).
+The frozen [corpus](corpus.json) has three artifact tasks per core role and one
+attempt per arm. The [grader](grader.mjs) checks semantic behavior: bounded
+execution and nonmutation for implementer code, executable counterexamples and
+a clean control for reviewer findings, and preservation, escalation and human
+authority for librarian drafts. These observations do not establish general
+quality or a reliability rate.
+
+A is the shipped role: inherited model, undeclared effort, instruction floor
+retained and five-minute cache lifetime. B requests medium effort on the same
+concrete inherited model through one native foreground persona child. The parent
+runs at high effort; host request metadata must establish effective child effort.
+The `--agent` main-session override is not this mechanism. Each parent and child
+has a fresh context. Case order alternates A/B then B/A; an invalid invocation or
+failed semantic control stops acquisition without resampling.
+
+The observed concrete model is Sonnet 5.5 on Claude Code 2.1.321. A medium win on
+this model and corpus does not establish medium effort for other inherited
+models. The product retains `model: inherit` and undeclared effort; no global
+lower-effort default is earned here.
+
+## Acquisition and accounting
+
+Private originals retain the journal, CLI output, parent/child transcripts and
+frozen source snapshots. Publication whitelists generic artifact answers,
+numeric request metadata, normalized command arguments, timestamps and digests.
+Answer presentation replaces only known acquisition and plugin-root prefixes
+with `<acquisition>` and `<plugin>`; the record lists the affected answer and
+retains both original and presented answer digests. Artifact contents and scores
+are unchanged. Original answer wording otherwise remains.
+Request identities and context identities are deterministically hashed; original
+local paths, session identities and unrelated conversation content do not ship.
+Public digests permit integrity checks; fidelity to private originals additionally
+requires the independent acquisition review.
+
+Acquisition fidelity **PASS**, signed `/root/checkpoint_520_open`, independent
+read-only reviewer, 2026-11-10, for capture
+`ff3688658bc20af6b78e834a5149ea6bd52bc88027b0340ec98cb52430c6d641`.
+The reviewer independently checked all 80 requests (39 parent, 41 child), native
+invocations, frozen sources, original answers, repair history and cost arithmetic.
+The one disclosed citation normalization matches the deterministic transformation
+and changes no JSON artifact or score. The checker and four capture/package tests
+passed. This establishes retained-event fidelity; the sample, decoder repair,
+reconstructed first-probe command and absence of billing evidence remain limits.
+
+Two mechanism probes precede the eighteen quality children. The first used the
+host's then-default Fable 5.2 and exceeded the configured one-dollar host-estimate
+ceiling after a child ran. Its failed parent and child requests remain overhead;
+it earns no quality result. Its command was reconstructed after execution from
+the retained source, which was also snapshotted after execution. It is not a
+contemporaneously recorded command. The second probe selected Sonnet 5.5 before
+any quality outcome and demonstrated the native medium-effort mechanism. Quality
+inference is limited to that model.
+
+Every observed parent, child and probe request is counted once. The frozen price
+vector is an index in uncached-input-token equivalents, not a price quotation or
+subscription bill: uncached input 1, five-minute writes 1.25, one-hour writes 2,
+unclassified writes 1.25, reads 0.1 and output 5. Registers separate observed
+cost from a cold-normalized index. Normalization reprices all input in the first
+request of each fresh parent and child context at 1.25, retaining subsequent
+requests' observed classes and all output. Probe overhead is reported separately
+from role comparisons. CLI USD values are host lifecycle estimates; they are not
+added to these indexes.
+
+## Disclosed decoder repair
+
+After the first quality outcome, acquisition stopped because the original
+decoder rejected a correct function inside one JSON fence followed by prose.
+The task requested a JSON artifact without forbidding surrounding prose; the
+original decoder already allowed a whole-answer fence. The retained answer
+passed the unchanged semantic execution checks.
+
+The [original grader](repairs/grader-before-decode-repair.mjs.txt) and
+[first answer](repairs/first-control-answer.txt) remain. A bounded decoder repair
+accepts exactly one JSON fence with prose and rejects competing artifacts or
+ambiguous fences. Semantic predicates, cases and pricing code stayed byte for
+byte identical. The original false score is preserved alongside the repaired
+true score. An independent checkpoint approved the exact decoder and continuation
+instrument hashes before the remaining seventeen untouched calls. The first
+child is never rerun. This is a post-outcome instrument repair, not an unchanged
+preregistration.
+
+## Offline verification and delivery
+
+The offline checker is `node cli/persona-routing.mjs --repo-root .`; it never
+starts a host. It checks the immutable acquisition digest, all three role records,
+semantic scores, generated registers, complete case/arm coverage, source and
+binding bytes, effective effort, unique contexts/requests, frozen task bytes,
+protocol snapshots, repair history and usage accounting. Exit 1 is a finding;
+exit 2 is unavailable data or a failed read. The existing A/B recipe runs it.
+
+The records and costs remain observations of source `01ca4887`; later bundle
+changes are not new measurements. Current core charters must remain byte-identical
+to that capture. A current plugin binding may change only its one nonempty,
+single-line description scalar: every other byte, including tools, body and
+context declarations, must match the historical binding. Malformed, duplicate,
+missing or multiline descriptions refuse comparison. This permits the later
+librarian description compression while preserving the acquired routing contract;
+it establishes neither current whole-bundle costs nor equivalent automatic
+delegation after description changes.
+
+The npm payload carries the records, frozen protocol evidence, grader and offline
+checker. Live acquisition and private normalization commands remain workshop
+tools. A plugin update delivers the baked `agents/` files. The CLI's persona form
+migration refreshes existing eligible bindings through the compiler planner:
+core sources only in the installed engine's own tree, composed pack sources
+through normal pack resolution. It creates no absent binding, installs no
+foreign core adapter and changes no gate settings. The historical v0.2.0 suite
+demonstrates actual check/write/check, idempotence, refusal and rollback.