okstra 0.206.0 → 0.207.0

package/runtime/skills/okstra-code-review/SKILL.md

@@ -6,9 +6,10 @@ description: >-
   unrelated to an okstra run. The tell is a review request over a diff:
   "review this stage", "review my branch", "code review", "leave the review
   in a file". The orchestrator censuses the diff into an explicit worklist,
-  four parallel reviewers return a verdict for every cell against this
-  project's coding-preflight rules, and a coverage audit re-dispatches any
-  gap. NOT for writing a PR body (okstra-pr-gen), starting a run
+  one or two reviewers (the user picks) each return a verdict for every cell
+  against this project's coding-preflight rules, a coverage audit
+  re-dispatches any gap, and the orchestrator settles what the reviewers
+  disagree on. NOT for writing a PR body (okstra-pr-gen), starting a run
   (okstra-run), or inspecting a finished task (okstra-inspect).
 ---
 
@@ -79,7 +80,7 @@ okstra code-review target --task-key <taskKey> --stage <N> --project-root <proje
 okstra code-review target --branch <name> [--base <ref>] --project-root <projectRoot> --text
 ```
 
-`Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, and `Round`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
+`Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, `Round`, and `Report language`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
 
 `Status: error` carries `Failure stage` and `Failure reason`. Report both and stop, unless the Exceptions table names that case.
 
@@ -95,7 +96,7 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
 
 **You never derive the base.** Pass `--base <ref>` only when the user named one; otherwise the CLI resolves it. `baseCommit` is a **ref, not necessarily a commit id** — a caller-supplied `--base` passes through verbatim — so use it as given in `git diff <baseCommit>..<headCommit>` and never present it as "commit `<sha>`".
 
-**Where to run git.** Use `worktreePath` when it is non-empty; otherwise run git in `projectRoot` and read the stage's `branch` ref. An empty `worktreePath` does **not** mean the stage is gone: a completed stage's registry row is `released`, so the field is empty even when the directory is still on disk. Either way the commits are on the branch.
+**Where to run git.** Use `worktreePath` when it is non-empty; otherwise run git in `projectRoot` and read the stage's `branch` ref. An empty `worktreePath` does **not** mean the stage is gone: a completed stage's registry row is `released`, so the field is empty even when the directory is still on disk. Either way the commits are on the branch. With no worktree there is no checked-out tree to read whole files from, so every brief tells the reviewer to read a file at the reviewed commit with `git -C <projectRoot> show <headCommit>:<path>` — never from the project root's working tree, which holds a different commit.
 
 **Then show the base and confirm it — branch mode and stage mode alike.** The CLI's answer is a recommendation the user has not seen yet, and a base nobody looked at is how unrelated commits slip into a review unnoticed. Print `baseCommit` verbatim next to `git -C <workdir> log -1 --oneline <baseCommit>` so the commit it names is legible, then ask with a 3-option picker:
 
@@ -117,43 +118,49 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
 
 A large census is never truncated. Report the cell count and confirm before dispatching — a silent cut is a false "I looked at everything" signal.
 
-## Step 3 — Materialize and dispatch four reviewers in parallel
+## Step 3 — Materialize and dispatch the reviewers in parallel
 
-Ask the runtime what this operation runs — do not choose the role, the providers, or the reviewer count
-here:
+**Ask how many reviewers** with a 3-option picker:
+
+1. `2 reviewers` — **the recommendation**: two different models each review the whole census, and you settle only where they disagree.
+2. `1 reviewer` — cheaper; you adjudicate every finding it returns.
+3. `Enter directly` — always last; accept only `1` or `2`.
+
+Then ask the runtime what those reviewers run — do not choose the role or the providers here:
 
 ```
