okstra 0.232.0 → 0.233.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 (183) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +8 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +36 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +279 -2
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +31 -41
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  77. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  78. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  79. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  80. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  81. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  82. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  83. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  84. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  85. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  86. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  87. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  88. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  89. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  90. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  91. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  92. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  93. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  94. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  95. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  96. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  97. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  98. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  99. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  100. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  101. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  102. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  103. package/runtime/python/okstra_ctl/material.py +2 -0
  104. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  105. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  106. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  107. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  108. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  109. package/runtime/python/okstra_ctl/paths.py +6 -1
  110. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  111. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  112. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  113. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  114. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  115. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  116. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  117. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  118. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  119. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  120. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  121. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  122. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  123. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  124. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  125. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  126. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  127. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  128. package/runtime/python/okstra_ctl/render.py +28 -2
  129. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  130. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  131. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  132. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  133. package/runtime/python/okstra_ctl/report_language.py +4 -1
  134. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  135. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  136. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  137. package/runtime/python/okstra_ctl/run.py +43 -35
  138. package/runtime/python/okstra_ctl/run_context.py +10 -1
  139. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  140. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  141. package/runtime/python/okstra_ctl/task_query.py +239 -0
  142. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  143. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  144. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  145. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  146. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  147. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  148. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  149. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  150. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  151. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  152. package/runtime/python/okstra_project/state.py +20 -0
  153. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  154. package/runtime/python/okstra_token_usage/cli.py +23 -10
  155. package/runtime/python/okstra_token_usage/collect.py +25 -22
  156. package/runtime/python/okstra_token_usage/policy.py +193 -0
  157. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  158. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  159. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  160. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  161. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  162. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  163. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  164. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  165. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  166. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  167. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  168. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  169. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  170. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  171. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  172. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  173. package/runtime/skills/okstra-run/SKILL.md +55 -183
  174. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  175. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  176. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  177. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  178. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  179. package/runtime/templates/manager/view.template.html +4 -0
  180. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  181. package/runtime/templates/trace/trace.template.md +42 -0
  182. package/runtime/validators/checks/fixtures-02.py +25 -33
  183. package/runtime/validators/validate-run.py +93 -36
@@ -14,7 +14,7 @@ Review what a diff changed — one okstra implementation stage, or any branch
14
14
 
15
15
  ## Rules
16
16
 
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.
17
+ The shared coding-preflight pack and declared project policy supply the rules. Use the pack's captured "Finding evidence and grading" section to decide whether a finding is established. 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.
18
18
 
19
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.
20
20
 
@@ -101,105 +101,113 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
101
101
 
102
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
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.
104
+ 3. **Capture and select one policy.** Set `<census-path>` to `<projectRoot>/.okstra/agent-invocations/code-review/<review-id>.census.md`, where `<review-id>` names this review and round (for example `pr<N>-r<round>`). `code-review census` refuses a census whose `.policy.json` would fall outside the project's `.okstra/`, and reuses the immutable policy already published beside an existing `<census-path>`, so give every new review round its own `<review-id>`. Step 3's `code-review prepare` writes the specialists' assigned censuses, slots, brief and batch in the same directory. 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 for a specialist. 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 specialist and gap-fill, passing additions to `code-review prepare` as the same repeated `--resource` inputs. Materialization routes language and framework bodies from the assignment's own targets, so a specialist can receive fewer packs than the census selection lists; the rule catalog and architecture routing stay identical because architecture detection reads the whole frozen tree. 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. Report a large census's size without truncation; dispatch follows the [authorization boundary](#authorization-and-recovery), not another confirmation based on size alone.
108
108
 
109
- ## Step 3 — Select one to three model teams with six specialists each
109
+ ## Step 3 — Select model teams and prepare every specialist
110
110
 
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:
111
+ Select one to three model teams; default to 2. Honor an explicit count without asking again; otherwise offer 2 as recommended, with 1 and 3 as alternatives. When the user names models, pass each as `--model <provider/model>` in team order instead of `--count`; otherwise the project's or global `operationModels.code-review`, then the adapter defaults, supply them. Write the result beside the census:
112
112
 
