# owed specification (0.27) owed is the acceptance ledger for a multi-agent task graph in one Git repository. "No receipt, not done": a node is complete only when owed shows it merged. Candidate acceptance requires every node obligation to be evidenced by a trusted executor or authorized reviewer, or visibly waived by the owner; merging also requires the prospective merge guard (§6.4). The design follows `pi-dag/ARCHITECTURE.md` (a3) and `formal/a4/CONTRACT.md` (a4.1 rulings). Threat model: same OS user; owed prevents mistakes, laziness and reward-hacking shortcuts by agents using the normal tools. It does not resist a process that edits the ledger file directly; it detects such edits (hash chain). Identities are claims (`--as`); the subagent rails (§2.1.3 and the writer-worktree rail §2.1.7) are rails against accidents and instructions, not security boundaries: a process can unset the variables or change directory. ### Compatibility (0.20–0.27) 0.27 adds no ledger entry kind. New plan keys are top-level `quarantine_sets` and check/invariant `quarantine_set` (§3.6). New optional entry fields are `obs.quarantine_passed`, `waive.tracked_by` and `ignorable` (§5). Historical ledgers without these additions retain their states and keys; checks without a set retain their previous definitions and keys. **0.26 reader behavior, checked against `v0.26.0`:** - `src/plan.ts`'s `parsePlan` ignores `quarantine_sets` and `quarantine_set`: it neither copies them nor rejects unknown top-level/check keys. It does **not** refuse a plan just for these keys. This is not safe interoperability: old executors omit shared names from keys and quarantine policy, and old plan recordings can discard the keys. Existing 0.27 observations can later make old replay refuse because their recorded keys differ. - `src/reducer.ts`'s `OBS_FIELDS`/`newerEntry` refuse an observation carrying `quarantine_passed` with code `version`, including a marked observation. - `waive.tracked_by` is ignored by 0.26's reducer and identical-act comparison (`src/reducer.ts`, `src/identical-acts.ts`): old waiver validation has no unknown-field check. It also ignores `ignorable` on a waive. The waiver's gate effect remains, but old views cannot track or settle that debt. - `ignorable` is unknown to 0.26. `newerEntry` refuses it on rule, obs, defer, abandon, hold and resume with code `version`. Strict-kind validation refuses it on escape, decoy-commit/reveal, adopt, launch, send, halt, evidence and sweep as an ordinary invalid entry; grant/refresh have their own unknown-field refusals. Other permissive kinds ignore it. Readers before 0.27 still refuse `ignorable` wherever they refuse unknown fields; the marker is not a retroactive compatibility mechanism. - `OWED_QUARANTINE_FILE` (§7.16) is execution environment, not a ledger field. 0.26's `src/exec.ts` neither creates nor consumes it and does not remove an inherited value. Upgrade executors/wrappers to use per-run plan delivery; a container must make the host file visible itself. - `attest --probe-trunk [--check ID] [--runs N]` (§7.27) requires the 0.27 CLI: 0.26's `src/cli.ts` refuses those options. The resulting `obs` kind and `probe: "trunk"` value already exist in 0.26 and replay there unless a new optional field such as `quarantine_passed`/`ignorable` is recorded. The pi attest tool does not expose probe mode; use the CLI. **0.27 upgrade order:** upgrade every reader — CLI, every driver and every pi session loading owed, with drivers/sessions restarted — to 0.27 **before the first 0.27 writer records shared quarantine policy, `obs.quarantine_passed`, `waive.tracked_by` or an entry carrying `ignorable`**. Upgrade result consumers and executors too. Recovery feedback can be written automatically on existing own-quarantine plans: complete the reader upgrade before allowing any 0.27 executor measurement (attest, genesis/trunk, merge, adopt or trunk probes), not merely before enabling sets or merging. Never strip fields or rewrite receipts for old readers. Once all readers support `ignorable`, later listed unknown display fields may be ignored; plan keys and nested receipt shapes have no such extensibility guarantee. `--tracked-by` and waive `--full` / tool `full:true` also require the current CLI/extension input surface. Native Cargo excusal, flaky-owner hold timing, waiver replies, admission lint and remeasure explanations add no separate serialized gate metadata. They need an upgraded executor/CLI/driver for the current behavior (§7.16, §9.9). 0.26 adds no ledger entry kind or plan key. The new optional ledger field is `obs.infra: ` (§7.26). A qualifying counted pass resolves only the consecutive setup failures on its exact subject/obligation/key; field-free historical ledgers retain their states, keys and conflict rules. **0.25 reader behavior:** `v0.25.0:src/reducer.ts`'s `OBS_FIELDS` excludes `infra`; `newerEntry` refuses the entire ledger with code `version` as soon as an observation carries it. Its automatic-remeasure validation also refuses an existing `auto_remeasure: true` receipt authorized only by the new setup predicate, even if no `infra` pass follows: 0.25 accepts only configured `remeasure_on` or shared-failure eligibility. That refusal is an ordinary invalid-entry refusal, not an unknown-field error. **0.26 upgrade order:** upgrade every reader — CLI, every driver and every pi session loading owed, with drivers/sessions restarted — before the first 0.26 writer records `obs.infra` or a setup-only automatic-remeasure receipt. These receipts are automatic, not opt-in plan policy: complete the reader upgrade before allowing any 0.26 executor measurement (`attest`, genesis/trunk measurement, merge or adopt). Upgrade before the first incompatible write, not just before merging. Do not remove fields or rewrite receipts for old readers. Other additions are runtime/results, not ledger fields: - `status.runtimeWarnings?: string[]` (§9.7): 0.25's `src/views.ts` does not consume it and its status renderer ignores it. Existing warning arrays may contain reads/timeout diagnostics; 0.25 array consumers retain those strings. - Metrics `infra: {total, byObligation}` (§9.4): 0.25's `src/metrics.ts` ignores this result property and renders its old metrics. This does not make it able to replay a ledger containing `obs.infra`. - Amendment previews/results add `covered: [{path, entry}]`; decisions add optional per-node `covered`. An all-covered amendment omits `plan` and `rule`, and an all-covered decision omits `plan` (§3, §8.3.1). In 0.25, `src/ops.ts`/`src/views.ts` do not consume `covered`; the amendment renderer and CLI assume `plan`/`rule` exist and cannot consume a 0.26 no-op result. Upgrade result consumers too, rather than treating missing entries as writes. - The driver lock may carry optional `max`, the command-line override. 0.25's `src/drive-bg.ts`/`src/drive-run.ts` ignore that unknown lock property; locks without it use the plan limit for current dispatch diagnostics (§9.8). - Ruling delivery adds optional `finished: [{node, writer}]` on `delivery` (and answer `rulingDelivery`), describing known writer calls that are neither running nor asking (§9.3). 0.25's `src/answer.ts` ignores this unknown result property; its rule renderer shows only counts/failure/unknown-writer lines. No ledger field is added. `RunView.result` already exists in 0.25's `src/types.ts`; 0.26 also retains available final text for pruned runs, which 0.25's `src/dsa.ts` discards. Worktree inspections are runtime facts, not replay inputs. Existing launch/send retries keep their recorded bytes; upgrade/restart the driver for the stopped-writer policy (§12.5.4). - Graceful stops record `drive.lock.stop-request` (§12.8), not a ledger entry. 0.25's `src/drive-bg.ts` ignores this file and signals on every stop; use only 0.26 stop/restart clients for the at-most-once graceful-stop guarantee. `--restart`, `report --cost`, `--version`/`version` and `--full` on rebase or candidate attest need a 0.26 CLI; 0.25's `src/cli.ts` refuses those new options or command forms. Review `--ack-rulings latest` / `ack_rulings: "latest"` requires 0.26 CLI/extension input support: 0.25 expects a number, not the alias. 0.26 records the computed number, which 0.25 can replay. The start tool's optional `restart` is an input flag, not a plan key: 0.25's `src/extension.ts` does not declare it and its start implementation cannot perform a restart. New ask/ready text, refusal recovery and unrelated-node batch-plan changes introduce no serialized gate/key metadata (§7.21, §9.8, §12.5.3). Concurrent adopts retain their individual total acquisition budgets (§8.4). 0.25 adds no ledger entry kind, plan key, acceptance gate or measurement key. The only new optional ledger field is `genesis.path`: the plan source recorded by `owed start` (§10.2), repository-relative when inside the repository and absolute otherwise. Historical genesis entries without it replay unchanged; an omitted-plan start whose latest genesis/plan has no source requires `owed start --plan `. **0.24 reader behavior:** `v0.24.0:src/reducer.ts` does not reject unknown fields on genesis and does not consume `path`; it ignores this field while retaining the same state and keys. Its `src/types.ts` has no genesis `path` member; ordinary `plan.path` already exists. No upgrade-before-write order is required for `genesis.path`. Older executors cannot initiate `owed start`: upgrade the CLI/pi extension to use that command, and restart pi to load it. Runtime/result additions are `StartResult` fields `initialized`, `updated`, `plan` (source path), `warnings` and `driver`; the driver's result may carry optional `alreadyRunning`. These are not ledger fields. A 0.24 driver-start consumer (`src/drive-bg.ts`, `DriveStart`) has no `alreadyRunning` branch and ignores that unknown result property; it cannot request start's reuse behavior, and its own `drive --detach` still refuses a live driver. Start is a new result, not a changed 0.24 response schema. Batch results may carry optional `deferred` counts/items per member, for the current merge key only (§8.3.4). The 0.24 batch result consumer (`src/cli.ts`, `batchMergeText`, and `src/ops.ts`, `BatchMergeResult`) does not consume that property: it ignores it and retains its old text; it is never replayed. QT adds presentation/runtime state only: JSON receipt fields are unchanged, while the existing omitted `drive.answer_grace_s` default changes from 900 to 600 seconds (§12.8.4). An explicitly recorded value retains its meaning; a 0.24 driver with no value uses 900 seconds. Upgrade/restart the driver to obtain the new wake timing. No measurement or acceptance evidence is affected. Tool exposure is host registration metadata, not ledger data (§11.2). 0.24 adds no ledger entry kind. New optional plan keys are `sweep.every` (§3.9, §7.15b), `risk` and `closure_neutral` (§3.8). New optional ledger fields are `sweep.boundary: {head, merge}` and `escape.sweep` (§7.15b); older owed refuses ledgers containing them. Identical-act retries (§8.3.3) and off-ref fast-forward adoption (§8.3.2) add no ledger field; older executors cannot initiate off-ref adoption but can replay its existing entries. Field-free historical ledgers without the new plan policies retain their states and keys. Runtime additions are `sweep-due`, `alreadyRecorded`, `reviewRequirement`, `reviewRequirements` and report/metrics `reviews.sameModel`. **0.24 upgrade order:** upgrade every reader to 0.24 — CLI, every driver and every pi session that loads owed, with each driver/session restarted — before (1) a 0.24 sweep records a confirmed boundary or automatic escape, (2) the plan sets `sweep.every`, or (3) the plan sets `risk` or `closure_neutral`. In (1), older readers refuse entries containing `sweep.boundary` or `escape.sweep`. In (2), 0.23 rejects `sweep.every` as an unknown nested plan key: once a plan containing it is recorded, old CLI, driver and pi readers cannot read the ledger state. In (3), 0.23 ignores the unknown top-level keys `risk` and `closure_neutral`. **Risk is not conservative:** a matched rule replaces the node's review for that path, and diff-wide maxima can raise or lower the requirement (§6.2a). An old executor ignoring a raising rule can merge with too few or too-low-rank reviews for the 0.24 policy; 0.24 replay then refuses the entire ledger at that merge. Conversely, a 0.24 merge relying on a lowering rule can have too few or too-low-rank reviews for the old node requirement; old replay refuses the entire ledger at that merge. Neither direction is safely interchangeable. Only `closure_neutral` used alone is conservative: an old executor ignores it and computes `closureTouched=true` for a new submit that changes closure, requiring closure-review even if 0.24 would call the change neutral. Replay retains recorded candidate facts; it does not recompute `closureTouched` for existing submits. Scheduling itself changes no sweep definition or acceptance key; risk changes requirements, not evidence keys; closure neutrality changes the closure-review fact, not full-file check hashes. 0.23 adds no ledger entry kind. New optional fields on existing entries are `submit.facts.carry`, `submit.facts.rebased` (§7.25), `defer.allowance` (§7.24), `decision` and rule `answers` (§8.3.1), and `lease_wait_ms` on `obs`/`merge` (§7.14a). The new plan permission is `allow[].defer`. Historical entries without these additions retain their states and keys. Older readers reject `allow[].defer`, executor defers and shared-only `auto_remeasure` receipts, or cannot interpret decision groups and halt semantics; upgrade all readers before using these features. **Upgrade order (ER6 + MX-P2):** owed <= 0.22.x replays a writer submit with `facts.carry` but ignores carry; when its review key changed, the node needs a new review. This is conservative, never a false pass. Those readers refuse an `executor:owed` submit with `facts.rebased` as ordinary `Entry #N invalid`, not code `version`. Readers in 0.13–0.22 refuse the whole ledger with code `version` once an `obs` carries `lease_wait_ms`; on `merge` they ignore that field. Upgrade the CLI, driver and every pi session that loads owed (restart those sessions) **before the first 0.23 measurement or executor rebase**. Leasing is on by default: any 0.23 measurement that acquires a lease, whether started by the driver, manual `attest` or `merge`, records `lease_wait_ms` on its observations/merge entries (§7.14a). This upgrade requirement is not limited to driver operations. The driver's lease uses `noWait` and retries on the next pass: its `lease_wait_ms` excludes cross-pass waiting and is a lower bound. 0.22 ships the previously unreleased 0.20.1 and 0.21 changes together. Upgrade every driver, CLI and pi plugin to **0.22 or newer before enabling `drive.merge_batch`**, issuing an explicit batch merge, or using writes globs, `waits_on` or `remeasure_on`. Older readers can misjudge batch merge guards, interpret globs as literal prefixes, or refuse new observation fields. Existing entries keep their recorded writes dialect; no migration rewrites them. String-template `exec.wrap` changes measurement keys only when configured; legacy argv wrappers and absent wrappers keep their existing keys (§7.22). No new ledger entry kind is introduced. 0.20 adds only optional fields to existing entry kinds and optional plan keys; it adds **no new entry kind**. Upgrade every driver, CLI and pi plugin together: older releases can ignore or misread new plan/observation fields, or refuse them with `needs a newer owed`. New optional ledger fields are `obs.signatures`, `obs.quarantined`, `resume.remeasure`, `resume.batch`, `submit.model` and `review.model` (§5). New plan keys are check/invariant `quarantine` and `template`, with template arguments `package`, `test`, `filters`, `min_ok`, `files`, `name_prefix`, `path` and `required` (§3.6). Runtime/view fields are not ledger entries. Without these additions keys and replay remain as in 0.17, except pooled repeat across several observations on one key (§7 RC1). 0.20.1 adds no ledger entry kind or field. Existing `obs.signatures` use a `v2|` encoding (§5, SG1); untagged signatures replay unchanged but never equal new signatures, including for signature-based defer carry. New optional plan keys are check/invariant `on_timeout` (§7.18) and global/node `drive.same_model: accepted` (§12.2). Older readers ignore `on_timeout`, reject `same_model`, or retain misleading failure/model diagnostics: upgrade executors, drivers, CLI and pi plugins together before using these keys. Receipt JSON `modelWarnings` now admits acknowledged objects as well as strings (§12.5.2). Merge-wait `ahead`/`job` are runtime-only fields (§9); old caches remain readable. No acceptance gate is weakened by diagnostic hooks, acknowledgements or retries. ## 1. Storage - Ledger directory: `$(git rev-parse --git-common-dir)/owed/` (shared by all worktrees, never committed). Override with env `OWED_DIR` (tests). - `ledger.jsonl`: one JSON object per line, append-only. Every entry has `{seq, ts, prev, kind, by, ...payload}`. `seq` starts at 0 (genesis) and increments by 1. `prev` = `hash` of the previous entry (genesis: 64 zeros). `hash(entry)` = sha256 hex of the canonical JSON (keys sorted recursively) of the entry **without** a `hash` field; the stored line also contains `hash`. - `blobs/`: content-addressed blobs (plans, logs, dispatch packets). - `cache/plans/.json` (0.10, N4): the persistent parsed-plan cache, `{v, sha, plan}`; `v` = cache format + owed version (`PLAN_CACHE_VERSION`). An op reads a plan from the in-process cache, then from this entry, then from the YAML blob; after a YAML parse it writes the entry atomically (temp file, then rename). Any read error, invalid JSON, other `v` or other `sha` means the entry is ignored and the YAML is parsed again; a write that fails is ignored: the cache never fails an op. It is a derived local file, as writable by local processes as the ledger and the blobs. `owed verify` never uses it for replay: it parses every plan blob from YAML and reads each cache entry raw. An entry of another `v` is rewritten silently (stale, not a fault). An entry of this `v` whose `sha` or plan differs from the blob, or a file that cannot be read or is not JSON, is reported in `cacheMismatch` (JSON; not a verify failure) and rewritten. `owed gc` (also `--dry-run`) removes entries whose sha no longer appears in a genesis or plan entry, and temp files older than 60 s (`GcResult.planCache`, a `Plan cache files ... removed` line); nothing is recorded in the ledger for them. - `snapshot/state.v8` (0.12, G1.4): the disk snapshot, a private derived cache of the replayed State and its replay metadata (§6, Resumable replay) at one ledger entry. One v8-serialized record `{format: "owed-snapshot/1", version: , seq, hash, digest, payload}`: `seq`/`hash` = the last folded entry, `payload` = the v8-serialized packed state (plans named by blob sha, re-resolved through the plan lookup), `digest` = sha256 of the payload. An op uses it only when format, version and digest match and the verified chain's entry `seq` has `hash`; a missing, unreadable, foreign or mismatching snapshot is ignored (and replaced), never an error. It is written atomically (temp file `snapshot/.state..tmp`, then rename; concurrent writers are harmless) after a load that folded at least 256 entries past the snapshot, or found none; a write that fails is ignored. `owed verify` never uses it for its result (§8). It lives in the private owed dir, is never committed and needs no gc: deleting it only costs one full replay. - `lock/`: mutual exclusion by atomic `mkdir`; contains `owner.json` `{pid, host, ts}`. A lock whose pid is dead on the same host is stale and may be broken. All read-check-append sequences run under the lock (§6.4). Other named locks (`merge`, `dispatch`, `genesis`, `attest-` per node, §7.11) work the same way; a wait that times out (60 s) fails with code `busy` (§7.11). - Every append: re-read ledger, verify chain tail, check guard, append the line with `fsync`, release. - **TR, torn read (0.20):** `Ledger.read()` without the ledger `lock` ignores only a final fragment without a trailing `\n`, returning the preceding complete entries with their chain verified. This is an append-in-flight tolerance, not permission to drop a malformed complete line: a complete bad line still fails with `ledger seq N: invalid JSON`. Inside `withLock` on the same Ledger instance, reads remain strict: a torn tail fails with `invalid JSON` or `incomplete line`. A crash-torn tail therefore cannot be appended after silently. Other reader paths are not covered by this change (§7.17). ## 2. Principals `Principal = {role, id}`; `role ∈ owner | parent | writer | reviewer | executor`. String form `role:id` (e.g. `owner:human`, `parent:main`, `writer:auth-api#2`, `reviewer:astra-1`, `executor:owed`). - Writers are created by dispatch: `writer:#`. - The executor is owed itself; only `owed attest`/`owed merge` produce executor observations. - The driver (`owed drive`, §12) acts as `parent:drive`. That name is the driver's only (0.6.0, G2.3): the ledger refuses, on append and on replay, an entry by `parent:drive` of any kind the driver never writes (it writes only `dispatch`, `launch`, `send`, `halt`, `rebase`, and `abandon` only for its own never-launched stale slot, §12.3 AH2), and the CLI `--as parent:drive` and the pi tools' `as: "parent:drive"` are refused for every command and tool, reads included (`parent:drive is the driver's identity: only owed drive records as it; it cannot be claimed with --as or as`); the driver passes it internally. - Owner acts are recorded with a `channel`: `delegated` (D25, the default: the main agent acts as owner with no human step), `tty` (interactive confirmation), `pi-confirm` (pi UI confirmation) or `flag` (`--i-am-owner`, shown as weaker in every view). `tty` and `pi-confirm` occur only under the opt-in gate `OWED_CONFIRM=owner` (§11). Agents must never use the flag; the skill says so. Ledgers written by 0.4.x stay valid; a 0.4.1 reader verifies and replays a ledger containing `delegated` (it never checked channel values). ### 2.1 Delegated owner (D25) A human states the task and leaves; the main agent (the top-level session) holds every authority, including the owner's. Accountability moves from pre-approval to audit: every act is in the hash-chained ledger and the brief lists the main agent's owner acts first (§9). 1. In pi, an owner tool (every tool that acts as an owner principal: plan with downgrades, adopt, waive, defer, decoy, review as owner, approve, evidence, init, …) runs with no dialog; the entry is `by: owner:`, `channel: "delegated"`. The default owner id in pi is `owner:pi`. 2. CLI: an owner command (`--as owner:`, or a command whose default principal is the owner) records `delegated` with or without a TTY, without a prompt; `--i-am-owner` stays accepted and records `flag`. The CLI's default owner principal is `owner:cli` (0.5.1, E3.3; matching pi's `owner:pi`), also with `--i-am-owner`; only under `OWED_CONFIRM=owner` it is `owner:human`. Compatibility: entries written by earlier versions keep `owner:human`; a script that matched `by: owner:human` for CLI owner acts now sees `owner:cli` (pass `--as owner:human` to keep the old id). 3. A process with `DSA_CALL` or `DSA_EXEC` in its environment (a pi-durable-subagents call) is refused for roles owner and parent, in pi tools and the CLI alike, before anything is recorded: `owner and parent acts are reserved for the main agent; this process is a subagent call (DSA_CALL)` (or `DSA_EXEC`). Reads (`status`, `why`, `report`, `brief`, `verify`, `decoy digest`) and `attest` (recorded as the executor) are not refused; the default role of such a process is unchanged. This is an accident rail, not a security boundary: a process can unset the variables. `owed drive` (and `owed_drive`) is not refused (D17 keeps starting a detached driver from a dsa call). 4. `OWED_CONFIRM=owner` (environment) restores the confirmation (§10, §11). Without it nothing ever waits on a human. 5. Every delegated owner act that eases acceptance needs a non-empty note or reason: a plan update with downgrades (`owed plan --note`, `owed_plan` `note`; the plan entry has an optional `note`), `waive` (`reason`), `defer` (`reason`), `adopt` (`note`); refused without one, nothing recorded. 6. The driver's "needs the owner" notifications read `: needs the owner (the main agent decides; owed lists the command): ; the driver leaves it alone; the main agent resolves it with: `; its owner halts for a stale review block or a stalled candidate end with `; the main agent resolves it with: ` (`views.ownerCommands`, in order: with an open candidate the brief's command for each owner item still owed, a waiver for every other item still owed and every uncleared block, and `owed abandon --note ""`; without one, as the brief's dispatch/clear hints, `owed dispatch ` first when no slot is open, then each waiver prefixed `after the writer submits a candidate:` since a waiver needs one; nothing for a merged node). The reason's own trailing `needs the owner` is not repeated. The driver's output line of a halt needing the owner reads `halt attempt , needs the owner (the main agent decides; owed lists the command): halted — `; other halts use `needs the parent (the main agent acts; owed lists the command)` (QT1). The halt rows of `status`, `why`, `brief`, `report` and entry lines use the same owner/parent wording. The ledger value `needs: 'human'` is unchanged: rendering only, no new entry shape or compatibility/version change. Evidence-only halts name the plan's role (`--as :`) and add `or --as owner:pi` (D23); no person is asked. Trunk drift is never a node halt (§12.7 Trunk drift). The commands of the brief, report and these texts omit `--as` where the command already defaults to the owner (waive, defer, adopt, approve, init) and use `--as owner:cli` where a role must be stated (owner review, owner evidence); under `OWED_CONFIRM=owner` that role is `--as owner:human`. Each such command for a candidate-bound act (waive, approve, evidence, owner review) on a node with an open candidate ends with (approve: is followed by) `--candidate ` of that candidate (G1.3, §8 act binding). 7. Writer-worktree rail (0.6.0, G2.1, F3): in a pi-durable-subagents call (`DSA_CALL` or `DSA_EXEC` set), an owed process (CLI or pi tool) whose working directory (the CLI's cwd, the tool's `cwd` argument, the pi session's directory or the process's own) is inside the open slot worktree of node X is refused `review` and `evidence` on X, nothing recorded: `a writer worktree cannot record a review or evidence for its own node; run the review from the repository root or another directory`. Waives are already refused for subagents (item 3). Like item 3 this is an accident rail, not a security boundary (§1). ## 3. Plan (content, YAML) ```yaml version: 1 trunk: main # branch name of the trunk closure: [".owed/**", "package.json", "**/conftest.py"] # check-closure path globs (pinned from base) setup: "npm ci --prefer-offline" # optional, run in every materialized tree before checks; default slot setup too slot_setup: "ln -s /shared/node_modules node_modules" # optional (0.16): string overrides setup in slots; false skips invariants: # state invariants on trunk (machine checks) - id: unit run: "npm test" timeout_s: 600 reads: ["**"] # declared read set (globs); default ["**"] min_tests: 1 # optional; parsed test count must be >= this nodes: - id: auth-api title: "Add token refresh" deps: [schema] writes: ["src/auth/", "test/auth/"] # prefixes or supported path globs (§3.7) checks: # node acceptance checks (become invariants after merge only if listed in invariants) - id: auth-tests run: "node --test test/auth" timeout_s: 300 reads: ["src/auth/**", "test/auth/**"] red: true # counterfactual: these tests must FAIL on the base with candidate test files overlaid tests: ["test/auth/**"] # files overlaid onto base for the red run (required if red) red_expect: "not ok|AssertionError" # optional regex the red-run log must match min_tests: 1 mutants: [".owed/mutants/auth/*.patch"] # optional: mutant patch globs inside the closure (read from the base) min_kill: 0.8 # optional, in (0, 1], default 1: fraction of mutants the check must kill review: {count: 1, min_rank: 1} # default {count: 0} brief: | # free text included in the dispatch packet ... drive: # optional (0.7.0): driver agents/models for this node only (§12.2); never an obligation writer: { agent: worker-cheap } # {agent?, model?}; default: the plan's drive.writer reviewer: { model: "example/model-small:high" } # default: the plan's drive.reviewer ``` A plan change that alters a node's spec, `setup`, `exec` or `closure` invalidates that node's submitted candidate: its keys were computed under the old plan. The node fields `type` (§3.1) and `drive` (§12.2) are not obligations: changing them invalidates no candidate and is never a downgrade. **Carry (0.10, N1).** When the invalidated candidate's node spec differs from the new one only in `checks`, `writes`, `type` and `drive` (plan-wide `setup`, `exec` and `closure` changes do not matter), the same `owed plan` call appends, inside the same ledger lock and right after the plan entry, a *carry submit*: a `submit` by `executor:owed` with `carry: ` = the carried submit, for the same commit at the same slot base, its facts recomputed with `candidateFacts` under the new plan (manual keys as for a normal submit). So evidence on unchanged keys (reviews, approve, evidence, measured checks whose key did not change) still counts, and the next attest measures only the changed keys. The candidate stays the writer's own commit: writer-only rules (no self-review, decoys) treat it exactly like the original. A change to any other node field (`brief`, `deps`, `review`, `title`, `approve`, `evidence`, …) never carries: the writer must see it and submit again, as in 0.9. A carry whose facts cannot be computed, or that validation would refuse, is left out (the plan is still recorded and the candidate stays invalidated), never silently: `owed plan` (and `owed_plan`) print `Not carried : ; the writer submits again`, and JSON has `notCarried: [{node, reason}]`. `owed why` and `owed status` show `candidate #C carried by plan #P from submit #S`, and `owed plan` prints one `Carried : …` line per carried node. The formal model does not cover carry (Deferred). **Amend: widen one node's writes (0.10, N3).** `owed amend --writes +[,+...] --note "" [--plan ]` (pi `owed_amend` `{node, writes, note, plan?, as?, cwd?}`) is a targeted plan update. The plan file is `--plan` (relative to cwd), else the `path` of the latest plan entry (refused when that entry has none). It is refused when the file's plan differs from the ledger's current plan (`plan file has unrecorded edits`; a comment-only difference is no difference), for an unknown or merged node, an empty path list or note, or a removal (`-path`, which requires `owed plan`). Bare paths and `+path` both mean additions. Each is a writes scope, not merely a filename: a path is already covered only when equal to an existing write or provably contained by it under §3.7 (`w === p || writeCovers(w, p)`). For example, `src/lib` under `src/*` widens ownership: the filename match does not cover the prefix range below `src/lib`. Uncertain containment is a real widening. Covered paths are skipped with `already covered by `; an all-covered amendment returns `writes unchanged` without changing the file or recording any entry. For a real widening, the edit locates the node's `writes` list with the `yaml` Document API and changes only that list's source text (a flow list gets `, path` before its `]`, a block list one `- path` line per path at the same indentation; a node without writes gets a block list through the Document API, which re-emits the file), so comments, order and style are kept; new paths are appended, paths already there skipped, and the result must parse to the current plan with only that node's writes widened. In one ledger lock amend then appends the plan entry exactly as `owed plan` would (the same drafting and guard: a widening is a downgrade, so it needs the owner or an `allow` rule of the current plan; the plan `note` is `amend : writes +. Limit: `, which also satisfies D25.5), any N1 carry submits, and a `rule` by the same principal with nodes `[]` and text `writes of widened by plan #P: +. Limit: `. The writer receives that ruling through the usual ruling path and reviewers acknowledge it (`rulings`). The edited text is written to a temporary file next to the plan file before the append (a write failure refuses: nothing recorded) and renamed over it after the append; if that rename fails, amend reports that the entries were recorded and where the recorded text is. Any refusal records nothing and leaves the file unchanged. Like `owed plan` (N2), amend retries a CAS refusal up to 3 attempts while the ledger's plan sha is unchanged; each attempt re-reads the ledger and the file, and a failed attempt removes its temporary file. **Atomic field edits (0.13, ED1–ED3, wais §65).** `owed edit --set = ... [--unset ...] [--node-new] [--rule "" [--writer]] [--resume [--after a,b] [--expect report]] --note "" [--dry-run] [--plan ]` edits the latest recorded plan file (or `--plan`, relative to cwd). Node paths are `title`, `brief`, `deps`, `writes`, `later`, `review.count`, `review.min_rank`, node overrides under `drive.*`, `checks.` (a whole mapping; its id is inferred from the path), and `checks..`. `--set` and `--unset` may repeat; assignments split at only the first `=`, and values are YAML. Sets run in argument order, then unsets; unknown paths, an unset of a missing field, malformed YAML and a mismatched check id refuse. `--node-new` adds a node from `deps`, `title`, `brief`, `writes` and check assignments; it refuses an existing id. An invariant edit is `owed edit --invariant --set = --note ""`; its id cannot change, and rule/resume options apply only to node edits. ED1 uses the `yaml` Document API and re-emits only the target map when safe, retaining its comments and keeping every byte outside it. Targets inside flow containers or containing anchors/aliases use whole-Document serialization so flow punctuation and references stay in context; comments are kept, but spacing may be normalized. Assignment values remain YAML nodes, so an alias can refer to an anchor elsewhere in the plan. A new block node appends to the nodes sequence. Every result is re-parsed and compared with the intended edited plan before it can be written; malformed YAML or a lost reference refuses. The final plan passes the same parser and hygiene checks as `owed plan`. Unrecorded semantic file changes refuse; comment-only edits are kept. ED2 uses the same plan drafting, guard, authority and N1 carries as `owed plan`/`amend`. One ledger lock guards and appends the plan, any carry submits, the optional rule naming the node (`writer` when requested), and the optional resume, in that order. All parent acts use the same principal/channel; carries remain `executor:owed`. The resume uses the prospective plan and ruling, requires an open slot and follows the normal resume validation, including `after` and `expect` (§12). A non-empty note is required, also satisfying delegated owner downgrade rules. The temporary file is prepared before the append and renamed over the source afterward, preserving its mode. A refusal records nothing, leaves the source unchanged and removes the temporary file. A rename failure after the append reports the recorded seq range and the recovery file, as amend does. `--dry-run` prints the textual diff and structured downgrades without writes or owner confirmation, including `--as owner:pi` with `OWED_CONFIRM=owner` in a non-TTY process. ED3 leaves `owed amend` unchanged. Compatibility: ED adds no ledger entry kinds or fields; its plan, carry, rule and resume entries use their existing schemas. Plan fields or resume options introduced elsewhere in 0.13 follow their own compatibility rules. **Known-red invariant debt (0.15, KR1–KR4).** An invariant may set `known_red: [{test: , fix: }]`. The list has at most 20 entries, unique non-empty names; each fix is a node of the same plan. Names are exact and case-sensitive (not globs); whitespace is preserved. This field is invariant-only and enters no check, invariant, review or other key. Adding an entry or changing its fix is a plan downgrade, recorded in the plan entry's `downgrades` as `inv: known_red "" added with fix (owner only)` or `fix changed from to (owner only)`. Only the owner may record it; no `allow` rule covers known-red in 0.15. Removal is not a downgrade. Use `owed edit --invariant --set 'known_red=[{test: "exact failing name", fix: repair}]' --as owner:pi --note "assign bounded trunk debt"`, or `--unset known_red` to remove the whole list. The existing atomic edit/plan authority, note and rollback rules apply. An entry is active while its fix node remains in the plan and has not merged. An invariant failure decided solely by named failing tests (the shared IR2 predicate: fail verdict, non-empty `failed`, no timeout, error, zero/unknown count or unmet `min_tests`, including repeat runs) becomes **W**, mark **⚠**, when every failing name is active. It is satisfied for merges and acceptance, not a measured pass or an invariant waiver. Invariant `why` receipts set `accepted: true` for E or W, and false for D (including lapsed or missing-fix failures). Its detail is `inv: known red: (fix: ; plan #)`; evidence includes the executor observations and current genesis/plan seq. An extra unlisted name, unknown names or any other failure keeps the ordinary evaluation; conflicts remain conflicts. Known-red never suppresses unlisted failures. For a fix node X's merge result, its own entries are inactive. If any of its names still fails, merge refuses with `X is the fix node of known-red on inv:, which still fail on the merge result`, even for an unchanged key or owner defer. Those names are also excluded from IR2's trunk failed-name comparison: existing trunk-red debt cannot excuse an unfixed fix node. After X merges the entries lapse, and a recurrence is ordinary red. `status`, `report` and `brief` list active debt, one line per invariant: `inv: known red: (fix: ), ...; plan #`, even when the latest observation passes. Full status also lists lapsed entries as removable with `owed edit --invariant ...`. JSON adds optional `knownRed` arrays of `{invariant, entries: [{test, fix}], plan: }` to these views; status also adds optional `lapsedKnownRed` with the same shape. Fields are absent when empty. No new ledger entry kinds or top-level entry fields are needed. Compatibility exception: owed 0.14 and older ignore `known_red` and treat the listed tests as ordinary failures (stricter); mixed versions may halt merges that 0.15 accepts; upgrade together. No compatibility flag is recorded, and the intro's version-refusal rule does not apply to this plan field. Ledgers without `known_red` keep their earlier states, keys and JSON views. Invariants removed by the owner no longer need their genesis observation. **Checks prepare their own artifacts** (0.8, L2.5). owed measures every check and invariant in a fresh temporary worktree of the candidate or merge tree (§7). Nothing that exists only in slot worktrees (build outputs, caches, `node_modules`) is present there. A check or invariant must prepare its own build artifacts, for example through `setup` or its `run` command. When a failure was environmental and the parent or owner fixes the check, the plan update supersedes the old execution block (§6.3), so it needs neither a rerun nor a waiver. Validation: unique ids; deps exist; acyclic; `red: true` requires `tests`; `writes` non-empty for nodes with checks; `mutants` (node checks only, non-empty) must lie inside the closure — each glob, read as a path, matches a closure glob, and a glob containing `**` needs a closure prefix (`dir/` or `dir/**`) covering it; `min_kill` requires `mutants` and lies in (0, 1]. Removing `mutants` or lowering `min_kill` is a downgrade. Plan changes are laws (§5) by owner or parent. Removing or weakening an obligation of a node relative to the previous plan (check removed, `red` turned off, `min_tests` lowered, review count/rank lowered, writes widened) is a **downgrade**: allowed only to the owner (or to a parent when an allowance of the prior plan covers it, §3.4), and listed in reports as ΔO⁻. ### 3.1 Worktree location and branch names (D19) ```yaml worktrees: # optional; unknown keys and bad types are errors root: ../dev/wais-worktree # absolute, or relative to the main worktree root; default .owed/wt branch: "{type}/{node}-{attempt}" # default "owed/{node}/{attempt}" nodes: - id: auth-api type: fix # optional, ^[a-z][a-z0-9-]*$, default feat; used only by {type} ``` The branch template must contain `{node}` and `{attempt}`; any placeholder other than `{node}`, `{attempt}` and `{type}` is a plan error. A plan being recorded (`init`, `plan`) is also refused (usage, nothing recorded) when `root` or the template contains a control character (a code point below 0x20, 0x7f, U+2028 or U+2029) or when the template is ambiguous, i.e. two distinct (node, attempt) pairs could expand to the same name. The rule is sufficient, not exact: `{node}` occurs exactly once, every `{attempt}` or `{type}` before it is directly followed by a literal character that cannot occur in its value (a digit for `{attempt}`; a lowercase letter, digit or `-` for `{type}`), and every one after it is directly preceded by one. So `owed/{node}/{attempt}` and `{type}/{node}-{attempt}` are accepted, `{node}{attempt}` (`a1`+`1` and `a`+`11` give `a11`) and `{node}-{type}-{attempt}` are refused. A plan being recorded is also refused when two node ids are equal ignoring case (`KB4` and `kb4`): on a case-insensitive filesystem they would share a branch ref and a worktree directory. These checks apply to plans being recorded, not to replay: a ledger whose recorded plan has such a block stays readable. A plan without the block parses to a plan without a `worktrees` key (the same canonical plan and sha as 0.4.1); a block present is filled with the defaults. Neither `worktrees` nor a node's `type` is an obligation: changing them is never a downgrade (a parent may record it), never invalidates a submitted candidate (the candidate-invalidation comparison ignores `type`), and affects only later dispatches; an open slot keeps the branch and worktree recorded in its dispatch entry (§8.1). ### 3.2 Execution environment: `exec` (D20) ```yaml exec: # optional; unknown keys and bad types are errors env: { CARGO_TARGET_DIR: /abs/shared/target } # string values, no expansion wrap: ["/abs/tmp/qa/heavy.sh"] # legacy argv prefix; alternatively a shell template (§7.22) wrap_grace_s: 30 # template-wrapper shutdown grace; nonnegative integer, default 30 parallel: 4 # 0.9: jobs one merge/adopt/genesis attest measures at once (integer >= 1, default 1) trees: reuse # 0.9: fresh (default) | reuse: stable measurement worktrees (§7.12) touch: reset # 0.11: reset (default) | always | never; tracked mtimes in reused trees ``` `env` names match `^[A-Za-z_][A-Za-z0-9_]*$` and may not be `CI` or `OWED`; a newly recorded plan (`init`, `plan`, `amend`) may also not set `OWED_TREE` (0.11). Replay does not check it, so a ledger whose older plan sets it still verifies; at run time owed's `OWED_TREE` overrides the plan's value; values are strings used verbatim (no `$VAR` or `~` expansion). The parsed plan keeps only non-empty fields: `exec: {}` and `exec: {env: {}}` are the same as no block (same plan blob, keys and views). `wrap: []` is an error. A change of `exec` is treated like a change of `setup`: it invalidates the submitted candidates (§3), attribution reruns of older blocks use the exec of the plan in force when the block was recorded (§7, step 1), and because a wrapper can weaken every check (`wrap: ["true"]` passes everything) the reducer records it as `{node: "*", what: "exec changed; cannot prove obligations were not reduced"}` in ΔO⁻: only the owner may change `exec`, so set it once. The recorded `downgrades` field of the plan entry (and the confirmation list of `owed_plan`) does not list it, as for `setup`. Plans without `exec` behave exactly as in 0.4.1; a plan with `exec` needs owed ≥ 0.5.0 to replay. `parallel` and `trees` (0.9) only schedule measurement: they are not part of `execKey` (§4.1), of any check key or of the L2 check definition, and the comparison above (candidate invalidation, the `exec changed` ΔO⁻ item) looks at `env`, `wrap` and explicitly set `touch` only. Changing `parallel` or `trees` therefore supersedes nothing, re-measures nothing and needs no owner authority (a parent may set them). An `exec:` block holding only `parallel` and/or `trees` is valid; the parsed plan keeps each of them only when it is set (`parallel: 1` and `trees: fresh` written explicitly are kept, and change the plan blob, not any key). A plan setting them needs owed ≥ 0.9.0 to replay. `parallel` must be an integer ≥ 1; `trees` is `fresh` or `reuse`. `touch` is `reset` (default), `always` or `never`, kept in the plan only when explicitly set, and requires owed ≥ 0.11.0. It affects reused trees only (§7.12), but an explicit value always enters `execKey`: changing it needs owner authority and new evidence, including when setting the default explicitly. ### 3.3 Owner approval and manual evidence (D23) Two optional node fields add obligations no executor can measure (§6.2 items 8–9): ```yaml approve: owner # the only value: obligation `approve`, discharged by the owner only evidence: # obligations `evidence:`, discharged by `owed evidence` (§8) - id: ui # ^[A-Za-z0-9][A-Za-z0-9._-]*$, unique in the node what: "looked at the real page" # non-empty by: reviewer # reviewer | parent | owner (default reviewer); the owner always qualifies ``` Unknown keys and bad values are errors. A node without them gets neither key in the stored plan (its canonical form, so a 0.4 plan's sha, is unchanged). Downgrades: `approve removed`; `evidence removed`; `evidence weakened` when its `by` changes to a role other than `owner`. Adding either, or changing an evidence `what` (a new key), is not a downgrade; it changes the node spec and so invalidates the open candidate (§3). ### 3.4 Owner allowances (D21) An optional `allow:` block lets the owner pre-authorize parent downgrades and parent adoptions. It is a list of rules; unknown keys and bad types are errors, and a rule needs at least one permission: ```yaml allow: - nodes: ["phaseA-*"] # node id globs (path.matchesGlob on the id); default ["*"] review_count: 0 # parent may lower review.count down to this (integer >= 0) review_rank: 1 # parent may lower review.min_rank down to this (1..3) writes: ["tests/", "docs/"] # parent may widen writes with prefixes inside these prefixes checks: ["ui-*"] # parent may remove/weaken node checks and evidence obligations (§3.3) whose id matches these globs defer: ["integration-*"] # owed may retain shared intermittent invariant debt (§7.24, 0.23) - adopt: ["testdata/", "tasks/"] # parent may adopt trunk commits whose changed paths all lie under these ``` `allow` is not an obligation: it is not part of any key and changing it never invalidates a candidate. - **Coverage.** A downgrade of a plan update is *covered* when a rule of the **prior** plan (never the new one) whose `nodes` match the node permits it: review count (rank) lowered to a value ≥ the rule's `review_count` (`review_rank`); every widened writes scope is provably covered by a rule's `writes` scope under §3.7; a check weakening (removed, red disabled, `min_tests` lowered, mutants removed/changed, `min_kill` lowered, definition changed) whose check id matches one of the rule's `checks` globs; an evidence obligation removed or weakened (`evidence removed`, `evidence weakened`, §3.3) whose evidence id matches one of the rule's `checks` globs. An item that reads both ways (e.g. check id `evidence`, evidence id `check`: `evidence check removed`) is covered only if every reading is. Never covered: `approve removed` (the owner's gate), `node removed`, `dependency removed`, any downgrade of trunk invariants, the plan-level `*` items (setup/closure changed, exec changed), and `allow` changes. Any change of `allow` other than deleting whole rules (some new rule deep-equals no prior rule, after defaults) is the downgrade `{node: "trunk", what: "allow changed"}`: owner only. - **Parent plan updates.** A `plan` entry by a parent whose downgrades (the detected ones and those the entry lists) are all covered is valid without an owner — a reducer rule, so it also holds on replay. The downgrades still enter ΔO⁻; every view labels them `by parent: under allowance (plan #S)`, where S is the seq of the latest genesis/plan entry that changed the `allow` block before that update. An uncovered downgrade still needs the owner; the refusal for a parent lists the uncovered items, each downgrade once: a listed item is left out when the same downgrade is already listed in its detected wording (`review count lowered` under `review count/rank reduced`, `check removed` under ` check removed`, `writes widened` under `writes scope expanded`, …). When every uncovered item widens writes, the refusal (CLI and `owed_plan`) adds one line (0.6.1 H2.1, `writesHint`): `hint: an allow rule {nodes: [""], writes: [""]} in the prior plan would cover this`, the new prefixes being those under neither the node's prior writes nor a matching prior rule. Recommended practice: keep writes strict and pre-authorize at plan time the prefixes integration/packaging nodes need (entry files, `package.json`, wiring directories). For a changed check definition (0.10, N2), the detected item names the changed fields among `run`, `timeout_s`, `reads`, `tests`, `red_expect`, in that order: ` check definition changed (run, reads); owed cannot compare commands, so this needs owner authority or an allow rule; to avoid it, add the new command as a new check id`. Detection and allowance coverage are unchanged. - **Check-less nodes** (0.6.1 H2.2). `owed init` / `owed plan` (CLI and pi tools) warn, refusing and recording nothing, for each node of the new plan with no checks and no evidence obligations: `warning: node has no checks: its acceptance rests on review alone`. The CLI prints them after the result; `--json` and the pi tools return `warnings: string[]`. - **Looped checks** (0.8, L3.3). After the check-less warnings and printed the same way, one warning per check or invariant that sets `min_tests` and repeats its command in a shell loop (`for|while|until … do`, or `seq N` in command position, as in `seq 5 | xargs …` or `$(seq 5)`): `warning: check of node ` (or `invariant `) `runs its command in a shell loop with min_tests : min_tests counts only the last TAP (# tests), jest/vitest (Tests:) or pytest (N passed) summary in the log, i.e. one run, not the sum of the runs (only cargo "test result:" lines are added up)`. That is the actual rule of `parseCounts` (§7): each later TAP `# tests`/`# pass`/`# fail` line (else the last `1..N` plan), `Tests:` summary or pytest summary line replaces the earlier one; cargo `test result:` lines are summed. Nothing is refused or recorded. In 0.10 (N2), both warning kinds skip nodes merged in the current ledger on `owed plan`; invariant warnings remain. `owed init` warnings are unchanged. In 0.11 (F4) a looped check whose command runs `cargo test` (also `cargo + test`) gets no warning: its `test result:` lines are summed. - **Parent adoptions** (§6.6): `adopt` by role parent is valid iff every path of `changed` matches an `adopt` scope of a rule of the **current** plan and `adoptGuard` passes. No owner channel is needed. - **Writes grants (0.22, GR / WG).** At measurement, owed grants independently eligible newly out-of-writes paths covered by an owner-written `allow.writes` rule. It appends one sorted `grant` before the writes observation, which passes only if no refused paths remain (§7.19), without a plan edit, ruling or parent round trip. A ruling still never accepts out-of-writes paths. Every replay validates the grant: only `executor:owed`; matching open node/attempt and current candidate commit; nonempty sorted unique exact repository paths, all in the candidate's `changed` and outside plan writes; current `writesAllowed` coverage and `allowanceSeq`; no closure match or path owned by another open slot's effective writes; no path previously granted to the attempt. Refused paths retain their reasons (`not covered by an allow rule`, `under closure`, `overlaps open node `), while unrelated eligible paths still receive grants. Effective writes are plan scopes plus exact granted paths (not new prefixes), used for measurement, merge recheck and dispatch/grant overlap. Grants survive candidate, rebase, plan and allowance changes within the attempt; a new attempt starts without grants. Attribution reruns retain the original writes measurement. The writes key remains `H({o: "writes", base, cand, writes: node.writes})` for legacy/wildcard-free scopes; syntax-2 wildcard scopes also include `writes_syntax: 2` (§3.7). The pass note is `all changed paths within writes (granted #: )` (multiple relevant grants are separated by `; `). Each grant enters ΔO⁻ as `{node, what: "writes granted: "}`, with `by: "executor:owed"` and `allowance`, labelled everywhere `granted by owed under allowance (plan #S)`. Owed 0.16 refuses any ledger containing a grant (unknown kind); grant-free ledgers retain their keys and states. Dispatch packets add `Pre-authorized by the owner (allowance plan #S): — change files there only when the task needs it; owed records the grant; do not ask.` Review packets (including driver reviewers) add `Writes granted under allowance (plan #S): — judge whether each belongs to this node's task; block if not.` ### 3.5 Candidate size limits (0.14, BD) Optional top-level `limits: {file_mib?: number, diff_mib?: number}` contains positive finite numbers in MiB (1 MiB = 1,048,576 bytes; fractions allowed). Unknown fields, non-numbers, zero, negative and non-finite values are usage errors. `owed submit` / `owed_submit` inspects the candidate's added/changed blob ids with `git diff --raw --no-renames` and sizes with `cat-file --batch-check`, without reading their content. `file_mib` bounds the largest changed candidate blob; `diff_mib` bounds their summed full sizes, once per changed path even when paths share a blob. Mode changes count; deleted files and gitlinks contribute zero. An exact limit is allowed. Exceeding either limit refuses with code `refused`, the limit and up to five largest changed files with byte/MiB sizes; nothing is appended to the ledger. The writer receives this as an ordinary submit refusal through the existing writer command path. With neither limit set, submit performs no size check. Limits are submit policy, not an obligation: they enter no key, do not invalidate existing candidates, and are not rechecked at merge or when carrying a candidate. Compatibility: BD adds no ledger entry kind or field. Without limits the ledger replays with the same states, keys and views as 0.13. Earlier owed ignores the plan field; use 0.14+ when enforcing limits. All buffered `git()` calls have a combined stdout/stderr bound of 256 MiB by default (clamped to the runtime's string limit). Output above the bound stops the process and returns `OwedError` code `refused` naming the subcommand, including with `allowFail`, before concatenating or decoding buffers. This covers other diffs, plan `show` and mutant `cat-file blob` content reads. The review diff streams stdout into a UTF-8 decoder and hash (§4); its stdout has no buffering bound, while stderr remains bounded. ### 3.6 Quarantine, shared sets and check templates An invariant or node check may set `quarantine: [{test, fix, note?}]`: at most 20 entries, unique exact non-empty test names, non-empty fix ids and optional non-empty notes; unknown entry keys are refused. Each `fix` must name a node of the current plan, otherwise validation reports `invariants: : quarantine fix is not a node of this plan` (or `: check : ...`). Adding a name or changing its fix is an owner-only downgrade, never covered by an `allow` rule: `inv: quarantine "" added with fix (owner only)` or `check ...`; reassignment says `fix changed from to `. Deletion is free; changing only a note does not widen the excuse. Entries are active while the fix exists and has not merged. The fix's own prospective merge is measured with its entries already inactive, so that fix must repair the test. The key includes sorted active test names; with none the hashed field is absent and the key equals 0.17's. A fix merging changes current trunk/merge keys and forces fresh measurement. An open candidate's stored check keys are not recomputed solely because a fix merged (§7.17). Editable paths include invariant `quarantine` and `checks..quarantine`. Quarantine is not `known_red`: it excludes tests from counts only under §7.16's proof. Top-level `quarantine_sets` defines reusable lists; a check or invariant selects one defined name with `quarantine_set`, optionally alongside its own entries: ```yaml # Plan excerpt; repair must also be a node in nodes. quarantine_sets: intermittent: - {test: "exact failing name", fix: repair, note: "bounded known risk"} invariants: - id: unit run: cargo test --no-fail-fast quarantine_set: intermittent ``` Set names match `[A-Za-z0-9_.-]+`; each set permits at most 200 entries. Entry validation is as above, with no control characters in set test names. A test in both the own list and selected set is refused, even if inactive; every fix must name a plan node. Active names are the union of own and set entries, sorted in the existing key field, not a separate set-name key. Fix merges disable both kinds of entry, including that fix's prospective merge tree (all batch members are treated as merged for batch measurement). Adding a set entry, changing its fix, or adding/changing a `quarantine_set` reference is an owner-only downgrade, never covered by `allow`; removals and note-only changes do not widen the excuse. Editable check/invariant paths include `quarantine_set`; change set mappings through the recorded plan file. A referenced set's entries also enter the check definition (§6.3), so changing them can supersede an old block just like changing own quarantine. Unreferenced sets affect neither that check's definition nor its key. When any sets exist, new/changed Cargo or Node test commands with neither `quarantine` nor `quarantine_set` receive `warning: inv:` (or `check /`) `runs tests without a quarantine set (sets: )`. This is admission guidance, not an acceptance gate; even an explicit empty own list suppresses it. Changes compare run, reads and timeout (§9.7). A check/invariant may use `template` **instead of** `run`. Loading expands it deterministically into `run` and, for test templates, `min_tests = min_ok`; no template metadata remains in the parsed plan. A handwritten identical expanded run/min_tests has identical keys. Supported keys: | template | Required | Optional | |---|---|---| | `cargo-tests` | non-empty `package`, safe integer `min_ok >= 0` | non-empty `test` (integration target), `filters` array (default `[]`) | | `node-tap` | non-empty `files` array, safe integer `min_ok >= 0` | non-empty `name_prefix` (literal anchored prefix) | | `evidence-json` | non-empty `path`, non-empty `required` field-path array | existing explicit `min_tests` | Strings reject NUL; list items must be non-empty strings. `required` paths use dot-separated own-property segments with no empty segment; numeric segments address array indexes. Presence, not truthiness, is checked: `false`, `0`, `""` and `null` count as present. Template-specific keys from another template are refused. For test templates explicit `min_tests` must equal `min_ok`. Templates do not infer `reads`, red `tests` or closure. Existing timeout, red, repeat and closure rules apply; dependencies are not installed. Errors name the full check/invariant field path and record no plan: `.template: unknown template `, `.run: cannot be combined with template`, `.: not supported by template