-okstra agent-prompt resolve-operation --operation code-review
+okstra agent-prompt resolve-operation --operation code-review --count <1|2>
 ```
 
 It prints the duty, the role, the reviewer count, and one `slot` line per reviewer carrying that slot's
-provider and model. The contract owns those values (`agents/operations/code-review.json`), so a machine
-with too few distinct models fails here rather than quietly running fewer reviewers. Dispatch exactly the
-slots it prints.
+provider and model. The contract owns those values (`agents/operations/code-review.json`, whose `count` is
+the ceiling), so a machine with too few distinct models fails here rather than quietly running fewer
+reviewers. Dispatch exactly the slots it prints.
 
 Every reviewer and later gap-fill is a separate auditable standalone invocation. For each slot, create
 `.okstra/agent-invocations/code-review/<invocation-id>.instructions.md` from that reviewer's brief, then run
-`okstra agent-prompt materialize` with `--purpose code-review`, `--audience <dutyId>`, that slot's
-`--provider` and `--model <modelRef>`, and the canonical `.prompt.md` path beside it; the returned
-assignment is authoritative. Run `okstra agent-prompt verify` against the returned `metadataPath` before
+`okstra agent-prompt materialize --project-root <projectRoot> --invocation-id <invocation-id> --host-runtime <runtime> --provider <slot provider> --model <slot model> --model-role <role> --audience <duty> --purpose code-review --instruction <instructions-path> --prompt <prompt-path>`,
+copying `role`, `duty`, and the slot's `provider` and `model` verbatim from `resolve-operation` (`--model`
+takes the `provider/model` value the slot line prints). The prompt path is the canonical `.prompt.md` beside
+the instructions file; the returned assignment is authoritative. Run `okstra agent-prompt verify` against the returned `metadataPath` before
 invoking any model.
 
 For a native host call, pass the verified prompt body and `hostModelValue`. For a deterministic provider
 process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path>`
 with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
 standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
-`.log`. Never substitute one model value for the other. Dispatch the four verified calls in parallel when the host supports
-it. Every brief carries:
+`.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
+it. **Every reviewer receives the same brief** — two reviewers are worth their cost only when both look at every cell. Every brief carries:
 
-- the diff, plus the work directory path so the reviewer can read whole files for context
+- the diff, plus how to read whole files at the reviewed commit: the `worktreePath` when it is non-empty, otherwise `git -C <projectRoot> show <headCommit>:<path>`
 - the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
-- **its own axis's cell list**, verbatim from the census
-- the absolute paths of the packs its axis reads (from step 2's routing)
+- **the whole census** — every cell of all four axes, verbatim
+- the absolute paths of every applied pack (from step 2's routing)
 - the calibration path, written out in full as Step 2 fixed it — `~/.agents/skills/okstra-code-review/references/review-calibration.md`. The verdict format, the severity points, and the rules for a legitimate `clean` are defined there, not in the brief; a reviewer that cannot open this file cannot return a usable verdict, so never hand it a relative path or a "next to the skill" hint
 
 Each axis is **one rule group**, so a cell is `target × <axis>` — never `target × <individual rule>`. The reviewer names the specific rule it found violated inside the verdict's `rule` field, and one cell may carry findings from several rules of its group.
 
-Axis scope — the `Reads` column names that group's rules, and a brief never restates them; the bodies are in the packs:
+Axis scope — each reviewer works all four axes; the `Reads` column names each group's rules, and a brief never restates them; the bodies are in the packs:
 
 | Axis | Cell | Reads |
 |---|---|---|
@@ -172,18 +179,47 @@ review result and cannot contribute a verdict.
 
 ## Step 3.5 — Audit the coverage
 
-Diff each reviewer's verified `returnedBody` cells against the slice you handed it. Any cell without a verdict
-→ dispatch **one gap-fill invocation per axis**, carrying only the missing cells and the same brief. Each
+Diff each reviewer's verified `returnedBody` cells against the census. Any cell without a verdict
+→ dispatch **one gap-fill invocation per reviewer**, on that reviewer's slot, carrying only its missing cells and the same brief. Each
 gap-fill uses a new invocation ID and repeats the full materialize → verify → dispatch → materialize-result →
-complete → verify-completion boundary from Step 3. Repeat until every cell of every axis has a verdict.
+complete → verify-completion boundary from Step 3. Repeat until every reviewer has a verdict for every cell.
+
+A missing verdict is unfinished work, never an implicit `clean`. Do not start Step 3.6 while a single cell is unaccounted for.
+
+## Step 3.6 — Check every citation
+
+Reviewers miscount lines. Pass every finding's `path:line` to one call:
+
+```bash
+okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
+```
+
+`ok` keeps the citation. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
+
+## Step 3.7 — Settle the findings
+
+Reviewers are wrong in a way a census cannot catch: a claim about code they did not open. What you settle depends on the reviewer count. A `must-fix` or `should-fix` with no `failure` or no `evidence` is rejected as "no failure scenario" in either case — the calibration requires both.
+
+**Two reviewers.** Pair the findings first: two findings are the same finding when they cite the same `path:line` and describe the same defect. Then:
+
+- **Agreed** — both reviewers report it with the same severity and timing. It stands as reported; you do not adjudicate it.
+- **Graded differently** — both report it, with a different severity or timing. Pick one of the two values after reading the code, and record both values and your reason in the finding. Never pick a third value.
+- **One-sided** — one reviewer reports it and the other returned `clean` for that cell or reported something else. Adjudicate it as below.
+
+**One reviewer.** Adjudicate every finding it returns.
+
+**Adjudicating** a finding: open each `evidence` location at `headCommit`, plus the definition of every symbol its `failure` depends on, and check the `failure` against that code.
+
+- **Confirmed** — the code produces the stated failure. The finding keeps its severity and timing.
+- **Rejected** — the code contradicts the claim (the called function never reads `this`, the value cannot be null there, the branch is unreachable). Move it to `Rejected` with the contradicting `path:line` and one sentence on what it shows.
 
-A missing verdict is unfinished work, never an implicit `clean`. Do not start Step 4 while a single cell is unaccounted for.
+Rejecting is a statement about the code, so it always carries a `path:line`. Never reject for being unconvinced. Apart from choosing between two reviewers' values, never promote, demote, or re-time a finding. Confirmed and agreed `park` findings go to `Parked`, unscored.
 
 ## Step 4 — Merge and write
 
 1. **Read `references/review-calibration.md`** (next to this file) and follow its report section — you are the one writing the file, and it fixes the Coverage sentence, the per-finding line format, the Score table columns, and the total row. The reviewers were given it for their verdicts; the report obeys it too.
-2. **Dedupe across axes.** The same defect surfaced by two axes stays once, under the rule that explains it best.
-3. **Severity is the reviewer's.** The merge concatenates and dedupes; it never re-grades. If a verdict looks wrong, the brief was wrong — improve the brief for next run and ship this one as returned.
+2. **Dedupe across axes and reviewers.** The same defect surfaced by two axes or two reviewers stays once, under the rule that explains it best, and each finding says how it was settled: `agreed`, `graded by orchestrator`, or `confirmed by orchestrator`.
+3. **Severity is the reviewers'; truth is yours.** The merge never re-grades or re-times a finding except by choosing between two reviewers' values in Step 3.7.
 4. **Write the report to `reviewPath`** with the Write tool (it creates the parent directories). Frontmatter fields, in this order:
 
 ```yaml
