okstra 0.231.1 → 0.232.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/README.md +12 -0
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +127 -0
  20. package/docs/architecture.md +7 -0
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  43. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  44. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  45. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  46. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  47. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  48. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  49. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  50. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  51. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  52. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  53. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  54. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  55. package/runtime/python/okstra_ctl/consumers.py +12 -9
  56. package/runtime/python/okstra_ctl/design_review.py +207 -0
  57. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  58. package/runtime/python/okstra_ctl/doctor.py +8 -25
  59. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  60. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  61. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  62. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  63. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  64. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  65. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  66. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  67. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  68. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  69. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  70. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  71. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  72. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  73. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  74. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  75. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  76. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  77. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  78. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  79. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  80. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  81. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  82. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  83. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  84. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  85. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  86. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  87. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  88. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  89. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  90. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  91. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  92. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  93. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  94. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  95. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  96. package/runtime/python/okstra_ctl/report_synthesis_packet.py +11 -2
  97. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  98. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  99. package/runtime/python/okstra_ctl/run.py +24 -1
  100. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  101. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  103. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  104. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  105. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  106. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  107. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  108. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  109. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  110. package/runtime/python/okstra_project/__init__.py +2 -0
  111. package/runtime/python/okstra_project/dirs.py +18 -0
  112. package/runtime/python/okstra_project/state.py +25 -20
  113. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  114. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  115. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  116. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  117. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  118. package/runtime/schemas/record-secret-patterns.json +41 -0
  119. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  120. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  121. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  122. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  123. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  124. package/runtime/templates/implementation-worker-preamble.md +4 -9
  125. package/runtime/templates/worker-prompt-preamble.md +4 -12
  126. package/runtime/validators/validate-run.py +14 -2
@@ -3,35 +3,27 @@ name: okstra-code-review
3
3
  description: >-
4
4
  Use when the user wants changed code reviewed and the result written to a
5
5
  file — either an okstra task's implementation stage, or any branch
6
- unrelated to an okstra run. The tell is a review request over a diff:
7
- "review this stage", "review my branch", "code review", "leave the review
8
- in a file". The orchestrator censuses the diff into an explicit worklist,
9
- one to three reviewers on distinct models (default two) each delegate structure, naming,
10
- readability, general defects, state and tests to six same-model subagents.
11
- Model reviewers consolidate their teams before the orchestrator settles the
12
- combined findings. A coverage audit repeats missing checks on their original model and specialty slots,
13
- and the orchestrator verifies and settles findings. NOT for writing a PR body (okstra-pr-gen), starting a run
14
- (okstra-run).
6
+ unrelated to an okstra run. Applies to requests such as "review this stage"
7
+ or "review my branch". Not for generating a PR description (okstra-pr-gen)
8
+ or starting a run (okstra-run).
15
9
  ---
16
10
 
17
11
  # OKSTRA Code Review
18
12
 
19
13
  Review what a diff changed — one okstra implementation stage, or any branch — against this project's coding-preflight rules, and leave the result as a file under the project.
20
14
 
21
- ## Complete accounting and bounded re-review
22
-
23
- A reviewer left to build its own worklist enumerates the diff differently every run, so every run finds different things. Here the worklist — the **census** — is built **once, by you, deterministically**, before any reviewer is dispatched. Reviewers receive their slice as input; they never rebuild, reinterpret, or extend it.
15
+ ## Rules
24
16
 
25
- Each model reviewer owns the full census and delegates its rules to six specialty subagents. Each model's team covers the full census independently; another model's findings never substitute for missing checks. Complete accounting does not prove that every defect was discovered. A follow-up keeps the full PR census but re-inspects only the correction's impact closure; unchanged verdicts require verified prior evidence and a current boundary attestation. Reading full context is required even when only the correction is being re-evaluated. Follow `references/census-rules.md#follow-up-review` before dispatch. Assignment, context and retry boundaries are lead checks, not runtime guarantees.
17
+ The shared coding-preflight pack and declared project policy supply the rules. Step 2 captures their bodies and selects resources for the frozen range. Reviewers read selected frozen guidance delivered with their invocation; installed paths identify provenance, not replacement content. Do not manually copy rules or the typed census into briefs.
26
18
 
27
- ## Rules
19
+ Apply the captured `clean-code.md` "Five simultaneous quality outcomes" through the existing groups and evidence fields. Complete accounting alone does not establish correctness, coding-principle conformance, performance, safety or security.
28
20
 
29
- The rules themselves are **not in this skill**. They live in this project's coding-preflight pack — `overview.md` (core principles plus the three-stage resource routing), `clean-code.md`, and the routed `languages/` / `frameworks/` / `architectures/` resources. Step 2 decides which of them apply; reviewers read them from the absolute paths in their brief. Never restate a rule in a brief or in the report — point at it.
21
+ This file owns execution, authorization and adjudication. Read the relevant contract before its step:
30
22
 
31
- This file owns execution, authorization, and adjudication. Read these references for the shared review contracts:
23
+ - [Census rules](references/census-rules.md) own target membership, IDs, exclusions, pack allocation and completion criteria.
24
+ - [Review calibration](references/review-calibration.md) owns verdict fields, grades, source citations, clean observations and report layout.
32
25
 
33
- - `references/census-rules.md` — how a diff becomes cells: the four axes, pack allocation, exclusions, and the two completion criteria.
34
- - `references/review-calibration.md` — the per-cell verdict format, severity definitions and points, when `clean` is the correct verdict, and the report's section order.
26
+ Complete accounting is not proof that every defect was discovered. Assignment accuracy, context sufficiency, authorization and semantic truth remain lead checks; parser guarantees are named at the applicable steps.
35
27
 
36
28
  ## Step 0 — Preflight
37
29
 
@@ -49,7 +41,7 @@ okstra preflight --runtime <host-runtime>
49
41
 
50
42
  Branch on the fixed first line:
51
43
  - `Okstra preflight: ready` → carry `Project root` as a literal string; every later step is anchored on it.
52
- - `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.
44
+ - `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). If this also fails, show `Reason` and `Recovery`, direct the user to `/okstra-setup`, then stop.
53
45
 
54
46
  <!-- BEGIN FRAGMENT: preflight-outdated-cli -->
55
47
  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).
@@ -79,7 +71,9 @@ Pick the mode from what the user actually gave you:
79
71
  2. Ask for the comparison base branch, tag or commit unless the user already named one. Do not infer a parent branch or substitute the repository default. Pass it as `--base <ref>`; branch mode rejects an omitted or invalid base and freezes the selected ref as a commit.
