okstra 0.224.0 → 0.225.0

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
 

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

@@ -4,32 +4,30 @@ Read this before verdicting. It defines the shape of an answer, not the rules
 
 ## One verdict per cell
 
-Return verdicts in census order, one per cell. A clean cell is a single line — do not pad it with prose:
-
-```
-- cell: src/orders/pricing.py × structural — verdict: clean
-```
+Return detailed findings in census order. Normal checks appear only in compact coverage rows with the shared rule IDs; do not repeat clean cell summaries outside that table. A grouped row does not cover rules absent from its status fields.
 
 A cell covers its whole rule group, so it can carry several findings from several rules; repeat the cell once per finding and name the violated rule in each:
 
 ```
 - cell: src/orders/pricing.py × structural
   verdict: finding
+  id: F-001
+  kind: design-violation
   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.
+  impact: the same tier-to-rate decision has two homes; changing the gold rate requires coordinating both implementations.
   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**, 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).
+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` (`finding` for a detailed finding), `rule` (the specific rule this finding violates, spelled as its pack spells it), `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), `id` (a finding ID such as `F-001`), `kind` (`execution-error` | `design-violation`), `failure` (for an execution error: reachable input or state and the wrong result), `impact` (for a design violation: the concrete design or maintenance consequence of violating the applicable rule), `evidence` (the `path:line` locations opened to establish the claim, including definitions it depends on), `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.
+**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 remains unevaluated: report the missing evidence and leave that rule unaccounted in the grouped row. Do not turn an inspection failure into `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.
+There is no length budget. Dropping a real finding to stay brief is the failure this review exists to prevent, and a cell with an unaccounted rule is re-dispatched as unfinished work, never read as a clean.
 
 ## Severity and points
 
@@ -39,23 +37,49 @@ There is no length budget. Dropping a real finding to stay brief is the failure
 | `should-fix` | a clear rule violation with no immediate breakage — a name that misleads, a function that fails the plain-English test, business logic in the wrong layer | 2 |
 | `nit` | real but small; the fix is cheap and obviously better | 1 |
 
-Grade the defect, not your confidence. If you are not confident, the verdict is `clean` — see the hedge test below.
+Grade the established consequence, not your confidence. An unsupported candidate is not a finding; incomplete inspection remains a coverage gap.
+
+## Separate execution errors from design violations
+
+- `execution-error`: establish a reachable input or state, the expected behavior, and the actual wrong result in `failure`, supported by opened code in `evidence`.
+- `design-violation`: identify the applicable pack rule, quote the violating code, and describe its concrete design or maintenance consequence in `impact`, supported by `evidence`. A runtime failure is not required. Examples include duplicated domain decisions, business logic in an I/O adapter, misleading names, and a function that violates the assigned readability rule.
+
+Both kinds carry a concrete fix. Severity and timing are independent of kind: a design violation can be `should-fix` and `now` even when current outputs are correct. Neither an alternative implementation nor a preferred name alone establishes a violation. An unreachable defensive scenario does not establish an execution error. The orchestrator checks these criteria in Step 3.7; semantic correctness is a review judgment, not a machine-validated guarantee.
+
+## Compact rule coverage
+
+Return exactly one row per assigned cell under `## Coverage Verdicts`. Keep detailed prose for findings; normal checks share one inspected source location. Rule IDs refer to the shared catalog, not to individual pack bullets.
+
+```markdown
+## Coverage Verdicts
+| Cell | Checked | N/A | Findings | Evidence |
+|---|---|---|---|---|
+| C-CR-0001 | S1,S2,S3,S4 | - | - | src/orders/pricing.py:42 |
+| C-CR-0002 | S2,S3,S4 | - | S1=F-001 | src/orders/totals.py:18 |
+| C-CR-0003 | - | T1=no state mutation; T2=non-test source; T3=non-test source; T4=no tests or new branches | - | src/orders/schema.py:1 |
+```
+
+The example uses the base structural and state-and-tests catalogs. `Checked` means inspected and no actionable finding for those rules. A criterion includes all applicable subconditions in its references; one inapplicable subcondition does not make the entire criterion N/A. Explicitly list the IDs; `all`, counts and ID ranges are not verdicts. `N/A` assigns `rule=reason`; `Findings` assigns `rule=finding-id`. Separate assignments with semicolons and multiple finding IDs for one rule with commas. Use `-` for an empty field. Every expected rule appears exactly once across the three status fields. Never infer an omitted rule as clean.
+
+Every row supplies one literal repository-relative source `path:line` for that cell's target file. Do not substitute a rule-pack citation such as `cc:5`, a global alias such as `E01`, or another target's path. The checker verifies that the file and line exist inside the project. Additional definitions and evidence remain in finding bodies.
+
+A finding ID names a body outside this section, in this reviewer's original or gap-fill result. N/A reasons are short inline applicability explanations, not aliases or rule references. Missing sources, unread rules and blocked inspection remain unaccounted checks and name their blocker. A partial row is rejected with the missing rule IDs; gap-fill rechecks that grouped cell, not every individual rule as a separate output row.
 
-**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.
+The command validates structured accounting and source locations; it cannot prove inspection quality or semantic truth. The lead still checks findings and applicability claims against the code.
 
 ## 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`.
+Every finding carries `timing`. For `now`, establish either an execution error or an applicable design rule violation introduced on a changed line. Correct current outputs alone do not make a design violation `park`.
 
 ## When `clean` is the right verdict
 
 `clean` is a result, not a concession. Return it when:
 
 - **The defect sits only on lines this diff did not change.** Findings anchor on changed lines; pre-existing warts are not this change's problem.
-- **The rule does not apply to this cell.** The census over-includes on purpose, so cells where a rule turns out to be irrelevant are expected — that is exactly what a `clean` verdict records.
+- **The rule does not apply to this cell.** Record the rule ID and applicability reason under `N/A`; other rules in the row may still be checked.
 - **The change is mechanical for this rule.** A signature-only or type-annotation-only edit does not reopen a function's body-level rules; a function the diff neither added nor renamed does not reopen its name.
 
 **The hedge test breaks a borderline `must-fix` or `should-fix`.** At those two severities the finding is one you would defend without qualifiers. If your draft note reaches for a softener that questions whether the point is worth raising at all — "marginal", "arguably", "if you are touching it anyway" — you are looking at a `nit` or at nothing: downgrade it or verdict `clean`, but never ship a hedged `should-fix`.
@@ -92,8 +116,8 @@ Merged and adjudicated by the orchestrator, written to `reviewPath`. Sections, i
 - **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`.
+- **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. Also show grouped cells expected and covered per reviewer, list any missing rule IDs and count reasoned applicability exclusions. Never present the number of rule flags as the number of independent review targets.
+- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. 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:
 
 ```