@@ -192,14 +228,15 @@ taskKey: <task-key>          # stage mode
 branch: <branch>             # branch mode
 stage: <N>                   # stage mode only
 round: <round>
+reviewers: [<provider/model>, ...]   # the slots Step 3 dispatched
 baseCommit: <exactly as the CLI returned it>
 headCommit: <headCommit>
 packs: [<applied coding-preflight pack paths>]
 generatedAt: <YYYY-MM-DD HH:MM>
 ```
 
-   Body sections, in this order: `## Coverage`, `## Must-fix`, `## Should-fix`, `## Nits`, `## Score`. Empty severity sections are omitted; `Coverage` and `Score` are always present, and a review with no findings still emits the Score table with a total of 0.
-5. **In the session, print only** the `reviewPath`, the count per severity, and the score total. The file is the deliverable — do not replay the findings in chat.
+   Body sections, in this order: `## Coverage`, `## Must-fix`, `## Should-fix`, `## Nits`, `## Parked`, `## Rejected`, `## Score`. Empty sections are omitted; `Coverage` and `Score` are always present, and a review with no confirmed `now` findings still emits the Score table with a total of 0. The score counts confirmed `now` findings only. Write the prose in the `Report language` from Step 1.
+5. **In the session, print only** the `reviewPath`, the count per severity, the parked and rejected counts, and the score total. The file is the deliverable — do not replay the findings in chat.
 
 ## Exceptions
 
@@ -207,7 +244,7 @@ generatedAt: <YYYY-MM-DD HH:MM>
 |---|---|
 | `preflight` reports `Okstra preflight: failed` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
 | `unknown command: code-review` | the `okstra` binary predates this skill — tell the user to update it (`npm i -g okstra@latest`) and stop |
