@sleepy_panda_srl/portulan 0.1.3 → 0.3.0

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/README.md

@@ -21,6 +21,39 @@ 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 a
+malformed value and `compile` refuses one, and neither supplies a value the persona did not write. For a
+persona a composed pack ships, `compile` writes the declared fields into the frontmatter of the role's
+hand-written host binding, `agents/<name>.md` in the workspace's tree, and 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.
+**Claude Code loads `agents/` only from a plugin root**, and a repository that is not a plugin loads its
+agents from `.claude/agents/`, which `compile` does not write. So outside a plugin the compiled block is
+loaded by nothing, and the degradation report says so for each persona it applies to. Where the tree is
+a plugin root the report is silent, which is not proof of loading: a plugin's agents load only while it
+is installed and enabled, and `compile` cannot see that. _(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.)_
+
+A binding has one persona owner across composed packs, 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.
+
 ## Status
 
 **Milestone 3 — contract, exemplars, and one host binding.** This README fixes the persona contract; the

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/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
@@ -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.

package/core/templates/handoff.md

@@ -1,25 +1,23 @@
 # Template — Handoff
 
-> A **handoff** records a decision and its *why*, so the next agent — or the next context window —
-> inherits the reasoning and not just the result. Write one **at the close of every session** — that part
-> is not conditional, and short is fine — and also when compacting, when hitting an iteration cap, or when
-> passing work across a persona boundary. Decisions without their why get silently re-litigated or
-> reversed. **Drop any section that has nothing to say** — the date and the decisions-with-why are the
-> only irreducible parts, and a handoff of five lines is a valid handoff. The date lives in the
-> **filename**, leading, in ISO form — `YYYY-MM-DD-{slug}.md` — not in a field inside the document: that
-> is what a gate checks and what makes the series sort chronologically. That is what keeps the
-> every-session rule from becoming ceremony: it scales down here, inside the artifact, rather than by
-> being skipped. _(Provenance: Cognition — handoffs record decisions and rationale. The every-session rule
-> and why it is binary rather than discretionary are in `../operating/loop.md`.)_
+> A **handoff** carries the work still open, so the next agent — or the next context window — starts
+> from where things stand rather than from the transcript. Write one when a session ends with work not
+> committed and pushed, when compacting, when hitting an iteration cap, or when passing work across a
+> persona boundary. Work that is committed carries its own why, in its commit message, so a handoff
+> says nothing the diff or a commit already says. **Drop any section with nothing to say**; five lines
+> is a valid handoff. The date leads the **filename**, in ISO form — `YYYY-MM-DD-{slug}.md` — because
+> that is what a gate checks and what sorts the series. _(Provenance: Cognition — handoffs record
+> decisions and their rationale. When one is owed, and why the commit carries the rest:
+> `../operating/loop.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}
 
-**State.** {where things actually are right now — done, in-progress, blocked — in a few lines.}
-
-**Decisions + why.** {each decision taken and the reason it was taken; the reasons are the payload.}
-- {decision} — because {why}; alternatives considered: {…}.
+**State.** {where things stand: what is done and committed, what is in progress and uncommitted.}
 
 **Open questions.** {what is undecided, and who decides it — flag the human-owned ones.}
 
@@ -27,3 +25,18 @@
 
 **Recoverability.** {anything left in a partial state, and how to make it safe; see
 `../operating/safety.md`.}
+
+---
+
+_A filled one, for a session that stopped mid-change:_
+
+# Handoff — 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.
+
+**Open questions.** Whether three attempts is the right cap — the owner of the upload service decides.
+
+**Next action.** `git stash pop`, run the integration suite twenty times, and read the one failure's log.
+
+**Recoverability.** Nothing was pushed; dropping the stash loses only the wrapper.

package/core/templates/memory-entry.md

@@ -8,6 +8,7 @@
 ---
 
 **type:** rule | decision | reference | glossary
+**dated:** {YYYY-MM-DD — the day this record's text last changed; an edit re-dates it. The per-record cap binds by it where the workspace declares a cutoff}
 **scope:** {the persona / repo / workspace this belongs to — memory is per-agent, not global}
 **provenance:** {one of the two forms below — a rule carrying neither is taste, and `doctor` rejects it}