freeharness 0.4.1 → 0.4.2

package/canonical/skills/subagent-driven-development/SKILL.md

@@ -1,60 +1,67 @@
 ---
 name: subagent-driven-development
-description: Use when executing an approved tasks.md from an OpenSpec change: one brief per task under .freeharness/sdd/<change>/, a fresh implementer per dispatch with an explicit tier and a disjoint write scope, a JSON handoff, the lead's own test run and diff review, one combined task reviewer, a 5-round circuit breaker and one final branch review via code-review. Not for ad-hoc one-file edits.
+description: Use when executing an approved tasks.md from an OpenSpec change: one small brief per task under .freeharness/sdd/<change>/, a fresh implementer per dispatch routed by class, tier and effort with a disjoint write scope and acceptance probes, a JSON handoff, the lead's own test run and diff review, one combined task reviewer, fix rounds only for blocking findings, a round-cap circuit breaker and one final branch review via code-review. Not for ad-hoc one-file edits.
 ---
 
 # Subagent-Driven Development Protocol
 
 <orchestrator_directive>
-The primary session is the lead: it dispatches, evaluates and rules; it never writes production code while executing `tasks.md`. A feature starts at `/opsx:propose`; this skill runs the approved `tasks.md` after `/opsx:apply`. Continuous execution: no "should I continue?" between tasks; the stop conditions below are the only pauses.
+The primary session is the lead: it dispatches, evaluates and rules; it never writes production code while running `tasks.md`. A feature starts at `/opsx:propose`; this skill runs the approved `tasks.md` after `/opsx:apply`. Continuous execution: no "should I continue?" between tasks; only the stop conditions below pause it.
 </orchestrator_directive>
 
 <workspace>
