@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

package/spec/slots.md

@@ -50,7 +50,7 @@ experience a failure. *(Binding non-goal: no ceremony that can't scale down.)*
 | `slots.memory` | path | no | constitution — thesis 1 *(memory)*; [`memory.md`](../core/operating/memory.md) |
 | `slots.repos` | path | no | constitution — thesis 1 *(repo cards)*; [`repo-card.md`](../core/templates/repo-card.md) |
 | `slots.tasks` | path | no | content — [`tasks/`](../.portulan/tasks/); constitution — BMAD, the story file as atomic context unit |
-| `slots.handoffs` | path | no | content — [`handoffs/`](../.portulan/handoffs/); [`loop.md`](../core/operating/loop.md) — a session ending with work not committed and pushed ends with one |
+| `slots.handoffs` | path | no | content — [`handoffs/`](../.portulan/handoffs/); [`loop.md`](../core/operating/loop.md) — when declared, the Stop-gate checks this series for open work; when absent, it asks to commit and push without a handoff |
 | `slots.proposals` | path | no | content — [`proposals/`](../.portulan/proposals/); [`evolution.md`](../core/operating/evolution.md) |
 | `slots.context` | path | no | criterion — milestone 12, *`compile` emits Claude Code's on-path and on-invoke targets*; [`context.md`](../core/operating/context.md) — the four load tiers |
 | `verify` | structured | **for a governing kind** | criterion — *verify recipes*; [`verification.md`](../core/operating/verification.md) — the workspace sets the default |
@@ -308,12 +308,21 @@ demonstration that a structured slot earns being structured. Recorded in custome
 ```json
 "verify": {
   "default": "{recipe-id}",
+  "stopTimeout": 360,
   "recipes": [
     { "id": "{recipe-id}", "run": "{command}", "requires": ["{tool}"], "doc": "{path}" }
   ]
 }
 ```
 
+`stopTimeout` is optional, added in 2.14: the Stop recipe deadline in seconds,
+undeclared at 90. A whole number from 1 through 2,147,423 keeps both Node timers
+in range. `doctor`, `compile` and the Stop runner refuse invalid values and
+declarations below 2.14. Recompile after changing it: the outer Stop hook gets
+sixty additional seconds. Both command and deadline come from the trusted
+hook-told workspace; a payload cannot select executable policy. See
+[execution and cap recovery](../cli/recipe-runner.md).
+
 `requires` exists because of an exit code. The recipes distinguish *red* (exit 1, the check ran and
 failed) from *could not run* (exit 2, a tool is missing), and that distinction is worthless if nothing
 declares what was needed. Customer zero now has two recipes with different needs — one POSIX-only, one
@@ -574,69 +583,50 @@ behind it, rather than left for a reader to assume the rail covers both halves.
 earlier, or later without a tighter cap, is the same hand edit, since it unbinds what the cap bound,
 and the same gate holds it for the same reason.
 
-## `handoffs` — an index over a series nobody can consolidate
+## `handoffs` — an individual cap and a generated window
 
-Added at 2.5, and it is deliberately one key. `slots.handoffs` is the series; this object says where
-its generated index goes. The same split as `memory` above, built by the same generator. A workspace
-keeps its index or not, and a copy on disk says which: a kept copy is byte-compared by the same recipe
-and regenerated by a write; with none, `index --check` renders the series, which proves every handoff
-yields a line, and nothing is written. This repository keeps none since 2026-09-23: a committed copy
-conflicted on every merge that added a handoff.
+`slots.handoffs` names the append-only series. `handoffs.index.path`, required whenever `handoffs`
+is present, names the derived index outside that series. A kept copy is byte-compared and regenerated;
+with none, `index --handoffs` prints it on demand. Without budgets the full series renders as before.
 
 | Field | What it is |
 |---|---|
-| `index.path` | Where the generated index is written. Must resolve **outside** `slots.handoffs` — see below. |
-
-`index` is **required whenever `handoffs` is present**, which is the one way this object differs from
-`memory`. There an object with no `index` is coherent: a workspace may rail its store's size and
-generate nothing. Here there is no budget and exactly one key, so `handoffs: {}` configures nothing —
-a no-op that reads as configured to anyone who greps for it, the same failure
-`librarian.staleness.proposal_days` without `slots.proposals` is refused for. Unlike the two
-conditional requirements below, this one *is* expressible in the declared subset, so the schema
-carries it rather than `doctor`.
-
-**Why it exists.** [`loop.md`](../core/operating/loop.md) has said since the handoff-cadence rule landed
-that *"the librarian that mines the series is milestone 5"*, and the series had no index at all while
-the store it sits beside had one. Measured on this repository the day the milestone-5 row was amended:
-the handoff series was **3.4×** the memory store. The layer with the index was the small one.
-
-**Every field on a line is derived, and the two carriers differ from the store's on purpose.** A
-record's title is its **filename** — [`memory-entry.md`](../core/templates/memory-entry.md) prescribes
-no heading, and most records carry none, so the filename is the only title every record has. A
-handoff's title is its **H1**: the filename leads with an ISO date and continues as a slug, so a
-filename-derived title reads `2026 07 28 the librarian goes on a cron` — a string no reader navigates
-by and no cross-reference uses. Every handoff in this repository carries an H1, so the heading is the
-carrier that actually exists here, and one that does not is **failed** rather than titled from its
-filename: a generated line whose title the generator invented is the one thing a generated file must
-not contain. The date is derived from the filename, which is where the cadence rule already puts it.
-
-**Its siting rule has two enforcers rather than one, and neither is redundant.** An index inside
-`slots.handoffs` is either a dated handoff to `docs.sh`'s `record` check or, carrying no date, failed
-by that check for exactly that. `index` refuses the siting outright, because it cannot render a series it would then be
-a member of. The second enforcer is not a second opinion: the generator physically cannot proceed,
-while the recipe is what catches a hand-placed file the generator never saw.
-
-**There is no budget here, and the absence is the argued half.** A budget's only permitted remedy is
-consolidation — merge, compress, split, retire ([`memory.md`](../core/operating/memory.md)) — and a
-handoff series is append-only by construction. Retiring a handoff to buy headroom destroys the record
-it exists to keep; **splitting one** — the move 2.8 added for the per-record rail — leaves the series
-no smaller; and raising the budget in the change that breached it is the one repair that doctrine rules out. Every
-remedy such a budget could ask for is barred, which makes it a rail designed to be broken — and a rail
-that fires with no legal repair is how a whole recipe gets switched off.
-
-_That test is the one the store's own aggregate byte budget later failed — which is why **this
-repository's workspace** swapped `kilobytes` for the per-record cap at 2.8 rather than widening it. The
-definition replaced nothing: both keys stay legal and a workspace may declare either. The argument this
-paragraph makes about handoffs is the argument `0025` makes about `kilobytes`, and it was written down
-before the case arrived._ Whether
-the series should be railed on some other axis is a **maintainer's question**, deferred to the
-reconciliation that follows milestone 5 rather than pre-answered here in the shape of an unused key.
-
-**What the pass reads that this object does not configure.** Record ages come from git for both series,
-and the handoff series is **reported** — count, oldest, total size — with no threshold and no demotion
-draft. That is not an omission: `librarian.staleness.record_days` drafts a demotion, and drafting one
-against an append-only series would recommend the single repair the paragraph above rules out, weekly,
-forever.
+| `series.budget.record_tokens` | Optional positive integer cap, added in 2.15, counted at explicit `context.ratio`. |
+| `series.budget.cutoff` | Required real YYYY-MM-DD date beside the cap; only later handoffs are bound. |
+| `index.path` | Generated index path, outside `slots.handoffs`. |
+| `index.budget.tokens` | Optional positive integer budget on the complete rendered index, added in 2.15. |
+
+Accepted [proposal 0037](../.portulan/proposals/0037-a-handoff-is-budgeted-where-it-is-written.md)
+keeps the series unbudgeted: deleting history cannot repair a size rail. An individual new handoff can
+still be compressed before merge, or facts moved to their owning records and linked. Never split a
+handoff, delete a decision's why, raise the cap or move the cutoff to repair a breach. The cutoff is set
+at the declaring change's date or newest merged handoff's date, whichever is later; the cutoff day
+itself stays unbound. Tightening the cap or lowering the ratio may advance it to exempt merged history;
+it never moves backward. Review holds these history-dependent rules and prevents backdating new work.
+
+`index` checks filename dates wherever a series is declared, with or without an index or cap: a real
+YYYY-MM-DD prefix, no more than one day beyond UTC today. An H1 is required only when rendering an
+index; titles come from that heading, dates from filenames. Each handoff's full UTF-8 byte length,
+corrections included, is converted with the same rounded bytes/ratio estimate as the context report.
+Every bound overage is red, with its count, cap, excess and repair; pre-cutoff overages are notes.
+Either token budget without an explicit ratio is refused by doctor and direct index calls.
+
+A budgeted index lists a contiguous newest-first prefix of whole lines. Header, separators, omission
+notice and trailing newline all count. The notice names the omitted count and source directory; no
+source record moves or disappears and no second index level exists. If the newest entry cannot fit,
+none are listed. A budget too small even for the header and notice is refused with its minimum.
+Neither series nor index is part of a boot or the always tier. Context and doctor report count, total,
+median, the three largest and rendered index bytes/tokens even without a tree, naming estimated or
+declared ratio and bound versus historical overages. Init offers independently optional 3000-token
+budgets, requires a supplied ratio on acceptance and computes the cutoff at write time from the same
+regular Markdown entries and filename-date boundary the index uses. Unrelated files cannot advance it;
+invalid selected dates or file types, or an uninspectable series, stop record-cap adoption before
+writing. Supplied ratio provenance is not proof of host calibration. Upgrade adopts neither policy
+nor ratio automatically.
+
+The librarian still ages the series from git and drafts no staleness demotion against it: retiring
+history is no repair. The session-end gate checks existence and today's date only; the cap is the
+index verify rail. The one-day cutoff gap and history-dependent no-raise rules remain review duties.
 
 ## `personas` — where a pack-declared memory scope lands, and how anyone can tell it did
 
@@ -713,8 +703,8 @@ one source for what each load tier holds; this object is its machine half, as `m
 | Field | What it is |
 |---|---|
 | `always.budget.tokens` | The most tokens the always tier may load, counted at the ratio below. |
-| `ratio.bytes_per_token` | Bytes per token, as a host's exact count measured them. At least 1. |
-| `ratio.calibrated_by` | The host whose exact count calibrated the ratio, by the id `compile` gives it: `claude-code`. |
+| `ratio.bytes_per_token` | Manually declared bytes per token for the host's measured domain. At least 1; provider estimates are qualified below. |
+| `ratio.calibrated_by` | The declared compile-host/domain ID. Doctor matches `claude-code` or `agents-md` to its reported format; a different or unknown valid ID is labeled as extrapolated. Provider/model provenance belongs in the count report. |
 
 ```json
 "context": {
@@ -729,30 +719,48 @@ it. Those are dependencies the subset can state, so they are the schema's and jo
 conditionals. A ratio alone is a legitimate shape: it is what a report in tokens needs, and the default
 is the report.
 
-**Declared, not measured per run.** The exact count asks the host, which is a network call no verify
-recipe may make, and a ratio that moved between runs would make one tree red on one run and green on the
-next. So the ratio is measured exactly on demand and declared, with the host that measured it. There is no
-date field, because the commit that changes the ratio dates it, and one ratio rather than one per host,
-because nothing yet reads a second.
+**Declared, not measured per run.** On-demand counting is a network call no verify recipe may make,
+and a ratio that moved between runs would make one tree red on one run and green on the next. There is
+no date field, because the commit that changes the ratio dates it. One declared ratio is shared by the
+two measured project formats. Reports compare `calibrated_by` with the format ID (`claude-code` or
+`agents-md`); a nonmatching or unknown ID makes that use an explicit extrapolation. The declaration
+still accepts any valid host slug. No second per-host ratio is declared.
+
+For [#506](https://github.com/sleepy-panda-srl/portulan/issues/506), Marius accepted “Provider count with
+stated limit” on 2026-11-09. `doctor --count-tokens MODEL_ID` and the direct context diagnostic submit
+the measured Claude Code project corpus to Anthropic, which returns an estimate that may differ from actual host
+usage and includes API framing. The effective ratio is approximate and manual; neither command writes
+this object or invents a `calibrated_by` provider ID. An empty corpus produces no request or ratio.
+The original exact-host wording is historical acceptance, not a claim of current host integration.
+See [the counting boundary](../core/operating/context.md#the-always-tier-is-budgeted-in-tokens).
 
 **Named for its tier.** Only the always tier is budgeted, and the budget sits under `always` so a budget
 on a later tier would sit beside it rather than force a rename, which would be a MAJOR.
 
 **Nothing is defaulted**, on memory's rule: an undeclared budget is not checked. `doctor` refuses a
 declared token budget that is not a positive integer, as it refuses the memory budgets, and a ratio under
-1, because a token covers at least one byte and a smaller figure is tokens per byte entered inverted.
+1, guarding against inverted units. Provider framing can put a tiny corpus below that floor; such a
+ratio is reported but cannot be declared.
 Both are `doctor`'s because the subset has no `minimum` and cannot say `integer`. `doctor` also refuses
 `context` in a manifest declaring a version before 2.9, whose own validator refuses it as unknown: the
 key is gated from birth, when no manifest can newly fail the check.
 
 **What checks the budget itself.** `doctor` measures the always tier of every workspace that declares
-a `tree`, through [`../cli/context.mjs`](../cli/context.mjs), and fails it over a declared budget, or
-where a declared budget cannot be judged; with none declared it reports the figure. _(This paragraph read
+a `tree`, through [`../cli/context.mjs`](../cli/context.mjs), for Claude Code and root vendored AGENTS.md.
+Doctor reports both automatically and judges the same declared cap independently for each, never
+summing separate contexts. AGENTS includes the file's inline guidance and pointer text without opening
+targets or expanding at-sign text; personal, above-tree, nested and plugin files are excluded. An absent
+optional root is zero; present unmeasurable sources, including an escaping AGENTS root, are reported
+unmeasured. A declared budget then cannot be judged and fails. Without a budget, measurement does not
+change the verdict. The default context/boot line and optional provider request stay Claude-specific;
+doctor validates both applicable budgets before requesting that count. _(This paragraph read
 *"What nothing checks yet: the budget itself"* until that report landed, and it was true then:
 [`a-mandate-nothing-checks-is-already-broken.md`](../.portulan/memory/a-mandate-nothing-checks-is-already-broken.md)
-is why no workspace here declared the key before something checked it.)_ No workspace in this tree
-declares it now either: Portulan's own contribution is railed by this repository's recipes, not by a
-budget in its manifest. And, as with memory, no checker establishes that a budget was not raised in the
+is why no workspace here declared the key before something checked it.)_ Neither this repository's
+workspace nor the demo workspace declares it: Portulan's own contribution is railed by this repository's
+recipes, not by a budget in its manifest. The synthetic
+[budget demonstration fixture](../cli/fixtures/context-budget/) does declare one. And, as with memory,
+no general checker establishes that a budget was not raised in the
 change that breached it.
 
 ## `sessions` — the host switches that change what a fresh session writes
@@ -775,17 +783,19 @@ Added at **2.11**, from `0038`'s rules 3 and 4 and row 12's cache-lifetime compi
 ```
 
 **Nothing is defaulted.** An undeclared switch is the host's own default and `compile` emits nothing for
-it, so a manifest without the key compiles byte for byte as before. A switch is declared once an A/B run
-has shown that it cuts spend with no loss, and [`sessions.md`](../core/operating/sessions.md) says which
+it, so an existing policy-backed manifest without the key keeps the same settings bytes. A switch is
+declared once an A/B run has shown that it cuts spend with no loss, and [`sessions.md`](../core/operating/sessions.md) says which
 sessions keep what a switch removes.
 
 **Two scopes, because the host has two.** `git_instructions` and `cache_lifetime` are project settings on
-Claude Code, so `compile` writes them into the settings it already generates from `gates`, and they reach
+Claude Code, so `compile` writes them into its native settings, independently of a gate policy, and they reach
 every session there, interactive or not. The exclusion is no setting at all: Claude Code 2.1.281 takes it
 only as a command-line flag or an SDK option, so only whatever starts a session can ask for it. `headless`
 is therefore read by Portulan's own runners that start sessions, today [`../cli/warm.mjs`](../cli/warm.mjs),
-which the package does not ship, and never compiled. A workspace with no gate policy has no settings
-for the first two to ride, and `compile` says that it compiled neither.
+which the package does not ship, and never compiled. Full compilation of an authored `repository`,
+`demo` or `portfolio` workspace also emits native restart advice and these declared switches without a gate policy. The settings contain no permissions
+or verification Stop hook; explicit `spend.restart: "block"` adds only the advisory Stop command.
+Missing manifests and pointers do not become governing workspaces.
 
 **Offered to an adopter, and still never defaulted** (2026-09-24). `init` offers `cache_lifetime` `"5m"`
 with what it saves and what a pause costs, asking once at a terminal or taking `--cache-lifetime`, and on
@@ -811,6 +821,7 @@ workspace computes it at, and what a crossed threshold does.
 | `multipliers.write["5m"]` | What a five-minute cache write costs, as the same multiple. At least 1. |
 | `multipliers.write["1h"]` | What a one-hour cache write costs, as the same multiple. At least 1. |
 | `horizon.requests` | The requests still to go at which the restart threshold is judged. A positive integer. |
+| `resume.tokens` | Additional restart expense in uncached-input-token equivalents, finite and nonnegative; absent means unknown. Added in 2.16. |
 | `restart` | `"advise"` or `"block"`: what a crossed threshold does. Undeclared, `"advise"`. |
 
 ```json
@@ -821,36 +832,40 @@ workspace computes it at, and what a crossed threshold does.
 }
 ```
 
-**What reads it.** A session is told to end into a handoff once its context passes
-`C* ≈ F × (1 + m_w / (n × m_r))`: `F` the fresh context, `m_r` the read multiplier, `m_w` the write multiplier
-at the lifetime the host recorded for the session's writes (the five-minute one where the records do not say),
-and `n` the horizon. [`../cli/ledger.mjs`](../cli/ledger.mjs) reads the key from `<dir>/workspace.json` when
-run with `--workspace <dir>`, and computes every threshold its report states at it. The restart advisory,
-[`../cli/advisory.mjs`](../cli/advisory.mjs), is handed its command and the host's payload and nothing else,
-so `compile` writes the figures onto each of its commands, the `PostToolUse` and `UserPromptSubmit` hooks, the
-status line and, where `restart` declares it, the block, as `--read`, `--write-5m`, `--write-1h` and
-`--horizon`, and its drift check holds them to the manifest: an edit to `spend` is drift until recompiled. A
-workspace with no gate policy has no settings for them to ride, and `compile` says that it compiled nothing.
-Every threshold the ledger or the advisory prints says whether its multipliers are declared, and so does a
-ledger report with no threshold to judge.
-
-**Declared, not defaulted.** Undeclared, both price at the general multipliers, a read at a tenth and writes
-at 1.25× and 2×, over a horizon of 20 requests, and say `undeclared`. That is ruling 2's answer to a spread no
-one figure fits: a model's cache reads cost between a fortieth and a tenth of an uncached input token. The
-general tenth puts the restart line early, which is the cheaper way to err, since a restart that comes too
-soon costs a fresh write and a handoff, and erring the other way, where reads cost a tenth, costs about four
-times more in excess reads over 20 requests. A declaration makes a team's contracted rates and its host's real
-prices one value. Either half may be declared alone, and the other keeps its general figures. The three
-multipliers are one set, because a threshold priced by one declared figure and two general ones would be
-priced by nobody's.
+**What reads it.** `cli/ledger.mjs --workspace <dir>` and the compiled advisory
+commands compute `C* = F + (F × m_w + R) / (n × m_r)`. Here `F` is the first
+recorded context after startup or compaction, `n` requests remaining, and `R` is
+`spend.resume.tokens` (optional since **2.16**). `R` is additional restart expense
+in uncached-input-token equivalents, excluding the existing fresh-context write
+and baseline reads. Include handoff output, boot/state recovery and additional
+rereads over the selected horizon. These are weighted cost units: 2,000 output
+tokens at 5× contribute 10,000 equivalents. A finite nonnegative number, including
+explicit zero, is priced; absent is unknown and the reported threshold is only a
+lower bound. No automatic predictor fills it.
+
+`compile` writes `--read`, `--write-5m`, `--write-1h`, `--horizon` and
+`--resume-tokens` on all advisory commands where declared, with drift checked.
+A harness may supply its task's estimates on these commands; no task-file resolver
+exists. A horizon is requests **remaining**, does not decrement automatically and
+must be revised by the caller. For example, `spend.horizon: {"requests": 3}` and
+`spend.resume: {"tokens": 10000}` price a short task's expected remainder.
+
+**Declared, not defaulted.** Undeclared multipliers remain read 0.1× and writes
+1.25×/2×, with a default horizon of 20. Advisory, status and ledger name the horizon
+and its origin, the multipliers and priced/unknown resume cost. Unknown cost or a
+default horizon produces conditional advice, never a claim that restarting must
+cost less. The caller supplies estimates; no configuration is silently installed.
 
 **`restart`: a block, only where declared.** `"advise"` is the advisory every workspace has: the line once,
 with a tool result or at a prompt. `"block"` keeps that line and adds a block at the end of a turn: at the
-first stop whose last recorded request is at or past the threshold and that no block provoked, the advisory's
-own `stop` command, which `compile` writes as a second `Stop` command beside the Stop-gate's, holds the turn's
-end with the line as its reason, once in a session and again after each compaction, and the turn goes on. A
-stop that a block provoked is never held, since a host that gives that retry a new session id would find no
-record of the hold and hold it again. It is the advisory's command rather than a reason inside the Stop-gate,
+first stop with an explicit horizon and resume expense, finite strictly positive
+estimated savings `n × read × (C − F) − write × F − R`, and no preceding hook
+block. Equality never holds, and comparison uses unrounded arithmetic rather than
+the displayed whole-token threshold. Without both estimates an existing block
+declaration reports conditionally without holding. Retry protection uses the
+host's `stop_hook_active` marker; omitting it while rotating session identities
+can repeat holds. A hold is once per session and again after each compaction.
+It is the advisory's command rather than a reason inside the Stop-gate,
 so the gate's counters and caps stay about the recipe and the handoff; and nothing ends the session, which
 stays the agent's or the human's act. `0038`'s *Enforcement* says the block comes *instead* of the line, and
 it is read here as *added*, because the line is what reaches an agent mid-stretch and a headless run's only
@@ -858,17 +873,20 @@ stop is its last (the coordinator session's delegated call of 2026-09-24); where
 the line, the block costs one request. Ruling 3 makes the block a workspace's own choice, so `init` asks
 nothing about it and `upgrade` offers nothing: the threshold is an estimate, and one priced at the general
 multipliers comes early for a model whose cache reads cost less than a tenth, where a block would hold a turn
-short of its real line. Undeclared or `"advise"`, the settings compile byte for byte as before; where
+short of its real line. In the existing policy-backed path, undeclared or `"advise"` settings retain their bytes; where
 `"block"` writes the command, `compile` says so on every run.
 
-**What is not here.** Ruling 2 has `init` offer the declaration from the host's own pricing setting where the
-host exposes one, else from a dated per-host table in the engine. Both are keyed by the model a host records,
-so both wait for their own change: until then `init` offers no figures, and a workspace writes its own by
-hand. Nothing checks a declared figure against what the workspace is billed; keeping it true is the declaring
-workspace's work.
+**Offered by `init`, never written without acceptance.** For Claude Code's last recorded main-session
+model in this repository, `init` offers a representable file-based managed `modelPricing` override,
+else its dated vendor table, else the general multipliers. It offers the horizon independently as
+requests still to go. `--multipliers '<JSON>'` and `--horizon <requests>` (or the same string answers in
+`--answers`) declare either key without an interview; a pointer refuses both. Accepting either drafts
+spec 2.12. The [pricing offer](../cli/spend-offer.md) names the supported IDs, matching and file-source
+limits. No network request is made. Nothing checks a declaration against a bill or a future model;
+keeping it true is the declaring workspace's work.
 
 **Checked by the schema and by `doctor`, and refused by every reader.** The schema holds the shape: both
-halves of `multipliers`, both lifetimes of `write`, and no key it does not name. The subset types the four
+halves of `multipliers`, both lifetimes of `write`, and no key it does not name. The subset types the numeric
 figures only as `number`, so `doctor` holds the read above 0 and at most 1, each write at least 1 and the
 horizon to a positive integer by hand: a token read from cache costs something and never more than the same
 token sent uncached, and writing one costs at least what sending it uncached does. Figures each in range can
@@ -876,11 +894,15 @@ still give no threshold, since it divides each write by the read, so `doctor` al
 divides past the largest number, which would put the restart line at Infinity, where no session reaches it.
 The ledger, `compile` and the advisory hold the same ranges themselves rather than trusting that `doctor` ran.
 The first two stop with exit 2; the advisory, whose exit 2 would erase the person's prompt, says once on
-stderr what it could not use and prices that half at the general figures. A threshold that a session's fresh
+stderr what it could not use and reports conditionally with fallback figures; any invalid flag prevents a Stop hold. An invalid resume estimate stays unknown. A threshold that a session's fresh
 context still carries past the largest number is none: the ledger stops with exit 2, and the advisory says it
 is not known. `doctor` refuses the key in a manifest declaring a version before 2.12, gated from birth as
-`sessions` was, and `restart` in one before 2.13. `compile` refuses `restart` there too, with exit 2 and
+`sessions` was, `restart` in one before 2.13, and `resume` before 2.16. Doctor and compile check the finite nonnegative resume bound independently. `compile` refuses `restart` there too, with exit 2 and
 nothing written, so that no block is compiled from a declaration its own version's validator refuses.
+For declared `restart`, the compiler requires a string `MAJOR.MINOR` on major 2, minor at least 13;
+missing or malformed versions and other majors stop with exit 2 before artifacts change. The compiler
+still accepts future minors on major 2 for this key; this is not a general manifest-version check or
+a claim that `doctor` accepts those versions.
 `restart` is one of two strings, which the subset types in full, and the ledger and `compile` refuse any other
 with exit 2.
 
@@ -907,14 +929,15 @@ The guidance itself, which is what the host loads.
 | Key | What it is |
 |---|---|
 | `tier` | `always`, `on-path`, `on-invoke` or `on-read`: `0036`'s four tiers, spelled as that proposal spells them. |
-| `paths` | On-path only, and required there: globs, relative to the repository the workspace governs, that load the unit when the agent first touches a match. A list, in flow form as above or as a block list of `- ` items. |
+| `paths` | On-path only, as an alternative to `target`: globs, relative to the repository the workspace governs, that load the unit when the agent first touches a match. A list, in flow form as above or as a block list of `- ` items. |
+| `target` | On-path only, as an alternative to `paths`: a literal child-directory `CLAUDE.md`, such as `api/CLAUDE.md`. Added within the existing 2.10 unit contract to complete accepted `0036`; older compilers reject this new unit field, so upgrade the compiler before using it. |
 | `description` | Every tier but `always`, and one line: what an agent reads to decide whether to open the unit. It is a skill's description on a host that lists skills, and the pointer line wherever the unit degrades to one. |
 
 **The tier is declared, never inferred**, and a unit sits in one tier, so what a unit costs is what its
 tier costs and nothing has to read the file to find out where it belongs.
 
 **`compile` emits it, per host.** For Claude Code, an `always` unit is an unscoped rule, loaded into every
-context; an `on-path` unit is a rule scoped by `paths:`; an `on-invoke` unit is a project skill, whose
+context; an `on-path` unit is either a rule scoped by `paths:` or the nested instruction file declared by `target`; an `on-invoke` unit is a project skill, whose
 description is always loaded and whose body loads when it is invoked; and an `on-read` unit is one line in
 an unscoped index of pointers, naming its file, its size in whole KB and its description (the size since
 2026-09-24, so a session knows what it passes over), while its file stays where it is for the agent to
@@ -927,8 +950,54 @@ each rule it wrote: it rewrites or removes only a rule the marker lists, stops w
 replace one it does not list, and stops too where the directory holds Markdown files and no marker in its
 form. It writes and removes nothing through a link.
 
+**Nested targets use two portable ownership records.** The first-line HTML mark binds the workspace,
+source and canonical target relative to the project; `.claude/rules/portulan/.instructions` pairs that source with its
+target. Both are committed, so clones can regenerate and check the same files. A missing owned file or
+changed body is repairable drift (`--check` exits 1). A human file, missing/torn/foreign mark or registry,
+link, nonregular output or ambiguous case-only move refuses before compilation writes anything.
+Complete atomic writes and exclusive new claims prevent a pending target from replacing a human file
+that arrives after planning. Intermediate registry rows retain old and new ownership until publication
+and stale cleanup finish, so a later run can recover an interrupted move. Only proved-owned files are
+retired when a target, tier or unit changes. Split/join rollback checks post-write bytes and file
+identity, recreates a deleted file exclusively, and preserves later human changes while reporting
+incomplete recovery. Complete prepared temporary files are recognized only by their reserved names
+and validated ownership records or destination-bound marks, and removed on retry. Malformed or
+unproved debris is preserved for manual review. Impossible stable multi-source records are refused.
+When a target is absent after interruption, agreeing proved artifacts retain its observed mode.
+Those witnesses and their source ownership survive until replacement publication, including a
+source rename and another interruption. Disagreeing modes refuse. A new target without an observed
+entry or proved permission witness uses ordinary creation permissions.
+Existing physical path spelling must match the declared target; distinct case-sensitive paths remain
+independent. Owned target sets use one spelling for every shared directory prefix, including pending
+and retired rows. Init projects the atomic writer's parent-directory permissions, not a file-write check.
+Read-only checking requires no mutation permission, and stable nested output
+produces no registry transition. Source slots and compiler control directories are reserved.
+
+A target has 1–32 child directories, each at most 128 ASCII characters, starting with a letter or digit,
+then letters, digits, dots, underscores, spaces or hyphens; no trailing dot/space, device names, globs,
+backslashes, traversal or a directory named `CLAUDE.md` (case-insensitive). That last exclusion
+prevents a target from becoming another target's ancestor file. The full path is at most 1,024 characters and ends exactly `CLAUDE.md`.
+This bounded portable subset avoids platform-dependent ownership aliases. Two units cannot claim one
+target, including a spelling differing only in case. `target` and `paths` are mutually exclusive.
+Nested bodies refuse actionable at-sign imports using the shared lexer, including absent, absolute,
+home and target-relative paths, without probing them. Supported code spans and fences remain literal.
+The body therefore cannot acquire a new import by moving beside a different file.
+
+The on-path claim assumes Claude starts at the project root. A session started inside the subtree may
+load its ancestor `CLAUDE.md` at startup; an explicit root import can load it eagerly too. Project-root
+budget accounting excludes unimported nested files and includes files explicitly imported by its roots.
+See [Claude's loading contract](https://code.claude.com/docs/en/memory#how-claude-md-files-load).
+Prospective compilation includes pending pre-existing guidance and measures its after corpus when
+representable. Native absolute imports may withhold that optional figure; a successful write measures
+the actual emitted result. An explicitly imported nested body can change that domain.
+Vendor switches recheck observed identities and bytes before retiring material, preserve changed or
+newly arrived files, and never recursively remove the old residence. Their residue advice uses the
+manifest's actual governed tree.
+The nested file's pure body is emitted once; its derived subtree scope is used for hosts' pointer
+fallbacks. The compiler does not emit a second scoped rule for it.
+
 **Checked by `compile`, not by the schema or `doctor`.** The subset cannot see inside a file, so the
-frontmatter is its consumer's to refuse: an unknown key, a tier outside the four, `paths` on a unit that is
+frontmatter is its consumer's to refuse: an unknown key, a tier outside the four, `paths` or `target` on a unit that is
 not on-path or reaching outside the repository, a missing `description` or one on an `always` unit, a unit
 with no guidance under its frontmatter, a link out of the workspace or into a directory `compile` writes into,
 a slot in one of those (`.claude/`, or the workspace's `compile/`, neither of which `vendor` carries), a name
@@ -955,6 +1024,73 @@ in it still reads from the repository root, as it did in `CLAUDE.md`.
 puts every section back as it stands, saying which one the digest shows edited since, and refusing a unit
 re-tiered since, or a file not at the top of this slot, rather than undo its tier or remove it.
 
+**The CLI split and join can resume an interrupted source migration.** Before claiming a source,
+`instructions --write` records the exact original operation in the reserved project-root directory
+`.portulan-instructions-journal` (mode 0700, metadata 0600). A retry with the original split or join
+command restores held originals and proves the saved operation again with the same planner before
+continuing. Units precede split roots; join roots precede unit retirement. Exact bytes, modes and
+recorded identities distinguish the operation's own publications from an independent save, even an
+identical replacement. A conflict preserves both entries and names the retained journal or claim.
+The intended whole source set and regenerated guidance must agree before commit is recorded.
+An unchanged or absent second root remains a dependency of the proof, rechecked before source edits
+and completion. Initial observations of both roots and original operands must be ordinary singly
+linked entries before a journal is created; an unsupported alias refuses without leaving a journal.
+A newly arrived reference cannot authorize retirement of the unit it names. Live references include
+moved markers and actionable native `@` imports, resolved relative to each root with the import lexer;
+inline and fenced examples stay literal. Normalized in-project paths and file or directory aliases
+are compared with direct operands even when the unit is absent. Reference discovery reads the two
+roots, without traversing imported bodies. Read-only split/join runs the structural source checks
+before offering a write; join checks both prospective root images for references to units it would
+retire. Write-time checks still revalidate those inputs. Split, join and upgrade form `0009` validate
+prospective source edits through the shared isolated
+guidance view before offering a write. The view applies creations and deletions together, recompiles
+all guidance and measures the resulting Claude corpus, including generated leads and index imports.
+Its compiler projection origin preserves engine/adopter identity and maps contained absolute lead
+and gate dependencies into the view. Aliases retain their directory entries and resolve to the same
+projected bytes, including dangling links after retirement. The view checks its emitted result again,
+retains retirements as absence through aliases, including case spellings first seen after emission,
+and distinguishes separate hard-link entries. Optional native directory aliases use the final file's
+project membership, including operands spelled outside and routes returning from outside. Their
+original lexical directory remains the base for later imports; outside bodies are not copied.
+Optional native non-files and missing imports follow
+the corpus reader; denied reads and required inputs remain checked. Linked ordinary outputs refuse
+a migration that would change or retire them; native compilation refuses to rewrite such an output,
+including a retiring marker's transitional write, before gate or persona publication. It derives
+the actual workspace, context slot, ownership and packs without reading another host's
+unrelated root. Unchanged read-only files retain their permissions. A deleted input cannot be copied
+back from the original tree by a later dependency lookup. Unrepresentable native absolute imports
+withhold only the optional numerical after forecast; successful writes measure the actual result.
+Publication snapshots retain their modes through rollback. If a changed root cannot be restored,
+rollback retains its dependent units and reports the pending operation instead of removing their text.
+Before unlinking a unit, the journal confirms its acquired public entry and pairs that fact with the
+exact claim intent, distinguished from preparation aliases. After interruption, a proved retired unit
+still referenced by either root is recreated exclusively when its path is absent, before the retry
+refuses an independently edited root. Handled failures restore the current attempt's safe images;
+the journal remains until the whole original operation has reached a proved terminal state.
+The saved proof contains only the two root observations and directly involved units; unrelated
+context bodies used to forecast index growth are not copied into the bounded journal.
+
+This is a local process-interruption protocol, demonstrated with SIGKILL, rather than
+a power-loss durability guarantee. Exclusive immutable lease children permit one live writer or
+recoverer in the same verified boot/PID namespace; a live, inaccessible or reused PID prevents
+takeover. Another namespace refuses. A cut after a source claim converges automatically. Unproved
+partial metadata, an unrecorded preparation file (including a retry killed before its first durable
+record), an ownerless initializer or an empty directory left after final cleanup can require
+manual review of the exact reported file or directory: preserve any source or claim bodies, then remove only
+the reviewed residue and rerun the original command. At initialization the source set is original;
+at final cleanup it is fully committed. Do not delete a pending journal merely to bypass its refusal.
+
+Read-only `instructions` reports a pending migration without changing it. Guidance compilation/check
+refuses a partial source set; a complete source set may still report stale generated guidance until
+the retry compiles it. `init`, `vendor` and `upgrade` refuse a pending journal; vendor also refuses
+instruction claim/staging residue rather than copying complete source bodies into another residence.
+The journal cannot overlap a current declared slot, checked again during recovery and terminal cleanup.
+Vendor refuses reserved journal paths found in its inventory and rechecks pending operations before
+publication and governance retirement. This recovery promise covers the CLI split/join only;
+upgrade form `0009` shares the source plan and guarded writes but has no process-restart journal.
+The distinction keeps the recovery record confined to this operation instead of creating a general
+workspace transaction format. Provenance: #629's independent source-interruption review.
+
 **An `always` unit may import whole files and write out another file's lead sentences or a gate policy's
 gates**, so a card carries a fact without holding a second copy of it:
 
@@ -971,6 +1107,15 @@ gates**, so a card carries a fact without holding a second copy of it:
   a path-scoped rule's included. The vendored `AGENTS.md` carries each import as a pointer line to the
   file in the vendored tree, and one for each file that file imports in turn, to the depth the host would
   load (2026-09-24), and `vendor` refuses an import leaving the workspace, which is all that tree holds.
+  **The shared reader refuses unsupported import-bearing regions by name**
+  ([#471](https://github.com/sleepy-panda-srl/portulan/issues/471)): inline emphasis,
+  escape or tag adjacency; code spans on comment-opening lines or across lines;
+  HTML blocks, indented code and indented fences; blockquoted lists; and list
+  continuations after nested lists, tags, indented code or HTML blocks. Refusal
+  replaces a guessed import set, including in nested files and instruction
+  rewriting. Syntax without an import and unrelated imports outside those regions
+  retain their supported behavior. This is bounded validation, not general
+  CommonMark or live-host lexer parity.
 - **A line `<!-- leads: <path> -->`, alone on its line, is replaced by the first sentence of each item in
   the first list of the file it names**, each item opening with a bold lead. The file stays the one
   source of those sentences, so a change there is drift until the unit is recompiled. `compile` refuses