80
72
  3. Detached HEAD — `git -C <projectRoot> symbolic-ref --quiet HEAD` prints nothing — is refused: ask the user to name a branch. Do not review a bare commit.
81
73
 
82
- **Then call the target CLI.** One call resolves everything the rest of this skill needs; the only reason to call it again is a base the user overrides in the confirmation step below.
74
+ **Select the comparison range before calling the target CLI.** Honor a supplied range without asking again. The first review normally starts at the recorded PR base. A requested correction review uses the previous reviewed head as `--base` and the current branch head as target unless the user explicitly requests the full PR. Record the PR merge-target branch/base separately in Coverage; selecting another review base changes neither. If the previous head or valid review record is unavailable, recover it or clarify before model calls. Rewritten history or a changed PR base requires an explicit range covering this PR's corrections without independently re-reviewing unrelated incoming work. Keep finding dispositions under [follow-up decisions](#follow-up-decisions).
75
+
76
+ **Then call the target CLI.** Resolve the selected range once. Call it again only if the user changes that range or the target changes before it is frozen. Pass an explicit `--base` in stage mode as well when the selected comparison base differs from the recorded stage base.
83
77
 
84
78
  ```bash
85
79
  okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --text
@@ -100,45 +94,27 @@ okstra model-io code-review-input --project-root <projectRoot> --base <baseCommi
100
94
  Carry this fixed Markdown view into the census and reviewer prompts. Do not
101
95
  pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
102
96
 
103
- **The user owns the comparison base.** Both modes resolve the selected base to a fixed commit before returning `baseCommit`. Stage mode selects the recorded stage base unless the user explicitly overrides it. Carry the returned hash verbatim into every later command and the report. Do not substitute the default branch or an inferred parent.
104
-
105
97
  **Read the frozen head in both modes.** Run git in `worktreePath` when it is non-empty, otherwise in `projectRoot`; call that location `<gitRoot>`. Read every whole source file, caller and test with `git -C <gitRoot> show <headCommit>:<path>`, including clean observations. A checkout on the selected branch may contain uncommitted edits or move during review. `worktreePath` identifies a Git repository, not authority to read its working files. Branch targets leave it empty; a released stage can also have an empty path. Deleted targets are read with `git -C <gitRoot> show <baseCommit>:<path>`; surviving callers and contracts are still read at the head.
106
- **Then show the base and confirm it — branch mode and stage mode alike.** The CLI's answer is a recommendation the user has not seen yet, and a base nobody looked at is how unrelated commits slip into a review unnoticed. Print `baseCommit` verbatim next to `git -C <workdir> log -1 --oneline <baseCommit>` so the commit it names is legible, then ask with a 3-option picker:
107
-
108
- 1. `Use <baseCommit>` — **the recommendation**, the value the CLI returned.
109
- 2. `Show what this range covers` — print `git -C <workdir> log --oneline <baseCommit>..<headCommit>`, then ask the same three options again.
110
- 3. `Enter directly` — always last: the user types a ref, and you call the target CLI a second time with `--base <that ref>`. Every field from the second call replaces the first call's, including `reviewPath` and `round`.
98
+ **Show the fixed range.** Print `baseCommit` and `headCommit` next to their `git -C <gitRoot> log -1 --oneline <commit>` descriptions. A user-specified or previously authorized range needs no second confirmation. Ask only when the intended range is ambiguous or the resolved range differs from it; do not dispatch until that discrepancy is resolved. If the user supplies a replacement base, call the target CLI with `--base <that ref>` and replace every returned field, including `reviewPath` and `round`.
111
99
 
112
100
  ## Step 2 — Census the diff
113
101
 
114
- 1. **Read `references/census-rules.md`** (next to this file) and follow it. It owns the cells; this step owns only the inputs and what you print.
115
- 2. Collect the diff from the work directory chosen in Step 1 — `git -C <workdir> diff --name-status <baseCommit>..<headCommit>` for the file list, and `git -C <workdir> diff <baseCommit>..<headCommit>` for the hunks. Before trusting that range, run `git -C <workdir> rev-list --count <headCommit>..<baseCommit>`: anything but `0` is the rewritten-history case in the Exceptions table. An empty diff skips Steps 3–3.5 (also in Exceptions).
116
- 3. **Route the packs once, here — and fix both absolute paths the briefs carry.** `okstra paths --field home` prints the okstra home; read `<okstraHome>/prompts/coding-preflight/overview.md` and walk all three stages of its routed resource selection over the changed-file list. The result is the applied pack list — the absolute paths reviewers will read. This routing happens exactly once per run; no reviewer repeats it.
117
-
118
- The second path is this skill's own calibration file. A subagent has no "next to this file" coordinate, so the brief must spell it out: `okstra install` writes this skill to `~/.agents/skills/okstra-code-review/` on every machine (and to `~/.claude/skills/` only when `~/.claude` exists), making the literal path `~/.agents/skills/okstra-code-review/references/review-calibration.md` — the same string whether the skill was copied in or dev-linked. Carry it, together with the pack list, into every Step 3 brief.
119
- 4. Build the cells per `references/census-rules.md` with `okstra code-review census --project-root <projectRoot> --base <baseCommit> --head <headCommit> --rules <rules-path> --out <census-path>`, where `<rules-path>` holds the shared rule catalog for the routed packs; on a follow-up add `--previous-census <prior-census-path>` so identical targets keep their IDs. Exit 1 lists changed non-Python code under Unresolved function boundaries: add those function cells by hand before dispatch. Then print, in this response: one cell table per axis, the exclusion list with a reason on every entry, and the applied pack list.
120
- 5. Restate both completion criteria and show they hold: censused files + exclusions = files in the diff, and every hunk maps to a censused function or to file-level code.
121
-
122
- **Membership is mechanical; judgment only ever decides a cell's verdict.** Never drop a cell because you doubt the rule applies to it — that doubt is the reviewer's answer, and its name is `clean`. Over-inclusion costs one line; a judged exclusion is the run-to-run variance this census exists to remove.
123
-
124
- A large census is never truncated. Report the cell count and confirm before dispatching — a silent cut is a false "I looked at everything" signal.
102
+ 1. **Read [census rules](references/census-rules.md).** Resolve `<okstraHome>` with `okstra paths --field home`; use its `prompts/coding-preflight/review-rules.json` as `<rules-path>`, without retyping a parallel catalog.
103
+ 2. Collect the diff from Step 1's Git root: `git -C <gitRoot> diff --name-status <baseCommit>..<headCommit>` for files and `git -C <gitRoot> diff <baseCommit>..<headCommit>` for hunks. First run `git -C <gitRoot> rev-list --count <headCommit>..<baseCommit>`: a nonzero count is the divergence case in Exceptions. An empty diff dispatches no reviewers.
104
+ 3. **Capture and select one policy.** Run `okstra code-review census --project-root <projectRoot> --base <baseCommit> --head <headCommit> --rules <rules-path> --out <census-path>`. The command captures canonical coding rules, declared project policy and protocol/calibration, then selects resources from the fixed range; declared architecture precedes layout signals. When resolved stage inputs explicitly name a run manifest, add `--run-manifest <run-manifest>` to reuse its author's captured policy. Never infer a latest run or claim policy equality without that source. Additional applied project policy uses repeated `--policy <path>` inputs in the same capture.
105
+ 4. Inspect the actual diff for embedded SQL, ORM queries and other resource needs automatic path/manifest routing misses. Add repeated `--resource <pack-relative-id>` inputs for applicable resources present in the archive; do not route again in a coordinator or child. Review selection excludes author-only source-writing procedures. Add `--previous-census <prior-census-path>` only for [ID continuity](references/census-rules.md#follow-up-review). Exit 1 identifies unresolved non-Python function boundaries: complete their manual inventory before dispatch.
106
+ 5. Carry the returned literal `Review policy` path as `<review-policy-path>`; the shared snapshot is `<census-path>.policy.json`. Preserve its `Review policy digest` and `Review resources` metadata lines in every full or assigned census. `-` resources means no explicit additions. Keep the same snapshot and resource values for every coordinator, child and gap-fill, passing additions as repeated `--review-resource` materialization inputs. Mutable installed skill or calibration paths are capture inputs, never replacements for delivered frozen guidance.
107
+ 6. Verify [both completion criteria](references/census-rules.md#completion-criteria) and follow [What to emit](references/census-rules.md#what-to-emit). Preserve the complete census and policy selection. For a large census, report its size and confirm dispatch; never truncate it.
125
108
 
126
109
  ## Step 3 — Select one to three model teams with six specialists each
127
110
 
128
- Let the user choose one to three reviewers with distinct models at review start; the default is 2. Honor an explicit count without asking again. Otherwise offer 2 as the default/recommended choice, with 1 and 3 as alternatives. Carry the selected value as `<reviewerCount>`; use 2 when the user accepts the default or supplies no count. Keep that count for this review and its gap-fills. The instruction and its default are checked by the retired Python suite; the runtime count range is enforced by `resolve_operation_slots` and the retired Python suite. This skill is model-agnostic: do not hard-code provider names, model names or versions, preferred model order, or specialty-to-model mappings. Resolve the roster from the runtime's registered model pool for each new review:
111
+ Select one to three distinct-model reviewers; default to 2. Honor an explicit count without asking again; otherwise offer 2 as recommended, with 1 and 3 as alternatives. Carry `<reviewerCount>` into this review and its gap-fills. Resolve each new roster from the registered pool, without hard-coded providers, models, versions or preferred ordering:
129
112
 
130
113
  ```