-| `worktreePath` is empty | not a hard stop and not a missing stage: run git in `projectRoot` against the stage's `branch` ref and continue |
+| `worktreePath` is empty | not a hard stop and not a missing stage: run git in `projectRoot` against the stage's `branch` ref, and have reviewers read whole files with `git -C <projectRoot> show <headCommit>:<path>` |
 | `baseCommit` is not an ancestor of `headCommit` — `git -C <workdir> rev-list --count <headCommit>..<baseCommit>` returns a **non-zero** count, meaning a rebase or squash rewrote the history the stage was recorded against, and `<baseCommit>..<headCommit>` would drag predecessor work in backwards | code-review is read-only, so do not force a reconcile. Offer two options: review against the branch's current tip, or run `okstra git-reconcile` first and retry |
 | the diff is empty | dispatch no reviewers; write the "no changes" report to `reviewPath` and stop. It is a normal report, not a free-form note: the same frontmatter, `## Coverage` reading "0 changed files → 0 cells on every axis, 0 files excluded" plus the applied packs, every severity section omitted, and `## Score` carrying the table with its single total row reading 0 |
 | the census is large | never truncate — report the cell count and confirm before dispatching |
@@ -215,9 +252,10 @@ generatedAt: <YYYY-MM-DD HH:MM>
 
 ## Principles
 
-- **Stay in the diff.** Every finding cites a line this diff changed. A cell whose only wart sits on untouched lines verdicts `clean` — pre-existing issues are not this change's problem.
+- **Stay in the diff.** Every finding cites a line this diff changed, and Step 3.6 checks it. A cell whose only wart sits on untouched lines verdicts `clean` — pre-existing issues are not this change's problem.
 - **Don't manufacture findings.** A census fully verdicted `clean` is a valid, useful result.
 - **No finding without a fix.** Readability findings carry a pseudocode sketch; naming findings carry a concrete alternative name.
 - **The census is law.** A reviewer that rebuilds its own worklist reintroduces exactly the run-to-run variance this skill exists to kill.
 - **Every cell gets a verdict.** `clean` is a result, not an omission; the audit treats a gap as unfinished work.
-- **The report prose is Korean.** Paths, identifiers, rule names, and quoted code stay verbatim.
+- **Only a checked claim scores.** A finding reaches the score after its citation is on a changed line and its failure holds against the code; everything else is `Parked` or `Rejected`, with its reason.
+- **The report prose follows `Report language`.** Paths, identifiers, rule names, and quoted code stay verbatim.

package/runtime/skills/okstra-code-review/references/review-calibration.md

@@ -18,11 +18,16 @@ A cell covers its whole rule group, so it can carry several findings from severa
   rule: DRY
   line: 42
   severity: must-fix
+  timing: now
   snippet: `discount = subtotal * 0.15 if tier == "gold" else 0`
+  failure: when the gold rate changes in `domain/tiers.py`, this line keeps charging 15% and the two prices disagree.
+  evidence: `domain/tiers.py:18`
   note: The same tier→rate table is already in `domain/tiers.py:18`; a rate change now has two homes. Call the existing lookup instead of re-expressing it here.
 ```
 
-Fields: `cell` (`target × axis`, exactly as the census wrote it — the axis is the rule group, and there is never one cell per individual rule), `verdict` (`clean` | `finding`), `rule` (the specific rule this finding violates, spelled as its pack spells it; omitted on `clean`), `line` (a line **this diff changed**), `severity`, `snippet` (the quoted changed line), `note` (1–2 sentences: what is wrong plus a concrete fix).
+Fields: `cell` (`target × axis`, exactly as the census wrote it — the axis is the rule group, and there is never one cell per individual rule), `verdict` (`clean` | `finding`), `rule` (the specific rule this finding violates, spelled as its pack spells it; omitted on `clean`), `line` (a line **this diff changed**, numbered at the head commit), `severity`, `timing` (`now` | `park`, below), `snippet` (the quoted changed line, verbatim — the orchestrator locates the finding by it), `failure` (required at `must-fix` and `should-fix`: the input or state that produces the wrong result, and what goes wrong), `evidence` (required at `must-fix` and `should-fix`: every `path:line` you opened to establish the failure — the definitions of the symbols the claim depends on, not only the cited line), `note` (1–2 sentences: what is wrong plus a concrete fix).
+
+**Open the definition before you claim its behaviour.** A claim about what a called function, method, or value does — that it reads `this`, throws, mutates its argument, returns `null` — cites that definition in `evidence`. A claim you could not check against its definition is not a finding; it is `clean`. The orchestrator opens every `evidence` location and rejects a finding the code contradicts.
 
 There is no length budget. Dropping a real finding to stay brief is the failure this review exists to prevent, and a missing cell is re-dispatched as unfinished work, never read as a clean.
 
@@ -36,6 +41,15 @@ There is no length budget. Dropping a real finding to stay brief is the failure
 
 Grade the defect, not your confidence. If you are not confident, the verdict is `clean` — see the hedge test below.
 
+**Name the failure.** A `must-fix` or `should-fix` states the input or state that produces the wrong result (`if the header is absent, line 42 throws before the 401 is returned`). Code that works as written is not a defect, however you would have written it differently: alternative structures, defensive guards for states no caller reaches, and "consider extracting / renaming / memoizing" are improvements. An improvement is either `park` or `clean`, never a `now` finding.
+
+## Timing — `now` or `park`
+
+- `now` — this change should fix it before it merges: a defect on a changed line, or a rule violation the change introduced.
+- `park` — real, but not this change's to fix: the fix lies outside the diff, or the code is correct and the finding asks for more (a regression test for behaviour that already works, a follow-up refactor). Parked findings are listed in the report and **do not score**.
+
+Every finding carries `timing`. When unsure, ask whether merging without the fix leaves this change wrong; if not, it is `park`.
+
 ## When `clean` is the right verdict
 
 `clean` is a result, not a concession. Return it when:
@@ -62,19 +76,25 @@ Loose typing in test files (`any`, dynamic casts, untyped fixtures) is a **typin
 
 ## The report
 
-Merged by the orchestrator, written to `reviewPath`. Sections, in this order, empty ones omitted except `Coverage` and `Score`:
+Merged and adjudicated by the orchestrator, written to `reviewPath`. Sections, in this order, empty ones omitted except `Coverage` and `Score`:
 
 ```
 ## Coverage
 ## Must-fix
 ## Should-fix
 ## Nits
