# owed MVP specification (parent-pinned, v0.1) owed is the acceptance ledger for a multi-agent task graph in one git repository. "No receipt, not done": a node counts as done only when every obligation on its current candidate is observed by a trusted executor or an authorized reviewer, or is visibly waived by the owner. The design follows `pi-dag/ARCHITECTURE.md` (a3) and `formal/a4/CONTRACT.md` (a4.1 rulings). This MVP implements the M0–M2 subset. 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.22) 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, wais #24).** 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, wais #26).** `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, a path without `+`, an empty note, and when every path is already in the node's writes; removing writes is not offered. 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; ruling #1484).** 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 (ruling #1484): 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, wais #19). 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 - 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, wais #22). 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, wais #31) 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 and check templates (0.20, MS4 / CT1) 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. 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