113
- ```
114
- okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount>
113
+ ```bash
114
+ okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount> --host-runtime <host-runtime> --out <projectRoot>/.okstra/agent-invocations/code-review/<review-id>.slots.json
115
115
  ```
116
116
 
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.
117
+ The printed slots and their `source` are authoritative; `--host-runtime` has already confirmed each slot's binding on this host. Every team has a different provider, and the operation contract owns the ceiling. Do not substitute remembered or preferred models; to change models at the user's request, run the command again with `--model`. Carry `<reviewerCount>` and the slots file into this review and its gap-fills.
118
118
 
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:
119
+ Each slot is one model team of four specialists, each under the slot's exact provider/model; the lead dispatches them, and no model call dispatches another.
120
120
 
121
- | Specialty within every model team | Assigned axis | Assigned rule IDs |
121
+ | Specialist within every model team | Assigned axis | Assigned rule IDs |
122
122
  |---|---|---|
123
123
  | Structure | `structural` | `S1`–`S4`, plus routed `S5`–`S10` |
124
- | Naming | `semantic` | `M1` |
125
- | Readability | `semantic` | `M2`, `M3` |
124
+ | Semantic | `semantic` | `M1`–`M3` |
126
125
  | General defects | `general` | `G1`–`G5` |
127
- | State | `state-and-tests` | `T1` |
128
- | Tests | `state-and-tests` | `T2`–`T4` |
126
+ | State and tests | `state-and-tests` | `T1`–`T4` |
129
127
 
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`.
128
+ `code-review prepare` splits the census into these axes, one `<review-id>.<axis>.census.md` each, and refuses a split that changes the rule catalog or leaves a cell unowned or doubly owned. A specialist whose axis has no cells is not prepared; record that acknowledgment. Never divide specialists between models or borrow another team's verdicts. An inability to run a specialist under the exact provider/model binding is an execution blocker, not permission to substitute a model, merge specialists into one call or simulate specialists as headings.
131
129
 
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.
130
+ ### Authorization and recovery
133
131
 
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.
132
+ The authorized review includes up to `4 × reviewerCount` specialist calls and the continuations in [Step 3.5](#step-35--audit-the-coverage). Existing authorization remains valid for investigation, safe recovery, resumed work and reinspection within the approved scope, assigned models and user-set call/cost limits. A stopped invocation, new invocation ID or automatic-retry stop does not revoke that authorization. Request approval only before expanding the approved scope, changing assigned models or exceeding a user-set call/cost limit. Pass a user-set call limit to `start` as `--max-calls`; it refuses to start calls beyond it, automatic repairs included. No command checks a cost limit; the lead tracks it. An insufficient limit blocks the affected dispatch rather than silently reducing the team. Authorization accuracy remains a lead check.
135
133
 
136
134
  ### Shared test execution evidence
137
135
 
138
136
  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.
139
137
 
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.
138
+ Each State and 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.
141
139
 
142
140
  ### Inspection scope and briefing
143
141
 
144
- Resolve each slot's scope before materializing its prompt, using Step 2's shared snapshot:
145
-
146
- ```bash
147
- okstra code-review scope --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --review-policy <review-policy-path>
148
- ```
142
+ Write one shared brief to `<projectRoot>/.okstra/agent-invocations/code-review/<review-id>.brief.md`. It carries the diff and the frozen read command; a short project layout; shared test evidence and blockers; and the inspection requirements below. `prepare` appends each specialist's team, axis, census paths and its `code-review scope` output, and materialization delivers the canonical rules and cells, so do not copy them into the brief. A specialist's task grants no delegation. 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.
149
143
 
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.
144
+ 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 specialist's axis limits verdict ownership, not context access. Route suspected issues on another axis through the lead without changing cells. Every reviewer also reads the delivered frozen calibration and applicable rule sections completely, without clipping normative lines.
151
145
 
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.
146
+ Every applied project instruction belongs in the shared snapshot. Snapshot content, resource selection and catalog bindings are fingerprinted, and 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.
153
147
 
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.
148
+ With an unchanged comparison base and policy, pass the previous round's batch as `--previous-batch`: `prepare` offers each item only the completions of the same team ordinal, axis, provider and model, latest attempt first, and `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. Prior records remain immutable; an identical range, rules and completed adjudication need no new call.
155
149
 
156
150
  `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.
157
151
 
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.
159
-
160
152
  ### Authenticated invocations
161
153
 
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:
154
+ Prepare every specialist of every team in one call:
155
+
156
+ ```bash
157
+ okstra code-review prepare --project-root <projectRoot> --review-id <review-id> --census <census-path> --review-policy <review-policy-path> --base <baseCommit> --head <headCommit> --slots <slots-path> --brief <brief-path> --host-runtime <host-runtime> [--resource <pack-relative-id> ...] [--previous-batch <previous-batch-path>]
158
+ ```
159
+
160
+ Pass the same `--resource` values as the census. For each team and axis, `prepare` writes the instructions, materializes the prompt under the cli-wrapper runner with the frozen policy, assigned census and fixed range, and verifies it. It prints one `Item:` row per prompt and writes `<review-id>.batch.json`. Show the selected teams and items before dispatch. An identical rerun reuses every published file; a refusal names the items already prepared. Use a new `<review-id>` when an input must change.
161
+
162
+ Every specialist call and continuation keeps its own invocation ID (`<review-id>-t<team>-<axis>-a<attempt>`) and is authenticated by the commands of Step 3.5. The single-invocation commands (`agent-prompt materialize`, `verify`, the provider wrapper, `materialize-result`, `complete`, `verify-completion`, `code-review scope` and `check-coverage`) remain for diagnosis and manual recovery only.
163
+
164
+ ## Step 3.5 — Audit the coverage
165
+
166
+ Start every prepared specialist, then wait for them:
167
+
168
+ ```bash
169
+ okstra code-review start --project-root <projectRoot> --batch <batch-path> [--max-calls <user-set-call-limit>]
170
+ ```
163
171
 
164
172
  ```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> ...]
173
+ okstra code-review await --project-root <projectRoot> --batch <batch-path> --timeout-seconds 540
166
174
  ```
167
175
 
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:
176
+ `start` launches each item in its own session and returns; the wrapper keeps running after the call ends, and a supervisor records its exit even when it fails preflight. `await` stops after the timeout with `POLL_TIMEOUT` (exit 75); call it again until it prints `ALL_DONE` (exit 0 complete, 1 incomplete). Keep the timeout below the host's command time limit. Do not run the wrappers yourself while a batch is in progress.
177
+
178
+ For each finished item, `await` publishes the raw return from `.tmp/`, writes and verifies the completion, and audits it against its own axis census. Frozen standalone completions are bound to the source/index integrity audit; a mutation or invalid audit fails the item. It then audits each team and axis over all of that specialist's attempts, latest first, and each team over the full census. `Item:`, `Axis:` and `Team:` rows report states, missing and unknown cells. A row for another axis's cell is an unknown cell on that axis. Read each completed item's verified body with:
169
179
 
170
180
  ```bash