+## Parked
+## Rejected
 ## Score
 ```
 
-- **Coverage** — one or two lines: N changed files → S `structural` / F `semantic` / T `state-and-tests` / G `general` cells, all verdicted; M files excluded with reasons; the applied packs, and any pack that was unavailable. The four counts are cell counts at the census's granularity — one cell per target per axis.
-- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix.
-- **Score** — every finding gets a row, and the table is emitted even when there are none, with a single total row reading 0:
+- **Must-fix / Should-fix / Nits** — confirmed `now` findings only.
+- **Parked** — `park` findings, with their severity, not scored.
+- **Rejected** — findings the orchestrator's adjudication disproved or that cite no changed line: the reviewer's claim in one line, then the contradicting `path:line` and what it shows. Not scored.
+
+- **Coverage** — two or three lines: the reviewers (`provider/model`, one or two); N changed files → S `structural` / F `semantic` / T `state-and-tests` / G `general` cells, all verdicted by every reviewer; M files excluded with reasons; the applied packs, and any pack that was unavailable; and how the findings were settled — agreed, graded by the orchestrator, confirmed by the orchestrator, rejected. The four cell counts are at the census's granularity — one cell per target per axis.
+- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix. Its note then says how it was settled: `agreed`, `graded by orchestrator` (with both reviewers' values), or `confirmed by orchestrator`.
+- **Score** — every confirmed `now` finding gets a row, and the table is emitted even when there are none, with a single total row reading 0:
 
 ```
 | # | Location | Rule | Severity | Points |
@@ -83,4 +103,4 @@ Merged by the orchestrator, written to `reviewPath`. Sections, in this order, em
 |   |   |   | **Total** | **3** |
 ```
 
-The report's prose is written in Korean. Paths, identifiers, rule names, and quoted code stay verbatim.
+The report's prose is written in the `Report language` the target CLI returned (the project's `reportLanguage`). Paths, identifiers, rule names, and quoted code stay verbatim.

package/runtime/skills/okstra-run/SKILL.md

@@ -261,9 +261,9 @@ okstra config set pr-template-path "<value>" --scope global
 
 If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
 
-Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate, in two passes. First count: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH> --dry-run` closes nothing and prints one `<paneId>\t<kind>` line per pane it would close — count those lines as `<n>`. Then run the same command **without** `--dry-run` to close them, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. `shutdown_request` alone only idles the agent and frees no pane, so it stays part of the run-end sequence for roster/token hygiene. A `cli-wrapper` run holds no pane at all, so `<n>` is `0` — still emit the checkpoint.
+Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH>` closes them, records `phase-batch-cleanup panes=<n>` with the number it closed, and prints that `PROGRESS:` line last — emit it as printed and do not call `okstra lead-progress append` for it. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. `shutdown_request` alone only idles the agent and frees no pane, so it stays part of the run-end sequence for roster/token hygiene. A `cli-wrapper` run holds no pane at all and `team reclaim` refuses it, so record the checkpoint there with `okstra lead-progress append … --phase phase-batch-cleanup --field panes=0`.
 
-Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same two passes first: `okstra team reclaim … --dry-run` to count the panes, then the same command without `--dry-run` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `team reclaim` call is what closes it. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
+Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run `okstra team reclaim … --gate` first: it closes the finished panes and prints `PROGRESS: phase-gate-cleanup panes=<n>` for you to emit, without recording a batch cleanup. Then `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `team reclaim` call is what closes it. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
 
 Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
 