-- Artifacts live in `.freeharness/sdd/<change>/` (gitignored; `init --project` creates it): `<task>.brief.md` and `<task>.review.md`. Files survive compaction; after compaction trust the review packages, `tasks.md` checkboxes and `git log`, never recollection.
-- Templates: `reference/brief.md`, `reference/handoff.md`. The validator `scripts/validate-handoff.mjs` has six subcommands: `briefs <dir|file...>` (header lines, Spec = change id, digest budget, write-scope overlap), `handoff <file> [--base <sha>] [--brief <brief.md>] [--in-flight <brief.md>...] [--lead <path>...]` (schema plus the diff guards; `--lead` excludes the lead's own paths), `budget <ledger.jsonl> <task> [--ceiling <n>]`, `ledger <change-dir>`, `recover <transcript.jsonl> <report> [--force]` and `name <dispatch-name>` (checks a dispatch name and prints the corrected form).
+- Artifacts live in `.freeharness/sdd/<change>/`: `<task>.brief.md` and `<task>.review.md`, plus the ledger, state and round-base files. Files survive compaction; trust the review packages, `tasks.md` checkboxes and `git log`, never recollection.
+- Templates: `reference/brief.md`, `reference/handoff.md`; the tier map is the emitted `reference/tiers.md`; the validator is `scripts/validate-handoff.mjs`. Read reference/workspace.md when the run starts or a validator subcommand's arguments are needed.
+- Preflight, before task 1: scan pairs of tasks sharing a file or an interface and rule on conflicts in a `## Preflight` note of the first review package.
 - Worker rules, restated in every brief: never `git stash`, `git checkout --` or `git reset` in the shared working tree (prove RED by writing the tests first or against a temp copy), and never dispatch a subagent.
-- Before task 1: read `tasks.md` once, list the tasks, note Global Constraints; scan pairs of tasks that share a file or an interface and rule on conflicts (spec is the authority) in a `## Preflight` note of the first review package.
+- Lead context rules: run `name`, `briefs` and `budget` for a dispatch in one Bash call and every `openspec follow-up add` of a task close in one Bash call; per round read the `git diff --stat`, the guard output and the gate output only, and read the full task diff once, at acceptance; never paste a worker transcript or a full diff into the conversation when a file path serves; run `/compact` at a task boundary once the lead context passes 200,000 tokens; the workspace files carry the state.
 </workspace>
 
 <dispatch>
-1. Brief: write `<task>.brief.md` (template). Header `Spec:` is the OpenSpec change id, never a copied spec; `Tier:` is explicit on every dispatch (fast for transcription of complete plan text or one-file mechanical edits, standard for multi-file integration, strong for design judgment; an omitted tier silently inherits the session model). Write scope names every file the worker may touch.
-2. Disjoint write scopes: run `validate-handoff.mjs briefs` over the batch; any overlap refuses the whole batch naming the file. Two implementers never run in parallel on intersecting scopes.
-3. Batch small same-shape tasks (the same one-line edit or field across files) into one brief and one dispatch; work that needs its own tests, judgment or review surface gets its own dispatch.
-4. Dispatch a fresh implementer with the brief path, the report path and the interfaces earlier tasks produced; nothing from the session history. The implementer follows `test-driven-development`; dispatch `test-writer` for the RED step when the failing tests are non-trivial. Record `Base:` (`git rev-parse HEAD`) before dispatching.
-5. At most 3 implementers in flight; a fix-round resumption counts as one. The fourth task waits for a slot; more than three needs a user ask recorded in the review package.
-6. Dispatch names follow `<role>-<task>[-r<round>][-<slug>]`: `impl-2_3`, `fix-2_3-r2`, `impl-1_3b` (a batch), `review-final-r1` (the final review) and `review-final-r1-security` (one of that round's parallel reviewers, the slug naming its lens). Write `_` for `.` because the Agent tool rejects a dot in a name; the ledger stores the dotted id and reads role, task and round through the slug. The lens slug is lowercase letters, digits and hyphens (`review-final-r1-lenses-b`); any other character leaves role and task null in the ledger. Before every dispatch, run `validate-handoff.mjs name <dispatch-name>` and use the printed corrected form.
-7. Budget: run `validate-handoff.mjs budget <ledger.jsonl> <task>` before every dispatch of a task, and again when its handoff is accepted; the brief's `Ceiling:` header overrides the default of 25,000,000 cache-read tokens for that task.
-8. Rewrite the brief's `## Why and rulings` digest before every re-dispatch (a fix round, a re-brief after `partial` or `blocked`) so it still matches the current decisions; a deviation the handoff does not cite is a reviewer P0 tagged `why-digest`.
-9. No nested subagents: a worker never dispatches helpers or reviewers; a worker-spawned reviewer is a defect, not rigor.
+1. Brief: start `<task>.brief.md` with `validate-handoff.mjs brief-init <change> <task>` and fill every `<fill: ...>` placeholder it leaves (the template stays the source of the fixed parts; `briefs` refuses one left); one task id per brief and per dispatch, never a batch. Header `Spec:` is the OpenSpec change id, never a copied spec; `Tier:` is explicit on every dispatch. Route by `Class:`: `docs`, `extraction`, `exploration` and `mechanical` (documentation, extraction, exploration, mechanical edits such as matrix rows, renames, one-line values and transcription of complete plan text) run on standard or strong; `summary` on fast, standard or strong, and `extraction` also on fast; `security` (a task that changes a security boundary: a guard, a hook verdict, an auth or secret path, input validation of untrusted payloads) and `complex` (a parser or state machine, concurrency, a cross-file contract, or a task that reached the round cap before; a validator tokenizer or collector edit routes as `complex` unless it changes a verdict a legitimate worker command reaches; lead-written files owe no hostile-input tests) run on strong with `Effort: high` only; `code` (a code change that is neither `security` nor `complex`) runs on strong, or on standard only with `Route: C1-C7 - <reason>` per `reference/brief.md`; any other class, or none, runs on strong only. A fast brief's reading set stays under 100,000 tokens at 4 bytes per token; the validator checks the class, never that bound. A fix round's tier and effort are what `validate-handoff.mjs route <brief> --round <n> [--p0] [--security]` prints (`--p0` or `--security` for a round carrying such a finding), and `round-base` given the same flags refuses a brief below them. `Effort:` is `medium` (default) or `high`, `high` on strong only. Write scope names every file the worker may touch. Read reference/loop.md when a brief is written: the sizing bounds and the split rule, the fixture scope, the grep for statements pinning a changed value, and the class ceilings.
+2. Probes and project rules: before the dispatch write `## Acceptance probes` (1 to 12 lines, `P<n>: <command, input or observable> -> <expected outcome>`) from the spec scenarios and the design's edge cases; a `security` or `complex` brief carries one probe expecting an allow or a pass and one corpus, fixture replay or generator probe. Fill `## Project rules` (1 to 20 lines) from the project CLAUDE.md invariants and protected boundaries that bear on the write scope plus the artifact rules; workers run without CLAUDE.md, so the section is their only copy. A probe of a guard or hook verdict runs the hook through node on a payload file (reference/brief.md).
+3. Disjoint write scopes: run `validate-handoff.mjs briefs` over the dispatch; any overlap refuses the whole batch naming the file, so no two implementers in flight share a file.
+4. Dispatch a fresh `implementer` agent with the brief path, the report path and the interfaces earlier tasks produced; nothing from the session history. On every implementer, test-writer and fix dispatch the per-dispatch model is the brief's `Tier:` resolved through `reference/tiers.md` (the alias the tier maps to; never a model name in this skill) and the per-dispatch effort is the brief's `Effort:` (`medium` when absent); the agent frontmatter is never the source of a brief's effort. An omitted per-dispatch model falls back to the implementer agent's tier. A per-dispatch effort overrides the frontmatter effort. A team dispatch inherits the session effort, except a plugin-defined agent spawned by name, which keeps its own; the agent frontmatter effort applies to plain subagent dispatches. The implementer follows `test-driven-development`; dispatch `test-writer` for the RED step when the failing tests are non-trivial. Record `Base:` (`git rev-parse HEAD`) before dispatching. Reviewers and implementers are never resumed: every review, re-review and fix round is a fresh dispatch. Dispatch every implementer, test-writer and reviewer through the Agent tool without `name`: the prompt's first line is `Dispatch: <dispatch-name>` and the Agent tool `description` repeats it. A named dispatch launches as a teammate when agent teams are enabled, at the session effort by the team rule above and with no SubagentStop until shutdown; without `name` it stays a plain subagent.
+5. Band of implementers in flight: small, at most 4 (the default); medium, at most 8; large, at most 12, only on the user's ask recorded in the review package with the latest quota reading under 50%. Medium or large only when the median accepted-task duration in the ledger exceeds four times the lead's service time per task. At most 16 dispatches of any role in flight. Every implementer runs in its own worktree whenever more than one is in flight. Read reference/trees.md when more than one implementer is in flight.
+6. Dispatch names follow `<role>-<task>[-r<round>][-<slug>]`: `impl-2_3`, `fix-2_3-r2`, `impl-2_4_1` (a sub-task), `review-final-r1` (the final review) and `review-final-r1-security` (one of that round's parallel reviewers, the slug naming its lens). The name goes in the prompt and the `description` (rule 4), never in the `name` parameter. Write `_` for `.`. The lens slug is lowercase letters, digits and hyphens. Before every dispatch, run `validate-handoff.mjs name <dispatch-name>` and use the printed corrected form. Read reference/loop.md when the printed form differs from the name.
+7. Budget: run `validate-handoff.mjs budget <ledger.jsonl> <task>` before every dispatch of a task, and again when its handoff is accepted.
+8. Rewrite the brief's `## Why and rulings` digest before every re-dispatch (a fix round, a re-brief after `partial` or `blocked`) so it still matches the current decisions; a deviation the handoff does not cite is a reviewer P0 tagged `why-digest`. A `[base]`, `hardening` or follow-up finding never enters a later brief's digest or write scope.
+9. No nested subagents: a worker never dispatches helpers or reviewers; a worker-spawned reviewer is a defect.
+10. Frontier: the lead passes the `frontier` model (the alias `frontier` maps to in `reference/tiers.md`) on every `agentic-architect` dispatch (a design, a design review, an architecture review) at effort `high`, or `medium` for a review scoped to one capability or one design decision, and records `Frontier: agentic-architect - <effort> - <reason>` in the review package (planning records: `agentic-architecture`); implementers, test-writers and reviewers never run on `frontier`; under a local-model profile `frontier` is unavailable and `agentic-architect` runs on its frontmatter tier and effort (`strong`, `xhigh`).
 </dispatch>
 
 <handoff>
-The worker returns only the JSON block (schema in `reference/handoff.md`): `task`, `status: completed|partial|blocked`, `files_changed`, `tests_run` (command, result, summary), `evidence` (one line per Verify item), `partial_output` (label of what is missing; required when partial), `blocked_reason` (stop token then detail; required when blocked), `concerns`. Stop tokens end the dispatch at the first one: `too-big`, `needs-confirm`, `ambiguous`, `regressed`, `scope`. Handle: `partial` -> re-dispatch with the label as the task; `blocked` -> fix the cause (context, tier, split, ruling) and re-dispatch; never re-run the same dispatch unchanged.
-On a missing, empty or block-less reply the first step is `validate-handoff.mjs recover <transcript.jsonl> <report>` over `~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl`, never a re-dispatch: it rebuilds the handoff from the last assistant-authored json block and writes it as the head of the review package.
+The worker returns only the JSON block (schema in `reference/handoff.md`): `task`, `status: completed|partial|blocked`, `files_changed`, `tests_run`, `evidence` (one line per Verify item and per probe id), `partial_output` (required when partial), `blocked_reason` (stop token first; required when blocked), `concerns`. Stop tokens end the dispatch at the first one: `too-big`, `needs-confirm`, `ambiguous`, `regressed`, `scope`. Handle: `partial` -> re-dispatch with the label as the task; `blocked` -> fix the cause (context, tier, split, ruling) and re-dispatch; never re-run the same dispatch unchanged. A guard `needs-confirm` on a line naming no guarded path: reference/loop.md.
+Every report ends with `## Checkpoint` (reference/handoff.md). The task's working state `<task>.state.md` is written by the SDD context hook at SubagentStop when installed, otherwise run `validate-handoff.mjs state <report> <task>.state.md`.
+On a missing, empty or block-less reply the first step is `validate-handoff.mjs recover <transcript.jsonl> <report>` over `~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl`, never a re-dispatch (reference/handoff.md).
 </handoff>
 
 <acceptance>
-- Worker reports are not acceptance. The lead reviews the final diff (`git diff <base>..HEAD`) and runs the Verify commands itself, then appends `## Lead evaluation` to the review package with the commands and their summary lines. A task with only the worker's claim is never marked done.
-- Guards before the reviewer: run `validate-handoff.mjs handoff <report> --base <Base> --brief <brief.md>`, adding `--in-flight <brief.md>` for every other brief still running so a peer's files are not charged to this worker, and `--lead <path>` for the lead's own paths (the change's `tasks.md`, any review package outside `.freeharness/`) so they are not charged either; a `claimed-unchanged`, `changed-unclaimed`, `scope`, `peer-scope` or `lead-path` failure returns to the worker as findings (a round), never straight to the reviewer; `peer-scope` means the worker claimed a file another dispatch owns, `lead-path` means it claimed one of the lead's own paths, neither ever worth passing on.
-- One combined task reviewer per task (spec compliance + code quality in one dispatch, tier explicit) reads the brief, the review package and the diff file; it treats the report as unverified claims. Findings follow the reviewer contract: `path:line: P0|P1|P2: problem. fix.` At most 3 reviewer dispatches per round; a fourth waits for a second round unless a user ask for more is recorded in the review package.
+- Worker reports are not acceptance. The lead reviews the final diff (`git diff <base>..HEAD`) once and runs the Verify commands itself, every probe included, then appends `## Lead evaluation` to the review package with the commands and their summary lines. A task with only the worker's claim is never marked done. A handoff whose `tests_run` holds no test command (a build alone) is `partial`, and the lead's run covers every test file that exercises an edited source, not only the files the brief names. A `Verify` list holds the task's tests plus the affected tests the changed-term check found, and implementers run only the Verify commands; the lead alone runs the full suite (the brief's `Suite:` command), at most one run at a time, after each accepted wave of parallel tasks and at the whole-change gate (reference/loop.md, "Test tiers and waves").
+- Budget gate: run `validate-handoff.mjs budget <ledger.jsonl> <task>` again when the handoff is accepted; `FAIL ceiling reached` stops dispatching the task and requires the same `## Controller ruling` as the circuit breaker.
+- Guards before the reviewer: run `validate-handoff.mjs handoff <report> --base <Base> --brief <brief.md> --agent <agent_id>`, adding `--in-flight <brief.md>` for every other brief still running and `--lead <path>` for the lead's own paths; every guard failure returns to the worker as findings (a round), never straight to the reviewer. Read reference/loop.md when a guard fails.
+- One combined task reviewer per task (spec compliance + code quality in one dispatch, tier explicit) reads the brief, the review package and the diff file; it treats the report as unverified claims, checks the brief's probes first (running each) and only then reviews the diff against the spec; a probe the reviewer adds after the dispatch is a finding judged by the blocking rule, never a silent new bar. A reviewer never writes to, reverts or checks out files in the shared working tree and proves a test RED only against a temporary copy outside it. Findings follow the reviewer contract: `path:line: P0|P1|P2 <type>: problem. fix.` with `<type>` one of `defect|hardening|refactor|test-gap|docs|design`, `defect` only when the current behavior violates a spec requirement, a documented contract or a behavior the owner has stated; a follow-up's own `Expected:` line alone never makes it a defect. At most 3 reviewer dispatches per round; a fourth waits for a second round unless a user ask for more is recorded in the review package.
+- Review tier: the lead picks each review dispatch's model (task reviewer, scoped re-reviews, the final branch review's reviewers), standard being the default: it runs `validate-handoff.mjs route <brief> --review --base <Base> [--round <n>] [--p0] [--final-spec] [--probed]` (`--final-spec` for the final branch review's spec-compliance pass, `--probed` (S4) for a scoped re-review whose every finding has a reproducing probe) and writes the printed `Review tier: <tier> - S<n> <reason>` line to the review package before the dispatch.
 - No finding suppression: never tell a reviewer what not to flag, never downgrade a finding for a stated rationale, never drop a finding silently; disagreement is a written ruling.
 - `test-driven-development` proof (failing run, then passing run) is part of the evidence; coverage numbers are not.
 </acceptance>
 
 <fix_loop>
-- A fix round = one fix dispatch + one scoped re-review of the fix diff only. Rounds 1-3 resume the same implementer with the findings verbatim; rounds 4-5 dispatch a fresh implementer one tier up with the brief, the report and the findings.
-- Circuit breaker: after round 5 with findings still open, stop dispatching. Write `## Controller ruling` to the review package for every open finding (real and load-bearing: smallest unblocking change, carried into the next brief; real and deferred, or contested: parked with the reason and the cost if wrong). Then ask the user before the next task; a structural defect that leaves every path a guess stops the run.
-- Second breaker: the budget ceiling. When `budget` reports `FAIL ceiling reached` for the task, stop dispatching it and write the same `## Controller ruling` as at round 5, one entry per open finding, each ruling carrying an id in the `R:<task>.<n>` form so the next brief's digest can cite it.
-- Every round appends `round <n>/5: <addressed>/<open>` to the review package. The lead never fixes findings itself.
+- Blocking: a finding is blocking when it is a P0, or a P1 `defect` introduced by the task's diff (it does not reproduce at the task's `Base:` for a task review, or at the round base for a re-review) or one that fails a brief probe or a spec scenario, or, on a `security` or `complex` task, a P1 of any type introduced by the diff that fails a brief probe, a spec scenario or the corpus probe against the base. The reviewer tags a P1 `defect` that reproduces at the base `[base]`; a `[base]` finding is never blocking. Only blocking findings open a fix round; every other finding is a follow-up recorded at task close. A non-blocking `docs` or `test-gap` finding, or a comment fix, may ride round 1 when a blocking finding opened it and the fix stays inside the write scope, never a later round. A blocking finding whose fix lies outside the write scope gets a controller ruling and a new brief, never a round. The lead retypes a finding only through a written ruling line. The gate cannot tell that a finding meets the evidence test (reference/loop.md): on a `security` or `complex` task the lead retypes such a P1 to `defect` through a written ruling line before running `gate`, so it blocks.
+- Ledger and gate: `<task>.findings.md` holds one line per finding, `F<n> <open|fixed|rejected|follow-up> r<round>: <reviewer contract line>`, written only by the lead. After every review run `validate-handoff.mjs gate <findings.md>`: it prints each `open` line as `blocking` or `follow-up` with the reason and exits non-zero when any is blocking; with no blocking line the task is accepted.
+- A fix round = one fix dispatch + one scoped re-review. Before each fix dispatch run `validate-handoff.mjs round-base <brief.md> <n>`, the round-cap check (it refuses `round-cap <n> over <cap>`), which copies the write-scope files under `rounds/<task>-r<n>/`. Every round dispatches a fresh `implementer` given the brief, the review package and `<task>.findings.md` (the ledger), on the tier and effort `route` prints for the round (dispatch rule 1; strong from round 3 on, never frontier, which is reserved for the agentic-architect role (dispatch rule 10)). Read reference/loop.md when a fix dispatch is written: the fix prompt order and the task state.
+- Re-review: a fresh re-reviewer is given only the ledger, the output of `validate-handoff.mjs round-diff <brief.md> <n>` and the probes; it returns a status for each open id and any new findings (from round 2 on only a P0 with a reproducer on the round diff; any other is a follow-up), and judges only the round diff: a finding on code the round diff does not change is a follow-up unless it is a P0.
+- Circuit breaker: at the round cap (3, or the run authorization's `Rounds:`; `round-base` refuses `round-cap`) with blocking findings still open, stop dispatching. Write `## Controller ruling` to the review package for every open finding (reference/loop.md). Then ask the user before the next task, unless every open finding is ruled "remove the addition". Second breaker: the class ceiling (reference/loop.md). At `FAIL ceiling reached` stop dispatching the task and write the same ruling, each with an `R:<task>.<n>` id the next brief's digest can cite.
+- Every round appends `round <n>/<cap>: <addressed>/<open blocking>` to the review package. The lead never fixes findings itself.
 </fix_loop>
 
 <completion>
-- Per task: lead evaluation present, review clean (or rulings written at the cap), `verification-before-completion` evidence recorded, then tick `[x]` in `tasks.md`.
-- After the last task: one final branch review via `code-review` over `git merge-base` to HEAD (domain reviewers + `pr-reviewer`, strong tier), under the same cap of 3 reviewer dispatches per round unless a user ask for more is recorded in the review package; one fix dispatch for the whole findings list, one scoped re-review, rulings for residuals. Then `git-workflow` for commit and PR; `/opsx:archive` when the change is done, with its compound step (retrospective line, telemetry file, rules or skill delta, memory observation).
-- Every deferred item (a parked ruling, a reviewer finding carried forward, a machine-only measurement) is recorded with `openspec follow-up add <change-id> "<text>" --from <task>`, never as prose; archive prints the unclaimed items.
-- Final message lists every ruling made (what, why, cost if wrong) and the `validate-handoff.mjs ledger <change-dir>` summary of dispatches and cache-read spend per task: a ruling that dies in the workspace was a decision made in secret.
+- Per task: lead evaluation present, gate clean (or rulings written at the cap), `verification-before-completion` evidence recorded, then tick `[x]` in `tasks.md`, then commit the task with `validate-handoff.mjs commit <report> [<report>...] -F <message-file> --lead <tasks.md>`, listing every report of the task, adding `--tree <Tree> --base <sha>` for a tree task (the lead writes the message file; the tick rides in the same commit). Every accepted task is committed this way, never by `git add` plus `git commit`. Read reference/loop.md when a task is committed.
+- After the last task: one final branch review via `code-review` over `git merge-base` to HEAD. Read reference/loop.md when the final branch review starts. Before the first final-review dispatch, write `final.brief.md` in the change workspace (header `Task: final`, the change's other headers, `Tier: strong`), since the cost tracker writes no ledger line for a dispatch whose task no in-flight brief declares; the lead writes it from the template, the fix dispatch reads it, and `validate-handoff.mjs briefs` checks it like any brief. Then `git-workflow` for commit and PR; `/opsx:archive` when the change is done, with its compound step (retrospective line, telemetry file, rules or skill delta, memory observation).
+- Every deferred item (a non-blocking finding, a parked ruling, a machine-only measurement) is recorded with `openspec follow-up add <change-id> '<text>' --type <type> --expected '<...>' --current '<...>' --impact '<...>' --from <task>`, never as prose, the type and the expected, current and impact context taken from the finding, plus `owner-step` for a machine or owner measurement and `upstream` for an item owed upstream; the lead passes every value single-quoted (a `'` written as `'\''`) because finding text may quote shell syntax that double quotes would expand; archive prints the unclaimed items.
+- Final message lists every ruling made (what, why, cost if wrong) and the `validate-handoff.mjs ledger <change-dir>` summary of dispatches and cache-read spend per task.
 </completion>
 
 <stop_conditions>
-Stop and ask the user only for: an irreversible or destructive operation; a security-sensitive action; a side effect outside the worktree (merge, push to a shared branch, publish); a task flagged "Ask first" in the proposal; the circuit breaker; a plan so broken that every path forward is a guess. Everything else is a ruling, written down, and the run continues.
+Stop and ask the user only for: an irreversible or destructive operation; a security-sensitive action; a merge or push outside the change branch, or a publish; a task flagged "Ask first" in the proposal; the round cap or the class ceiling of the run authorization (the circuit breaker); a plan so broken that every path forward is a guess. Ceilings and the round cap come only from the owner (proposal.md `## Run authorization`, or `--ceiling`); the lead never raises them, and stops for neither below them. A cap with every finding ruled "remove the addition" is no stop. Everything else is a ruling, written down, and the run continues.
 </stop_conditions>