171
- ~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path> "" <role> --invocation-metadata <metadataPath>
181
+ okstra agent-prompt verify-completion --project-root <projectRoot> --purpose code-review --completion <completion-path> --json
172
182
  ```
173
183
 
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.
184
+ Only that command's `returnedBody` is usable. Audit current verified completions and gap-fills only; prior completions are scope inputs, never current verdicts. `code_review_coverage.py` verifies completions and refuses mixed model assignments; `review_verdicts.py` checks the supplied catalog, rule accounting and source anchors at the fixed commits. Neither proves exhaustive references or semantic truth.
175
185
 
176
- ## Step 3.5 — Audit the coverage
186
+ `await` repeats two cases once per team and axis without the lead: an invocation that exits non-zero without a returned body is retried, and an attempt whose rejected cells were all rejected for how their rows are written gets a format repair of those cells carrying the parser's reasons. Format reasons cover the table columns, duplicate rows or rule verdicts, an N/A alias, the finding ID form, a finding body missing outside the Coverage Verdicts section, and the wording of clean-check evidence; a missing row counts only when the response has no verdict at all. Rejections for unchecked or unknown rules and for evidence that names a missing file or line are not format reasons and wait for `gap-fill`. Do not repeat those yourself. A repeated failure stops blind retries; diagnosed recovery after correcting its cause follows the [same authorization](#authorization-and-recovery).
177
187
 
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:
188
+ For every other open cell, request the next attempt from the same logical specialist:
179
189
 
180
190
  ```bash
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> ...]
191
+ okstra code-review gap-fill --project-root <projectRoot> --batch <batch-path> [--reject <team>:<cell-id> ...]
182
192
  ```
183
193
 
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.
194
+ `gap-fill` sends only each latest attempt's missing or invalid cells, plus cells you reject, with their reasons and the previous attempt's verified body, under the same range, rules and full-context requirements; a failed or stalled attempt gets its whole assignment again. Then `start` and `await` the new items. It prints `NO_PROGRESS: <team>/<axis>` instead of a new attempt when the last gap-fill closed none of its cells; stop that pair. Each specialist's progress is judged separately; one specialist's stop does not stop another's permitted work. Do not reassign omissions or rerun completed investigations.
185
195
 
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.
196
+ Stop blind gap-fills when they make no progress, evidence is unavailable, authentication, billing, execution or integrity verification fails, or a response has unknown cell IDs. Preserve the response and diagnose the cause; do not relabel unknown IDs or repeat the same failing invocation without a concrete recovery. A reached user call/cost limit stops further calls covered by that limit.
187
197
 
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.
198
+ Continue investigation, safe recovery and re-verification within the [existing authorization](#authorization-and-recovery). Resume affected checks once evidence shows the blocker is resolved, retaining the fixed range, assigned model and frozen policy. Preserve prior results, baselines and audit records unchanged; do not weaken checks, rewrite evidence or accept a failed result to make recovery pass. Failure alone is not a reason to request renewed approval.
189
199
 
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.
200
+ While a blocker remains unresolved, continue other permitted work and record every unevaluated pair, owner and blocker in [Coverage](references/review-calibration.md#the-report). These checks have no defect kind, severity, timing or points; the review remains incomplete even at score zero. Manual assessment cannot replace verified reviewer coverage. The lead checks recovery evidence and authorization bounds; the parser checks accounting and source anchors.
191
201
 
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.
202
+ An isolated false observation reopens the affected cells and any dependent conclusions, not automatically every valid verdict. Reject those cells with `gap-fill --reject <team>:<cell-id>`; the next attempt's rows come first in every later audit, so the corrected row replaces the disproved one while the older attempt still covers unaffected cells. If the error's extent cannot be bounded, report the uncertainty and re-inspect the full affected assignment under the [existing authorization](#authorization-and-recovery). Never edit an immutable response to make it pass.
193
203
 
194
204
  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.
195
205
 
196
- ### Consolidate within each model, then across models
197
-
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.
206
+ ### Audit each team, then compare teams
199
207
 
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.
208
+ The `Team:` rows of the final `ALL_DONE` are each team's full-census audit over every current completion of that team, gap-fills included. Specialists own disjoint cells, so their union is the team's full-census coverage. Build each team's model report from its verified `returnedBody` values only: namespace finding IDs by team and specialist, retain every finding with its specialist provenance, and record conflicts rather than discarding them. Never convert missing rules to clean.
201
209
 
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.
210
+ Proceed to Step 3.6 only after each selected team passes full-census coverage or stops explicitly incomplete. Stopped teams contribute verified verdicts plus unevaluated checks; they cannot supply complete coverage.
203
211
 
204
212
  ## Step 3.6 — Check every citation
205
213
 
@@ -213,7 +221,7 @@ Apply the [source-citation forms](references/review-calibration.md#source-citati
213
221
 
214
222
  ## Step 3.7 — Settle the findings
215
223
 
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.
224
+ 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 perform targeted inspection under the [existing authorization](#authorization-and-recovery) rather than silently declaring it clean.
217
225
 
218
226
  ### Follow-up decisions
219
227
 
@@ -225,7 +233,7 @@ To reopen an unchanged verdict, name its prior decision and new evidence: a reac
225
233
 
226
234
  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.
227
235
 
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:
236
+ **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 specialists. Multiple specialists 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:
229
237
 
230
238
  - **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
239
  - **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.
@@ -6,11 +6,11 @@ Build one census for the fixed comparison range selected in [Step 1](../SKILL.md
6
6
 
7
7
  Use `prompts/coding-preflight/review-rules.json` under the runtime asset root as the catalog for `code-review census --rules`. The generator resolves pack references and emits `## Rules` with `Rule | Group | Reference` columns and `## Cells` with `Cell | Target | Group` columns. Project-specific references may supplement it; do not retype a parallel base catalog.
8
8
 