@@ -428,7 +428,7 @@ If the anchor (`implementation_base_commit`) is reported unresolvable, run the s
 Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
 
 ### Stage ended FAIL — stop the queue and report (not an exception gate)
-When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`prompts/profiles/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
+When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
 
 ### Exception gate during chaining
 If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)

package/runtime/templates/manager/view.template.html

@@ -59,9 +59,26 @@ h3 { font-size: 15px; margin: 0; }
 table { width: 100%; border-collapse: collapse; }
 th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
 th { color: var(--muted); font-weight: 600; font-size: 12px; white-space: nowrap; }
-.wrap { display: inline-block; min-width: 220px; }
 code.id { white-space: nowrap; word-break: normal; }
 code { font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; word-break: break-all; }
+.children table { table-layout: fixed; }
+.children th:nth-child(1) { width: 23%; }
+.children th:nth-child(2) { width: 22%; }
+.children td { padding-top: 14px; padding-bottom: 14px; overflow-wrap: anywhere; }
+.child-ticket { display: block; margin-bottom: 4px; }
+code.child-key { word-break: normal; }
+.child-status { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 4px 10px; margin: 8px 0 0; font-size: 12px; }
+.child-status dt { color: var(--muted); }
+.child-status dd { margin: 0; }
+.child-assignment { line-height: 1.65; }
+.child-links { display: flex; flex-wrap: wrap; gap: 8px 16px; margin-top: 10px; font-size: 12px; }
+.child-error { color: var(--blocked); margin: 8px 0 0; font-size: 12px; }
+@media (max-width: 700px) {
+  .children table, .children tbody, .children tr, .children td { display: block; width: 100%; }
+  .children thead { display: none; }
+  .children tr { padding: 12px 0; border-bottom: 1px solid var(--line); }
+  .children td { padding: 6px 0; border: 0; }
+}
 .chip {
   display: inline-block;
   padding: 1px 8px;

package/runtime/templates/reports/quick-input.template.md

@@ -52,7 +52,7 @@ taskType: "{{FM_TASK_TYPE}}"
 > If left blank, any changes beyond the explicit requirements of the input will be treated as out of scope by default.
 > Any exclusions that appear necessary will be recorded only as follow-up recommendations in the final report, and no further action will be taken.
 
-**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 ## Config and Deployment References
 

package/runtime/templates/reports/task-brief.template.md

@@ -95,7 +95,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > Workers MUST NOT expand into items listed here. If a worker believes an excluded item must be addressed to satisfy the requirement, the worker records it as a recommended follow-up task in the final report and stops — it does not silently include the work. If this section is left empty, workers treat any change beyond what `Request Summary` and `Current Context` explicitly demand as out of scope by default.
 
-**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 ## Configuration References and Expected Values
 

package/runtime/validators/validate-brief.py

@@ -32,7 +32,7 @@ Checks performed per brief file:
 10. `scope` is one of {reporter-input, codebase} (absent ⇒ reporter-input).
 11. codebase-scan variant (`scope: codebase`): the Scan Scope section is
     non-empty and Priority Lenses lists 1–4 values from the lens whitelist
-    (`scripts/okstra_ctl/improvement_lenses.py` SSOT).
+    (`scripts/okstra_ctl/phases/improvement_discovery/lenses.py` SSOT).
 12. When present, `Related Task Graph` is a markdown table with the canonical
     columns and relation/direction values from the okstra-brief-gen contract.
 13. The requirement/objective section `## Desired Outcome` (required in every
@@ -70,7 +70,7 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
     if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
         sys.path.insert(0, str(_ssot_dir))
 
-from okstra_ctl.improvement_lenses import (
+from okstra_ctl.phases.improvement_discovery.lenses import (
     LENSES,
     MAX_PRIORITY_LENSES,
     MIN_PRIORITY_LENSES,