okstra 0.223.2 → 0.225.0

package/runtime/schemas/final-report-v2.0.schema.json

@@ -9557,7 +9557,8 @@
               "block": {"type": "string", "enum": ["execution", "record"]},
               "stageScope": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
               "contentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of subject+payload+block+stageScope for the current extract."},
-              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "contentHash at the last apply-verdicts. Matching hashes keep a pre-self-fix verdict."},
+              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Body hash at the last apply-verdicts; insufficient on its own for runtime verdict reuse."},
+              "verifiedReviewHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Runtime fingerprint of the judged body, declared evidence closure, contract, roster and detailed votes."},
               "id": {
                 "type": "string",
                 "minLength": 1
@@ -9597,6 +9598,7 @@
                   "additionalProperties": false,
                   "properties": {
                     "claimKind": {"description": "Set only on DISAGREE. `fact` claims are settled by reproduction, `judgement` by quorum.", "enum": ["fact", "judgement", null]},
+                    "dependencies": {"type": "object", "required": ["complete", "itemIds", "paths"], "additionalProperties": false, "properties": {"complete": {"type": "boolean"}, "itemIds": {"type": "array", "items": {"type": "string", "minLength": 1}}, "paths": {"type": "array", "items": {"type": "string", "minLength": 1}}}},
                     "reproduction": {"description": "Set only on a `fact` claim. The probe okstra runs; see okstra_ctl/claim_reproduction.py.", "type": ["object", "null"]},
                     "reproductionResult": {"description": "Written by okstra, not by the worker.", "enum": ["reproduced", "not-reproduced", "not-runnable", null]},
                     "worker": {

package/runtime/schemas/final-report-v3.0.schema.json

@@ -9849,7 +9849,8 @@
               "block": {"type": "string", "enum": ["execution", "record"]},
               "stageScope": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
               "contentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of subject+payload+block+stageScope for the current extract."},
-              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "contentHash at the last apply-verdicts. Matching hashes keep a pre-self-fix verdict."},
+              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Body hash at the last apply-verdicts; insufficient on its own for runtime verdict reuse."},
+              "verifiedReviewHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Runtime fingerprint of the judged body, declared evidence closure, contract, roster and detailed votes."},
               "id": {
                 "type": "string",
                 "minLength": 1
@@ -9896,6 +9897,7 @@
                   "additionalProperties": false,
                   "properties": {
                     "claimKind": {"description": "Set only on DISAGREE. `fact` claims are settled by reproduction, `judgement` by quorum.", "enum": ["fact", "judgement", null]},
+                    "dependencies": {"type": "object", "required": ["complete", "itemIds", "paths"], "additionalProperties": false, "properties": {"complete": {"type": "boolean"}, "itemIds": {"type": "array", "items": {"type": "string", "minLength": 1}}, "paths": {"type": "array", "items": {"type": "string", "minLength": 1}}}},
                     "reproduction": {"description": "Set only on a `fact` claim. The probe okstra runs; see okstra_ctl/claim_reproduction.py.", "type": ["object", "null"]},
                     "reproductionResult": {"description": "Written by okstra, not by the worker.", "enum": ["reproduced", "not-reproduced", "not-runnable", null]},
                     "worker": {

package/runtime/skills/_fragments/bash-invocation-rule.md

@@ -1 +1 @@
-Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+Run one shell-command tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — literal command tokens keep execution permissions reviewable):

package/runtime/skills/_fragments/host-question-interface.md

@@ -0,0 +1 @@
+For authored questions, `prompt_user` means the current host's available question interface, not a literal tool name. Use the selected host relay when one is provided. Preserve every question, option, description, and answer; use native controls only when the live session permits them and the complete interaction fits its limits. Otherwise show complete numbered choices and accept the user's reply; collect free text through normal conversation. If a native control is refused, follow the relay's recovery mapping, or use text when no relay is provided. A delivery acknowledgement or preselected option is not an answer; wait for the user's actual response.

package/runtime/skills/_fragments/host-runtime-selection.md

@@ -0,0 +1 @@
+Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.

package/runtime/skills/_fragments/wizard-bash-invocation-rule.md

@@ -1 +1 @@
-**Bash invocation rule (permission-friendly)**: every Bash command in this skill begins with the literal token `okstra` (or another already-allowed binary) and passes literal argument values. Do not introduce shell variables (`$STATE_FILE`, `$ANSWER`, `$projectRoot`, ...), `$(...)` command substitution, or leading `VAR=...` assignments — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every wizard call. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.
+**Shell invocation rule (permission-friendly)**: every shell command in this skill begins with the literal token `okstra` (or another already-allowed binary) and passes literal argument values. Do not introduce shell variables (`$STATE_FILE`, `$ANSWER`, `$projectRoot`, ...), `$(...)` command substitution, or leading `VAR=...` assignments — any of those make the command harder to audit; apply the selected host adapter's execution-permission guidance. When a prior tool call emitted a path or value, read it from the tool output and paste the literal string into the next command.

package/runtime/skills/_fragments/wizard-preflight.md

@@ -6,7 +6,7 @@ Record the semantic functions that the live harness can actually perform. Always
 
 The host-native provider runs as the current lead session when its role is supported. Other selected providers run through their registered CLI wrappers. Claude remains only the model-policy default; it is not the process owner.
 
-Run one Bash tool call (Bash invocation rule from the top of this file applies):
+Run one shell-command tool call (Shell invocation rule from the top of this file applies):
 
 ```bash
 okstra preflight --runtime <host-runtime>

package/runtime/skills/_fragments/wizard-render-bundle.md

@@ -29,9 +29,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: `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 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. After collecting results and token usage, apply the selected adapter's `shutdown_workers` operation only to confirmed-complete workers; preserve in-flight workers and the lead. 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 `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.
+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 apply the selected adapter's `shutdown_workers` operation to confirmed-complete workers after collecting their results and token usage; preserve in-flight workers and the lead. 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).
 
@@ -44,13 +44,13 @@ Step 3's empty-answer and escaping rules apply verbatim: every flag in `renderAr
 `renderArgv` already contains exactly one `--lead-runtime <host-runtime>` pair. Do not add or replace it. Do not enumerate a fixed provider list in this skill because the wizard and role model pool own the ordered tokens.
 
 ```bash
-okstra render-bundle \
+okstra render-bundle --summary-only \
   <outcome.renderArgv token 1> \
   <outcome.renderArgv token 2> \
   <each remaining outcome.renderArgv token in order>
 ```
 
-`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" below).
+`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" below).
 
 Before acting as the lead, read `resources.leadPromptMetadataPath` from the run
 manifest and execute the host-native specification-link gate:

package/runtime/skills/okstra-brief-gen/SKILL.md

@@ -6,6 +6,10 @@ disable-model-invocation: true
 
 # okstra-brief-gen
 
+<!-- BEGIN FRAGMENT: host-question-interface -->
+For authored questions, `prompt_user` means the current host's available question interface, not a literal tool name. Use the selected host relay when one is provided. Preserve every question, option, description, and answer; use native controls only when the live session permits them and the complete interaction fits its limits. Otherwise show complete numbered choices and accept the user's reply; collect free text through normal conversation. If a native control is refused, follow the relay's recovery mapping, or use text when no relay is provided. A delivery acknowledgement or preselected option is not an answer; wait for the user's actual response.
+<!-- END FRAGMENT: host-question-interface -->
+
 Generate a single `task brief` markdown file under the okstra project domain
 (`.okstra/briefs/<task-group>/<task-id>.md`) so it can be fed to
 [`okstra-run`](../okstra-run/SKILL.md) as `--task-brief`.
@@ -114,10 +118,10 @@ and never writes them. Decision files (when raised by
 
 ## Step 0: Preflight
 
-Every Bash command in this skill is a **separate Bash tool call**.
+Every shell command in this skill is a **separate shell-command tool call**.
 
 <!-- BEGIN FRAGMENT: bash-invocation-rule -->
-Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+Run one shell-command tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — literal command tokens keep execution permissions reviewable):
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
@@ -144,13 +148,7 @@ selection and the material it collects as separate interactions: a native
 choice selects the input path, and the next free-text interaction receives a
 path, URL, ticket reference, or body.
 
-In Codex, call `request_user_input` with the two or three listed options in
-their stated order. Do not add an `Other` option: the Codex client adds its
-own free-text `Other` row. When the user supplies a value through that row,
-classify it through the normal reporter-source rules (ticket, URL, or user
-input) and do not ask them to repeat it. If the host does not expose a
-compatible native control, render the same options as a numbered text choice
-and retain the explicit free-text follow-up where this skill specifies one.
+Use the current host's native single-select mapping with every listed option in order. If the host supplies its own free-text row, do not add a duplicate. Classify a custom value through the normal reporter-source rules and do not ask the user to repeat it. If no compatible native control is available, render the complete options as numbered text and retain the specified free-text follow-up.
 
 ## Step 1: Choose input source
 
@@ -190,7 +188,7 @@ for every variant and every source type below.
 
 ### 1.0. brief variant
 
-`AskUserQuestion` (single-select):
+`prompt_user` (single-select):
 
 - **Label**: `"Brief variant?"`
 - **Options**:
@@ -207,7 +205,7 @@ collected source material, then classify a ticket reference or URL normally.
 
 If the user picked `Reporter input`, proceed to Step 1.A's sub-flow below — this is the existing 4-source flow. Choose ONE of:
 
-`AskUserQuestion` (single-select):
+`prompt_user` (single-select):
 
 - **Label**: "Source of this brief?"
 - **Options** (single-select):
@@ -252,7 +250,7 @@ Order of operations:
    placeholder group.
 
    **Sequential, never batched.** Run Step 2a as its **own**
-   `AskUserQuestion` call, then ask sub-step 1's ticket question in a
+   `prompt_user` call, then ask sub-step 1's ticket question in a
    **separate** call — never combine the task-group and ticket-ref
    questions into one. When you relay this preflight, tell the user in one
    line *why* task group comes first (it scopes where this ticket's brief —
@@ -262,30 +260,30 @@ Order of operations:
    directory segment to equal the slugified frontmatter `task-group`, so a
    brief written before the group is known — or under an invented placeholder
    group — fails validation rather than landing in the wrong tree.
-1. `AskUserQuestion` (free text):
+1. `prompt_user` (free text):
    `"Ticket key or URL (e.g. LIN-1234, PROJ-42, https://linear.app/..., https://your.atlassian.net/browse/...)"` →
    `ticket_ref`. Issue this only **after** Step 2a's task-group answer is in
    hand (per sub-step 0's sequential rule).
 2. Auto-detect the tracker by URL host or key prefix (`linear.app` → Linear,
    `atlassian.net` or `JIRA_*` pattern → Jira, `github.com/.../issues/` →
    GitHub, `notion.so` → Notion). If detection fails, ask once more via
-   `AskUserQuestion`.
+   `prompt_user`.
 3. Check whether the tracker's **MCP tools** are loaded in the current
    session and prefer them when available:
    - Linear → `mcp__linear__*` family (e.g. `get_issue` /
-     `getIssueByIdentifier`). If absent, try `ToolSearch` with the keyword
-     `linear` — it auto-waits for connecting MCP servers.
-   - Jira → `mcp__jira__*` (or `mcp__atlassian__*`). Same `ToolSearch`
-     fallback.
+     `getIssueByIdentifier`). If absent, try the host's tool-discovery capability (when available) with the keyword
+     `linear`; if discovery is unavailable, continue to step 4.
+   - Jira → `mcp__jira__*` (or `mcp__atlassian__*`). Use the same capability-discovery
+     fallback when available; otherwise continue to step 4.
    - GitHub → `gh issue view <num> --repo <owner>/<repo> --json title,body,comments,labels,state`
      (an authenticated `gh` CLI is the default path — usable even when MCP
-     is present). If `gh` is missing or unauthenticated, try `ToolSearch`
+     is present). If `gh` is missing or unauthenticated, try the host's tool-discovery capability (when available)
      for `mcp__github` family; otherwise fall through to step 4 (paste /
      skip).
    - Notion → `mcp__notion__API-retrieve-a-page` /
      `API-get-block-children`.
 4. If **no** MCP or CLI path is available:
-   - Ask the user via `AskUserQuestion`:
+   - Ask the user via `prompt_user`:
      `"<tracker> MCP is not connected. (a) Paste the ticket body here  /  (b) Skip this source"`.
    - Never invent ticket content.
 5. Preserve the retrieved fields (summary/title, description body, comments,
@@ -311,11 +309,11 @@ Order of operations:
 
 Order of operations:
 
-1. `AskUserQuestion` (free text): `"Link URL"`.
-2. Fetch directly via `WebFetch`. If `WebFetch` is deferred, load its schema
-   first via `ToolSearch` with `select:WebFetch`.
+1. `prompt_user` (free text): `"Link URL"`.
+2. Fetch through an available URL-fetch tool. If tools are deferred, discover
+   that capability through the current host when discovery is available.
 3. On fetch failure or auth required (login wall, intranet-only, etc.):
-   - Ask the user via `AskUserQuestion` to paste the body.
+   - Ask the user via `prompt_user` to paste the body.
    - Never invent URL content.
 4. Preserve the fetched content (title + body + quotes/examples) **verbatim**
    in Source Material. Do not excerpt or summarize long pages to fit a line
@@ -333,7 +331,7 @@ Two sub-modes combined under one option.
   Material as `conversation synthesis` and quote key utterances verbatim
   wherever possible.
 - **Inline input**: if conversation context is empty or thin, take one
-  free-text `AskUserQuestion`. The received text is preserved in Source
+  free-text `prompt_user`. The received text is preserved in Source
   Material without changing a character.
 
 When both are used, record them as two separate sub-sources under Source
@@ -343,20 +341,20 @@ Material.
 
 If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 
-1. `AskUserQuestion` (free text):
+1. `prompt_user` (free text):
    `"Scan scope — comma-separated paths inside the project (e.g. src/foo/, src/bar/baz.py)"` → `scan_scope` (CSV).
-2. `AskUserQuestion` (multi-select, options = the lens values from `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py`'s `LENSES` — code source: `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`):
+2. `prompt_user` (multi-select, options = the lens values from `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py`'s `LENSES` — code source: `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`):
    `"Priority lenses (pick 1–4)"` → `priority_lenses` (1..4 values from the enum).
    Current `LENSES` values (this list mirrors the module — if they diverge, the module wins; Step 6.6 `validate-brief` enforces the subset): `performance`, `security`, `readability`, `architecture`, `test-coverage`, `dx`, `observability`, `accessibility`.
-3. `AskUserQuestion` (free text):
+3. `prompt_user` (free text):
    `"Out-of-scope paths (optional, comma-separated)"` → `out_of_scope` (CSV, empty allowed).
-4. `AskUserQuestion` (free text):
+4. `prompt_user` (free text):
    `"Candidate cap (1–12, default 8)"` → `candidate_cap` (integer; empty → 8).
-5. `AskUserQuestion` (free text):
+5. `prompt_user` (free text):
    `"Context — why is this scope being scanned now? One short paragraph."` → `context`.
-6. `AskUserQuestion` (free text):
+6. `prompt_user` (free text):
    `"Desired outcome — what kinds of improvements do you want surfaced? Anti-goals?"` → `desired_outcome`.
-7. `AskUserQuestion` (free text):
+7. `prompt_user` (free text):
    `"Constraints — untouchable areas, deadlines, compatibility (optional)"` → `constraints`.
 
 Validation (before Step 4 sharpening):
@@ -374,7 +372,7 @@ If the user picked `Error feedback`, the input is a `.zip` produced by `okstra e
 Input: the `.zip` produced by `okstra error-zip`. Ask the user for the zip path (if a path was received earlier, propose reusing it as `Recommended:`).
 
 1. Read the zip's `report.md`, show the frequent-cluster table to the user, and have them pick **one cluster**.
-   `AskUserQuestion` (single-select, `Specify manually` always last):
+   `prompt_user` (single-select, `Specify manually` always last):
    1. top-1 cluster (highest frequency) — marked `Recommended:`.
    2. top-2 cluster.
    3. `Specify manually` — the user names a cluster directly from the table.
@@ -413,7 +411,7 @@ shown in slug form.
 
 If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop.
 
-`AskUserQuestion` (single-select):
+`prompt_user` (single-select):
 
 - **Label**: `"Task group?"`
 - **Options** (recommendations first, `Enter directly` always last):
@@ -465,7 +463,7 @@ relations are also tracked via the brief's `parent-id` frontmatter
   - Jira `PROJ-42` → `PROJ-42`
   - GitHub `owner/repo#123` → `gh-<repo>-123`
   - Notion (no canonical id) → `notion-<8-char-page-short-id>`
-- **File / URL / User-input sources**: `AskUserQuestion` (free text):
+- **File / URL / User-input sources**: `prompt_user` (free text):
   - `"Ticket / identifier (e.g. dev-9043, INV-1234, login-error)"` →
     `ticket_id`
 
@@ -483,7 +481,7 @@ to Source Material body, not to the filename):
   5. Trim leading/trailing `-`
   - Example: Linear `LIN-1234 "Fix flaky login retry on 5xx"` →
     `LIN-1234-fix-flaky-login-retry-on-5xx.md`
-- **Other sources**: `AskUserQuestion` (free text):
+- **Other sources**: `prompt_user` (free text):
   - `"File title (short summary, e.g. fix-login-retry, dev-9043-brief)"` →
     `file_title`
   - Apply rules 1–5 above. Re-ask on empty input.
@@ -495,7 +493,7 @@ alphanumeric character after slugification. Apply Step 2c on collision.
 
 ### 2c. Collision handling
 
-If a brief file already exists, `AskUserQuestion` with (`Skip` /
+If a brief file already exists, `prompt_user` with (`Skip` /
 `Append suffix` / `Overwrite`). Default recommendation: `Skip` —
 protects briefs the user has already edited. `Append suffix` adds a
 timestamp suffix to the filename stem.
@@ -503,7 +501,7 @@ timestamp suffix to the filename stem.
 When multiple collisions occur in tracker multi-generation mode:
 
 - First echo the colliding file list to the user.
-- Ask **once** with `AskUserQuestion` for a bulk policy.
+- Ask **once** with `prompt_user` for a bulk policy.
 - **Even when `Overwrite` is selected, confirm one more time for each
   colliding file**, or warn that downgrading to `Append suffix` is safer. Silent bulk overwrite is forbidden.
 
@@ -585,7 +583,7 @@ project's domain.
 
 Inspect the synthesized brief draft. For each REQUIRED section below that is
 empty or trivially thin **after** reading Source Material verbatim, ask **at
-most one** `AskUserQuestion` to fill it. Never ask about sections already
+most one** `prompt_user` to fill it. Never ask about sections already
 covered by the source material.
 
 **Enforced:** `validators/validate-brief.py` fails a brief whose required section is missing, has a blank body (`check_variant_required_sections`), or still carries the template's `<...>` text (`check_template_scaffold`). `## Source Material` is exempt from the template-text check because it holds the reporter's words verbatim.
@@ -599,12 +597,12 @@ The following rules absorb the useful parts of `grill-me` /
    inspection (e.g. "does this symbol exist?", "what does this endpoint
    return today?"), do that **instead of** asking the user. Only ask when
    the codebase cannot answer.
-2. **Question carries a recommended answer** — every `AskUserQuestion`
+2. **Question carries a recommended answer** — every `prompt_user`
    issued in this step must put the recommended option **first** with the
    suffix `(Recommended)`. Free-text fallbacks are still allowed, but the
    recommendation must be visible.
 3. **One at a time** — never batch multiple questions into one
-   `AskUserQuestion` call. Ask, wait for the answer, fold it into the
+   `prompt_user` call. Ask, wait for the answer, fold it into the
    draft, then ask the next.
 4. **Bounded budget** — at most **1** sharpening question per empty
    required section, plus **at most 2** disambiguation questions arising
@@ -788,7 +786,7 @@ the skill does not write outside okstra's subtree.
 ### 4.5b. Approval flow (per entry)
 
 For each draft, **first echo the target absolute path on one line** (so
-the user sees the exact file that will be written), then `AskUserQuestion`:
+the user sees the exact file that will be written), then `prompt_user`:
 
 - **Label**: `"Apply glossary entry?"` (keep the label short — absolute
   paths belong in the echo line above, not in the option chip)
@@ -936,7 +934,7 @@ one row per requirement unit, its destination section, and for an end-state
 unit the `EB-` / `PB-` / `EO-` id it became. That table is what lets the
 reporter check their own list in one pass. Then ask:
 
-`AskUserQuestion`: `"Proceed with this brief?"` — options `Save` / `Edit`.
+`prompt_user`: `"Proceed with this brief?"` — options `Save` / `Edit`.
 On `Edit`, return to Step 4 for the section to revise; a unit the user reports
 missing returns to this sweep instead.
 
@@ -991,7 +989,7 @@ in the brief's frontmatter and skip the rest of this step.
 
 ### 6.5b. Ask once: collect now or later
 
-If the list is non-empty, run **one** `AskUserQuestion`:
+If the list is non-empty, run **one** `prompt_user`:
 
 - **Label**: `"This brief has <N> question(s) only the reporter can answer. Collect their answers now?"`
 - **Options**:
@@ -1094,7 +1092,7 @@ constraints, ticket relations — and no single brief can recover it
 (observed: a 15-brief group whose reason, "the origin keeps going down under
 attack traffic", appeared in none of them, so option selection measured a
 per-page ratio instead of origin load). If the file is absent, ask once via
-`AskUserQuestion`:
+`prompt_user`:
 
 - `Create the group context skeleton now (Recommended for a new task-group)`
   → run `okstra group-context init --project-root <PROJECT_ROOT> --task-group <task-group>`
@@ -1168,7 +1166,7 @@ group context skeleton: <abs>/<task-group>/group-context.md   (fill before /okst
 - If a URL fetch fails or hits an auth wall, do not guess — ask for a
   paste.
 - Never fabricate content for empty sections; use `_(none)_`.
-- Echo each `AskUserQuestion` outcome on one short line.
+- Echo each `prompt_user` outcome on one short line.
 
 ## Failure Modes
 
@@ -1177,7 +1175,7 @@ group context skeleton: <abs>/<task-group>/group-context.md   (fill before /okst
 | `project.json not found` | okstra not set up in this project | Tell user to run `okstra-setup`; stop. |
 | `briefs/<group>/<id>.md already exists` | duplicate task-key | Step 2c overwrite prompt. |
 | Source file not found | bad path in Step 1 | Re-ask. |
-| Linear/Jira MCP not connected | tracker MCP missing from the session | Try `ToolSearch` once → if still missing, ask the user to paste the body. Never guess. |
+| Linear/Jira MCP not connected | tracker MCP missing from the session | Try the host's tool-discovery capability (when available) once → if still missing, ask the user to paste the body. Never guess. |
 | URL fetch fails or 401 / login wall | intranet, paywall, JS-rendered page | Ask the user to paste the core body. Never guess. |
 | Tracker body is in non-MD format (ADF / HTML) | Jira description, Notion blocks | Convert format only, preserve semantics. Annotate the conversion in the `format:` meta. |
 | Brief comes out skeletal after synthesis | source too thin AND user picked `User input` with little context | Switch to inline input mode and ask one or two targeted questions. |

package/runtime/skills/okstra-brief-gen/references/reporter-confirmations.md

@@ -5,9 +5,9 @@ pending list of `intent-check:` / `conversion-block:` rows.
 
 ## 6.5c. Batch the questions
 
-For each pending row, formulate one question. Because the `AskUserQuestion`
-tool caps options at 4 per call and questions per call also at 4, split into
-batches of ≤ 4 questions.
+For each pending row, formulate one question. Batch only when the current
+host's question interface can present every question and option within its
+live limits; otherwise ask sequentially without dropping any option.
 
 **Cap — 12 questions per Step 6.5 run.** When the pending list exceeds 12
 rows, sort by priority and ask only the top 12 this round:

package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md

@@ -27,7 +27,7 @@ which briefs are emitted, and how re-runs stay idempotent.
 
 ## 2. Ask once at the top parent
 
-If there is one or more child, `AskUserQuestion` (single-select):
+If there is one or more child, `prompt_user` (single-select):
 
 - **Label**: `"This ticket has sub-tickets. How should the child tree be handled?"`
 - **Options**:

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

@@ -18,7 +18,7 @@ The display name is typed at join. Do not invent a default name.
 
 ## Step 0: CLI
 
-Run as a separate Bash tool call with literal leading token:
+Run as a separate shell-command tool call with literal leading token:
 
 ```bash
 okstra chat --help

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

@@ -34,17 +34,21 @@ This skill owns review calibration only:
 
 ## Step 0 — Preflight
 
+<!-- BEGIN FRAGMENT: host-runtime-selection -->
+Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.
+<!-- END FRAGMENT: host-runtime-selection -->
+
 <!-- BEGIN FRAGMENT: bash-invocation-rule -->
-Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+Run one shell-command tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — literal command tokens keep execution permissions reviewable):
 <!-- END FRAGMENT: bash-invocation-rule -->
 
 ```bash
-okstra preflight --runtime claude-code
+okstra preflight --runtime <host-runtime>
 ```
 
 Branch on the fixed first line:
 - `Okstra preflight: ready` → carry `Project root` as a literal string; every later step is anchored on it.
-- `Okstra preflight: failed` → the check only sees the cwd of the Bash call, so a project that is not the cwd can read as missing setup. Ask whether the user pointed at a specific project directory; if they did, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this also fails do you show `Reason` and `Recovery`, then stop.
+- `Okstra preflight: failed` → the check only sees the cwd of the Bash call, so a project that is not the cwd can read as missing setup. Ask whether the user pointed at a specific project directory; if they did, re-run targeting it: `okstra preflight --runtime <host-runtime> --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this also fails do you show `Reason` and `Recovery`, then stop.
 
 <!-- BEGIN FRAGMENT: preflight-outdated-cli -->
 If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
@@ -154,7 +158,7 @@ it. **Every reviewer receives the same brief** — two reviewers are worth their
 
 - 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)
-- **the whole census** — every cell of all four axes, verbatim
+- **the whole census** — the shared rule catalog once and every grouped 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
 
@@ -169,7 +173,7 @@ Axis scope — each reviewer works all four axes; the `Reads` column names each
 | `state-and-tests` | non-test source file × `state-and-tests`, test file × `state-and-tests` | `clean-code.md` "Mutation and state boundaries" and "Testing discipline"; plus the routed language pack's self-mock signals |
 | `general` | non-test source file × `general` | correctness bugs, swallowed errors, `clean-code.md` "Untrusted input and security" (work that grows faster than the input before a size bound rejects it, input building SQL / shell / paths / fetch targets / templates / regexes, a new entry point without auth or ownership checks, secrets or personal data in code, logs or responses, evaluating input), clear performance problems, core principle 7 (fix at the cause — nothing previously green edited to silence a failure); `clean-code.md` "Wrapping a third-party call" — a recovery branch the library already performs, a comment naming a condition the call site never establishes, a rethrow that drops the original error; plus the routed language pack's language-specific traps |
 
-Say it plainly in every brief: **the census is law** — work the cells exactly as given, return a verdict for every one, never re-derive the list. There is no length budget; dropping a finding to stay brief is the failure this skill exists to prevent.
+The materialized prompt injects the `code-reviewer` duty contract. Keep task briefs focused on the assigned census, comparison range, rule paths, and result format; do not restate the injected duty.
 
 Capture each raw model return under `.okstra/agent-invocations/code-review/.tmp/`. Publish it with
 `okstra agent-prompt materialize-result`, publish the immutable completion marker with
@@ -179,12 +183,19 @@ review result and cannot contribute a verdict.
 
 ## Step 3.5 — Audit the coverage
 
-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 reviewer has a verdict for every cell.
+Keep normal output to one compact Coverage Verdicts row per cell, with explicit rule IDs and one source anchor. No target-by-bullet verdict table or repeated per-rule clean prose.
+
+For each reviewer separately, audit its grouped rows and explicit rule-ID accounting using its verified completion marker:
+
+```bash
+okstra code-review check-coverage --project-root <projectRoot> --census <grouped-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
+```
+
+The command reuses the existing completion verification boundary and refuses mixed model assignments. Exit 0 means every cell accounts for all rules in its group with valid source evidence and no unknown cell ID; exit 1 lists missing cells, missing rule IDs or invalid grouped verdicts; exit 2 reports invalid input or completion evidence. It validates the shared catalog and source anchors, but does not establish whether the selected references are exhaustive or a verdict is true.
+
+For missing checks, dispatch one gap-fill invocation per reviewer on that reviewer's original slot, carrying only its incomplete grouped cells, their shared catalog entries, the same range and rule paths. Ask for one complete row for each such cell, not separate replies per missing rule. Use a new invocation ID and repeat the full materialize → verify → dispatch → materialize-result → complete → verify-completion boundary. Re-run the audit with that reviewer's initial and gap-fill markers. Earlier usable verdicts remain unchanged. An invocation with unknown IDs is invalid; record its rejection and request a corrected new invocation before auditing the retained valid completions. Do not silently relabel IDs.
 
-A missing verdict is unfinished work, never an implicit `clean`. Do not start Step 3.6 while a single cell is unaccounted for.
+The Checked/N/A/Findings fields must account for every expected rule ID exactly once; a generic clean or all-checked statement never covers an omitted rule. Do not start Step 3.6 until every reviewer passes the audit. If evidence remains unavailable, report the specific blocker and incomplete coverage instead of writing a completed review.
 
 ## Step 3.6 — Check every citation
 
@@ -198,19 +209,19 @@ okstra code-review check-lines --project-root <projectRoot> --base <baseCommit>
 
 ## 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.
+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. Before pairing findings, check every finding, including agreed ones, against its `kind`: an `execution-error` needs an evidenced reachable `failure`; a `design-violation` needs an applicable named rule, code evidence, and concrete `impact`. Both need a fix. Missing or unsupported required evidence goes to `Rejected` with the specific reason; do not demand a runtime failure for a design violation.
 
 **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.
+- **Agreed** — both reviewers report it with the same severity and timing. It keeps its severity and timing after the evidence and kind checks above; agreement does not replace those checks.
 - **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.
+**Adjudicating** a finding: open each `evidence` location at `headCommit` and the definitions its claim depends on. For `execution-error`, check reachability and the stated wrong result. For `design-violation`, read the assigned rule and check the cited violation and concrete `impact`. An axis does not determine the kind.
 
-- **Confirmed** — the code produces the stated failure. The finding keeps its severity and timing.
+- **Confirmed** — the code supports the execution failure or the applicable design violation and its impact. 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.
 
 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.
@@ -257,5 +268,5 @@ generatedAt: <YYYY-MM-DD HH:MM>
 - **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.
-- **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.
+- **Only a checked claim scores.** A finding reaches the score after its citation is on a changed line and its kind-specific evidence 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/census-rules.md

@@ -8,13 +8,48 @@ The census is the worklist: an explicit list of cells, each one a `target × axi
 
 This is what makes the cell count reproducible: the axis list is fixed at four, so the census size depends only on the diff. Splitting an axis per individual rule would make the count depend on how many rules the reader chose to enumerate that day — the exact variance this census exists to remove.
 
-The specific rule a finding violates is named **inside the verdict**, in its `rule` field (`review-calibration.md`), not in the cell label. One cell can therefore carry findings from several rules of its group, and it still counts as one cell for coverage.
+The specific rule a finding violates is named **inside the verdict**, in its `rule` field (`review-calibration.md`), not in the cell label. One cell can therefore carry findings from several rules of its group, and it still counts as one cell. Rule coverage is represented inside each grouped verdict below.
+
+## Shared rule catalog and grouped cells
+
+Keep one cell per target and axis. Each reviewer returns one compact row per cell, not one prose verdict per pack bullet. Define the shared rule catalog once, then let cells reference its group. Do not materialize a target-by-bullet Cartesian product.
+
+Use these named review criteria. Each criterion includes the relevant subconditions and carve-outs in its canonical pack; those bullets do not get separate verdict IDs:
+
+| Group | Rule IDs and scope |
+|---|---|
+| `structural` | `S1` reuse/DRY; `S2` simplicity/KISS; `S3` responsibilities/SOLID; `S4` current scope/YAGNI; when an architecture pack is routed: `S5` thin ports, `S6` I/O-only adapters, `S7` domain-object placement, `S8` dependency direction, `S9` boundary ports, `S10` domain-owned business rules |
+| `semantic` | `M1` truthful and specific names; `M2` single-purpose readable flow, including size and nesting; `M3` comments and explanatory values |
+| `state-and-tests` | `T1` state and mutation boundaries; `T2` no self-mocking; `T3` behavioral outcome assertions; `T4` discriminating fixtures, test titles and branch coverage |
+| `general` | `G1` correctness and regressions; `G2` error handling and third-party wrappers; `G3` untrusted-input and resource bounds; `G4` performance; `G5` routed language/framework and project conventions |
+
+Write the selected IDs with their absolute pack/section references under `## Rules`. Multiple references for a criterion go in the same Reference field, separated by semicolons. Do not turn every heading, bullet, formatter instruction or example into another rule. Read the original references rather than restating their bodies.
+
+Write targets under `## Cells`; each has a stable `C-CR-...` ID, the target and its group. A function target includes its path and position, e.g. `src/orders/pricing.py:42 calculate_price`. Distinguish same-line anonymous functions with their columns. Targets are repository-relative; no absolute or parent-traversal paths.
+
+```markdown
+## Rules
+| Rule | Group | Reference |
+|---|---|---|
+| S1 | structural | /absolute/pack/clean-code.md#DRY |
+| S2 | structural | /absolute/pack/clean-code.md#KISS |
+
+## Cells
+| Cell | Target | Group |
+|---|---|---|
+| C-CR-0001 | src/orders/pricing.py | structural |
+| C-CR-0002 | src/orders/totals.py | structural |
+```
+
+The example is abbreviated; the actual catalog includes the named criteria above for every used group. Add `S5` through `S10` only for a routed architecture pack; otherwise the base catalog has 16 criteria. Freeze the catalog and cell IDs before dispatch and send the same census to each reviewer. The command `code-review check-coverage` enforces catalog membership, rule accounting and source-anchor validity against this saved census; the lead still checks that the catalog names the intended references and that verdicts are true.
+
+Do not omit a cell because a rule seems inapplicable. Record that criterion under `N/A` with its reason in the compact row. The normal case lists checked rule IDs once with one inspected source anchor for the cell. This preserves rule-level omission checks without repeating paths and explanations for every rule.
 
 ## The one principle
 
 **Membership is mechanical; judgment only ever decides a cell's verdict.**
 
-Never ask "does this rule apply to this file?" while building the census — that question is the reviewer's, and its answer is a verdict (`clean` when the rule turns out not to apply). Over-inclusion is cheap: a clean verdict costs one line. A judged exclusion is variance — it is the exact failure this census exists to remove, because the next run judges differently and the review changes shape.
+Never ask "does this rule apply to this file?" while building the census — that question is the reviewer's, and its answer is a verdict (`n/a` with a reason when the rule turns out not to apply). Over-inclusion is cheap: a clean verdict costs one line. A judged exclusion is variance — it is the exact failure this census exists to remove, because the next run judges differently and the review changes shape.
 
 Two consequences:
 
@@ -94,6 +129,7 @@ In the orchestrator's response, before Step 3:
 
 - one table per axis, in the order `structural`, `semantic`, `state-and-tests`, `general`, listing every cell
 - the exclusion list, one line per file, each with its reason
+- the shared rule catalog, grouped cell table and total cells per axis
 - the applied pack list (absolute paths)
 - the two completion criteria with their actual numbers