9
- A cell is one `target × axis`, not one target per rule or pack bullet. Its group contains all selected rule IDs; [compact coverage](review-calibration.md#compact-rule-coverage) accounts for those IDs within one row. Select `S5`–`S10` only for a routed architecture pack; the base catalog otherwise has 16 criteria. Preserve the generated `Review policy digest` and `Review resources` metadata in every coordinator or specialty subset; dividing an assignment does not select another shared policy.
9
+ A cell is one `target × axis`, not one target per rule or pack bullet. Its group contains all selected rule IDs; [compact coverage](review-calibration.md#compact-rule-coverage) accounts for those IDs within one row. Select `S5`–`S10` only for a routed architecture pack; the base catalog otherwise has 16 criteria. Preserve the generated `Review policy digest` and `Review resources` metadata in every specialist's assigned census; dividing an assignment does not select another shared policy.
10
10
 
11
11
  Keep absolute pack/section references under `## Rules`. Separate multiple references with semicolons, including observed-fact error guidance for G2 and the routed normative clauses for G5 rather than just a pack's first line. Reviewers read the selected frozen clauses delivered with their invocation; the absolute source references identify provenance.
12
12
 
13
- Each `## Cells` row has a stable `C-CR-...` ID, a repository-relative target and its group. Function targets include path, position and name; distinguish same-line anonymous functions by column. Absolute and parent-traversal target paths are invalid. Freeze the catalog, cells and ordering before the [team assignment](../SKILL.md#step-3--select-one-to-three-model-teams-with-six-specialists-each).
13
+ Each `## Cells` row has a stable `C-CR-...` ID, a repository-relative target and its group. Function targets include path, position and name; distinguish same-line anonymous functions by column. Absolute and parent-traversal target paths are invalid. Freeze the catalog, cells and ordering before the [team assignment](../SKILL.md#step-3--select-model-teams-and-prepare-every-specialist).
14
14
 
15
15
  Membership follows the mechanical tests below, never an expected violation or a judgment that a rule is irrelevant. Keep such cells and let the reviewer record reasoned `N/A` statuses. Read frozen whole-file source to locate boundaries; neither working files nor hunk headers are a complete function inventory.
16
16
 
@@ -51,11 +51,11 @@ Step 2 captures and selects the coding-preflight resources once. Allocate the se
51
51
  | routed `frameworks/*.md` | `general` |
52
52
  | routed `architectures/*.md` | `structural` |
53
53
 
54
- A pack not selected for the assignment is not handed to its reviewer; selected applicable clauses are read completely before verdicting. Source-writing procedures in `authoring-checks.md` remain author-only. Materialization delivers calibration with the selected policy, not coordinator execution instructions.
54
+ A pack not selected for the assignment is not handed to its reviewer; selected applicable clauses are read completely before verdicting. Source-writing procedures in `authoring-checks.md` remain author-only. Materialization delivers calibration with the selected policy, not orchestrator execution instructions.
55
55
 
56
56
  The catalog owns each criterion's source binding: S1–S4 cover DRY/KISS/SOLID/YAGNI, routed S5–S10 cover H1–H6, M1–M3 cover naming/readability/comments, T1–T4 cover state and test quality, and G1–G5 cover correctness/errors/security/performance/routed conventions. Keep `clean-code.md`'s DRY domain-literal and variant checks with `structural`, and the observation requirements in [compact coverage](review-calibration.md#compact-rule-coverage) with `general`.
57
57
 
58
- General inspection also applies the captured `clean-code.md` "Five simultaneous quality outcomes" through existing groups. G1 establishes caller-visible expectations and a reachable distinguishing state; G3 follows input through access, sinks, disclosure and downstream cost. G4 identifies workload, declared latency/throughput/resource limits and baseline, then compares applicable measurements or bound tests. A necessary missing limit or measurement stays unverified. These checks add no axes or duplicate reviewers; route evidence outside the specialty to its owner.
58
+ General inspection also applies the captured `clean-code.md` "Five simultaneous quality outcomes" through existing groups. G1 establishes caller-visible expectations and a reachable distinguishing state; G3 follows input through access, sinks, disclosure and downstream cost. G4 identifies workload, declared latency/throughput/resource limits and baseline, then compares applicable measurements or bound tests. A necessary missing limit or measurement stays unverified. These checks add no axes or duplicate reviewers; route evidence outside a specialist's axis to its owner.
59
59
 
60
60
  ## Unregistered language
61
61
 
@@ -88,5 +88,5 @@ evidence. Every invocation still receives its complete assigned census through t
88
88
  Before Step 3, summarize the fixed comparison range, cell counts per axis,
89
89
  included/excluded file counts and exclusion categories, applied packs, and the
90
90
  two completion criteria with their actual numbers. Link the complete census and
91
- pack list rather than reprinting their tables in chat. If the census is large,
92
- report its size and confirm dispatch without truncating the stored worklist.
91
+ pack list rather than reprinting their tables in chat. Report a large census's
92
+ size without truncation; dispatch follows the [existing authorization](../SKILL.md#authorization-and-recovery), not a size-only confirmation.
@@ -35,15 +35,15 @@ return the concrete plan conflict instead of downgrading a current violation.
35
35
  | Severity | Meaning | Points |
36
36
  |---|---|---|
37
37
  | `must-fix` | a defect, or a rule violation that will cost real work later — wrong behavior, a swallowed error, a duplicated decision, a self-mocked test that proves nothing | 3 |
38
- | `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 |
38
+ | `should-fix` | an explicit applicable project rule breach or evidenced design or maintenance impact without immediate breakage — a name that hides units callers need, business policy placed against the declared architecture | 2 |
39
39
  | `nit` | real but small; the fix is cheap and obviously better | 1 |
40
40
 
41
- Grade the established consequence, not your confidence. An unsupported candidate is not a finding; incomplete inspection remains a coverage gap.
41
+ Grade the established consequence, not your confidence or a preferred style. Function length, nesting depth, numeric literals and alternative names alone do not establish a finding. An unsupported candidate is not a finding; incomplete inspection remains a coverage gap.
42
42
 
43
43
  ## Separate execution errors from design violations
44
44
 
45
45
  - `execution-error`: establish a reachable input or state, the expected behavior, and the actual wrong result in `failure`, supported by opened code in `evidence`.
46
- - `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.
46
+ - `design-violation`: identify the applicable rule, quote the violating code, and establish an explicit applicable project requirement or concrete design or maintenance consequence in `impact`, supported by `evidence`. A runtime failure is not required.
47
47
 
48
48
  Both kinds carry a concrete fix. An axis does not determine the kind. 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.
49
49
 
@@ -68,9 +68,9 @@ Return one compact Coverage Verdicts row per cell under `## Coverage Verdicts`.
68
68
 
69
69
  Every row supplies one literal repository-relative source `path:line` for that cell's target file. The citation may be backtick-quoted and followed by a short observation, separated by a space or ` — `, before any ` :: ` rule observations. A bare citation remains valid. Do not use line ranges or substitute a rule-pack citation such as `cc:5`, a global alias such as `E01`, or another target's path. The checker verifies the declared source side and location; `base:` requires the frozen `--base`, and line 0 requires an empty regular file. These explicit forms override the head-line default above. Additional definitions and evidence remain in finding bodies. `review_verdicts.py` enforces the source grammar; `tests/verification/test_design_review.py` covers described anchors and invalid source rejection.
70
70
 
71
- For `general` cells, checked G2, G3 and G5 each carry a compact observation in that same Evidence field: `target/path:line :: G2=source/path:line observed outcome mapping; G3=source/path:line observed workload and bound; G5=source/path:line applicable clauses and observed conformance`. Each observation begins with an existing project-source citation; it may cite a relevant callee. Keep rule-pack references in the catalog or the observation text, not in the project-source citation slot. Separate assignments with semicolons; the same `RULE=` boundary applies, so a semicolon inside an observation stays part of it. Findings and reasoned N/A already explain their criteria and need no duplicate clean observation.
71
+ For `general` cells, checked G2, G3 and G5 each carry a compact observation in that same Evidence field: `target/path:line :: G2=source/path:line observed outcome mapping; G3=source/path:line observed input path through access checks, sinks, disclosure and work bounds; G5=source/path:line applicable clauses and observed conformance`. Each observation begins with an existing project-source citation; it may cite a relevant callee. Keep rule-pack references in the catalog or the observation text, not in the project-source citation slot. Separate assignments with semicolons; the same `RULE=` boundary applies, so a semicolon inside an observation stays part of it. Findings and reasoned N/A already explain their criteria and need no duplicate clean observation.
72
72
 
73
- Inspect before compressing results into rows. G2 observations trace possible dependency outcomes into returned tags, diagnostics and errors. G3 observations account for each input dimension, changed loops and downstream scans, parsing or allocation, with bounds before expensive work; a type-only callee change does not remove amplified caller work. G5 observations identify each applicable normative clause and observed conformance, independently of passing tests or linters. Trace shared predicates before calling similar orchestration duplicated policy.
73
+ Inspect before compressing results into rows. G2 observations trace possible dependency outcomes into returned tags, diagnostics and errors. G3 observations trace outside-process input through access checks, sinks and disclosure, and the bounds applied before expensive work (changed loops, downstream scans, parsing, allocation); a type-only callee change does not remove amplified caller work. G5 observations identify each applicable normative clause and observed conformance, independently of passing tests or linters. Trace shared predicates before calling similar orchestration duplicated policy.
74
74
 
75
75
  `checked`, `clean` and `no issues` alone are verdict labels, not observations. `review_verdicts.py::_checked_rule_evidence` rejects missing observations, notes for unchecked criteria and invalid source locations. It validates structure and source existence, not the observation's truth.
76
76
 
@@ -93,13 +93,9 @@ Every finding carries `timing`. For `now`, establish either an execution error o
93
93
  - **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.
94
94
  - **The change is mechanical for this rule.** A behavior-preserving signature-only or type-annotation-only edit does not reopen unrelated body-level rules. Leave pre-existing naming issues outside the review. A behavior change can make an unchanged name misleading; review that newly introduced mismatch against the applicable naming rule and anchor the finding on the changed behavior.
95
95
 
96
- **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`.
97
-
98
- The test does not empty the `nit` tier. A `nit` says the defect is small because that is the tier's definition, not because the reviewer is hedging — it still names a concrete defect on a changed line and a concrete fix.
99
-
100
96
  ## Every finding carries its fix
101
97
 
102
- - **Readability findings** carry a 4–6-line pseudocode sketch demonstrating the clearer flow, not a full refactor.
98
+ - **Readability findings** identify the concrete comprehension or maintenance problem and carry a short pseudocode sketch showing how the fix addresses it.
103
99
  - **Naming findings** carry a concrete alternative name, and one clause saying what the new name encodes that the old one did not.
104
100
  - **Structural findings** name the destination: which layer, module, or existing symbol the code should move to or call.
105
101
 
@@ -109,7 +105,7 @@ Loose typing in test files (`any`, dynamic casts, untyped fixtures) is a **typin
109
105
 
110
106
  ## The report
111
107
 
112
- After [consolidation](../SKILL.md#consolidate-within-each-model-then-across-models) and [adjudication](../SKILL.md#step-37--settle-the-findings), write `reviewPath` using Step 1's values and dispatched slots. Keep this frontmatter order, with `taskKey` and `stage` only in stage mode and `branch` only in branch mode. `baseCommit` and `headCommit` name the current comparison range, not a separate PR merge base.
108
+ After [the team audits](../SKILL.md#audit-each-team-then-compare-teams) and [adjudication](../SKILL.md#step-37--settle-the-findings), write `reviewPath` using Step 1's values and dispatched slots. Keep this frontmatter order, with `taskKey` and `stage` only in stage mode and `branch` only in branch mode. `baseCommit` and `headCommit` name the current comparison range, not a separate PR merge base.
113
109
 
114
110
  ```yaml
115
111
  mode: stage | branch
@@ -130,7 +126,7 @@ Use these level-two sections in order: `Coverage`, `Must-fix`, `Should-fix`, `Ni
130
126
  - **Parked** — `park` findings, with their severity, not scored.
131
127
  - **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.
132
128
 
133
- - **Coverage** — record the fixed range, PR merge-target branch/base, review kind, supporting impact paths and prior head/report where applicable; apply the ledger rules in [follow-up decisions](../SKILL.md#follow-up-decisions). List changed-file and per-axis cell counts, exclusions with reasons, applied/unavailable packs, selected team/specialty assignments, expected/covered cells and rule IDs per child, empty-specialty acknowledgments, each team's `(cell ID, rule ID)` union and coordinator audit. Preserve verified child-to-team-to-final provenance, settlement outcomes and gap-fill rounds. State complete or incomplete and list every unevaluated pair with team, specialty and blocker under [Step 3.5](../SKILL.md#step-35--audit-the-coverage); those checks have no kind, grade, timing or points. On follow-ups distinguish inspected/inherited cells, scope fallback/expansion reasons and new-finding origins. Never label inherited cells newly inspected or rule flags independent targets.
129
+ - **Coverage** — record the fixed range, PR merge-target branch/base, review kind, supporting impact paths and prior head/report where applicable; apply the ledger rules in [follow-up decisions](../SKILL.md#follow-up-decisions). List changed-file and per-axis cell counts, exclusions with reasons, applied/unavailable packs, selected team/specialist assignments, expected/covered cells and rule IDs per specialist, empty-specialist acknowledgments and each team's full-census audit. Preserve verified specialist-to-team-to-final provenance, settlement outcomes and gap-fill rounds. State complete or incomplete and list every unevaluated pair with team, specialist and blocker under [Step 3.5](../SKILL.md#step-35--audit-the-coverage); those checks have no kind, grade, timing or points. On follow-ups distinguish inspected/inherited cells, scope fallback/expansion reasons and new-finding origins. Never label inherited cells newly inspected or rule flags independent targets.
134
130
  - **Test evidence inside Coverage** — record each shared test command, tested head, environment, exit code and log path, identifying reused results and their matching inputs. Distinguish test-source inspection from actual execution. State failed, missing or blocked required checks; a completed code inspection does not imply the implementation passed its release gate. Do not claim an unexecuted test passed or count duplicate reviewer runs as independent evidence.
135
131
  - **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`, or `confirmed by orchestrator`. Any grade correction retains every reporting reviewer's severity/timing pair, the final pair, the applicable rubric and the source-cited impact or scope reason. A corrected grade may differ from every reported value; the original responses remain immutable.
136
132
  - **Score** — use `# | Location | Rule | Severity | Points` columns. Count each confirmed `now` finding once after citation and evidence checks, using the severity points above. End with a Total row, including Total 0 when there are no scored findings. Parked, rejected and unevaluated checks do not score; Total 0 does not make an incomplete review clean.
@@ -62,7 +62,7 @@ Submit the answer shape required by `interaction.answerProtocol`; do not add nor
62
62
 
63
63
  The final `confirm` step is a normal `pick` step with three options — `Proceed` / `Edit` / `Abort`(abort) — and is rendered the same way (no special handling). `Edit` rewinds to any earlier step (including `base-ref`); `Abort` terminally cancels the wizard. The branch/worktree decision the run will actually use (for `implementation`, the **stage worktree** — not the task-key directory) is folded into the Step 4 confirmation summary block as a `worktree` line, so there is no separate branch-confirm prompt.
64
64
 
65
- Never invent additional questions. **Never drop, hide, merge, reorder, or truncate** a `pick` / `pick_group` option — relay every `options[]` entry, including the flagged recommendation. Do not collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist. The wizard's arrays are the complete authoritative choice sets, regardless of the current host UI's usual option limit. The run-prompt recommendation rule (1–2 recommendations + Enter directly) shapes the **option set** only for prompts this skill authors itself, never for wizard-provided options — you may not add, drop, or reorder a wizard option to produce a shortlist. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
65
+ Never invent additional questions. Relay every `pick` / `pick_group` option the wizard sends, in order, including the flagged recommendation: the wizard's arrays are the complete choice set whatever the host UI's usual option limit, and the run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
66
66
 
67
67
  **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` steps), or that marks the free-input / abort escape as a recommendation.
68
68
  <!-- END FRAGMENT: wizard-relay-protocol -->
@@ -82,7 +82,7 @@ Run one shell-command tool call (Shell invocation rule from the top of this file
82
82
  okstra preflight --runtime <host-runtime>
83
83
  ```
84
84
 
85
- Read the fixed text lines. If the first line is `Okstra preflight: failed`, show `Runtime readiness` and every repeated `Readiness check`, `Readiness check status`, and `Readiness check action`, then stop before Step 2. Show `Reason` and `Recovery` for every failure. Do not relabel a host login, license, daemon, trust, or other readiness failure as missing Okstra setup. 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). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — `npx` is not on the literal-token allow-list and will force a confirmation prompt on every wizard call afterward. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
85
+ Read the fixed text lines. If the first line is `Okstra preflight: failed`, show `Runtime readiness` and every repeated `Readiness check`, `Readiness check status`, and `Readiness check action`, then stop before Step 2. Show `Reason` and `Recovery` for every failure. Do not relabel a host login, license, daemon, trust, or other readiness failure as missing Okstra setup. 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). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — every later wizard call still invokes the stale `okstra` on PATH, so an `npx` call does not recover the run. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
86
86
 
87
87
  On `Okstra preflight: ready`, require `Runtime readiness: ready` before Step 2. These checks come from the selected host adapter and are independent of worker-provider choices. Any other readiness value is unrecognized runtime output: show it and stop before Step 2 instead of guessing that the host is ready.
88
88
 
@@ -145,7 +145,7 @@ Use this built-in mapping only when the successful preflight response omitted `r
145
145
  For numbered interactions, render every option as a 1-based Markdown item containing its label followed by its description verbatim, in original order. For `sequential-group`, ask every question in order and build one compact JSON object keyed by `questions[].step`. Submit each user message unchanged; the wizard owns numbered and grouped normalization.
146
146
  <!-- END FRAGMENT: wizard-preflight -->
147
147
 
148
- The supported lead hosts are a `claude-code` lead, or any lead under cmux. `render-bundle` refuses any other lead before it writes a task artifact; show that refusal and stop instead of moving the user to another session.
148
+ The supported lead hosts are a `claude-code` lead, or any lead under cmux. With any other lead, stop before Step 2 and say so instead of moving the user to another session. **Not enforced:** `render-bundle` always passes `--render-only`, which skips prepare's lead-runtime check.
149
149
 
150
150
  ## Step 2: Initialize the wizard for a discussion
151
151
 
@@ -184,15 +184,13 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
184
184
  ```
185
185
  If the answer contains spaces or shell metacharacters, wrap it in double quotes around the literal string only — never inside `"$VAR"`.
186
186
 
187
- **MANDATORY: empty answers must pass `--answer ""` explicitly.** If the user's reply is the empty string, the call MUST still include the flag with an empty literal value:
187
+ Pass `--answer` even when the user's reply is empty:
188
188
  ```bash
189
189
  okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer ""
190
190
  ```
191
- Omitting `--answer` entirely is forbidden. The wizard does not read a missing `--answer` flag as "submit empty": without `--answer` or `--no-submit`, `wizard step` returns `ok: false` naming `--answer` and exits 2, and the step is not submitted. Submitting `--answer ""` is the only way to advance past an intentionally-blank step (e.g. "use phase default").
191
+ Without `--answer` or `--no-submit`, `wizard step` returns `ok: false` naming `--answer`, exits 2 and submits nothing, so `--answer ""` is the only way past an intentionally blank step (e.g. "use phase default"). If the literal answer contains `"`, escape each occurrence as `\"` inside the double-quoted argument.
192
192
 
193
- **Escaping rule**: if the literal answer contains `"`, escape each occurrence as `\"` inside the double-quoted argument. Empty values must still be `--answer ""` — the flag itself is mandatory, even when the value is empty.
194
-
195
- **Enforced:** `tests-js/wizard.test.mjs` pins `parseFlags` on the empty literal (`--answer=` parses to the empty string, a value beginning with `--` is kept) and on the `--no-submit` peek that is the only sanctioned way to see the current prompt without submitting; the Node wrapper (`src/commands/execute/wizard.mts`) is what forwards them to Python.
193
+ **Not enforced:** no test pins the empty-literal parsing or the `--no-submit` peek; the Node wrapper (`src/commands/execute/wizard.mts`) forwards both flags to Python.
196
194
  3. **Handle result**:
197
195
  - `ok: true` → echo `result.echo` to the user on one short line, then loop with `result.next`.
198
196
  - `ok: false` → show `result.error` to the user verbatim, then loop with `result.current` (re-prompt the same step). If `result.current` is `null`, do not loop — the current step cannot render (e.g. corrupt Stage Map); surface the error and stop so the user fixes the plan.
@@ -203,7 +201,7 @@ The discussion steps the wizard asks, in order: task selection (or task-group an
203
201
  <!-- BEGIN FRAGMENT: wizard-confirm-step -->
204
202
  ## Step 4: The confirm step's question text is the selection summary
205
203
 
206
- When `next.step == "confirm"`, the prompt's `label` already carries the full selection summary (`선택 확인:` followed by one line per resolved input — task-type, task-key, brief, base-ref, worktree, every role slot, directive, related-tasks, clarification, stage, …) and ends with the question. Render that `label` **verbatim, every line, as the question text** of the `confirm` picker (Proceed / Edit / Abort) — the same way you render any other pick step's label. Do not re-author it as a table, do not summarise it into prose, do not drop a line because its value is `(none)`: the user confirms what is on screen, and a line you left out is a setting they never saw (observed: a lead's own table omitted `directive`, `base-ref` and `brief`). Render the picker **as the final output of that turn** — emit nothing after the picker call.
204
+ When `next.step == "confirm"`, the prompt's `label` already carries the full selection summary (`선택 확인:` followed by one line per resolved input — task-type, task-key, brief, base-ref, worktree, every role slot, directive, related-tasks, clarification, stage, …) and ends with the question. Render that `label` **verbatim, every line, as the question text** of the `confirm` picker (Proceed / Edit / Abort) — the same way you render any other pick step's label. Do not re-author it as a table, do not summarise it into prose, do not drop a line because its value is `(none)`: the user confirms what is on screen, and a line you left out is a setting they never saw. Render the picker **as the final output of that turn** — emit nothing after the picker call.
207
205
 
208
206
  `okstra wizard confirmation --state-file <path>` returns the same block as `{ok: true, text: ...}` for a text-only host or when the user asks to see the summary again; it is not a substitute for the label.
209
207
 
@@ -219,51 +217,35 @@ When `next.kind == "done"`, fetch the public wizard outcome:
219
217
  okstra wizard outcome --state-file /var/folders/.../okstra-wizard.AbCd.json
220
218
  ```
221
219
 
222
- Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], renderArgs: {...}, orchestration: {chainStages: "..."}, persistActions: [...], confirmationText: "..."}}`.
223
-
224
- `renderArgv` is the canonical ordered `okstra render-bundle` argument list. Pass its tokens verbatim and in order. Repeated `--role-count` and `--role-model` flags are intentional. `renderArgs` is a compatibility and inspection view only; do not reconstruct an invocation from it. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
225
-
226
- `userAuthorization`, when present, preserves the confirmation prompt actually emitted by this wizard and the relayed `proceed` response. Its `--user-authorization-json` token carries that record into the run manifest; preserve it unchanged. Do not synthesize a receipt for older confirmed states. The record documents task scope; it does not grant host execution privileges.
220
+ Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], renderArgs: {...}, orchestration: {chainStages: "...", hostRulesPath: "..."}, persistActions: [...], confirmationText: "..."}}`.
227
221
 
228
- Before retrying a worker in an existing run, inspect its last invocation attempt: await running work; append an attempt only after `failed-no-mutation` within the retry budget. Preserve every other terminal attempt. `okstra team dispatch` routes the legacy declaration-only implementer failure to a separate same-model evidence-recovery invocation; collect its result before independent verification. Other terminal failures need `okstra agent-prompt materialize` with a new `--invocation-id`, distinct `--prompt`/`--result` paths, and unchanged assignment/model for a bounded correction. Do not restart completed implementation or request renewed approval for unchanged scope. Enforcement: `dispatch_core._next_attempt` and `execution_manifest._validate_next_attempt`.
222
+ Use the outcome to inspect the confirmed scope and `orchestration.chainStages`. `renderArgv` and `renderArgs` remain compatibility and inspection views; do not copy their tokens into a command. Bundle preparation reads the confirmed state file directly and preserves empty values and repeated role/model flags in code. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
229
223
 
230
- Run every `outcome.persistActions[]` entry BEFORE `render-bundle`. The only supported action is:
224
+ Before the first `render-bundle` invocation, read `outcome.orchestration.hostRulesPath` verbatim when it is non-empty. The wizard selects and checks this absolute runtime path; it contains the selected task's waiver, recovery, and chaining rules needed even when preparation fails. An empty string means this task declares no host rules. Use the emitted path rather than constructing one from the task type.
231
225
 
232
- ```json
233
- {"command":"config.set","key":"pr-template-path","scope":"project|global","value":"<path>"}
234
- ```
226
+ After successful preparation, use the frozen `instruction-set/host-orchestration-rules.md` identified by the rendered launch prompt for resumed work and stage chaining. Read that frozen copy within the run as the launch prompt requires: reading the canonical file before preparation does not satisfy the implementation session read gate. An already prepared legacy run without the new outcome field keeps its existing skill and prepared-instruction contract. If a fresh outcome omits `hostRulesPath` or its non-empty path cannot be read, stop and report a runtime/skill version mismatch; do not infer waiver or recovery rules.
235
227
 
236
- Execute the matching command for `scope`:
228
+ `userAuthorization`, when present, preserves the confirmation prompt actually emitted by this wizard and the relayed `proceed` response. Preparation carries that record into the run manifest unchanged. Do not synthesize a receipt for older confirmed states. The record documents task scope; it does not grant host execution privileges.
237
229
 
238
- ```bash
239
- okstra config set pr-template-path "<value>" --scope project
240
- okstra config set pr-template-path "<value>" --scope global
241
- ```
230
+ Before retrying a worker in an existing run, inspect its last invocation attempt: await running work; append an attempt only after `failed-no-mutation` within the retry budget. Preserve every other terminal attempt. `okstra team dispatch` routes the legacy declaration-only implementer failure to a separate same-model evidence-recovery invocation; collect its result before independent verification. Other terminal failures need `okstra agent-prompt materialize` with a new `--invocation-id`, distinct `--prompt`/`--result` paths, and unchanged assignment/model for a bounded correction. Do not restart completed implementation or request renewed approval for unchanged scope. Enforcement: `dispatch_core._next_attempt` and `execution_manifest._validate_next_attempt`.
242
231
 
243
- If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
232
+ `render-bundle --wizard-state-file` applies the confirmed PR-template save action before preparing the bundle. Do not execute `outcome.persistActions[]` separately. An unknown action, missing save authorization, or changed save scope stops preparation before settings are written. If an older confirmation did not record the save scope, reopen that confirmation rather than inventing a receipt. A settings write failure stops preparation; a later preparation failure reports that the successful settings write remains saved.
244
233
 
245
234
  Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — close the panes of the dispatches that finished in the prior round so they do not accumulate: `okstra team reclaim --project-root <projectRoot> --run-manifest <RUN_MANIFEST_PATH>` closes them, records `phase-batch-cleanup panes=<n>` with the number it closed, and prints that `PROGRESS:` line last — emit it as printed and do not call `okstra lead-progress append` for it. The command reads each dispatch's recorded status, so an in-progress worker keeps its pane whichever moment you call it. It closes only the panes okstra opened and recorded — a pane the harness opened for its own teammate carries no recorded id and is not okstra's to close. After collecting results and token usage, apply the selected adapter's `shutdown_workers` operation only to confirmed-complete workers; preserve in-flight workers and the lead. A `cli-wrapper` run holds no pane at all and `team reclaim` refuses it, so record the checkpoint there with `okstra lead-progress append … --phase phase-batch-cleanup --field panes=0`.
246
235
 
247
236
  Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run `okstra team reclaim … --gate` first: it closes the finished panes and prints `PROGRESS: phase-gate-cleanup panes=<n>` for you to emit, without recording a batch cleanup. Then apply the selected adapter's `shutdown_workers` operation to confirmed-complete workers after collecting their results and token usage; preserve in-flight workers and the lead. This keeps a user gate from being shown while finished worker panes remain; in-progress dispatches keep their panes. Then follow `prompts/lead/okstra-lead-contract.md` "User confirmation before an approval blocker": read cited plan items, worker findings, and files before asking, and ask in the user's language with each option's outcome.
248
237
 
249
- Build the `okstra render-bundle` invocation from `outcome.renderArgv`, passing every token verbatim and in order (including empty strings — they are intentional `use phase default` markers).
238
+ Prepare the bundle with the same literal absolute state-file path used by the wizard. Do not append scope inputs such as task type, role/model, directive, or lead runtime; the command rejects mixing those inputs with `--wizard-state-file`.
250
239
 
251
240
  Before invoking it, follow the active host relay's execution-permission guidance. For Codex, read "Permission before bundle preparation" in the relay already selected at preflight: bundle preparation can write protected Git metadata while creating a branch and worktree, even with `--render-only`. Apply this guidance to the first invocation and each subsequent phase or stage preparation.
252
241
 
253
- Analysis sidetracks therefore forward wizard-owned tokens such as `--analysis-target "<value>"` and `--evidence-inputs "<value>"` when they are present. These are examples of the verbatim token rule, not a separate hard-coded argument list.
254
-
255
- Step 3's empty-answer and escaping rules apply verbatim: every flag in `renderArgv` whose following value is the empty string MUST still be passed explicitly (e.g. `--related-tasks ""`, `--directive ""`) — the wizard's intent is always "flag present with empty value", even where prepare's default happens to be the same empty value.
256
-
257
- `renderArgv` already contains exactly one `--lead-runtime <host-runtime>` pair. Do not add or replace it. Do not enumerate a fixed provider list in this skill because the wizard and role model pool own the ordered tokens.
242
+ The only preparation additions are `--summary-only`, a stage in the confirmed implementation chain, and the existing separately user-confirmed `--tdd-bypass` / `--qa-waiver` exceptions under their host orchestration rules. Never infer an exception grant from the original wizard confirmation.
258
243
 
259
244
  ```bash
260
- okstra render-bundle --summary-only \
261
- <outcome.renderArgv token 1> \
262
- <outcome.renderArgv token 2> \
263
- <each remaining outcome.renderArgv token in order>
245
+ okstra render-bundle --wizard-state-file /var/folders/.../okstra-wizard.AbCd.json --summary-only
264
246
  ```
265
247
 
266
- `render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" below).
248
+ `render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, `okstra run manifest:`, and other preparation status. `--summary-only` omits the lead prompt body from stdout; Step 6 reads the verified saved prompt from the manifest path. Parse the labelled lines for `TASK_ROOT`, `INSTRUCTION_SET_PATH`, and `RUN_MANIFEST_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "Concurrent-run detection branch" in the selected host rules).
267
249
 
268
250
  Before acting as the lead, read `resources.leadPromptMetadataPath` from the run
269
251
  manifest and execute the host-native specification-link gate:
@@ -282,9 +264,11 @@ it does not claim that the host exposed or attested the delivered prompt bytes.
282
264
 
283
265
  The python function underneath allocates the run sequence number and writes `run-context-*.json` under the per-task lock (`~/.okstra/.locks/<task-key>.lock`), then writes `run-inputs-*.json` + all manifests + discovery files outside that lock, and registers the run in `~/.okstra/recent.jsonl` with status `prepared` under the central `~/.okstra/.lock` (a registration failure is reported on stderr and does not fail prepare).
284
266
 
285
- **Not enforced:** `tests-js/wizard.test.mjs` pins the argv the wizard produces (`orderedRenderArgv` preserves the Python role selection bytes and repeated role order), not the argv you pass. Prepare's parser defaults most flags to `""` (e.g. `--directive`), so a dropped empty value is indistinguishable from its default and nothing rejects it — passing every token verbatim is on you.
267
+ Enforcement: `wizard.launch.load_confirmed_launch` validates the confirmed snapshot and save receipt; `render-bundle.prepareRenderBundle` preserves ordered inputs and rejects scope overrides before writes. `tests/wizard/test_launch.py` and `tests-js/render-bundle.test.mjs` cover these contracts. Host execution permission remains a separate host decision.
268
+
269
+ After successful preparation of a single run, delete the literal state-file path. For an implementation chain with multiple stages, keep it until preparation of the last confirmed stage succeeds. Do not delete it after a failed preparation. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` keeps an interactive `rm` alias from blocking cleanup. The preparation code never deletes this file.
286
270
 
287
- You can delete the literal state-file path after this point — its job is done. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` is what keeps a `rm='rm -i'` alias from turning this into a confirmation prompt nobody is there to answer.
271
+ If the file disappears before a remaining stage is prepared, stop that chain and report the completed and remaining stages. Reopen the wizard for the remaining scope; do not rebuild its inputs or approval receipt from a previous run. Already prepared runs resume from their run manifest without this file. After an interrupted or uncertain preparation, inspect the task's existing runs before retrying: this command does not promise exactly-once preparation.
288
272
  <!-- END FRAGMENT: wizard-render-bundle -->
289
273
 
290
274
  <!-- BEGIN FRAGMENT: wizard-lead-takeover -->