131
114
  okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount>
132
115
  ```
133
116
 
134
- It prints the duty, the role, the reviewer count, and one `slot` line per reviewer carrying that slot's
135
- provider and model. The operation contract (`agents/operations/code-review.json`) owns the duty and count ceiling;
136
- the duty supplies the role, and the runtime model pool supplies the provider/model assignments.
137
- Always pass the selected count explicitly; the operation contract's count is the ceiling, not this skill's default.
138
- A machine with too few distinct models fails here rather than quietly running fewer reviewers.
139
- Dispatch exactly the returned slots; never replace them with a remembered or preferred model list.
140
- Keep the resolved assignments within that review and its gap-fills. Child inheritance below refers to
141
- the selected runtime assignment, never to a specific model required by this skill.
117
+ The returned duty, role and `slot` provider/model values are authoritative. The operation contract owns the ceiling; `resolve_operation_slots` enforces the count range and refuses too few distinct models. Pass the count explicitly because the contract ceiling is not the default. Keep the returned assignments for coordinators, children and gap-fills; do not substitute remembered or preferred models. Default selection and assignment fidelity remain lead checks.
142
118
 
143
119
  Each returned slot is a model-team coordinator, not a specialty. Every coordinator receives the full census and delegates to six actual subagents using its exact provider/model assignment:
144
120
 
@@ -151,109 +127,79 @@ Each returned slot is a model-team coordinator, not a specialty. Every coordinat
151
127
  | State | `state-and-tests` | `T1` |
152
128
  | Tests | `state-and-tests` | `T2`–`T4` |
153
129
 
154
- Each model coordinator divides its received full census into six assigned censuses and passes each one to its responsible subagent. The orchestrator supplies the same full census to each coordinator; the coordinator owns division and delivery within its team. Copy the specialty's rules and all cells of its axis without changing IDs, targets, references or ordering. Naming/readability share semantic cell IDs; state/tests share state-and-tests cell IDs. Their rule subsets differ. Within each team, assigned `(cell ID, rule ID)` pairs are disjoint and their union equals the full census's pairs. Across models the entire assignment repeats independently. Never partition specialties between models. An empty specialty is recorded by its coordinator as not applicable without inventing checks or dispatching an empty review. Do not pass an empty census to `scope` or `check-coverage`, which require cells.
130
+ Give each coordinator the same complete census. The coordinator divides it by the table, retaining each specialty's rules and all cells of that axis with IDs, targets, references and order unchanged. Naming/readability share semantic IDs, and state/tests share state-and-tests IDs, with disjoint rule subsets. Each team's `(cell ID, rule ID)` union must equal the full census; every model repeats that assignment independently. Never divide specialties between models or borrow another team's verdicts. A coordinator acknowledges an empty specialty without spawning it or passing an empty census to `scope` or `check-coverage`.
155
131
 
156
- Show all selected model teams and the six-specialty division policy before dispatching coordinators. Each coordinator records its concrete child assignments before spawning them. The initial review includes `reviewerCount` coordinator calls and up to `6 × reviewerCount` specialty subagent calls, plus automatic coverage gap-fills, format repairs and single provider retries under Step 3.5. Honor any user-set cost or call limit; an insufficient limit blocks dispatch rather than silently reducing the team. This authorization does not cover further provider retries, new scope, another model or a new implementation round. Instruction presence is checked by the retired Python suite; delegation, authorization and assignment accuracy remain lead checks.
132
+ Show the selected teams and division before dispatch; each coordinator records its concrete child assignments before spawning. It owns actual separate child invocations, collection, gap-fills and [consolidation](#consolidate-within-each-model-then-across-models). The orchestrator launches coordinators and does not perform those duties for them. Children do not delegate further. An inability to spawn and collect children under the exact provider/model binding is an execution blocker, not permission to substitute a model, serialize the whole review into one call or simulate specialties as headings. Keep team verdicts private until independent model reports are complete.
157
133
 
158
- Each selected model coordinator itself spawns its six specialty subagents through a supported delegation surface, collects their verified completions, requests any specialty gap-fills, and consolidates their results before returning its model report. The orchestrator launches the selected coordinators; it does not spawn their children on their behalf or consolidate raw child results. These are actual separate model calls, not six headings in one response. Preserve the verified provider/model binding and standalone evidence for every child. If a coordinator cannot spawn and collect its children under that binding, report an execution blocker rather than moving those responsibilities to the orchestrator, substituting a model or replacing the team with one serial review. Specialty subagents do not delegate further. Never share other model teams' verdicts before independent team reports are complete.
134
+ The authorized review includes `<reviewerCount>` coordinator calls, up to `6 × reviewerCount` specialty calls and the bounded continuations in [Step 3.5](#step-35--audit-the-coverage). Honor user call/cost limits; an insufficient limit blocks dispatch rather than reducing the team. New scope, another model, a new implementation round or retries beyond those limits require their own authorization. Delegation and authorization accuracy remain lead checks.
159
135
 
160
136
  ### Shared test execution evidence
161
137
 
162
- Before dispatch, inspect the project's test commands and applicable verification requirements. Reuse saved results only when their source tree, dependencies, configuration and test inputs match the fixed head. Otherwise the lead runs the relevant tests once in a checkout of that head isolated from user edits, preserving command, head, environment, exit code and full log. Run the project's required full gate at its prescribed stage; do not invent a universal test command or require every reviewer to rerun the same suite. External, paid or destructive tests keep their existing authorization boundary.
163
-
164
- Share the evidence with all model teams and subagents. Every model's Tests subagent independently checks whether tests discriminate the changed behavior, cover applicable failure and boundary cases, and avoid self-mocking; test success is not proof of correctness or rule conformance. A missing, failed or blocked required test stays explicit in the report. If review identifies a necessary additional local test, the lead runs it once and shares the result. Reviewers do not edit code, add tests or launch duplicate suites. Follow-up changes invalidate affected results; unchanged, matching evidence is reused. These are lead/reviewer checks, not enforced by the coverage parser.
138
+ Inspect repository test commands and requirements before dispatch. Reuse results only when source tree, dependencies, configuration and inputs match the frozen head. Otherwise the lead runs relevant tests once in an isolated checkout of that head, preserving command, head, environment, exit code and full log. Follow the repository's full-gate timing and existing external/paid/destructive-test permissions. Share results with all teams; necessary additional local tests run once through the lead. Reviewers neither edit/add tests nor launch duplicate suites.
165
139
 
166
- Every coordinator, specialty subagent and later gap-fill is a separate auditable standalone invocation. Record its team slot, specialty (or coordinator), parent coordinator ID and assigned census path in the instructions. Use unique IDs for all calls. For each invocation, create
167
- `.okstra/agent-invocations/code-review/<invocation-id>.instructions.md` from that reviewer's brief, then run
168
- `okstra agent-prompt materialize --project-root <projectRoot> --invocation-id <invocation-id> --host-runtime <runtime> --provider <slot provider> --model <slot model> --model-role <role> --audience <duty> --purpose code-review --instruction <instructions-path> --prompt <prompt-path>`,
169
- copying `role`, `duty`, and the slot's `provider` and `model` verbatim from `resolve-operation` (`--model`
170
- takes the `provider/model` value the slot line prints). The prompt path is the canonical `.prompt.md` beside
171
- the instructions file; the returned assignment is authoritative. Run `okstra agent-prompt verify` against the returned `metadataPath` before
172
- invoking any model.
140
+ Each Tests specialist independently inspects assertions, failure/boundary discrimination and self-mocking; passing commands do not prove correctness or conformance. Corrections invalidate affected results only. Report missing, failed or blocked checks in the [test-evidence fields](references/review-calibration.md#the-report). These are lead/reviewer checks, not parser guarantees.
173
141
 
174
- For a native host call, pass the verified prompt body and `hostModelValue`. For a deterministic provider
175
- process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path> "" <role> --invocation-metadata <metadataPath>`
176
- with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
177
- standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
178
- `.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
179
- it. **Every reviewer receives its assigned census** and independently owns its verdicts. On follow-ups, add that slot's verified previous results and scope decision as described below. Every brief carries:
142
+ ### Inspection scope and briefing
180
143
 
181
- - the diff and the fixed-head read command `git -C <gitRoot> show <headCommit>:<path>`, where Step 1 resolved `<gitRoot>`
182
- - the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
183
- - **the assigned census** — its rule subset and grouped cells, verbatim, plus its model-team slot, specialty, parent coordinator ID and the full census path for context. Coordinators receive the full census and all six child assignments; children receive only their own verdict assignment
184
- - the absolute paths of the packs allocated to its axes (from step 2's routing)
185
- - shared test execution evidence, including missing or blocked verification
186
- - the full-context inspection requirement: read whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head; follow transitive effects as needed. Read with targeted `git show` ranges and `git grep`; never print a whole generated report or graph dump (for example under `graphify-out/`) into a child's context. Specialty limits verdict ownership, not access to context. Report a suspected issue outside the assignment to the lead, who checks it and routes any required inspection to the owning specialist without duplicating or changing cells
187
- - 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
188
-
189
- **Resolve each slot's inspection scope before materializing its prompt.** Run:
190
-
191
- Use `~/.agents/skills/okstra-code-review/SKILL.md` for `<skill-path>`, the calibration path fixed in Step 2 for `<calibration-path>`, `~/.agents/skills/okstra-code-review/references/census-rules.md` for `<census-rules-path>`, and `<okstraHome>/prompts/duties/code-reviewer.json` for `<duty-contract-path>` using Step 2's resolved home. This installed duty source exists before materialization; invocation materialization still freezes its own duty snapshot. Keep the same ordered list of policy documents and applied project instructions across rounds. Policy content is matched by position; catalog references retain the rule-to-resource binding.
144
+ Resolve each slot's scope before materializing its prompt, using Step 2's shared snapshot:
192
145
 
193
146
  ```bash
