# Loop-lane convention ## Contents - [1. Three-session topology](#1-three-session-topology) - [2. Escalation contract](#2-escalation-contract) - [When work stops for the owner](#when-work-stops-for-the-owner) - [The owner's standing direction](#the-owners-standing-direction) - [3. Capability tiers](#3-capability-tiers) - [4. Loop-layer invariants](#4-loop-layer-invariants) - [5. Consumers and launch surfaces](#5-consumers-and-launch-surfaces) - [Permission modes](#permission-modes) - [6. Rate-limits binding](#6-rate-limits-binding) - [7. Operator steering through GitHub state](#7-operator-steering-through-github-state) - [Confirm-then-record](#confirm-then-record) - [8. Scheduled reader](#8-scheduled-reader) - [Versioning](#versioning) Owner doc for the concerns shared by every **loop lane**: a session that wraps a single-pass mechanic in a self-paced drain loop over a repository's backlog. Three lanes adopt it: the `work-items` `work-loop` and `attend-queue` skills and the `source-control` `babysit-loop` skill. Because those live in two different plugins, the topology, escalation contract, capability-tier vocabulary, and loop-layer invariants they share cannot live inside either plugin. A sibling-plugin file import is a defect ([`plugin-philosophy.md`](../../plugin-philosophy.md#design-boundary)), and a cross-plugin convention lands in an owner doc before the second plugin adopts it ([convention registry](../../plugin-philosophy.md#convention-registry)). This is that owner doc. **Pointer-not-copy.** Each mechanic below is owned by a plugin or a sibling convention; this doc fixes the *contract* every lane holds to and points at the owner for the *mechanism*. It never restates a mechanics block. The `autonomy` plugin remains the governing-policy pointer (the guardrail matrix), and the loop lanes are the interim executor for the not-yet-built autonomy runner ([`runner.md`](../../../plugins/autonomy/reference/runner.md)); this convention is the loop-layer contract that operates within that policy. ## 1. Three-session topology A drained repository runs three cooperating sessions, each with exactly one authority: | Session | Authority | Never does | |---|---|---| | Worker loop (`work-loop`) | Claims items, authors PRs | Merges | | Babysit lane (`babysit-loop`) | Advances and merges PRs within the matrix's merge-policy column | Decides operator-owned questions | | Attended queue (`attend-queue`) | Human-in-the-loop triage and escalation answers | Runs unattended | The worker loop is PR-only; merge authority belongs to the babysit lane; judgment belongs to the attended queue. No lane crosses into another's authority. ### Autonomy ladder (merge authority) Merge authority is a configurable ladder with the safest rung shipped by default: **human merge for every PR except gate-proven ones at the `c2-mechanical` rung**. The babysit loop's partition reads no work class either: a PR with a close-linked item is eligible at a rung once that rung's promotion cells are promoted (`C2-auto-merge` at `c2-mechanical`, every promotable cell at `c3-autonomous` and `full-autonomy`), whoever authored it and whatever class its item carries, none included. Its promotion evidence credits each autonomous merge to the cells of the rung its lane pin names, never to a class. **C5 (untrusted-provenance) is the one class hold: no rung, no tracked config, and no invocation argument reaches it.** The pr-merge lane reads no class: it merges a pull request the lanes App opened for one closing issue on the verifier verdict at its head, and refuses fork pull requests, so C5 stays human there too ([the pr-merge lane](../../conventions/pr-pipeline/README.md#the-pr-merge-lane), [`work-classes.md`](../../../plugins/autonomy/reference/guardrails/work-classes.md#merge-authorities-that-read-no-class)). The unattended merge gate (`/source-control:babysit-prs`, `--unattended`) reads no class either, by [owner decision](https://github.com/melodic-software/claude-code-plugins/issues/9668#issuecomment-6386299330): no class caps its rung, its promotion evidence is read by rung, not class (`merge` (`C2`) needs `C2-auto-merge`, `merge-reviewed` (`C3`) every C3 cell), and its one class-named check is the trust hold, which refuses a pull request whose linked issue carries `work-class: untrusted-provenance` or had it removed by a non-human. Its rung and rung cap remain pacing caps. Higher rungs are opt-in per repository, up to full autonomy, where frontier-tier subagents resolve conflicts, answer review comments, and drive a PR to merge, and they are bounded by the C5 hold regardless of rung name. This shipped default is itself the recorded baseline rung, versioned in this convention and in the tracked config. A repository adopts it through its own reviewable lane-enabling change, the binding/config PR that turns a lane on in that repo, which is the recorded, human-ratified act for the baseline rung, so no lane ever auto-merges without a reviewed change having enabled it. Raising any higher rung, including any C3-autonomous merge, is a config change on the tracked, layered config ([config-cascade](../config-cascade/README.md)), which makes it exactly the autonomy matrix's required **human-ratified knob flip recorded on the governance surface** ([`work-classes.md`](../../../plugins/autonomy/reference/guardrails/work-classes.md#promotion-and-demotion)). C3-autonomous merge is therefore reachable only through a recorded, reviewable flip, never by default. That is the matrix's promotion contract honored by construction. Demotion stays automatic and fail-closed, per the same owner doc. **Merge-rung raises come only from the tracked config, with one named, explicit paired-argument exception.** Invocation arguments never raise the merge rung *implicitly*: a raise binds only from the tracked config layer, so every increase in the *standing* merge authority is the recorded, reviewable act above. An argument may otherwise only select a *lower* (safer) rung for a single run, never a higher one. The one exception: an invocation whose own argument line explicitly types **both** the literal `autopilot` tier keyword **and** the dedicated raise argument `--merge c3-this-run` (each never inherited, never defaulted, never supplied by a config layer, never composed by a model on the caller's behalf), in a repository that has already adopted the baseline rung above, widens that single run's merge authority to the C3 rung, still bounded by the C5 hold. The pair is deliberate: `autopilot` predates the exception as a merge-inert tier keyword, so a saved invocation, alias, or expanded template that already carries it must acquire no merge authority. The tier keyword alone leaves the merge rung at its tracked-config value. `c3-this-run` exists for this exception alone, so its presence is never a leftover; it is not a rung name and is invalid in the tracked config. This is a **per-invocation, single-run widening**, not a standing rung change: it persists nothing to config, ratifies nothing on the governance surface, and reverts the moment a launched invocation omits either token. It is not a substitute for the recorded C3-autonomous flip above. A repository wanting *standing* C3 autonomy still needs that config change; this exception only ever covers the one invocation that named it. **A safer argument still wins.** The exception lifts only the *raise* restriction, and the raise is mutually exclusive with a safer cap by grammar: every merge-dimension argument value other than `c3-this-run` only ever selects a lower rung, so an invocation naming `autopilot` and an explicit `human-only` merge rung merges nothing. The resolution order is tracked rung, then the paired raise, then the C5 hold. **The paired raise never widens an unattended merge.** The unattended merge path (`/source-control:babysit-prs`, the merge gate's `--unattended`) takes its rung only from tracked files read at the pull request's base SHA and at the default branch head, the lower of each, `merge.rung` in `docs/conventions/pr-pipeline.yaml` and the tracked merge rung, lowered by the human-set rung cap and any demotion record. No invocation argument reaches it, so `autopilot --merge c3-this-run` widens a worker-tier run and never an unattended merge. **The partition tests the PR, not the item's stamp.** The one class it applies, C5, a lane derives from the pull request, never from a recorded class. C5 follows the code's provenance, which "dominates every other property": a cross-repository head, or an author neither attested by the provider as an owner or member of the base repository nor attested by that repository's own team-tracked config as a trusted internal bot (an outside collaborator pushing a base-repository branch is external despite a same-repository head; a missing or unreadable signal fails closed to C5). A fork PR closing an internally classified C2/C3 item is therefore still outside the exception; a repository-owner allowlist is not a trusted-author list and never stands in for that test. The internal-bot attestation is itself a recorded, reviewed trust grant on the tracked config: exact bot identities, read only from the target repository's team-tracked config on its default branch (never any working tree, argument, or other layer), fail-closed to the empty set when unset, never bypassing the fork test and never weakening a dependency-manager merge hold. The key, its grammar, and its composition rules are owned by the babysit lane's config reference (`plugins/source-control/reference/config-resolution.md`, `babysit_loop_trusted_internal_bot_logins`). The diff feeds no class into the rung test, and a PR whose diff cannot be read fails closed to escalation. The partition's verdict attaches to the exact head SHA it examined: any push after the verdict, whether the pre-escalation resolver's or the merge-capable worker's own fix, re-derives the verdict on the new head before any merge, so no head merges that the partition never examined. Every PR this exception reaches that is blocked on a **machine-escalated** `needs-human` item, a contradictory or security-relevant **machine-authored** review thread, or an open finding gets a **fresh frontier-tier subagent** dispatched to resolve the blocker, sharing no context with whatever produced the PR (§3), and holding the PR's own worker lease for the duration, before the deterministic merge gate runs; the gate itself is never bypassed or weakened by this exception, only the human-ratification step ahead of it is replaced by an independent agent's resolution for this single run. The tier is resolved through §3's capability-tier binding, never a family alias fixed in a lane. **What the dispatch never reaches.** Human blocking feedback, whether a `CHANGES_REQUESTED` review, explicit human blocking language, or an unresolved inline human thread, remains a stop-and-ask condition that escalates and is never resolved past; this exception does not amend a lane's own human-feedback contract. Nor does it reach an **operator-parked** item: §2's role label marks parked and machine-escalated items alike, and only the machine marker separates them, so an item without that marker stays the attended queue's and draws no dispatch. Merge conflicts route to a lane's dedicated conflict-resolution path and integrate merge-only; this exception never authorizes rebasing a PR branch, which would need a force-push the lanes forbid. ### Lane write identity Every forge write an unattended lane makes, whether a label, comment, claim, thread resolution, PR, `git push`, merge, telemetry upsert or escalation, runs under one dedicated identity, so the tests that ask whether a person acted (label provenance, thread resolution, merge-queue enqueuer, a demotion record's close) never count a lane's action as a person's. The identity is the login a repository names in `merge.agent-identity` in its `docs/conventions/pr-pipeline.yaml`. It must be a GitHub App installed on that repository only: a machine user is a `User` and would pass every human test. - **Launch.** A lane starts in an environment whose only GitHub credential is the identity's installation token. Delivering and refreshing that token on each lane host is provisioning outside this repository. - **Identity gate, every cycle.** At the start of every cycle, the first included and before any write, the babysit lane and the worker lane read `docs/conventions/pr-pipeline.yaml` fresh from the target's default branch through the forge's contents read, never from a local checkout. A read that fails (any answer but the content or not-found), a body that does not decode, or a file that does not parse as YAML is a refusal. A not-found answer means no file only when the repository's contents root at the same ref reads 200, the merge gate's own rule (`_file_at`); otherwise the file may exist but be hidden from the token, and that is a refusal too. A readable file that names no `merge.agent-identity`, or no file, skips the gate (the residual below). Running it every cycle catches a lane that was already running when the identity was configured, or whose credential changed mid-run. - **The rule** is the merge gate's: `resolve_identity` and `credential_refusal` in `plugins/source-control/skills/babysit-prs/scripts/babysit_merge_policy.py`, which read the acting login (GraphQL `viewer { login }`) and the session's account listing (`gh auth status --json hosts`). The babysit lane runs both through `babysit-postmerge.sh --preflight`; the worker lane, in another plugin, makes the same reads and applies the same rule. Both lanes then run `lane-push.sh --login --check` (below) from the checkout they push from; a babysit lane launched from a neutral directory has no checkout at cycle start and skips it, since each push's `lane-push.sh` runs every refusal before pushing. Each of these refuses (the preflight prints the code shown): - `agent-identity-unconfigured`: the named identity is empty. - `agent-identity-invalid`: the identity is not a GitHub App login (`[bot]`, letters, digits and single inner hyphens), or is the shared `github-actions[bot]` or `dependabot[bot]`. - `agent-identity-self-login`: the identity is one of the lane's own self logins. - `acting-login-unreadable`: the `viewer` read failed or returned no login. - `acting-login-mismatch`: the acting login is not the identity (compared case-insensitively). - `credentials:credentials-unreadable`: `gh auth status` failed, did not parse, or lists no account. - `credentials:other-account-listed`: any listed account, active or not, on any host, has a login other than the identity. - `credentials:unknown-account-listed`: an inactive entry has no login. - `credentials:identity-not-active`: there is not exactly one active `github.com` entry. Any refusal means the lane writes nothing that cycle, telemetry and escalations included: it reports the reason in its own session output and stops. Whether `viewer` returns the App's login on an installation token is unprobed until the identity exists. - **Lanes push only through `lane-push.sh`.** A `git push` authenticates through git's own URL and credential helper, not through gh, and the checkout's remotes, the environment, global config and command-line overrides can each send it elsewhere or as someone else. So no lane instruction runs a bare `git push`: every lane push, babysit's and the worker lane's alike, runs `scripts/lane-push.sh` (canonical `lib/lane-push.sh`, carried by the source-control and work-items plugins), which builds the push instead of inspecting it. It builds the URL as `https://github.com//.git` from its arguments, or from the pull request's head repository for `--pr`, and pushes `HEAD:refs/heads/`, fast-forward only. It drops every `GIT_*` variable plus `SSH_ASKPASS`, sets `NETRC=/dev/null` (git lets libcurl use a netrc entry before it asks any helper, and libcurl falls back to the passwd home's `.netrc` when HOME is empty, so emptying HOME would not stop it), ignores global and system config, resolves git and gh to absolute paths before entering `--dir`, and forces gh (by absolute path) as the only credential helper with https as the only transport. It reads the acting login with that same gh and refuses unless it is the identity. Where the target names no identity, the worker lane passes the session's own login; `push-branch.sh` (below) refuses instead. It exits 0 pushed, 1 the push ran and failed, 2 refused with nothing pushed, printing `lane-push: refused: `: - `usage`, `bad-dir`: arguments missing or contradictory, or `--dir` is not a directory. - `bad-login`, `bad-repo`, `bad-branch`, `bad-pr`: a value outside its allowlist (owner `[A-Za-z0-9-]`, repository `[A-Za-z0-9._-]`, branch `[A-Za-z0-9._/-]` that also passes `git check-ref-format`, a decimal number); a pull request's head is held to the same lists. - `gh-missing`, `gh-path-unsafe`, `git-missing`, `git-path-unsafe`: no gh or git on `PATH`, a git or gh path that is not absolute (a relative `PATH` entry), or a gh path the helper cannot quote. - `config-unreadable`: the repository-local config cannot be listed (not a checkout). - `local-config-url`, `local-config-include`, `local-config-credential`, `local-config-http`, `local-config-remote`: the local or worktree config holds a `url.*`, `include.*` or `includeIf.*`, `credential.*`, `http.*` key, or a `remote.*.vcs` or a `remote..*` whose name is not a plain remote name. These survive the global and system scrub and can redirect or re-credential an https push, so any of them fails closed. - `head-unreadable`: the pull request's head repository and branch could not be read. - `default-branch`, `default-branch-unreadable`: the target is its repository's default branch, by `--branch` or as a pull request's head, and that repository is not a fork of the base (a fork's own default branch pushes; names compare canonically, so an old repository name changes nothing), or the repository could not be read. - `login-unreadable`, `login-mismatch`: the `viewer` read failed or returned another login. `--check` runs every refusal but the push. Named residual: whoever can replace the gh or git binary on the lane host, edit the script, or write the checkout's `.git` directory (its config, hooks or alternates) already runs code as the lane; the script cannot close that. - **Two push paths.** The pull-request skill's `push-branch.sh`, which the autopilot ready flip, the work lane's monitor and every babysit-prs push reach, keeps the operator's resolved remote and plain `git push` for interactive use, attended babysit-prs runs included. Inside a lane it hands the push to `lane-push.sh` instead, bound to the configured identity: it runs the babysit lane's identity preflight (`babysit-postmerge.sh --repo --preflight`, which with no `--agent-identity` reads `merge.agent-identity` from the base repository's default branch) and passes the identity it prints as `--login`, so `lane-push.sh` refuses unless the token acts as that identity at push time. It refuses when the preflight refuses (no identity configured included), the branch is checked out in no worktree and no `--dir` names one, or `--pr` names a fork head without `--dir` (a fork head's name can match a local branch of the base repository). With `--pr`, `lane-push.sh` reads the destination from the pull request, never a remote. It detects a lane by the acting gh login: a GitHub App `[bot]` login, which the identity contract above requires of a lane and an operator never holds. No launcher sets a lane marker, so a lane running on an operator token keeps the operator path (the "No identity configured" residual). Residuals, each named: - R1. Two push code paths to maintain, `push-branch.sh` and `lane-push.sh`. - R2. The interactive path trusts the operator's git config, SSH agent and remotes, by design: the operator is the principal. - R3. A lane on an operator host with `SSH_AUTH_SOCK` or `~/.ssh` keys reachable can push as the operator with a plain `git push`, whatever either script does. Only a lane host whose sole credential is the identity's closes it (a Phase 15 precondition of the auto-merge rollout). Whether today's lane launcher strips `SSH_AUTH_SOCK` was not checked (open question). - R4. The lane check in `push-branch.sh` is advisory, as is every instruction to use `lane-push.sh`: a lane that skips the scripts is stopped only by the credential boundary. A failed acting-login read keeps the operator path. - R5. `NETRC=/dev/null` takes effect only on a libcurl that reads `NETRC`; the release that added it was not checked, and an older libcurl ignores the variable and reads `~/.netrc`. - R6. Proxy and CA variables (`https_proxy`, `ALL_PROXY`, `SSL_CERT_FILE`) are not scrubbed. They can redirect or intercept a lane push; they supply no GitHub credential. Not verified (G4). - **No identity configured.** The merge path stays inert and the lanes run as before, under whatever credential the session holds, and that credential's writes read as human. Named residual. - **One-cycle latency.** The gate runs at cycle start, so in the cycle in which a config naming the identity lands, a lane that passed the gate with none configured still holds the operator's token until its next gate. A plain `--merge` it runs in that window merges under the operator. Named residual. - **Interactive sessions,** the attended queue included, keep the operator's credential, so their label writes count as human provenance. That is accurate only while the user directs the session. Named residual. - **Lane pushes need workflow-file permission.** `lane-push.sh` pushes with gh's token over https, so a lane whose identity lacks the Workflows repository permission cannot push changes to workflow files. That includes a work lane on a target that names no identity: it pushes with the operator's gh token, which lacks the `workflow` scope unless the operator granted it (`gh auth login` requests `repo`, `read:org` and `gist`). Attended runs, babysit-prs' included, push through `push-branch.sh` on the operator's own transport and are not affected. Accepted: the script has no fallback to another transport or credential. Named residual. ## 2. Escalation contract A lane escalates by creating or labeling a tracker item that carries the **`needs-human` role label**, resolved through the consumer's tracker binding (`config.role_labels` of the `tracker` mapping in `/work-items.yaml`) and never compared as a string literal ([`label-taxonomy.md`](../../../plugins/work-items/reference/label-taxonomy.md#canonical-roles) owns the canonical roles and the resolution). A machine-marked bot comment discriminates a worker-*escalated* item from an operator-*parked* one. Both carry the same role label, so the marker, not a second label, carries the distinction. No lane creates labels; the label set is IaC-owned. The same step that files the escalation writes the local escalation record (below), the deterministic surface for out-of-band notification. The event classes that oblige escalation are governing policy owned by [`guardrails.md`](../../../plugins/autonomy/reference/guardrails.md#escalation) (gate failure, verification divergence, admission rejection, demotion, structural-plan approval, and untrusted-provenance). An event class does not by itself stop work for the owner: each routes to the lane that owns its follow-up (a failed gate or a verifier dissent to the lane doing the work, a demotion to its fix issues through intake triage, the cell re-earning from run evidence), an audited admission rejection stays final with any follow-up entering intake as a new signal, and each carries the `needs-human` role label only for a reason or kept control [When work stops for the owner](#when-work-stops-for-the-owner) names. Structural-plan approval stops only when the plan changes intent or the primary design; untrusted-provenance is a kept trust control (below). The post-merge demotion alert ([`post-merge-file-demotion-issues.yml`](../../../.github/workflows/post-merge-file-demotion-issues.yml)) follows the record rules [#11022](https://github.com/melodic-software/claude-code-plugins/issues/11022) set and the pr-pipeline "Demotion issue" rule ([the local babysit lane](../../conventions/pr-pipeline/README.md#the-local-babysit-lane)) states: a red-main record carries no label and clears once main is green at a later commit; a canary, revert or read-back record, which a green main does not clear, keeps `needs-human` only until it lifts on its own lane-verifiable condition, when the alert's `close-cleared` job closes it and removes the label; a fix or quarantine issue intake triage did not receive gets a marker comment each later alert run retries, with no label; and a red-main record gets `needs-human` when a failing check got no fix issue because it was over the cap or outside the name charset, which no retry can file. This convention adds no second escalation channel; the telemetry comment (§4) is the report surface, never the sole path when human action is required. The escalation record write and the out-of-band notification seam below are notification depth on the one filed escalation, the fan-out posture the runner design ([`escalation.md`](../../../plugins/autonomy/reference/runner/escalation.md)) names, never a second channel: the tracker item remains the single escalation of record. ### When work stops for the owner The owner's rule, 2026-10-27, verbatim, with reason 3 as the owner reworded it on 2026-10-28: > "I (the human) should only ever be in the loop or involved via signals like needs-human / needs-decision labels if there is 1. A change in original intent/vision 2. Something comes up during implementation (things don't always go to plan, new findings while doing the actual work) that alters intent/vision or the primary design 3. A real HIGH/CRITICAL security or cost risk, as defined in section 3. Everything else needs to move through the factory floor, the conveyer belt autonomously once work has been deemed agent ready and intent/vision have been translated, expressed and codified in the work item contract. Any changes from that intent/vision are what require my intervention." > > "Any actual security risks, like tokens/secrets being leaked, things that would compromise my accounts, $$$, etc. particularly if the repository is public." | Reason | Label | Lane that decides | |---|---|---| | Original intent or vision changes, or the item cannot answer an intent question | `needs-owner-decision`, `Flags: intent` | Intake triage ([`intake-triage.yml`](../../../.github/workflows/intake-triage.yml)) | | A finding during implementation alters intent, vision or the primary design | human-gated role label (`needs-human` by default) | The lane doing the work: `work-loop`, `work-resolve-issue`, or pr-verify once address-feedback's [round cap](../../conventions/pr-pipeline/README.md#loop-caps) is spent | | A HIGH or CRITICAL security issue, such as leaked tokens or secrets, an account compromise, or real money at risk (the repository is public) | human-gated role label for an existing weakness; `needs-owner-decision`, `Flags: security` for work whose result would carry one | Intake triage for issues; the security review lane for pull requests | | Anything that can bill the owner | human-gated role label, `Flags: cost` | Intake triage for issues; the pr-merge lane's cost hold for pull requests | A choice of means or a design detail is none of these reasons: the lane doing the work decides it on evidence, as the owner's standing direction "Decide from evidence" says. The issue lane's pre-edit pushback reaches the owner only when the run names `cause: intent` (or `intent-change`), a hold code (`security-risk`, `cost-risk`, `design-change`, `intent-change`) in its reason or its cause, or a `host-run` or `attended` code followed by text naming a security risk (owner decision 2026-10-29); a pushback opening with such a code and no security risk takes that code's route. Any other pushback goes back through intake triage once, whose own intent, security and cost rules decide whether it stops ([`stop-routes.json`](../../../.github/scripts/work-resolve-issue/stop-routes.json) `pushback-means`, `retries: 1`); a second one fails. A pushback whose words (its reason, its summary or a not-done item) or cause name a security risk marks its intake comment `security`; when that intake round is spent, it holds for the owner as `security-risk`. The mark does not carry over to later runs: intake triage re-judged it before admitting the issue again. The owner's standing direction on cost and other stops (the owner's section 3), 2026-10-27, verbatim: > "Cost, which comes to me: anything that can bill me. That means Azure, GitHub (larger runners, Actions minutes or storage on private repositories, paid storage or artifact retention beyond the free quota, plan or seat changes) and any other billing account." > > "Not cost, so spend it freely: model usage under the Claude subscriptions, and each account's promotional $200 API credits. Extra usage is off and spending limits are set on all 12 accounts, so reaching a limit stops work and never bills; treat it as a capacity limit." > > "A limit that protects the host, a rate budget or plan usage (such as a breaker or kill switch) is a safety limit, not such a stop." > > "Any other stop is a defect to fix, not a reason to ask me." The owner's standing direction section 10, 2026-10-29, verbatim. The security review lane reads its threat model from this record ([`/review:security-review`](../../../plugins/review/skills/security-review/SKILL.md), "Owner threat model: throughput phase"): > The only actors are me, our bots, our agents and our GitHub Apps. There are no outside contributors. Holds that guard against our own actors (path holds, trust-path holds, person-approval holds, bot-author holds, pin/repin ceremony) are friction, not security boundaries, and come off now. > > Section 3's "high/critical boundary" means only: a token or secret leaking, my accounts being compromised, or anything that bills me. Nothing else qualifies. > > Phase: maximum throughput until open issues and open PRs both reach 0. Hardening (re-adding holds, pins, reviews) is deferred to after that, as configuration edits. **The phase's zero** counts open pull requests and open issues outside cordoned milestones. A milestone in `cordoned-milestones` in [`admission-rules.json`](../../../.github/actions/resolve-config/admission-rules.json), the one place those names live, holds issues open on purpose, so they never hold the phase open. A drain exit counts the same way (§4). The owner's answer on 2026-11-04 (#13252), asked whether to exclude the milestone from the count, with exclusion recommended: > gjo w/ recomendations Trust holds (untrusted provenance, an untrusted spec) are security controls the owner keeps, and so is the issue lane's hold on a patch carrying a credential shape or not proven clear of one (`patch-credential` and `scan-refused-output` in [`stop-routes.json`](../../../.github/scripts/work-resolve-issue/stop-routes.json)), a token-leak path under section 10. A patch proven clear, or a fault that says nothing about credentials, retries. Intake triage keeps one more: text in an issue addressed to the triage run (its labels, its rules or its output) rather than describing work, an injection attempt, stops for the owner with the `needs-human` role label ([`intake-triage.yml`](../../../.github/workflows/intake-triage.yml) ESCALATION rule). It is none of the reasons as written, but the text tries to steer a lane, and loosening a security control stays with the owner (owner decision 2026-10-29, #10517). [`apply-verdict.mjs`](../../../.github/scripts/intake-triage/apply-verdict.mjs) never refuses the hold on such an escalated verdict, though it carries no flag. The pr-merge gate keeps two more holds for the owner, each a reason [`babysit_risk.person_reasons`](../../../plugins/source-control/skills/babysit-prs/scripts/babysit_risk.py) names (owner decision 2026-10-30, #11020): - A trusted-actor widening (`trust-gate:trusted-actors`): a newly trusted login is a path to compromise the owner's accounts. - A file listing past the files API's cap (`files-capped`): the files past the cap stay unjudged, and no lane can read them. A listing a read did not finish (`files-incomplete`) is the lanes' to read again. In pr-merge's risk score, a high path (a floor path, a configured denied path, or an aliasing path, symlink, submodule or mode change) still holds a pull request but does not stop it for the owner, who set no path restrictions. A review finding there stops for the owner only as a CRITICAL security finding; an IMPORTANT or SUGGESTION one is reported and does not hold, and an unresolved IMPORTANT thread does not keep a stale review-lane hold. Three labels take work off the unattended path, and each means one thing (owner decision, 2026-10-28): | Label | Meaning | Who lifts it | |---|---|---| | human-gated role label (`needs-human`) | An owner decision: one of the reasons above | A listed human, by answering | | `attended` | The owner must be present: a manual step on external state an agent cannot safely run or test, of a class [`pr-pipeline.yaml`](../../conventions/pr-pipeline.yaml) `attended.classes` lists, such as a DNS or registrar change, a cloud resource outside an IaC repository's preview and deploy flow, a new key or secret, an elevated pass, or a network registration. It asks no decision | Only a listed human, once the step is done | | `host-run` | Work an agent run or builder session on a host takes, which the issue lane cannot make: an unattended host run, or a change to a path the lane cannot push. Builder items are worked one at a time: interview, plan, implement (owner decision Q-host-run, 2026-11-04) | Removed, with `agent-ready` added again, to hand the work back to the lane | On an issue, the holds live on its Work status field: `needs-human`, `needs-owner-decision`, `needs-reporter-info` and `needs-spec` are field states (`models.issue-status` in [`pr-pipeline.yaml`](../../conventions/pr-pipeline.yaml)). A hold label such as `needs-human` or `needs-owner-decision` still holds on top of the field, so a listed human lifts a hold by changing the field and removing any hold label. `needs-session` is the session-builder queue, not an owner stop: a pr-unblock stop on a change the lane cannot make (a protected path, a weakened required check, a check the `fix-ci` rung-up could not fix, an unfinished dependency review, a review thread the lane left open with no verdict to settle it) goes to an agent session, which removes the label once it has made the change; pr-merge's `clear-escalations` sweep removes it when a same-head retry cleared the stop ([routing table](../../conventions/pr-pipeline/README.md#activities)). Intake admission refuses `attended` and `host-run` alike, parked at Work status confirmed, and adds `host-run` itself when every done-when item is one an unattended lane run cannot perform, none is a paid eval, and nothing else refuses, waits or holds the issue. It adds `host-run` the same way to a size-split sub-issue whose patch is over the scan job's cap, which a builder session takes. Admission does not read the paths an issue names: a resolve-issue run whose change needs a path the issue lane cannot push stops with `patch-protected-path`, which adds `host-run` (`stop-routes.json`); `needs-session` stays the queue for pull requests pr-unblock stops on. It maps a refinement's `External state: manual (...)` line to `attended`; a resolve-issue run that reaches such a step stops with the `manual-external` code, which routes to `attended` ([Attended work](../../conventions/pr-pipeline/README.md#attended-work)). An issue that mixes such items with items the lane can do also parks at `status: confirmed`, with no `host-run`, for refine.mjs to split in the same intake run; refused for that reason only by work-unblock's admission, outside an intake run, it parks at Work status needs-triage, so the triage sweep sends it to intake first: no person answers a split. Every intake hold for a person (`needs-owner-decision`) names its owner reason in a `stop-reason lane=intake-triage` marker. A session does not hold a pull request that a lane already judges (a Dependabot tier, the security review lane's verdict), or ask the owner about it, on its own concern. It routes the concern to that lane's owner as an issue, and labels the pull request only for a HIGH or CRITICAL risk it can evidence (a published advisory or malicious-package report, a leaked secret, a compromised publisher). ### The owner's standing direction The owner's standing direction for every session and lane, 2026-10-28, verbatim. Sections 2, 3 and 10 (2026-10-29) are quoted in [When work stops for the owner](#when-work-stops-for-the-owner); section 6 is [design-for-change](../../standards/design-for-change.md). > **1. Decide from evidence** > > - Decide on facts, data and metrics; use /discovery:research when a question needs outside sources. State the basis of each decision. > - When the evidence settles a question, act on it. Do not ask me. > > **4. Throughput** > > - Aim for the highest throughput with the least friction that is safe, within GitHub, infrastructure and Claude rate limits. > - Find and remove overhead and churn: redundant runs, repeated work, needless holds and manual steps. > > **5. Efficiency** > > - Trigger work only when needed. Prefer events (the Hollywood principle: "don't call us, we'll call you") to polling, and batch where possible. > - No redundant runs or duplicate work across sessions. > - Respect GitHub API rate limits and Claude API/OAuth subscription limits; spend time, orchestration and execution carefully. > - Store only what is needed. Give every artifact, log, cache and stored file a retention policy so nothing grows unbounded, above all where it could cost money. > > **7. Use of Time** > > If you're waiting on a PR, another session, an eval, or anything that you report as "YOU" waiting on: Make sure you have proper monitoring so you don't waste time and can immediately do your work as soon as it is unblocked/ready. ### Cross-lane PR hold Holding a **pull request** is a different act from escalating a tracker item, and this section owns it separately because the two acts fail differently: a tracker escalation waits for the attended queue, while a merge-capable lane may act on a PR within minutes, so a hold carries a hard real-time deadline. A hold that lands after the merge is not a hold. - **The `do-not-merge` label is the only cross-lane hold.** A lanes App hold line, a member's veto comment on a lanes App pull request and a person merging by hand use it; ci-status reads no body hold text or `pr-unblock/*` stop status. pr-merge's enable-auto-merge job labels a member's veto on the next scheduled run that reads the pull request's discussion, at the latest before any run arms it, and takes that label off once a later comment by each vetoing member lifts it, never a `do-not-merge` anyone else added. ci-status's merge-holds step still fails a lanes App pull request on the veto comment itself, so the veto holds before the label lands and if the label is removed. The label is the one hold mechanism enforced server-side: the org ruleset requires the `ci-status` check, whose `check-contract` step fails on the `do-not-merge` label and re-evaluates on `labeled`/`unlabeled`, so applying the label flips a SHA-bound required check with no bypass actors. A PR already in the merge queue is held by the same check: its merge-group run's `ci-status` re-reads the label and fails, and the queue removes the PR. A label that lands after that run's `ci-status` passed does not stop the merge, so on a queued PR also dequeue it (the `dequeuePullRequest` command under **Hold a PR** in [§7](#7-operator-steering-through-github-state)). A PR **comment is advisory, except a member's veto comment, which holds a lanes App pull request and gets the label** (above): an escalation comment on the PR obliges nothing until the label is on. - **Hold first, explain second.** The moment a lane decides a PR must not merge, it applies `do-not-merge`, before drafting the escalation comment and before assembling the supporting evidence. Explain-then-hold inverts the deadline: the drafting time is exactly the window a merge-capable lane needs, and drafting against a snapshot means the explanation can describe a PR that no longer exists in that state. - **Freshness re-read before any hold action.** Immediately before applying a hold, or acting on a hold decision drafted earlier, re-read the PR's live `state` and `mergedAt`. A hold decision formed against a stale snapshot can target an already-merged PR, and announcing its state from that snapshot misleads every downstream reader. - **Record the reason.** The explanation comment carries one line ``, a lowercase kebab-case word (`superseded`, `eval`). A hold waiting only on eval evidence of no loss ([skills and agents](../../review/skills-and-agents.md)) uses `reason=eval`, and the session that posts the paired result adds a line `` when the run is VALID and shows no loss. pr-merge's scheduled run then removes `do-not-merge`, after a comment naming the record and the head, when that record is the newest since the label went on and names the current head, both lines are by a listed human, on a line of their own outside a quote or fence, and no other reason, body hold or member veto stands ([`release-eval-hold.mjs`](../../../.github/scripts/pr-merge/release-eval-hold.mjs)). Keep "do not merge" and `do-not-merge` out of the record comment: they read as a veto. ### Escalation record write Every escalation an autonomous lane files (`work-loop`, `babysit-loop`; the attended queue answers escalations, it does not file them) also writes a local **escalation record** in the same step that files the tracker item, **immediately before** it posts the marker comment: a new JSON file created with the **Write tool** at `.claude/lane-escalations/--.json` in the session's checkout, with stamp `YYYYMMDDTHHMMSSZ` and `` the tracker item number (e.g. `20260726T031500Z-1234-work-loop.json`). The record carries the machine-readable shape of the escalation the tracker item already holds: ```json {"schema":"loop-lane/escalation-record@1","lane":"work-loop","kind":"escalated", "repo":"/","item":"", "summary":"","written_at":""} ``` `kind` mirrors the marker comment's `kind` token. The write is signal, not storage: no lane reads the record back, and the tracker item stays the escalation of record. **Ignoring the record directory is the lane's own preflight, not a consumer obligation.** Because the write is unconditional, an unignored directory strands an untracked file in the working tree a lane runs its gates against, and escalation detail sits one careless stage from being committed. Nothing delivers a tracked ignore rule into a consuming repo, since this marketplace's root rule covers only its own dogfooding checkout and a plugin ships no consumer-side `.gitignore`, so a lane that depended on the consumer having added one would break for every existing consumer that upgrades without noticing. Each lane therefore closes this itself, once at lane start, before any cycle runs: if `git check-ignore -q .claude/lane-escalations/` reports the path unignored, append `/.claude/lane-escalations/` to `$(git rev-parse --git-common-dir)/info/exclude`. That file is per-clone and untracked, shared across the clone's worktrees, so the repair needs no consumer change, alters no tracked file, and cannot itself dirty the tree. A consuming repo may still add the rule to its tracked `.gitignore` through its lane-enabling adoption change, which is the durable form and is carried to every clone. The preflight then finds the path already ignored and does nothing. Three rules make the signal deterministic: - **Write tool, never a shell redirect.** Only a `Write` tool call emits the `PostToolUse` event the hook below keys on; a shell redirect writes the same bytes but emits only a `Bash` tool event, which the hook's `Write` matcher never sees. - **One record per newly filed escalation.** What suppresses a duplicate is the read the lane already performs before escalating: an item that already carries its marker for this kind, such as an idempotent label re-convergence, is not a new escalation, so the cycle files no second comment and writes no second record. Within that rule the `-` filename is unique, so each newly filed escalation is a fresh `Write` (never an `Edit`) producing exactly one hook event. - **Record first, marker second, and the failure direction is chosen.** The two writes are not atomic, and a lane can stop between them. Written in this order, a stop after the record leaves an escalation with no tracker comment; the next cycle reads no marker, re-escalates, and writes a second record, a duplicate notification recoverable by the human who receives it. The reverse order fails the other way and cannot be recovered: a stop after the marker post leaves the marker standing with no record ever written, and that standing marker suppresses the record on every later cycle, so the out-of-band notification for that escalation is lost permanently. Ordering is what makes the notification fail loud rather than silent; no reconciliation pass is needed, and none would be reliable, since a compensating write can stop in exactly the same window. **Background-job launch mode.** The tracker marker comment is the escalation of record whether or not the record file was written. A loop lane must not call `EnterWorktree` (the terminal would end the long-lived orchestrator session). Launch a background lane from inside an isolated linked git worktree to keep the record Write; a background launch from a checkout that is not a linked worktree may have the Write refused or landed in an auto-created worktree. Which launch conditions let the record file be written is a harness behavior this convention does not verify. The work-loop skill's "Background-job launch mode" paragraph in [`SKILL.md`](https://github.com/melodic-software/claude-code-plugins/blob/main/plugins/work-items/skills/work-loop/SKILL.md) owns that text and its verification record. The `summary` restates the marker comment's one-line question, text the lane already published on the tracker, so the record itself adds no new secret surface. The payload the hook sends is larger than the record; see the egress note below. ### Out-of-band notification seam The local channels (OS toast, terminal bell/OSC 9, in the `autonomy` plugin's `lane-notify.sh`) reach only an operator at the machine running the lane. The escalation record write gives a consuming repo a deterministic surface that reaches one who is not: a `PostToolUse` hook in the consuming repo's own tracked `.claude/settings.json`, matched on the `Write` tool, filtered to the record directory, with a `type: "http"` handler that POSTs the hook event's JSON, whose `tool_input.content` carries the record, to the repo's chosen endpoint. Documented default shape: ```json { "hooks": { "PostToolUse": [ { "matcher": "Write", "hooks": [ { "type": "http", "url": "https://alerts.example.com/lane-escalations", "if": "Edit(/.claude/lane-escalations/**)", "headers": { "Authorization": "Bearer $LANE_ESCALATION_WEBHOOK_TOKEN" }, "allowedEnvVars": ["LANE_ESCALATION_WEBHOOK_TOKEN"], "timeout": 30, "statusMessage": "Notifying escalation webhook..." } ] } ] } } ``` Every element is a first-party mechanism. The bullets state what the hook relies on; each specific is read live at the pointer. - **Pointer**: for the handler type, its fields and header interpolation, see [HTTP hook fields](https://code.claude.com/docs/en/hooks#http-hook-fields); for the `if` field, see [Common fields](https://code.claude.com/docs/en/hooks#common-fields) and [Read and Edit](https://code.claude.com/docs/en/permissions#read-and-edit); for the POST body, see [Common input fields](https://code.claude.com/docs/en/hooks#common-input-fields); for failures, see [HTTP response handling](https://code.claude.com/docs/en/hooks#http-response-handling). - The hook is an `http` handler on `PostToolUse` in the consuming repo's project `.claude/settings.json`: per-consuming-repo configuration that no plugin ships. We rely on it as deterministic (it fires on the matched lifecycle event, no model judgment) and as carrying no claude.ai subscription or Remote Control dependency. - The `if` field carries exactly one rule, in the `Edit(...)` form (never `Write(path)`), with a single leading `/` so it anchors at the settings source. Each worktree checkout carries its own copy of the tracked settings file, so we rely on the one tracked rule anchoring at each worktree's own root. That is an applied inference, not a documented guarantee. - The secret rides only in a header whose variable is listed in `allowedEnvVars`, sourced from the operator's environment and never from the repo. We treat the `url` field as non-interpolating, an applied inference, which is why the endpoint URL is tracked config. - **Egress note.** We treat the POST body as the full `PostToolUse` hook input, not just the record: alongside `tool_input` (the record's path and content) it carries session metadata, for example `session_id`, `cwd`, and `transcript_path`, which are absolute local paths and project identity. Configuring the hook is the consuming repo's deliberate opt-in to that egress; point the URL only at an endpoint trusted with it. - We rely on a failed POST (a non-2xx response or a connection failure) being non-blocking: a dead endpoint never blocks a lane. **Destination is the consumer's choice.** The URL is any HTTP endpoint the consuming repo controls: a generic webhook receiver, an internal alerting service, or a relay that reshapes the payload for a chat service (a Slack incoming webhook expects its own JSON shape and rejects the raw hook payload, so Slack reach goes through a relay). Two non-deterministic layers may ride alongside, never instead: the built-in `PushNotification` tool, and model-driven outbound send via a chat plugin (UNVERIFIED here: confirm the plugin and its send capability against its own docs before relying on it). The model decides when to call `PushNotification`, and its phone leg depends on Remote Control, so we treat that leg as absent whenever any Remote Control requirement or mobile-push setup step is unmet, including on a machine that turns feature-flag fetching off. Only the http hook is the deterministic leg. - **Pointer**: for the tool, see the `PushNotification` row of the [Tools reference](https://code.claude.com/docs/en/tools-reference) (the tool table sits under the page title, with no section of its own); for the phone leg's conditions, see [Remote Control requirements](https://code.claude.com/docs/en/remote-control#requirements) and [Mobile push notifications](https://code.claude.com/docs/en/remote-control#mobile-push-notifications); for the variables that turn fetching off, see [Features that need feature-flag fetching](https://code.claude.com/docs/en/env-vars#features-that-need-feature-flag-fetching). **The hook binds to the session's project, never to the repository a lane targets.** The record path is relative to the session's checkout, and the hook that fires is the one in that session's loaded project settings. So a lane whose scope argument names a repository other than its own checkout, a supported merge-lane mode, POSTs to the *launching* project's endpoint, and the target repository's tracked hook is never consulted. That is the hook as specified rather than a misconfiguration: "the consuming repo" is whichever project the lane session runs in, which is also the project whose settings the harness loaded. **Running the lane from the target repository's own checkout is therefore a requirement, not a preference, whenever that repository's endpoint is the one that must hear**. A lane launched from a neutral directory or another repository's checkout notifies that project's endpoint or nobody, and no configuration in the target repository changes it. Writing the record into the target repository's tree instead would be strictly worse, not a fix: the hook's `if` rule anchors at its own settings source, so a record written outside the session's project matches no loaded rule and fires no hook at all, trading a notification-to-the-wrong-endpoint for silence. Note the asymmetry with policy resolution, which deliberately reaches the target repository's tracked file over `gh api`: that is a read a lane performs, while the hook is fired by the harness from loaded settings, which no lane can redirect. **Degradation.** A consuming repo with no hook configured loses only the out-of-band leg. The tracker escalation and the local notify are unchanged, and the record files are inert byproducts that nothing reads. A closed laptop or a dead process emits no hook event at all; the record write covers a lane that is running but unattended, and lane-down detection stays with the stop gate and telemetry freshness (§4). **A configured hook can also fail silently.** We treat a header variable missing from `allowedEnvVars` as interpolating to an empty string (for the rule, see [HTTP hook fields](https://code.claude.com/docs/en/hooks#http-hook-fields)), and a listed variable unset in the operator's environment as doing the same, an applied inference. Either way a failed POST is non-blocking, so a misconfigured hook can 401 on every escalation while the lane runs on with nothing surfaced outside debug logs. Verify the leg when wiring it, by writing a throwaway record file with the Write tool and confirming the endpoint received the POST, and treat webhook silence across cycles that filed escalations as a check-the-hook signal, never as proof of health. ## 3. Capability tiers Model selection is expressed as **capability tiers defined by order, never by family name**. Capability does not track family across generations (a current mid-tier model can equal a prior top-tier one), so a tier named for a family silently rots. Three ordered tiers, each bound to a Claude Code alias (see "Alias binding" below): | Tier | Role | Alias | |---|---|---| | frontier | Complex-stamped items; all security-surface work, always; orchestrator where the organization chooses it | `best` | | strong | Orchestrator by default ([ADR 0100](../../adr/0100-run-the-orchestrator-on-the-session-model-opus-by-default.md)); default implementer / worker for unrouted or complex work | `opus` | | fast | Mechanical items an objective check backs (a build, a test run, a schema or exit-code check), and phases a plan routes `sonnet` as well-scoped | `sonnet` | **Security-surface work** is work that changes authentication, authorization, the handling of tokens or secrets, permissions, or a network boundary. It is a property of the work, judged beside its work class, not one of the work classes. This is the one statement of its scope; other surfaces point here. Fixed rules: the orchestrator runs at the strong or frontier tier, in the coordinator shape where the larger model plans and coordinates and the workers execute; workers stay strong, and a mechanical item drops to the fast tier only when an objective check decides whether its output is correct; a reviewer or verifier is never on a weaker model than the implementer it checks (equal pairings are valid); security-surface work routes to the frontier tier unconditionally. - **Pointer:** for the coordinator shape and when delegation pays, see [optimizing for cost and intelligence: orchestrator strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#orchestrator-strategy-delegate-bulk-work); for the reviewer rule, the advisor capability rule in [advisor tool: model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) and the warning about a checker that passes bad work in [re-run failures at higher effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#re-run-failures-at-higher-effort). - **Recheck trigger:** next model release. - **Judgment:** the sources state a model-capability rule only. That a reviewer or verifier also runs at an effort level no lower than the implementer's is our judgment, as is reading the advisor pairing rule onto a reviewer subagent. ### Alias binding The tier table above binds each tier to an alias, never to a model version, so a release that moves an alias needs no edit here. Which model an alias resolves to, on each provider, is read live from the model page whenever it matters, and never restated in this convention. - **Pointer:** for what each alias resolves to on each provider, see [Model aliases](https://code.claude.com/docs/en/model-config#model-aliases); for each model's position and capabilities, see [models overview: compare models](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). - **Recheck trigger:** any new model on Claude Code's model page. The reasons behind each binding: - **frontier binds `best`, not `fable`.** We bind the frontier tier to `best` because that alias names the tier rather than a model family, so the binding does not pin a stale model; what it resolves to today is in the 2026-11-09 note below. For Fable's access, version and billing requirements, see [Work with Fable](https://code.claude.com/docs/en/model-config#work-with-fable). *Note, 2026-11-01:* `best` is a launch alias, not a value the Agent tool's per-invocation `model` takes ([subagents: choose a model](https://code.claude.com/docs/en/sub-agents#choose-a-model); recheck when that list changes). A lane's frontier-tier Agent dispatch, the security-surface rule's included, therefore names `opus` while the Fable rung waits on an owner decision and a per-week Fable allowance, as the CI lane profiles' ladder paragraph under "Models" in `docs/conventions/pr-pipeline/README.md` records, and `fable` once both are set. The lane prompts follow this note. One exception: the explicit-`autopilot` pre-escalation resolver (babysit-loop's `reference/pre-escalation-dispatch.md`) does not take `opus`, because `opus` is also the strong tier's alias and adds no capability over the review-work model that reference rules out; while the Fable rung is off, that run escalates instead of dispatching. *Note, 2026-11-09:* from Claude Code v2.1.321, `best` resolves to the same model as `opus`, so a frontier launch on `best` runs Opus. The binding stays `best` by owner decision (2026-11-09): lane dispatch already names `opus` while the Fable rung waits on the owner, so nothing a lane runs changes. Binding the frontier tier to `fable` is part of that same pending decision. Pointer: [Model aliases](https://code.claude.com/docs/en/model-config#model-aliases). As of: 2026-11-09. Recheck trigger: that table changing what `best` resolves to. - **strong binds `opus`.** We bind the strong tier to `opus` because the models overview names the model it resolves to as the general starting point; raw capability order (Fable above Opus) does not decide the binding alone. - **fast binds `sonnet`.** We bind the fast tier to `sonnet` for mechanical items whose output an objective check decides, where its speed and cost against the tiers above (see the models overview) pay. The tier has nothing to do with Claude Code's fast mode, a separate speed setting on the models its page lists. Pointer: [Speed up responses with fast mode](https://code.claude.com/docs/en/fast-mode) (the supported models sit in the page's opening). - **`haiku` is admissible nowhere in these lanes today, and no tier binds it.** Four grounds, each our reading of the source it points at; the release figures behind them are in [docs/upstream/haiku-5-5-launch.md](../../upstream/haiku-5-5-launch.md): 1. **Reviewer floor.** Lanes need a reviewer at least as capable as the executor it checks (the fixed rules above; see [advisor tool: model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility)). The launch benchmarks place Haiku 5.5 well below the models the strong and fast tiers bind, so a Haiku reviewer fails the floor against every tier's executor. 2. **Early stop and unverified completion.** The prompting guide records Haiku 5.5 stopping early under a long agent prompt and reporting code changes done without running a check (see [prevent early stopping](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#prevent-early-stopping-in-long-agent-prompts) and [tell coding agents to verify](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#tell-coding-agents-to-verify-their-changes)). Unattended lanes rely on a worker finishing and checking its own work. 3. **Over-refusal.** The system card reports Haiku 5.5 over-refusing more than any other model it tested in its automated agentic behavioral audit ([system card](https://www.anthropic.com/claude-haiku-5-5-system-card), section 6.2.2). A lane cannot tell a refusal from a stall without a human. 4. **Provider alias.** `haiku` resolves to Haiku 5.5 only on the Anthropic API and to Haiku 4.5 on the other providers (see [Model aliases](https://code.claude.com/docs/en/model-config#model-aliases)), so one binding would not mean one model across operators. - **As of:** 2026-10-10. - **Recheck trigger:** a Haiku role passes this repository's routing eval ([#6901](https://github.com/melodic-software/claude-code-plugins/issues/6901)), a revised Haiku 5.5 system card, a change to either prompting-guide section, or Haiku 4.5 retiring. **Known gaps carried with the binding.** No lane detects either of these today, so each is recorded here rather than left as an unstated assumption: - **Classifier fallback, on every tier.** The models the `best`, `opus` and `sonnet` aliases resolve to run safety classifiers. A flagged request can re-run on a different model, after which the session stays there, or end in a refusal for a category with nowhere to fall back to. Security work trips them most often, and frontier is the tier all security-surface work routes to, but the strong and fast tiers carry the same gap: a lane's tier can drop mid-run, or a cycle can stop on a refusal, with nothing in the lane noticing. - **Pointer:** for the fallback targets, the categories without one, and the provider setup, see [Automatic model fallback](https://code.claude.com/docs/en/model-config#automatic-model-fallback) and [Security research and biology workloads](https://code.claude.com/docs/en/model-config#security-research-and-biology-workloads). - **Usage-credit consent, by launch shape.** We treat only a CI lane (`claude-code-action` or `claude -p`) as able to spend usage credits on Fable unasked. A local lane launches with `claude --bg` (`lane-launcher.sh`), so we treat a usage-credit stop there as a turn that ended with nothing spent, and check a stalled Fable local lane for one first; no lane detects it. Whether `--permission-prompts none` changes this for a `--bg` lane is UNVERIFIED. - **Pointer:** when judging whether a lane can bill usage credits unasked, fetch [Fable and usage credits](https://code.claude.com/docs/en/model-config#fable-and-usage-credits) live. - **Recheck trigger:** that section changes which session shapes hold or skip the consent prompt, or a lane changes its launch shape. **Independence, where a dispatch stands in for human ratification.** The one dispatch that resolves a blocker in place of a human decision, the explicit-`autopilot` merge-authority exception (above), additionally requires the frontier-tier subagent to be a **fresh context sharing no conversation history with whatever produced or previously reviewed the PR**: not a continuation of the PR-authoring session, and not the same subagent instance that already replied on the thread being resolved. A same-context or self-continuation dispatch does not satisfy this requirement even at the frontier tier. The point of the tier is capability, while the point of this rule is that the resolution is a genuinely independent second opinion, not the original author or reviewer re-affirming itself. **Where independence stops is a decision, not an omission.** The fresh-context requirement above is the *only* one this contract imposes, and there is deliberately **no** routine per-cycle independent review of ordinary loop output. The rationale: independence is the substitute for a *human decision*, and the ordinary path takes none. Its correctness rests on deterministic gates, the merge gate, CI, and the admission gate, which are unbiased by construction, so a reviewer spending a frontier-tier dispatch every cycle would re-check machine-checkable facts and buy no independence that is not already there. The one path that does carry the requirement is precisely the one where no gate can decide and an agent's judgment stands in for a person's. A lane's conflict path is not a second instance: it dispatches a fresh conflict *worker* to resolve, which is a resolution role rather than a second opinion ratifying a decision a human would otherwise make. This is the boundary's stated justification, so the boundary is revisited when that premise changes: a path whose outcome stops being gate-decidable acquires the independence requirement, recorded as a versioned entry in [`CHANGELOG.md`](CHANGELOG.md) rather than silently. **Runtime resolution is by model alias only.** A lane names an alias (`best` / `fable` / `opus` / `sonnet` / `haiku`), never a dated model name, because we treat the alias as the handle that follows the provider's recommendation while a model ID is a pinned snapshot. We treat aliases as the only handle that works under subscription OAuth, so they are the runtime path; the Models API list endpoint is the **build/audit-time** verification path, since it may require an API key a loop session lacks. No lane hard-codes a model ID (Pointer: for alias semantics, see [Model aliases](https://code.claude.com/docs/en/model-config#model-aliases)). The binding is built from a live official-docs read at authoring time, never from recall. Any new model on Claude Code's model page re-reads the reasons under "Alias binding"; a binding that changes is recorded in this convention's [`CHANGELOG.md`](CHANGELOG.md). ### Rate-limit windows The lanes model subscription (Pro/Max) usage as two limits, one over the last five hours and one over the week, and act only on the operable pause floor in the rate-limits binding (§6); the cap's scoping and limits are not restated here. - **Pointer**: for the subscription usage windows and caps, see the [Anthropic support article](https://support.claude.com/en/articles/11049741-what-is-the-max-plan). - **As of**: 2026-07-23 - **Recheck trigger**: the support article changes the window structure, or a Claude Code release note changes the rate-limit fields the guard reads. ## 4. Loop-layer invariants Every loop lane holds these, whatever single-pass mechanic it wraps. **Stop shapes.** A lane runs in one of two shapes: *standing* (idle backs off toward longer wakeups; no activity-timeout stop) or *drain* (stops when its backlog is empty). Drain carries a **terminal state**: when every remaining open item is human-gated or escalated and no PR is in flight, the lane reports and stops cleanly rather than idling forever. Without it, an overnight drain deadlocks on the first unanswered escalation. An issue in a cordoned milestone (§2, "The phase's zero") is not backlog to either exit; a repository without `admission-rules.json` has no cordoned milestones. A standing lane is additionally bounded by the `/loop` launch surface's **seven-day expiry**, which we treat as binding both launch shapes (§5), idle backoff notwithstanding. Pointer: [Seven-day expiry](https://code.claude.com/docs/en/scheduled-tasks#seven-day-expiry). As of: 2026-07-27. Recheck trigger: a Claude Code release note changes `/loop` expiry. A standing lane therefore requires a relaunch owner, today always the operator, for whom `harness-ops` `lanes` `restart` is a one-command path (operator-initiated by contract; see the cycle-budget paragraph below). The lane records its loop-started timestamp in the lane's #502 telemetry block so the approaching expiry is visible ahead of time, and an expiry hit is handled exactly like the cycle-budget hit below: a restart-request into the #502 block, then a clean stop. **Self-pacing.** A lane paces itself through `/loop` with the interval omitted; Claude schedules the next iteration with `ScheduleWakeup`, and no lane expects an operator to call it. Idle raises the delay toward the ceiling. Pointer: for the delay bounds and who calls the tool, see [Let Claude choose the interval](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval) and the `ScheduleWakeup` row of the [Tools reference](https://code.claude.com/docs/en/tools-reference). The self-pacing section the `source-control:babysit-prs` skill owns is the worked precedent. **The prompt runs fresh; the session does not.** Each cycle re-sends the lane's prompt verbatim into the **same** session, so "runs fresh every time" describes the prompt and never the context: a lane prompt never assumes a fresh one, and what carries forward also degrades, since auto-compaction summarizes earlier history in place rather than preserving it (the `harness-ops:lanes` skill owns the mechanism). **Forge writes converge on rerun.** Every step that writes to the forge (a label, comment, branch or pull request) leaves the same forge state when it runs again after a stop at any point: it reads the current forge state first, compares it with the state it is meant to leave, and writes only the difference. The reason is that lanes restart and are re-dispatched: a budget hit, an expiry, a crash or a later dispatch reruns a step whose earlier run may have stopped partway, and a step that writes from what an earlier run intended rather than what the forge holds now duplicates a comment or undoes a later change. Restart adoption under "Instance-collision detection" below and §2 "Escalation record write" (its "One record per newly filed escalation" rule) are cases of this rule (pstack's `make-operations-idempotent` principle). Reading first covers a rerun that follows a stop, not two runs that overlap; §7 "Confirm-then-record" and [`posting-lanes.md`](posting-lanes.md) own that case. **Cycle budget (#691).** A per-session cycle budget bounds one session; a budget hit **always** emits a restart-request into the #502 telemetry block and stops the loop cleanly, because a running loop cannot `/clear` or relaunch itself, since a relaunch is the only context reset a lane gets (the `harness-ops:lanes` skill owns the mechanism). What happens next is launcher-relative. Under a launcher that acts on restart-requests, the lane is relaunched and the loop continues: the budget restarts the **session**, never ends the **loop**. `harness-ops` `lanes` ships that launcher as `consume-restarts`: each `run` relaunches, through `lanes restart`, every configured lane that is stopped and whose telemetry carries a non-null `restart_request`. It runs only on an OS schedule the operator registers from `consume-restarts print-schedule`; the skill never registers one. Until the operator registers it, every budget hit, under `lanes` or a bare interactive `/loop` alike, is a **terminal** manual-restart state: the stop is reported in lane telemetry, and the operator owns the restart (`lanes` `restart` is the operator's one-command path). The restart-request in the #502 block is written so that the operator, or `consume-restarts` once its OS schedule is registered, can act on the same surface. **Telemetry comment (#502).** Each lane **instance** maintains exactly **one** status comment on a tracking item, identified by a machine sentinel marker and **edited in place** every cycle, never a second comment for that instance. The unit is the writer identity, not the lane type: N concurrent instances of one lane legitimately hold N sentinel-identified comments on that lane's telemetry item, one each, and no instance ever edits another's. `harness-ops`'s `telemetry-upsert.sh` is the interim home of this contract and a compatible reader (`/work-items:morning-brief` reads the same surface); an installed plugin cannot invoke a sibling plugin's script, so each lane **inlines** the small `gh api` upsert and the coupling to `harness-ops` stays one-directional. An inlined upsert is bound by the `@path`-as-body rule in `/harness-ops:lanes`, section "Never pass a body as an `@path` string", and encodes that rule mechanically in its own block (#943) as three checks. A **pre-write gate** refuses a body that is empty, a literal `@path`, not sentinel-prefixed, or under a 16-byte payload floor measured below the sentinel line, before any API call. The **write's own exit status** is then checked, because a failed write leaves the previous cycle's body in place, which a read-back running regardless would accept. A **post-write read-back** re-reads what the write stored, the only check that sees a write which reported success and stored something else. Every branch that ends without a verified body reports UNREPORTED and skips the duplicate-supersede pass, so a cycle whose own write is unproven never tombstones a racing session's comment; carry that forward, since stderr does not survive the session. Known limits inherited from the wrapper: a PATCH that succeeds while storing the previous body still verifies, and the read-back proves *some* well-formed telemetry is present, not *this* cycle's. Not replicated inline: the 64 KiB cap, the body-file containment checks, retries, and the wrapper's distinct non-zero exits. Every inline branch exits 0. **Lane-instance identity (#1295).** The marker names the **writer**, not the lane type. A marker that names only the lane makes two concurrent instances resolve one comment and clobber each other's durable state under last-writer-wins, so one machine's adaptive cap and streaks overwrite another's. The marker therefore carries a lane-instance suffix, the lane-type marker becoming its prefix: ```text MARKER="@" ``` `` is resolved from launch config, defaulting to a random id made once and kept in the plugin data dir when unset (never the hostname, which the public marker would publish) (headless-config floor: never block on an interview, log the assumption). It must be **stable across restarts**, since durable state is precisely what survives a `/loop` expiry or a cycle-budget relaunch, and **distinct across concurrently running instances**, so two lanes on one machine must each be given an explicit id. It is operator-supplied text interpolated into a shell string and a `jq` program, so every lane **validates it before use** against `^[a-z0-9][a-z0-9-]{0,31}$`, rejecting outright and never sanitizing-and-continuing, and the validation lives in the lane's own executable block, not only in this prose. The value appears verbatim in tracker comments; an operator who does not want a machine name published in a public tracker sets an opaque id. The instance is reported on its **own `instance:` line** in the cycle report, never appended to the `lane:` line: `morning-brief`'s lane capture is `[a-z0-9_-]+`, which would silently truncate a suffix at the `@` and report the lane as if nothing were partitioned. Rendering one row per instance is that reader's own follow-up; emitting the field is this contract's obligation. Only the *instance* is new. The other two components of the (repo, lane, instance) identity already hold by construction: the comment lives on one issue in one repository, and the telemetry item is per-lane. The **issue title is not touched**. The `Lane telemetry: ` title contract that the drain-exit snapshot, the intake sweep, and the attention view all match on is the reason the marker was chosen as the partition key rather than the title. **Instance-collision detection.** Partitioning is correct only while ids are distinct, so a collision is detected rather than assumed away. This binds every lane that carries a durable-state block; the attended queue, which carries none, is bound by the marker partition alone. Its operator is present by definition, so an id collision there surfaces to a human in the same pass. The durable state block carries `lane_instance`, a per-session random `writer_nonce`, an ISO-8601 UTC `heartbeat_at` rewritten every cycle, and `paused_until`. At cycle start, after reading its own block: - `writer_nonce` matches mine: this is ordinary continuation. - `writer_nonce` differs **and** the block is stale (`heartbeat_at` older than **2 hours**, and past `paused_until` when set): a previous session of this same instance restarted or died. Adopt the block, write my nonce, continue. This is the ordinary restart path. Two hours is twice the one-hour `ScheduleWakeup` delay ceiling (Pointer: [Let Claude choose the interval](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval); as of 2026-11-15; recheck trigger: that section changes the ceiling), so a healthy lane at maximum idle backoff can never look stale. - `writer_nonce` differs **and** the block is fresh: **another live lane is using my instance id.** Write nothing to the block, escalate per §2 (role label + machine-marked comment), and stop the loop cleanly. `paused_until` is not the rate-limit latch and does not replace it: the latch says *do not claim work*, `paused_until` says *do not read my silence as death*. A lane entering a rate-limit pause writes it before pausing, so a paused lane is never adopted as a dead one. Detection runs before any write, so an id collision degrades to a stopped lane rather than silently clobbered durable state. **Adopting the partition (one-time).** No pre-existing comment matches an instance's new sentinel, so the first cycle after adoption posts a fresh block from defaults. That is intended and fails closed. The legacy un-suffixed comment is left in place and **never adopted, edited, or tombstoned by a lane**: its marker names no writer, so no instance can prove it owns it, and a lane that adopted it would reintroduce exactly the shared-comment clobber this rule removes. Retiring it is an operator action. Until then it remains readable, and stale: `morning-brief` will show it aging past the staleness threshold, because nothing is writing it. **Durable loop state.** Conversation context is lossy across compaction, so a lane persists its adaptive-cap streak counter, its rate-limit-warning latch, its consecutive-no-progress counter, its cycle count, and its instance-identity fields in a machine-readable block of that same #502 telemetry comment, and re-reads them at each cycle start. Every counter in the block is **per-instance**: each measures the experience of one lane instance, which averaging two instances' experience into one block never did. **No-progress detector.** Every stall mechanism below the loop layer is per-PR or per-item, so a lane cycling repeatedly while accomplishing nothing in aggregate is invisible to itself: each gate correctly declines to spend a worker, and nothing notices the aggregate is zero. Each unattended lane (worker and merge; the attended queue is exempt, its operator being present by definition) therefore persists a consecutive-no-progress counter, `no_progress_streak`, beside its other durable counters in the #502 state block (absent from a re-read block = 0). What counts as a qualifying progress event is lane-specific and defined in each lane body; the semantics here are shared. A cycle whose cycle-start snapshot held actionable work for the lane and that ended with no qualifying progress increments the counter; an idle cycle, with nothing actionable in view, leaves it unchanged (idle is not stalled); any qualifying progress resets it to zero. A **held** cycle is a third state and also leaves the counter unchanged: whenever the rate-limits floor (§6) bars the lane from claiming new work, the lane declines mutating work *by design*, so however much sits in its snapshot, no qualifying progress was available to make. The **bar** is what the hold keys on, never the pause window alone. A lane whose inlined floor latches that suppression in durable state stays barred after the pause ends, and a latch no fresh healthy snapshot ever clears would otherwise trip the threshold by itself. A held lane is not a stalled one, because guard suppression outlasting three cycles would otherwise escalate a lane for obeying the guard exactly. Only cycles the lane was free to act in are counted, so the detector measures a lane failing to move a queue it could have moved. When an increment brings the counter to the stall threshold, default **3** consecutive no-progress cycles (a lane may expose the threshold as its own config key), the lane **escalates and keeps looping**: a stalled lane is usually a signal about the queue, not a reason to terminate. The stall escalation rides §2's contract unchanged (role label + machine-marked comment), a loop-health signal on the one channel, not a second channel and not a new guardrail event class. At most one stall escalation per lane is open at a time: before raising one, the lane checks for an existing open stall escalation authored by its own write identity (author-matched, so a third party's lookalike never suppresses the signal) and raises nothing while one exists. The stall escalation itself is never a qualifying progress event, so the detector cannot reset itself by escalating, and more generally, a lane's own repeat attempt at the same still-unresolved blocker never qualifies either: the detector measures the queue moving, not the lane retrying. When progress resumes while a stall escalation is still open, the lane records the resumption as a comment on it and leaves the disposition to the operator. **Per-cycle usage sample (measure-only).** So that a cycle's share of the shared subscription windows is measured, each lane records a `usage_sample` in that same durable-state block every cycle, holding the two window percentages the rate-limits floor (§6) already read that cycle plus each window's rise since the previous sample. The reading is already in hand, so measuring costs nothing beyond the write. **The one permitted readback.** The previous cycle's sample is read back for exactly one purpose: deriving the new sample's `five_hour_delta_pct` and `seven_day_delta_pct` from its `five_hour_pct` and `seven_day_pct`, covering each subtraction and the rollover comparison deciding whether that delta is written at all. That derivation is the delta fields' only permitted consumer. Both deltas are kept, each independent of the other, because an account may report only some of the windows, and the five-hour delta alone left such an account with no rate measure. No other read is permitted, and no sample field reaches a decision at any threshold, in a lane or in any gate a lane runs: not pacing, backoff, an adaptive or item cap, a merge rung, admission, escalation, a warning, or a pause. **The delta measures the preceding interval.** The guard reading is taken at cycle start, before that cycle's own work, so `at` is the cycle-start observation time and each delta is the rise between the previous cycle's reading and this one: it covers the interval **preceding** the cycle whose report carries it, and that cycle's own consumption lands in the next cycle's sample. Read the series as a lagging one. Measure first; whether the data supports acting on it is a later, separately decided question. Three properties bound that decision, stated here once and held by citation from each lane body: the reading is a snapshot no fresher than the guard's staleness rule allows, from a **machine-local**, last-writer-wins file that rate-limits's mod writes in interactive and headless sessions alike, so an unattended lane samples wherever the guard is installed and mods are on, and an empty sample means unobserved rather than zero; the figures are **account-scope**, so the three-lane topology means concurrent lanes move the same windows and a per-cycle rise is one lane's own consumption only when that lane is the sole active session; and they are a **percentage of a subscription window, not a token count**, absent entirely for non-subscription auth. No lane claims a token count, because we found no session-total token field readable at a cycle boundary. The status line's cumulative *cost* field would attribute to a lane, but the guard's snapshot does not carry it; widening the snapshot is a guard-side change this invariant deliberately does not make. Pointer: for the fields a session exposes, see [Available data](https://code.claude.com/docs/en/statusline#available-data). **Headless-config floor.** A headless lane launch never blocks on an interview and never reads run config back from its own telemetry state block, which the lane can edit. The work-loop lane takes run config from its launch args only; when the stop mode (`--drain` or `--standing`) is absent it stops before any cycle work with a message naming the relaunch tokens, and only `shard`, `scope` and `ordering` fall back to their defaults. The babysit loop takes launch args, then its tracked config layer, then tier defaults, and logs the assumption. The interactive path may run a mini-interview and offer to persist the answer; the headless path never waits on one. **Lane-editable config and the four sandbox conditions.** Every local lane reads some config at run time that the lane's own process could edit (audited in #7680). work-loop and attend-queue read the tracker binding (`docs/conventions/work-items.yaml`'s `tracker` mapping) from the checkout, including the role labels that admission matches on. The triage step they run reads `docs/conventions/work-items.yaml` and `docs/conventions/pr-pipeline.yaml` from the working tree when no `--config-ref` is given, and both lanes read that `work-items.yaml` for `ai_disclaimer` the same way. The babysit loop reads its `babysit_loop_*` keys from the `source-control` config's user-global, team and local layers, and reads the team layer from the working tree when the checkout is the target repository. A deny rule makes such a file read-only to a lane only when at least these four conditions hold for that lane's session: 1. the sandbox is enabled 2. `allowUnsandboxedCommands` is `false` 3. no command that can write the file is listed in `excludedCommands` 4. every file-writing MCP tool the session loads is denied The deny rule itself is an `Edit` deny on the file, which the sandbox merges into its own write boundary; a sandbox `denyWrite` entry names the same path explicitly. The other escape surfaces, such as `failIfUnavailable` and `filesystem.disabled`, are in the [harness-config audit's escape-surface table](../../../plugins/harness-config/skills/audit/reference/required-permissions.md), which owns the full sandbox-boundary check. No tracked settings file or launch surface in this repository sets these for a local lane. The `lanes` launcher starts each lane with `--permission-mode auto` plus any per-lane `--settings` the operator adds. So treat each of these files as lane-editable until that lane's launch meets every condition. Some bounds hold anyway, and none of them depends on the sandbox: - the unattended merge gate reads its rung at the pull request's base SHA - the trusted internal bot list binds only from the target repository's default branch - the binding's personal override accepts only lease, auth and `docs` keys, which keeps the personal override from reshaping team state but does not stop a lane editing the team binding itself Pointer: when judging whether a deny rule stops a lane writing a file, fetch [Configure sandboxing](https://code.claude.com/docs/en/sandboxing#configure-sandboxing) and [How permissions interact with sandboxing](https://code.claude.com/docs/en/permissions#how-permissions-interact-with-sandboxing) live. **Provider backoff (seam exit 8).** A tracker-seam exit 8, meaning the provider is unavailable or secondary forge limits are hit under one credential, is handled as backoff-and-retry and counted as a **dirty** signal for the adaptive cap: the cycle makes no further provider call, and the next try waits until the provider's reset (`x-ratelimit-reset`, or `retry-after` when sent), never a retry loop. **Snapshot drain exit.** The drain-exit condition is evaluated against a snapshot taken at cycle start; new automated intake arriving mid-cycle is **reported, never chased**, so an item-producing bot cannot hold a drain open indefinitely. **Autonomous-pipeline reminder.** An autonomous lane carries standing clauses of its own against the two stopping failures a pipeline cannot recover from: a turn ending on unexecuted intent, and a turn stopping to ask permission nobody is there to give. In this repository those clauses are hand-authored inline in each autonomous lane's launch prompt, and **deliberately so**: a launch prompt is pasted into a terminal that may have no plugin installed, so it stays self-contained. **Pointer-not-copy does not reach them**, and this is the one place in this doc where that is true: the rule governs a *mechanism* a plugin owns, and a self-contained paste block owns its own text. The `autonomy` plugin's `reference/autonomous-pipeline-reminder.md` states the same clause set once, with its provenance, as the artifact an adopting org drops into **its own** pipeline. The Worker and Merge lane prompts in `prompts/loops/loop-lane-prompts.md` carry the first failure's clause (never end a turn on a status summary or an offer to continue), "speak to me only when fully blocked", and the reminder's recovery clause, its deliberate-block sentence included, each in the lane's own voice. No lane consumes that file, and a lane author changing these clauses should read it as the reference wording rather than as a source the prompts import. Two boundaries are lane-topology facts and so belong here rather than there: an **attended** lane deliberately carries no such clauses, because "recommend, then wait for my direction" is the opposite posture; and the `lane-stop-gate` hook mechanizes exactly one of them, so the clauses are not redundant with a lane that has the gate armed. **Subagent discipline preamble.** Every subagent a lane dispatches carries a standing discipline preamble, because a dispatched non-fork subagent runs in a fresh, non-inherited context: it inherits no posture from the cycle root's own sweep and has to set its own. A fork inherits the root's context instead ([subagents: how forks differ from other subagents](https://code.claude.com/docs/en/sub-agents#how-forks-differ-from-other-subagents)). When the `discipline` plugin is enabled, the dispatch prompt invokes its sweep skill, which resolves its own membership. The preamble never enumerates the individual disciplines, per this doc's own **Pointer-not-copy** rule: a hand-copied list drifts from the plugin that owns it. Invoked at the subagent's conversation start, that skill reports its cheap posture digest rather than running its audit fan-out, so the preamble costs one skill read per dispatch and does not recurse; the fan-out belongs to the cycle root's once-per-cycle pass, and the skill's own audit forks never re-invoke it. When the plugin is not enabled, the dispatch prompt inlines the equivalent standing instructions (verify claims against authoritative sources before acting, prefer installed skills over ad-hoc approaches, and re-check work against the active conventions). The reference is presence-gated with this inline fallback per the [seam-phrasing convention](../seam-phrasing/README.md): `discipline` is never a hard dependency. ## 5. Consumers and launch surfaces | Consumer | Plugin | Lane | |---|---|---| | `work-loop` | `work-items` | worker (PR-authoring drain) | | `attend-queue` | `work-items` | attended triage / escalation queue | | `babysit-loop` | `source-control` | merge lane over `/source-control:babysit-prs` | **Launch surfaces.** A lane launches interactively via `/loop`, the primary surface and a bundled skill needing no install (Pointer: [Bundled skills](https://code.claude.com/docs/en/skills#bundled-skills)), or headless via the `harness-ops` `lanes` launcher, which stores the one-line lane prompt through its `prompt_dir` interface (#480). `lanes` is a **supporting, strictly one-directional** launcher: it launches the lane; no lane body ever requires, imports, or degrades without `harness-ops`. Every mention of `lanes` in a lane body is presence-gated with the `/loop` fallback documented at the site, per the [seam-phrasing convention](../seam-phrasing/README.md). **Two launch shapes, selected per invocation, and neither deprecates the other.** Supplying an interval (`/loop 15m …`) gives a fixed, jittered cron schedule; omitting it gives the self-paced shape, where Claude picks each delay within the §4 bounds. We treat `ScheduleWakeup` as the pacing mechanism of the self-paced shape only. The §4 seven-day expiry binds both shapes. Both are current; this note reconciles which applies where and changes neither. Pointer: for both shapes, see [Run on a fixed interval](https://code.claude.com/docs/en/scheduled-tasks#run-on-a-fixed-interval) and [Let Claude choose the interval](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval); for the size of the offset a cron task gets, see [Jitter](https://code.claude.com/docs/en/scheduled-tasks#jitter). - **A lane always omits the interval.** Two §4 invariants need the self-paced shape and neither survives a cron schedule. *Idle backoff*, the standing shape's "idle backs off toward longer wakeups", derives the next delay from what the cycle just observed, which a fixed cadence cannot consume. And a self-paced loop can **end itself** (Claude calls `ScheduleWakeup` with `stop: true`), which is how the drain shape's terminal state stops a lane cleanly; we treat a fixed-interval loop as running until stopped by hand or until the seven-day expiry, so a drain lane launched that way cannot honor its own stop condition (Pointer: [Stop a loop](https://code.claude.com/docs/en/scheduled-tasks#stop-a-loop)). The lane shape is therefore self-paced because those two invariants require it. Two of the lane's other per-cycle signals, the adaptive-cap streak and seam exit 8 counted as dirty, govern *how much work a cycle takes on*, not when the next one fires, and are unaffected by either shape. The drain-exit snapshot is not one of them: it is the pacing signal named above, the input deciding whether the cycle calls `ScheduleWakeup` with `stop: true` instead of scheduling another run at all. - **A fixed interval is the operator's shape for invoking a single-pass mechanic directly.** The interval chosen once *is* the whole cadence policy. No per-cycle state derives a better one, so there is nothing for the cron schedule to discard. `babysit-prs`'s documented `/loop 15m /source-control:babysit-prs worker --unattended` line is that shape. The two shapes coexist inside one plugin without conflicting because they answer different invocations, not competing defaults: `babysit-prs` documents a fixed-interval launch of *itself*, while its cadence mapping (the self-pacing cadence contract owned by the `source-control:babysit-prs` skill) is the self-paced contract the `babysit-loop` lane consumes. Reading either as the other's default is the confusion this note exists to prevent. **Known gap: the self-paced shape is version-conditional off the first-party API.** We record a lane launched on Microsoft Foundry, Amazon Bedrock, Google Cloud's Agent Platform, or Claude Platform on AWS, or with feature-flag fetching turned off, as having the self-paced shape only on a Claude Code version at or above the floor the scheduled-tasks page names for those providers; below that floor it runs without it. Pointer: for the provider and version conditions on a dynamic `/loop`, see [Let Claude choose the interval](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval) and the `ScheduleWakeup` row of the [Tools reference](https://code.claude.com/docs/en/tools-reference). A lane launched below the floor keeps the loop but loses both properties the bullet above depends on: idle backoff cannot lengthen the wake, and the lane cannot end itself, so a **drain** lane there deadlocks on the first unanswered escalation exactly as §4's terminal state exists to prevent, and runs until stopped by hand or until the seven-day expiry. No lane detects the provider or the version today, so this is recorded as a known gap rather than left as an unstated assumption, on the model §6 uses for the single-account assumption. ### Permission modes Root `AGENTS.md` ("Unattended lanes") holds the rules every session loads: no bypass mode and no hook `ask` in a lane. This subsection holds which mode each lane runs in. - **Local lanes** launch with `--permission-mode auto`. When the auto-mode classifier denies a lane's action, the denial comes back to the session as an error tool result and the session moves on; it shows in the transcript and in `claude logs `. Whether it reaches lane telemetry is unprobed. - **CI lanes** run with no prompt handler, so an unlisted tool is denied. Intake triage and the review lanes pass `--permission-mode dontAsk` with a fixed tool allowlist. Read-runner activities (`fix-ci`, `fix-docs`) run `dontAsk` with explicit allow rules and no write token; `permission-mode: auto` there fails red, because under the launcher's subprocess env scrub the CLI starts in the default mode. All run under the hardening in [ADR 0049](../../adr/0049-run-ci-lanes-on-github-hosted-runners-under-trigger-and-token-hardening.md), which also covers the untrusted-text risk for them. - **`--permission-prompts none`** is documented for print-mode runs where nobody can answer a prompt. A host run on 2026-10-28 (Claude Code 2.1.312, [probe record](../../../plugins/session-flow/skills/continue-in-background/reference/denial-probe.md)) launched `claude --bg --permission-mode auto` without that flag: one classifier denial came back to the session as a tool error and it went on to its next step. What a `--bg` lane does with the flag is UNVERIFIED. - **Pointer:** for the flag, fetch [CLI flags](https://code.claude.com/docs/en/cli-reference#cli-flags) live. - **As of:** 2026-11-01. - **Recheck trigger:** that page's `--permission-prompts` row changes. **Launch options.** An unattended Claude Code launch passes this set, drawn from what the lanes launcher builds. Other headless launchers adopt it when next touched. A flag whose effect no probe has shown stays out of the table. The lanes launcher also passes `--permission-prompts none` on `--bg` launches; that use stays until a probe settles the UNVERIFIED bullet above. | Option | Applies to | Value | |---|---|---| | `--permission-mode` | Every launch | By lane kind, per the bullets above: `auto` for local lanes, `dontAsk` for CI lanes | | `--model` | Every launch whose lane sets a model | The lane's configured model | | `--effort` | Every launch | The lane's configured effort | | `-n ` | `--bg` launches | The lane's name | | `--permission-prompts none` | `-p` launches on Claude Code 2.1.259 or later | Passed; older CLIs reject the flag | ## 6. Rate-limits binding All three lanes consume the shared subscription rate-limit windows (§3). An installed plugin cannot read a sibling plugin's files or this repo's `docs/` at runtime, so each consuming lane body **inlines the operable floor**, the fixed snapshot-file path, the pause threshold, the staleness rule, and drain-then-pause, and cites the guard's reader contract for provenance only. This section names those four items and deliberately restates none of their values: a number written here would be one more copy, outside the block the check below compares. That reader contract is [`plugins/rate-limits/reference/reader-contract.md`](../../../plugins/rate-limits/reference/reader-contract.md), shipped with the `rate-limits` plugin. This convention records the inline-floor rule so the values stay byte-identical across lanes and to that contract's own floor block. **Who writes the file, and what wakes a paused lane.** rate-limits's mod writes the fixed-path file in interactive and headless sessions alike. A paused lane's Monitor on that file wakes on the mod's writes, and a machine-wide write floor bounds them: a reading whose whole-point percentages have not moved is rewritten no sooner than the floor interval after the file's last write, whichever session on the machine wrote it, while a whole-point move writes at once, so a lane's own turn that moves a window can wake it once. A lane may set the guard's report mode with `--settings`; this is optional. **Pausing is opt-in.** By default a lane never pauses, slows, or stops on a window reading, and a reading never lowers its model, effort, or review depth: at the pause threshold it keeps working and reports the window, its percentage and reset time, and the operator's options, as the floor's **Drain-then-pause** bullet words them. An operator who wants drain-then-pause sets the floor's opt-in variable in the lane session's environment, for example through an `env` entry in `--settings` at launch. The rest of the floor (pause end, Monitor, account switch, latch) applies only to an opted-in lane. Reactive-only backoff on a rate-limit error the session itself hits is unchanged: that is the API refusing, not a lane choosing to stop. A default pause stopped every lane at the threshold and led sessions to read a usage reading as a reason to stop or to ration quality ([#7118](https://github.com/melodic-software/claude-code-plugins/issues/7118)). **An account switch is the operator's act.** A lane never performs or scripts one. The [claude-code-account-rotation](https://github.com/melodic-software/claude-code-account-rotation) tool switches only on a human click, and its README lists running the loop lanes while rotating as outside its first version: a lane whose operator switches accounts relies on the floor's **Account switch** bullet and the known gaps below. **A named check enforces the rule.** `scripts/check-loop-lane-floor-drift.sh` extracts the floor block from the reader contract and compares it against an explicit registry of every surface that inlines it: the three lane bodies, the `docs-hygiene` `extract-ssot` orchestrated mode, the `source-control` `pull-request` watch handoff, and the two launch-prompt templates under `prompts/loops/`. The five prose copies must match byte for byte; the prompt templates carry the floor inside a blockquote re-wrapped to a narrower column, so their registration compares the block after normalization. Normalization strips blockquote markers, backticks and emphasis, and flattens whitespace runs, so **line breaks and markup are free in that mode while every word is still asserted**: bolding `10 minutes` or not is invisible to the check, dropping `either` from the pause threshold or weakening `must` to `may` is not. The check runs in CI as the `loop-lane-floor-drift-gate` lane, with its own suite `scripts/check-loop-lane-floor-drift.test.sh`. **The registry does not decide what gets checked; the corpus does.** Before comparing anything, the check scans every tracked file for the floor's opening bullet and fails on any carrier its registry does not name. That is what keeps registration from being optional: a new lane that inlines the floor and forgets the entry turns the lane red on the pull request that adds it, rather than passing green and going stale at the next contract change. The registry stays because it carries each consumer's comparison mode, which no scan can infer; the scan bounds the registry. **What that pair guarantees, stated exactly.** Every tracked file carrying the floor is either a registered consumer, compared on every run, or a member of the check's own `DATA_CARRIERS` list, which is what a file holding the marker as test data or illustration goes on. Both lists live in the check, both are printed on every run including `--check`, and both fail on an entry that has gone stale. So the checked set equals the carried set minus a finite, enumerated, reviewed exception list. It is deliberately not phrased as an equality: an exception list exists, and a claim of "provably equal" would be exactly the unbacked assurance this section was rewritten to remove. **A file cannot excuse itself, and that is why the exception list is not an in-file annotation.** An annotation on the shape `# lane-coverage-ok:` and `# silent-skip-ok:` use anchors to a syntactic site, a job key or a guard line, which bounds what it can excuse; a file has no such site, so any file mentioning the token anywhere, in prose or in a fixture string, would exempt its own floor copy and drift unwatched. With the exception list in the check, a new data carrier costs an edit to the gate, which is the review the exception needs. **Neither half is optional, and path shape cannot supply either.** `scripts/check-cross-plugin-source-drift.sh`, the repo's general copy-drift gate, is blind here by construction: it skips `SKILL.md` by basename, and it clusters copies by identical path-within-plugin, while these copies sit at unrelated paths. Copies can stay identical to each other, which is the half a reviewer notices, while all of them drift from the reader contract, so the check compares each copy against the contract. The scan exists because a registry alone can miss a copy nobody registered. **Single-account-per-machine is a known gap, not a safe assumption.** The snapshot file is last-writer-wins, and before it carried an account identifier a machine running lanes under more than one account fed one account's healthy windows to lanes running on the exhausted one, with no way for the guard to detect it. Same-machine account rotation is real operating practice, not a hypothetical. This is a **gap**, not an invariant. Assuming one account per machine describes how the guard is built, not a rule, and it fails open in a contract that fails closed on every other unresolvable input. It would also bake a solo-operator posture into a contract whose sibling "assumes no machine, org size, or budget" ([`routines.md`](../../../plugins/autonomy/reference/routines.md) §Hosting stance): a multi-account machine is an ordinary team and multi-tenant shape. Calling it a gap keeps anyone from assuming nothing is missing. **The resolution is account identity, and all three sides have landed.** The snapshot file carries an `account.email` field naming the account whose windows a snapshot describes, present whenever the writer could attribute the observation and absent rather than wrong when it could not (`plugins/rate-limits/reference/reader-contract.md`, "Snapshot file shape"). Reader-side invalidation of latched state is a **MUST** in the inlined floor's "Account switch" bullet: a paused lane records the account of the snapshot that tripped the pause (not the account `.claude.json` names at pause entry, because the snapshot can be as old as the floor's staleness rule allows), reads `.oauthAccount.emailAddress` directly from `${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json` at pause entry and on every wake and Monitor tick, and on a change drops the latch and resumes when the new account is below the pause threshold, or re-latches against the new account's `resets_at`. One branch goes past "drop when the new account is below the threshold": when no fresh snapshot attributes the new account, its windows are unknown, so the lane drops the latch and runs reactive-only, the outcome the staleness rule already gives unknown windows. The lane-floor re-audit is satisfied by the drift gate: the floor block moved to every carrier together and `scripts/check-loop-lane-floor-drift.sh` fails when any copy differs. **Known gap: unattributable cases.** The gap narrows rather than closes. A switch the lane cannot attribute goes unseen: the snapshot's field is absent whenever the writer could not attribute, a reader that cannot read `.oauthAccount.emailAddress` keeps its latch (fail-closed, never a spurious drop) until the latched pause ends, and a pause whose tripping snapshot has no `account.email` starts with no latched account and adopts the first account it reads, so a switch before that read goes unseen. All three depend on an internal `.claude.json` key or on the writer's attribution. **Guard-mode telemetry.** Each lane records the guard's mode, proactive, reactive, or unknown, in its #502 telemetry block every cycle, so a silent degradation to reactive-only stays visible on the tracking surface. ## 7. Operator steering through GitHub state Lanes run on separate machines under separate Claude accounts, and the peer tools (`SendMessage`, `ListAgents`) reach only same-account sessions, so no session can message a lane on another machine. The attended operator, a human or an `attend-queue` session, steers a lane only through GitHub state the lane already reads: labels, the Work status field, claims, and the PR hold. No agent relays another agent's summary; each lane's own telemetry comment is its report of record. The commands below take `R=/`. **Read a lane.** `/work-items:morning-brief` reads every lane's telemetry comment. To read one directly, find the `Lane telemetry: ` issue and print its sentinel comments, one per instance: ```bash gh issue list -R "$R" --state open --search '"Lane telemetry: work-loop" in:title' --json number,title gh api "repos/$R/issues//comments" --paginate \ --jq '.[] | select(.body | startswith("" ``` `babysit-loop` respects the label at every tier and rung; only `--strip-do-not-merge` typed into that lane's own invocation overrides it. Remove the label to release the PR; an eval hold is released by its record ([Cross-lane PR hold](#cross-lane-pr-hold)). **Run a PR's plugin evals.** The `eval: run` label runs [`pr-run-plugin-evals.yml`](../../../.github/workflows/pr-run-plugin-evals.yml) on a same-repository, non-draft PR: the suite of each plugin whose `skills/`, `agents/` or `evals/` the PR changes, deterministic graders only, under `--max-cost-usd`, with a PASS or NOT COMPARABLE verdict per case in the job summary. Only a listed human's label starts a run, and a selected plugin is refused when it changes anything but its eval case files (`prompt.md`, `case.yaml`, `graders/*.md`, `samples/**/*.json`) and the markdown in its `skills/` or `agents/`, changes a case's `allowed_tools`, `env`, `context` or other run keys, has a case that loads another plugin or a directory the PR changes, changes a skill's or agent's tool, hook or shell settings, or holds a symlink or submodule. It is advisory: no required check reads it. Add the label again to run the current head. ```bash gh pr edit -R "$R" --add-label "eval: run" ``` **Pause a lane: no GitHub control exists.** `paused_until` is written by the lane itself before a rate-limit pause and means "do not read my silence as death"; no lane reads it as an instruction. The nearest GitHub-state lever is deliberately leaving the lane no work: park its remaining issues or hold its PRs. A standing lane then idles; a drain lane stops at its drain-terminal state (§4) once every remaining item is human-gated or escalated and no PR is in flight. **Stop a lane: no GitHub control exists.** Stopping is a session action on the lane's own host: `/harness-ops:lanes stop ` there, reached from another machine through `/fleet:reach`. ### Confirm-then-record This repository's confirm-then-record pattern for a lane's external write is two rules already stated above, with no state word beyond the one the telemetry read-back reports: - **`UNREPORTED` is the state for a write that cannot be proven.** A branch that ends without a verified body reports `UNREPORTED` and does nothing that assumes the write landed (§4 "Telemetry comment"). - **Record first, marker second.** The record is written before the marker that suppresses a repeat, so an unproven stop re-escalates, a duplicate a person discards, and never loses the signal (§2 "Escalation record write"). That is the failure direction chosen. A check-then-act dedupe does not cover two runs that overlap. Every posting lane, marked covered by a `concurrency:` group, by another atomic claim, or uncovered, is listed in [`posting-lanes.md`](posting-lanes.md). A reconciliation pass and a two-phase in-progress record are out of scope. ## 8. Scheduled reader A scheduled reader is a lane that reads sources on a schedule and posts what changed. The "Building effective agent automations" post closes on six rules for one; its [upstream record](../../upstream/claude-dev-building-effective-agent-automations.md) holds our decisions on it. A new scheduled lane meets each rule through the mechanism named here, not through a checklist of its own: | Rule | Mechanism that meets it | |---|---| | Bookmark per source | `/work-items:morning-brief`'s per-repo bookmark ("What each section reports"); for ai-briefing, the mechanism tracked in #7678; for state a cloud routine keeps between runs, a tracker comment read back on the next run (the §4 "Telemetry comment" carrier), confirmed by a live run on Claude Code 2.1.314 (#8991) and rerunnable with `/harness-ops:behavior-probes`'s `cloud-routine/state-read-back-next-run` case. A routine's comments post as the account owner's GitHub login, so the reader finds them by sentinel marker, never by author | | Failed read reported as unreadable | `/work-items:morning-brief` "Degraded sections"; for ai-briefing and a headless lane's MCP load check, the mechanism tracked in #7678 | | Live re-check before posting | [`pr-run-activity.md`](../../conventions/pr-pipeline/pr-run-activity.md) "prepare: review-threads" | | Post confirmed before it is recorded | §2 "Escalation record write" (record first, marker second); §4 "Telemetry comment" (post-write read-back); for overlapping runs, [`posting-lanes.md`](posting-lanes.md) | | Config re-read each run from a store the lane cannot edit | §4 "Headless-config floor"; base-SHA config in `.github/workflows/pr-run-activity-read.yml`; [ADR 0049](../../adr/0049-run-ci-lanes-on-github-hosted-runners-under-trigger-and-token-hardening.md) decision 4, with the review and intake lanes tracked in #7234. Not met for local lanes: each reads config it can edit, and §4 "Lane-editable config and the four sandbox conditions" names what makes a deny rule hold | | Read-only access, and a cap on each run | Not met for read-only access: CI lanes hold the write token their job needs and every tool, the gap [ADR 0049](../../adr/0049-run-ci-lanes-on-github-hosted-runners-under-trigger-and-token-hardening.md) accepts and bounds with short-lived, scoped tokens (decision 3); for run limits per task class, the mechanism tracked in #7677 | Two related items sit outside the six rules: an external heartbeat for scheduled lanes (#7673) and the time zone a scheduled prompt names for dates (#7679). ## Versioning This contract is versioned in [`CHANGELOG.md`](CHANGELOG.md). A change to the topology, the escalation contract, the tier vocabulary, or any loop-layer invariant is a major bump; additive guidance is a minor bump. **Recheck triggers** ([upstream-drift](../upstream-drift/README.md) owns the record shape and the trigger discipline). Two. A firing that finds drift lands its outcome as a changelog entry; a no-drift firing refreshes the record's as-of date in place, with no entry and no bump: - Any new model on Claude Code's model page re-reads the §3 alias binding and its known gaps. - Any change to this convention, or to a consuming lane, that relies on an upstream-pointed record re-reads that record's pointer first and refreshes its as-of date with the outcome. The upstream surfaces these records point at, the `/loop` seven-day expiry, the `ScheduleWakeup` bounds, model-alias semantics, and the rate-limit windows, move on a research-preview cadence. Where re-verification finds drift, the changed value lands here as a recorded entry rather than silently inside a lane body.