194
- okstra code-review scope --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --policy <skill-path> --policy <calibration-path> --policy <census-rules-path> --policy <duty-contract-path>
147
+ okstra code-review scope --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --review-policy <review-policy-path>
195
148
  ```
196
149
 
197
- For a follow-up, add `--previous-head <priorHead> --previous-census <prior-assigned-census-path>` and repeat `--completion <prior-completion-path>` for that model team's same specialty's retained verified completions. Include every applied project instruction as another `--policy`. Use the same specialty and selected provider/model; a missing or changed assignment starts with full inspection of that specialty. Never substitute another team's or another specialty's evidence. Prior records remain immutable. An identical head, rules and completed adjudication need no new model call; reuse the existing report.
150
+ Every applied project instruction belongs in the shared snapshot. Additional scope `--policy` paths must already identify captured sources; keep their order across rounds. Snapshot content, resource selection and catalog bindings are fingerprinted. Materialization separately freezes its rendered role and duty contracts. For a new correction base, inspect the whole current census without earlier full-PR completions as reuse inputs. Full inspection means the supplied census, not an expanded PR range.
198
151
 
199
- Carry the fixed scope text into the brief. `Recheck` names mandatory inspections; `Carry candidates` are proposals, not automatic coverage. Each reviewer inspects the delta, searches changed symbols' callers and tests, checks the dependency inventory and expands Recheck for newly discovered effects before accepting any candidate. Unknown or unbounded effects require a full review. The full census remains unchanged; no candidate silently disappears. Return current coverage rows for both inspected and inherited cells, plus the baseline and dependencies in the calibration format. Only this current invocation's verified completion and gap-fills enter the current coverage audit; old completions are scope inputs, never current verdicts.
152
+ With an unchanged comparison base and policy, add `--previous-head <priorHead> --previous-census <prior-assigned-census-path>` and repeated `--completion <prior-completion-path>` from this team's same specialty and provider/model only. A missing or changed assignment needs full inspection of that specialty. `code_review_scope.py::review_scope` checks prior integrity, baseline, ancestry, references and policy fingerprints; incompatible or legacy baselines fall back to full inspection, while invalid integrity stops calculation. Prior findings, changed targets/recorded inputs, unverified cells and missing dependency records reopen. Input paths are whole files. Prior records remain immutable; an identical range, rules and completed adjudication need no new call.
200
153
 
201
- Each axis is **one rule group**, so a cell is `target × <axis>` — never `target × <individual rule>`. The reviewer names the specific rule it found violated inside the verdict's `rule` field, and one cell may carry findings from several rules of its group.
154
+ Every reviewer reads whole target files, enclosing definitions, affected callers/callees, outcome consumers, contracts and tests at the frozen head, following transitive effects. Open definitions before claiming their behavior. Use targeted `git show` ranges and `git grep`, not whole generated reports or graph dumps. A specialty limits verdict ownership, not context access. Route suspected issues in another specialty through the lead without changing cells.
202
155
 
203
- Axis scope — each specialist works its assigned axes; the `Reads` column names each group's rules, and a brief never restates them; the bodies are in the packs:
156
+ `Recheck` is mandatory; `Carry candidates` are proposals. Before inheriting any verdict, search the delta's changed symbols and wiring beyond recorded dependencies, including result/error mappings, state, test assumptions, contracts and downstream work. Reopen newly affected cells across applicable axes. Unknown reachability, dynamic/configuration-driven wiring or unexplained failures require broader supporting inspection, up to the full current census. Source outside that census remains context, not an independent target. Expanding the comparison range or model-call authorization requires approval. Dependency completeness and current boundary attestations remain reviewer/lead judgments; scope output cannot mark a cell clean.
204
157
 
205
- | Axis | Cell | Reads |
206
- |---|---|---|
207
- | `structural` | non-test source file × `structural` | core principles 1, 2, 3, 6; `clean-code.md` DRY / KISS / SOLID / YAGNI; the completion sweep's domain-literal and documented-fork items; plus the architecture pack when one was routed |
208
- | `semantic` | function × `semantic` | core principles 4, 5; `clean-code.md` meaningful naming, functions-do-one-thing, the plain-English summary test, the 50-line cap, nesting depth, magic numbers, comments-explain-why |
209
- | `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 |
210
- | `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 |
158
+ Each brief carries the fixed scope text, diff and frozen read command; a short project layout; team/specialty/parent IDs and the full-census path for context; the shared policy identity; shared test evidence and blockers; and the inspection requirements above. Pass the assignment through `--review-census` with unchanged digest/resource metadata; materialization delivers its canonical rules and cells, so do not copy them into the brief. A coordinator's task explicitly owns child dispatch, checks, gap-fills and consolidation; a specialist's task grants no delegation and carries no coordinator procedures. Read the delivered frozen calibration and applicable rule sections completely, without clipping normative lines. Require its [baseline, dependency and carry fields](references/review-calibration.md#compact-rule-coverage), including current coverage for inherited cells. Do not restate the materialized duty.
211
159
 
212
- 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.
160
+ ### Authenticated invocations
213
161
 
214
- Capture each raw model return under `.okstra/agent-invocations/code-review/.tmp/`. Publish it with
215
- `okstra agent-prompt materialize-result`, publish the immutable completion marker with
216
- `okstra agent-prompt complete`, then run `okstra agent-prompt verify-completion`. Parse only the
217
- `returnedBody` emitted by that last command. A model response without a verified completion is not a
218
- review result and cannot contribute a verdict.
162
+ Every coordinator, child and continuation uses a unique invocation ID. Write its brief to `.okstra/agent-invocations/code-review/<invocation-id>.instructions.md`, with the canonical `.prompt.md` beside it, then run:
219
163
 
220
- ## Step 3.5 — Audit the coverage
164
+ ```bash
165
+ okstra agent-prompt materialize --project-root <projectRoot> --invocation-id <invocation-id> --host-runtime <runtime> --provider <slot provider> --model <slot model> --model-role <role> --audience <duty> --purpose code-review --instruction <instructions-path> --prompt <prompt-path> --review-policy <review-policy-path> --review-census <assigned-census-path> --review-base <baseCommit> --review-head <headCommit> [--review-resource <pack-relative-id> ...]
166
+ ```
167
+
168
+ Copy duty, role, provider and `provider/model` from the resolved slot. Run `okstra agent-prompt verify` against the returned `metadataPath` before any model call. Native calls receive the verified prompt body and `hostModelValue`; provider processes use:
169
+
170
+ ```bash
171
+ ~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path> "" <role> --invocation-metadata <metadataPath>
172
+ ```
221
173
 
222
- Each spawning coordinator owns this loop against the [coverage format](references/review-calibration.md#compact-rule-coverage):
174
+ Use the verified prompt path and never interchange model values. `worker-dispatch` handles run-manifest assignments, not standalone prompts. The wrapper writes the prompt's `.log`; dispatch verified calls in parallel where supported. Capture raw returns under `.okstra/agent-invocations/code-review/.tmp/`, publish with `okstra agent-prompt materialize-result`, then `complete` and `verify-completion`. Only that last command's `returnedBody` is usable. Frozen standalone completions are also bound to the source/index integrity audit; a mutation or invalid audit prevents usable completion evidence. Audit current verified completions and gap-fills only; prior completions are scope inputs, never current verdicts.
223
175
 
224
- 1. Collect each child's investigation of its assigned census, including evidence, findings and explicit rule accounting.
225
- 2. Compare the collected results with the assigned subsets and the received full census; list missing cells and rules by responsible child.
226
- 3. Return only those omissions or invalid verdicts to the same responsible subagent, preserving its logical child identity and original assignment. Resume that child when supported; otherwise use a linked continuation invocation with its prior verified results. Do not assign the omission to another reviewer or restart completed investigations.
227
- 4. Collect the supplementary results and repeat the audit and requests until no cells or rules remain unaccounted for. A new invocation ID records each continuation without changing logical ownership.
228
- 5. Only then consolidate the complete results and return the model report. A stopping condition below produces an explicitly incomplete status with its blocker, never a completed review.
176
+ ## Step 3.5 — Audit the coverage
229
177
 
230
- For each model team's specialty subagent separately, audit its grouped rows against that child's assigned rule subset using its verified completion marker:
178
+ Each spawning coordinator collects its children's evidence, findings and [coverage rows](references/review-calibration.md#compact-rule-coverage). Audit each child separately against its assigned subset using verified completion markers:
231
179
 
232
180
  ```bash
233
181
  okstra code-review check-coverage --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
234
182
  ```
235
183
 
236
- Pass the `headCommit` that `okstra code-review target` returned. The command reads head evidence at `<headCommit>` and explicit `base:` evidence at `<baseCommit>`, never the project root's working tree, so a review run from a checkout on another commit audits the reviewed lines. 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.
184
+ Use Step 1's frozen commits. `code_review_coverage.py` verifies completions and refuses mixed model assignments; `review_verdicts.py` checks the supplied catalog, rule accounting and source anchors at those commits. Exit 0 means complete valid accounting with no unknown cell; exit 1 lists missing/invalid cells or rules; exit 2 reports invalid input or completion evidence. Neither command proves exhaustive references, delegation or semantic truth.
237
185
 
238
- Automatically fill missing verdicts, unaccounted rules and malformed rows within the authorized review. Preserve every raw response and completion. For each incomplete specialist, dispatch one gap-fill on its original slot and specialty carrying only its incomplete grouped cells, their assigned rule subset, the same range, rule paths and full-context requirements. Ask for a complete row per affected cell under that subset. Use a new invocation ID and repeat materialize → verify → dispatch → materialize-result → complete → verify-completion. Audit that child's initial and gap-fill markers against its entire assigned census. Earlier usable verdicts remain unchanged. Repeat while the incomplete cell count decreases, until every assigned cell passes. Do not rerun completed specialists or borrow another model team's verdicts.
186
+ For an incomplete child, send only its missing or invalid grouped cells, assigned rule subset, same range, rule paths and full-context requirements back to that same logical child. Resume it where supported; otherwise create a linked continuation carrying its verified prior results. Use a new invocation ID and the [authenticated lifecycle](#authenticated-invocations), asking for a complete row per affected cell. Preserve raw results and earlier usable verdicts; audit initial plus gap-fill completions against the child's whole assignment. Repeat only while the incomplete count decreases. Do not reassign omissions or rerun completed investigations.
239
187
 
240
188
  Two cases get one bounded repeat before the no-progress rule applies. A row rejected only for its syntax (cell or rule separators, escaping, a column count, an observation form the calibration does not allow there) gets one format repair: a continuation on the same child that carries the parser's rejection text and asks for the same verdicts in the calibration row format. That repair does not count toward the no-progress stop. An invocation that exits non-zero without a returned body is retried once on the same slot and specialty under a new invocation ID; a second failure is a provider-execution stop. Each specialist's gap-fills, repair and retry are judged separately: one specialist's stop never stops another specialist that has not had its own gap-fill.
241
189
 
242
- Stop with incomplete coverage when a gap-fill makes no progress, a user-set call/cost limit is reached, source evidence is unavailable, or an invocation fails authentication, billing, provider execution or integrity verification. Unknown cell IDs are invalid: preserve the response and report the blocker rather than relabeling IDs or retrying automatically. Do not treat infrastructure failures as missing inspections. A stopping condition fails the review instead of pausing it for authorization: dispatch no further gap-fills, continue to Step 3.6 with the verified results, and record every unaccounted `(cell ID, rule ID)` pair as a `must-fix` `now` coverage finding that names the pair, its responsible team and specialty, and the blocker. That finding stays open until a later review round accounts for the pair. A manual assessment does not satisfy reviewer coverage or create a verified completion. The lead checks these stopping conditions; the parser only checks accounting and source anchors.
190
+ Stop the affected coverage loop when a gap-fill makes no progress, a user call/cost limit is reached, source evidence is unavailable, or authentication, billing, provider execution or integrity verification fails. Unknown cell IDs also stop the loop: preserve the response rather than relabeling or automatically retrying. Dispatch no further gap-fills for that stopped assignment; a global user limit stops further dispatch altogether. Continue with verified results and record every unevaluated pair, owner and blocker in [Coverage](references/review-calibration.md#the-report). These are not code findings and receive no kind, severity, timing or points; the review remains incomplete even at score zero. Manual assessment cannot replace verified reviewer coverage. A later review needs its own authorization. The lead checks stopping conditions.
243
191
 
244
192
  An isolated false observation reopens the affected cells and any dependent conclusions, not automatically every valid verdict. Record the excluded completion/cells and retain only independently valid evidence. Semantically rejected rows enter the same affected-cell gap-fill procedure; count them as incomplete when checking progress. If an older row is syntactically valid but disproved, pass the corrected completion first so the existing first-usable rule selects it; retain the older completion only for unaffected rows. If the error's extent cannot be bounded, report the unresolved extent; a full correction requires explicit authorization. Never edit an immutable response to make it pass.
245
193
 
246
- Before accepting a clean general cell, open its G2/G3/G5 observations and verify the result-meaning trace, the downstream workload and pre-work bound, and the applicable documented convention checks. If opened code contradicts an observation, record the affected cells and dependent conclusions as semantically rejected and use the bounded gap-fill procedure above. Exclude the entire completion only when the error's extent cannot be bounded; report the blocker instead of automatically requesting a full correction. Keep original artifacts immutable for the audit trail. The parser enforces presence and source locations; the lead checks truth. Keep these observations inside the existing Evidence column, without adding verdict rows.
194
+ Before accepting clean general cells, open and verify their [G2/G3/G5 observations](references/review-calibration.md#compact-rule-coverage). Contradictory source evidence rejects the affected cells and dependent conclusions through the bounded procedure above. This is a truth check beyond the parser's format/source-location checks.
247
195
 
248
196
  ### Consolidate within each model, then across models
249
197
 
250
- After its six child assignments pass, the coordinator that spawned those children consolidates their verified results into one model report itself. It does not hand raw child results to the orchestrator for consolidation. Preserve every finding and its child completion provenance. Namespace finding IDs by team and specialty to avoid collisions. For a shared semantic or state-and-tests cell, combine the children's disjoint rule statuses into one complete grouped row; union their source observations and dependency files. Preserve inspected/inherited distinctions and the frozen baseline. Never convert an unaccounted rule to clean or silently discard a conflicting finding. Record conflicts for the lead to settle against the code.
251
-
252
- The coordinator returns the full-census coverage, findings, and a child manifest listing each specialty, invocation/completion paths, assignment path and audit result, including empty-specialty acknowledgments. Publish and verify this coordinator completion through the same standalone boundary. The lead checks that every full-census `(cell ID, rule ID)` status is supported by the corresponding child's verified row and that all child findings survive consolidation. A coordinator's summary is not proof that its children ran. This provenance reconciliation is a lead check; the coverage parser does not enforce delegation or parent-child relationships.
198
+ Once each child has passed its audit or stopped explicitly incomplete, their coordinator consolidates the audited results into the model report. Namespace finding IDs by team/specialty, retain every finding and child provenance, and record conflicts rather than discarding them. Combine complementary rule statuses for shared semantic and state/test cells into complete rows; union observations and dependency files while retaining inspected/inherited distinctions and the frozen baseline. Never convert missing rules to clean.
253
199
 
254
- Audit each coordinator's completion against the full census using `check-coverage`. Do not feed split-rule child completions directly into a full-census audit: the parser selects whole usable rows and does not merge partial rows. If consolidation loses a rule or finding, return the discrepancy to the spawning coordinator so it corrects its report from its saved child results; the orchestrator does not reconstruct the report. Do not rerun completed children. Preserve and verify the replacement coordinator response. Such consolidation corrections fall within authorized gap-fills and the same progress/cost stopping conditions.
200
+ Return full-census coverage, findings and a child manifest naming specialties, assignment paths, invocation/completion paths, audit results and empty-specialty acknowledgments. Publish and verify the coordinator completion through the same lifecycle. The lead reconciles every full-census pair and finding against verified child rows; a coordinator summary alone does not prove delegation. Audit the coordinator against the full census with `check-coverage`, never mixing model assignments. The parser selects whole usable rows and cannot merge split child rows, so children are not direct full-census audit inputs.
255
201
 
256
- Do not start Step 3.6 until all selected model reports independently pass full-census coverage and child provenance reconciliation, or a report has stopped under a Step 3.5 stopping condition. Never combine different model assignments in one `check-coverage` call. The lead then compares the selected independent model reports and settles their combined findings in Step 3.7. A stopped report contributes its verified verdicts and its coverage findings; the review is failed, never presented as complete coverage.
202
+ Return aggregation discrepancies to their coordinator for correction from saved child results, without rerunning completed children or having the orchestrator reconstruct the report. Authenticate the replacement; the same gap-fill progress/cost limits apply. Proceed to Step 3.6 only after each selected model passes full-census coverage and child provenance checks or stops explicitly incomplete. Stopped teams contribute verified verdicts plus unevaluated checks; they cannot supply complete coverage.
257
203
 
258
204
  ## Step 3.6 — Check every citation
259
205
 
@@ -263,44 +209,46 @@ Reviewers miscount lines. Pass every finding's `path:line` to one call:
263
209
  okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
264
210
  ```
265
211
 
266
- `ok` keeps the citation. Use `base:<path>:<line>` for removed lines, reading the snippet with `git -C <gitRoot> show <baseCommit>:<path>`. Use `<path>:0` only for an empty file at the head; its snippet is the empty string and its evidence describes the removed behavior or empty-file consequence. A deletion within a surviving file may also retain its head anchor before the cut. For `not-changed` or `not-in-diff`, locate the snippet at its declared side and re-anchor it only to a changed location on that side. Otherwise move it to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
212
+ Apply the [source-citation forms](references/review-calibration.md#source-citations). Keep `ok` citations. For `not-changed` or `not-in-diff`, locate the snippet on its declared side and re-anchor only to a changed location there; otherwise reject it as "cites no changed line". Repeat until every retained citation is `ok`.
267
213
 
268
214
  ## Step 3.7 — Settle the findings
269
215
 
270
216
  A formatting-only or minor correction does not automatically require another model review. The lead verifies the exact delta, confirms that behavior, public contracts, dependencies and requirements are unchanged, and records the relevant deterministic checks. A nit label alone is insufficient. Keep the prior reviewed head and the current checked head distinct; never present an old completion as evidence for a new head. If impact is uncertain, record the uncertainty and request authorization for targeted inspection rather than silently declaring it clean.
271
217
 
272
- On follow-ups, retain the previous adjudication ledger: resolved, still open, parked and rejected. Recheck every fix and its affected paths. Reopening an unchanged verdict names the prior decision and new evidence: a reachable failure, a previously missed applicable rule with concrete impact, or a changed dependency/requirement. Classify each new finding as fix-introduced, previously missed, or newly in scope; do not count an old discovery as a new regression. A corrected rule interpretation can reopen a real defect; repeated preference or an alternative implementation cannot. Do not suppress a demonstrated failure because a prior reviewer marked it clean. Optional improvements remain parked and do not require a code change or another review round unless the user requests them. Keep existing severity/timing adjudication rules below.
218
+ ### Follow-up decisions
219
+
220
+ Retain the prior ledger's resolved, still-open, parked and rejected dispositions separately from the current census. Absence from a correction range does not resolve a finding. Recheck fixes and affected paths; before merge, reconcile the initial full review and subsequent correction/reuse evidence against the final PR. A correction report alone is insufficient for that cumulative check.
221
+
222
+ To reopen an unchanged verdict, name its prior decision and new evidence: a reachable failure, missed applicable rule with concrete impact, or changed dependency/requirement. Classify discoveries as fix-introduced, previously missed or newly in scope; do not label old discoveries regressions. Corrected interpretations can reopen real defects; preference cannot. Do not suppress demonstrated failures because of prior clean results. Optional improvements stay parked without requiring changes or another round unless requested.
223
+
224
+ ### Evidence and grades
273
225
 
274
226
  Before pairing findings, check every finding, including agreed ones, against the [kind-specific verdict criteria](references/review-calibration.md#separate-execution-errors-from-design-violations) and [finding requirements](references/review-calibration.md#every-finding-carries-its-fix). Record the specific reason for rejecting unsupported evidence. Then settle single and overlapping reports as below.
275
227
 
276
228
  **Selected independent model reports.** With one model, adjudicate its report directly against source evidence; do not require cross-model agreement. Group the consolidated findings by the same `path:line` and defect. Adjudicate every finding, including one reported by only one model or one of its children. Multiple children within one team count as one model's report, not independent model agreement. Missing inspection is never a clean verdict or a vote. For overlapping reports:
277
229
 
278
- - **Agreed** — multiple model teams report the same defect 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.
279
- - **Graded differently** — at least two report it with different severity or timing. Choose one reporting reviewer's severity/timing pair for that finding after reading the code, and record all reported values and your reason. Never choose an unreported value or use majority vote in place of evidence.
230
+ - **Agreed** — multiple model teams report the same defect with the same severity and timing. Verify the grade against the established consequence; agreement does not replace evidence or calibration.
231
+ - **Graded differently** — at least two report it with different severity or timing. Set the final grade from source evidence and the calibration rubric, recording every reported value, the final value and the reason for any change. The final value may differ from every reported value; never use majority vote in place of evidence.
280
232
  - **Single report** — only one model team reports the defect. Check the other teams' corresponding rule verdicts, then adjudicate against source evidence as below; silence does not override a demonstrated defect.
281
233
 
282
234
  **Adjudicating** a finding: open each `evidence` location at its declared side (`baseCommit` for `base:` citations, otherwise `headCommit`) and the definitions its claim depends on, then apply the verdict criteria linked above.
283
235
 
284
- - **Confirmed** — the opened evidence satisfies the verdict criteria. The finding keeps its severity and timing.
285
- - **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.
236
+ - **Confirmed** — the opened evidence satisfies the verdict criteria. Apply the calibrated severity and timing, retaining the original reported values and source-cited reasoning for any correction.
237
+ - **Rejected** — the code contradicts the claim. Record the contradicting `path:line` and what it shows.
286
238
 
287
- Never reject for being unconvinced. Apart from choosing among the reporting reviewers' values, never promote, demote, or re-time a finding.
239
+ Do not reject or regrade merely because a finding is inconvenient, tests pass, or several reviewers disagree. A correction to severity or timing requires the applicable rubric, opened source evidence and a concrete impact or scope reason. Preserve the immutable reviewer responses and record the final adjudication separately. Unsupported inspection remains unevaluated rather than becoming a clean verdict.
288
240
 
289
241
  ## Step 4 — Merge and write
290
242
 
291
243
  1. Read the [report format](references/review-calibration.md#the-report), which owns the metadata, body sections, finding layout, scoring, and language.
292
244
  2. Dedupe across axes and reviewers. Keep the same defect once under the rule that explains it best, retaining the Step 3.7 adjudication and reported grades.
293
245
  3. Write the report to `reviewPath`, creating its parent directories, with the fields returned by Step 1 and the adjudicated results. Follow the referenced format without redefining it here.
294
- 4. In the session, print only `reviewPath`, the count per severity, the parked and rejected counts, and the score total. Do not replay the findings in chat.
246
+ 4. In the session, print only `reviewPath`, whether the review is complete, the unevaluated-check count, the count per severity, the parked and rejected counts, and the score total. Do not replay the findings in chat.
295
247
 
296
248
  ## Exceptions
297
249
 
298
250
  | Situation | Handling |
299
251
  |---|---|
300
- | `preflight` reports `Okstra preflight: failed` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
301
252
  | `unknown command: code-review` | the `okstra` binary predates this skill — tell the user to update it (`npm i -g okstra@latest`) and stop |
302
- | `worktreePath` is empty | not a hard stop and not a missing stage: run git in `projectRoot` against the stage's `branch` ref, and have reviewers read whole files with `git -C <projectRoot> show <headCommit>:<path>` |
303
253
  | `baseCommit` is not an ancestor of `headCommit` — `git -C <workdir> rev-list --count <headCommit>..<baseCommit>` returns a **non-zero** count | Stop and show the divergence. Ask the user to choose an ancestor commit that preserves the intended review changes, or to authorize `okstra git-reconcile` before retrying. Do not use the reviewed branch's current tip as a recovery base or infer that divergence proves a rebase. Resolve and confirm a replacement through Step 1, then repeat the ancestry and range checks. Never reconcile automatically. |
304
254
  | the diff is empty | dispatch no reviewers; write the [empty-diff report](references/review-calibration.md#empty-diff) to `reviewPath` and stop |
305
- | the census is large | never truncate — report the cell count and confirm before dispatching |
306
- | detached HEAD (branch mode) | refuse and ask the user to name a branch |