okstra 0.231.1 → 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 (265) hide show
  1. package/README.md +19 -271
  2. package/dist/cli-registry.mjs +14 -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/memory/memory.mjs +9 -55
  10. package/dist/commands/memory/memory.mjs.map +1 -1
  11. package/dist/commands/trace/capacity.d.mts +12 -0
  12. package/dist/commands/trace/capacity.mjs +21 -0
  13. package/dist/commands/trace/capacity.mjs.map +1 -0
  14. package/dist/commands/trace/model.d.mts +89 -0
  15. package/dist/commands/trace/model.mjs +251 -0
  16. package/dist/commands/trace/model.mjs.map +1 -0
  17. package/dist/commands/trace/progression.d.mts +11 -0
  18. package/dist/commands/trace/progression.mjs +194 -0
  19. package/dist/commands/trace/progression.mjs.map +1 -0
  20. package/dist/commands/trace/review.d.mts +7 -0
  21. package/dist/commands/trace/review.mjs +51 -0
  22. package/dist/commands/trace/review.mjs.map +1 -0
  23. package/dist/commands/trace/task-link.d.mts +18 -0
  24. package/dist/commands/trace/task-link.mjs +72 -0
  25. package/dist/commands/trace/task-link.mjs.map +1 -0
  26. package/dist/commands/trace/trace.d.mts +1 -0
  27. package/dist/commands/trace/trace.mjs +293 -0
  28. package/dist/commands/trace/trace.mjs.map +1 -0
  29. package/dist/lib/bounded-file.d.mts +1 -0
  30. package/dist/lib/bounded-file.mjs +36 -0
  31. package/dist/lib/bounded-file.mjs.map +1 -0
  32. package/dist/lib/config-store.d.mts +34 -0
  33. package/dist/lib/config-store.mjs +70 -0
  34. package/dist/lib/config-store.mjs.map +1 -0
  35. package/dist/lib/file-lock.mjs +4 -5
  36. package/dist/lib/file-lock.mjs.map +1 -1
  37. package/dist/lib/input-limit.d.mts +4 -0
  38. package/dist/lib/input-limit.mjs +8 -0
  39. package/dist/lib/input-limit.mjs.map +1 -0
  40. package/dist/lib/memory-auto-register.d.mts +1 -0
  41. package/dist/lib/memory-auto-register.mjs +98 -0
  42. package/dist/lib/memory-auto-register.mjs.map +1 -0
  43. package/dist/lib/memory-entry-contract.d.mts +12 -0
  44. package/dist/lib/memory-entry-contract.mjs +46 -0
  45. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  46. package/dist/lib/python-helper.d.mts +1 -1
  47. package/dist/lib/python-helper.mjs +3 -2
  48. package/dist/lib/python-helper.mjs.map +1 -1
  49. package/dist/lib/record-secrets.d.mts +1 -0
  50. package/dist/lib/record-secrets.mjs +28 -0
  51. package/dist/lib/record-secrets.mjs.map +1 -0
  52. package/dist/lib/report-language-tag.d.mts +1 -0
  53. package/dist/lib/report-language-tag.mjs +4 -0
  54. package/dist/lib/report-language-tag.mjs.map +1 -0
  55. package/dist/lib/report-language.d.mts +1 -0
  56. package/dist/lib/report-language.mjs +50 -0
  57. package/dist/lib/report-language.mjs.map +1 -0
  58. package/dist/lib/skill-catalog.mjs +3 -0
  59. package/dist/lib/skill-catalog.mjs.map +1 -1
  60. package/dist/lib/types.d.mts +2 -1
  61. package/docs/architecture/storage-model.md +163 -5
  62. package/docs/architecture.md +17 -4
  63. package/docs/cli.md +511 -0
  64. package/docs/contributor-change-matrix.md +1 -2
  65. package/docs/project-structure-overview.md +33 -42
  66. package/package.json +1 -1
  67. package/runtime/BUILD.json +2 -2
  68. package/runtime/agents/common.json +8 -8
  69. package/runtime/agents/operations/trace-interface-review.json +6 -0
  70. package/runtime/agents/operations/trace-scope-review.json +6 -0
  71. package/runtime/agents/roles/verifier.json +2 -4
  72. package/runtime/bin/okstra-provider-exec.py +10 -4
  73. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  74. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  75. package/runtime/prompts/coding-preflight/clean-code.md +88 -286
  76. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  77. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  78. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  79. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  80. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  81. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  82. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  83. package/runtime/prompts/coding-preflight/overview.md +25 -38
  84. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  85. package/runtime/prompts/duties/code-reviewer.json +15 -18
  86. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  87. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  88. package/runtime/prompts/host-orchestration/README.md +18 -9
  89. package/runtime/prompts/launch.template.md +3 -2
  90. package/runtime/prompts/lead/context-loader.md +2 -0
  91. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  92. package/runtime/prompts/lead/report-writer.md +6 -6
  93. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  94. package/runtime/prompts/profiles/_common-contract.md +1 -1
  95. package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
  96. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
  97. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  98. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
  99. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  100. package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
  101. package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
  102. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  103. package/runtime/python/okstra_ctl/code_review_census.py +162 -7
  104. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  105. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  106. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  107. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  108. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  109. package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
  110. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  111. package/runtime/python/okstra_ctl/code_review_target.py +212 -13
  112. package/runtime/python/okstra_ctl/consumers.py +12 -9
  113. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  114. package/runtime/python/okstra_ctl/design_review.py +207 -0
  115. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  116. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  117. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  118. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  119. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  120. package/runtime/python/okstra_ctl/doctor.py +8 -25
  121. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  122. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  123. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  124. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  125. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  126. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  127. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  128. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  129. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  130. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  131. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  132. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  133. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
  134. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  135. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  136. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  137. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  138. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  139. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  140. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  141. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  142. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  143. package/runtime/python/okstra_ctl/json_boundary.py +51 -5
  144. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  145. package/runtime/python/okstra_ctl/manager_cli.py +148 -1
  146. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  147. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  148. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  149. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  150. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  151. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  152. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  153. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  154. package/runtime/python/okstra_ctl/manager_sync.py +45 -25
  155. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  156. package/runtime/python/okstra_ctl/material.py +2 -0
  157. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  158. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  159. package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
  160. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  161. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  162. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  163. package/runtime/python/okstra_ctl/paths.py +6 -1
  164. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  165. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  166. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  167. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  168. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
  169. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
  170. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  171. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  172. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  173. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  174. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  175. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  176. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
  177. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  178. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  179. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
  180. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  181. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  182. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  183. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  184. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  185. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  186. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  187. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  188. package/runtime/python/okstra_ctl/render.py +28 -2
  189. package/runtime/python/okstra_ctl/report_assembly.py +53 -11
  190. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  191. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  192. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  193. package/runtime/python/okstra_ctl/report_language.py +4 -1
  194. package/runtime/python/okstra_ctl/report_narrative.py +182 -7
  195. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  196. package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
  197. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  198. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  199. package/runtime/python/okstra_ctl/run.py +67 -36
  200. package/runtime/python/okstra_ctl/run_context.py +10 -1
  201. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  202. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  203. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  204. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  205. package/runtime/python/okstra_ctl/task_query.py +239 -0
  206. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  207. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  208. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  209. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  210. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  211. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  212. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  213. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  214. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  215. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  216. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  217. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  218. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  219. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  220. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  221. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  222. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  223. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  224. package/runtime/python/okstra_project/__init__.py +2 -0
  225. package/runtime/python/okstra_project/dirs.py +18 -0
  226. package/runtime/python/okstra_project/state.py +45 -20
  227. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  228. package/runtime/python/okstra_token_usage/cli.py +23 -10
  229. package/runtime/python/okstra_token_usage/collect.py +25 -22
  230. package/runtime/python/okstra_token_usage/policy.py +193 -0
  231. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  232. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  233. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  234. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  235. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  236. package/runtime/schemas/record-secret-patterns.json +41 -0
  237. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  238. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  239. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  240. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  241. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  242. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  243. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  244. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  245. package/runtime/skills/okstra-code-review/SKILL.md +92 -136
  246. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  247. package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
  248. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  249. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  250. package/runtime/skills/okstra-manager/SKILL.md +31 -0
  251. package/runtime/skills/okstra-memory/SKILL.md +8 -1
  252. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  253. package/runtime/skills/okstra-run/SKILL.md +55 -183
  254. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  255. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  256. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  257. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  258. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  259. package/runtime/templates/implementation-worker-preamble.md +4 -9
  260. package/runtime/templates/manager/view.template.html +4 -0
  261. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  262. package/runtime/templates/trace/trace.template.md +42 -0
  263. package/runtime/templates/worker-prompt-preamble.md +4 -12
  264. package/runtime/validators/checks/fixtures-02.py +25 -33
  265. package/runtime/validators/validate-run.py +107 -38
@@ -204,22 +204,49 @@ The final report keeps both — executor's `Validation evidence` AND each verifi
204
204
 
205
205
  ### Static design & test-quality review (gate — runs after the command re-run, before the verdict)
206
206
 
207
+ When the dispatch supplies Frozen Design Review, its census is the assigned worklist.
208
+ Return the binding lines, grouped Coverage Verdicts and Design Findings format it
209
+ specifies. Do not substitute file-level summaries or the executor's self-check for
210
+ function-level M1/M2/M3 judgments. Missing accounting remains incomplete.
211
+
212
+ When Verification inputs contains a Frozen Review Policy, apply its captured
213
+ rule sources, architecture declaration and `review-rules.json` metadata instead
214
+ of current project settings and installed rules. Read them through the
215
+ verification-input projection. Original paths identify provenance, not a live
216
+ baseline. Select applicable resources with the router below. Legacy inputs
217
+ without this policy continue to use the lookup below.
218
+ For the captured policy, repeat `--source-path <repository-relative-path>` for
219
+ the relevant changed files in one `okstra model-io verification-input
220
+ --run-manifest <run-manifest>` call. Read complete selected rule bodies, not only
221
+ the available-resource index, and do not clip normative lines.
222
+
223
+ Apply the captured `clean-code.md` "Five simultaneous quality outcomes" to the
224
+ actual diff: correctness, coding principles, performance, safety and security
225
+ retain their applicable acceptance conditions. Reuse declared bounds and shared
226
+ execution evidence. A necessary missing bound or check remains unverified;
227
+ neither a green command nor complete grouped rows establish all five outcomes.
228
+
229
+ Resolve conflicts by `overview.md` policy precedence: explicit repository
230
+ instructions and declared architecture, the common pack, then surrounding code
231
+ conventions. Cite the governing instruction for an exception; an existing code
232
+ pattern alone does not waive an explicit architecture rule.
233
+
207
234
  Re-running commands proves the diff *builds and passes*; it does NOT prove the diff is *well-designed*. Lint/test green is necessary but not sufficient — self-mocked tests, interaction-only assertions, and untruthful names all survive a green pipeline. This gate is the filter for exactly those defects, so the executor's design errors are caught here instead of in post-merge PR review. It is a real gate, not a checklist: it enumerates the full diff and a blocking hit forces `FAIL`. This blocking-check taxonomy is the **gate counterpart** of the executor's `Pre-commit diff review sweep` (`_implementation-diff-review.md`) prevention pass — the same defect families, different action (executor fixes in place; verifier fails the verdict). Both lists are inlined on purpose: each sidecar is delivered stand-alone into a flat CLI prompt (lazy-read, not INCLUDE-expanded), so neither can factor the taxonomy into a shared fragment.
208
235
 
209
- - **Scope (no silent sampling).** Enumerate every changed source/test file via `git diff --name-only <base>...HEAD` and review each one. Skipping a changed file silently is a `contract-violated` outcome. If a file's language has no reference and is not covered by the agnostic checks below, record `design-review skipped: <file> (language=<x> no reference)` — never pass it silently.
210
- - **Load the same conventions the executor used via the routed pack.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Read `overview.md` first, then `clean-code.md`, then apply the router's three ordered stages: language, framework, architecture. In each stage, iterate every rule, treat a rule as matched when any listed condition is true, and accumulate every matching resource — including `frameworks/node-server.md` for server-side Node work and `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex layouts. Degrade to the agnostic checks below when the resolved pack is unreadable, and record either `coding-conventions: resources=<...>` or `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`. The verifier does NOT inline language rules — it loads the same situation-specific resources as the executor preflight.
211
- - **Load the project's review rule packs.** Run the project-context projection above and union its `Project Review Rule Packs` entries with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. Read only those files and the `references/*.md` files they directly name. Do not search parent directories or host skill catalogs. Apply the rules as an overlay on this static review, but do NOT dispatch extra reviewer agents unless the task explicitly configured them. Record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited` in the worker result — an unreadable declared pack is a recorded gap, not a skip.
212
- - **Declared architecture style promotes the placement overlay from advisory to binding.** Take `Architecture style` from that projection and record `architecture-style: <hexagonal|layered|none>` in the worker result next to the `coding-conventions:` line. A declared `hexagonal` counts the overlay as loaded even when none of the router's Stage 3 layout signals matched, so the **Hexagonal** blocking check below applies in full, and the concrete-adapter injection listed under Advisory findings is promoted to a blocking finding → verdict `FAIL`, not a `should-fix`. A declared `layered` has no pack resource; its binding invariant is direction — an upper layer may import a lower one, never the reverse — so a changed file whose import list reaches back up a layer, or around a layer boundary, is a blocking placement violation cited `path:line` from that import list. The `layered` half is worker judgement: no machine check reads layer names, so a missed reverse dependency is a missed finding, not a validator failure. A `none` or absent projected style leaves Stage 3 detection-driven and the placement items advisory. **Enforced:** `scripts/okstra_project/resolver.py` `resolve_architecture` reads the same stored field for the planning-side rule in `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_variation_point_analysis`, and `_validate_verifier_fail_blocks_verdict` keeps the resulting `FAIL` from being dropped during synthesis.
236
+ - **Scope (no silent sampling).** Enumerate every changed file via `git diff --name-only <base>...HEAD`, apply the shared census exclusion policy and review every retained file, including executable configuration. Record each exclusion and its reason; extension alone does not establish one. Skipping a retained changed file silently is a `contract-violated` outcome. If a file's language has no reference and is not covered by the agnostic checks below, record `design-review skipped: <file> (language=<x> no reference)` — never pass it silently.
237
+ - **Load the executor's selected frozen conventions.** Use the captured projection above when available and record `coding-conventions: resources=<...>`. Only legacy inputs without that policy use the `**Coding preflight pack:**` installed path and its router, including every matching language/framework/architecture resource. A missing required captured source is blocked input; never replace it with live content. For unreadable legacy resources only, retain the agnostic checks and record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`.
238
+ - **Load the project's review rule packs.** Union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, use their captured bodies and directly named captured `references/*.md` bodies from the verification-input projection. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or read live originals. Only unfrozen legacy inputs run project-context for `Project Review Rule Packs` and read those declared files and their directly named references. Do not search parent directories or host skill catalogs. Apply the rules as an overlay on this static review, but do NOT dispatch extra reviewer agents unless the task explicitly configured them. Record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited` in the worker result — an unreadable declared pack is a recorded gap, not a skip.
239
+ - **Declared architecture style selects the placement overlay.** Take `Architecture style` from the captured projection, or the legacy project-context projection, and record `architecture-style: <hexagonal|layered|none|undeclared>` beside `coding-conventions:`. A declared `hexagonal` selects H1–H6 even without layout signals and makes H5's otherwise-advisory concrete-adapter item binding. A declared `layered` selects no pack resource; its invariant is upper-to-lower dependency direction and variation points on layer boundaries. Cite changed reverse dependencies from their imports. Explicit `none` selects no overlay; only absent or `undeclared` style uses layout detection. An inferred hexagonal overlay retains each rule's criteria and severity, including H5's undeclared-style advisory exception. Apply policy precedence and shared grading; an established current blocking finding requires `FAIL`. `review_policy.py` selects the declared overlay and `_validate_verifier_fail_blocks_verdict` prevents a recorded `FAIL` from being dropped during synthesis; neither proves boundary interpretation.
213
240
  - **Blocking checks (any hit → verdict `FAIL`, cited `path:line` + rule name, recommended fix recorded — the verifier does NOT apply it):**
214
241
  - **Security (every changed file that reads input from outside the process or acts on its behalf — `clean-code.md` "Untrusted input and security"):** work that grows faster than the input — pairwise uniqueness, nested scans, a backtracking regex, input-driven recursion — reachable before a size/count bound has rejected oversized input (read the validation framework's configuration: class-validator without `stopAtFirstError` still runs `@ArrayUnique` after `@ArrayMaxSize` fails, and a byte-size body limit does not bound element count); input concatenated into SQL, a shell command, a file path, a server-side fetch target, a template or a regex; a new route / handler / resolver without the project's auth guard, or a lookup by an input-chosen id that never compares the caller with the owner; a secret, full token, password or personal data written to source, logs, an error message or a response; `eval`, dynamic code, or unsafe deserialization applied to input. Cite the input that triggers it and its effect — for unbounded work, the input size and the measured or derived cost.
215
242
  - **New duplication / DRY:** two or more newly added or meaningfully modified blocks implement the same helper stack, transform, or domain rule. Literal copy-paste is always blocking; semantically equivalent transforms across services are blocking unless the approved plan explicitly justified keeping them separate. The comparison is not limited to this diff: a newly added block that is byte-identical to a block already in the repository — base code, or a copy an earlier stage landed — is the same blocking finding, cited at both the new `path:line` and the existing one, because `final-verification` grades that cross-stage copy as an Acceptance Blocker and a per-stage `clean` only defers it. Test helpers and test support code count. Recommend the shared module location.
216
243
  - **Self-mocking:** a test for `Foo` stubs/spies a method on the `Foo` instance under test (`jest.spyOn(sut, ...)`, `spyOn(FooService.prototype, ...)` in `foo.*.spec.*`, `vi.mocked(sut)` + stub). Mocking injected collaborators is fine.
217
244
  - **Interaction-only assertion:** a test whose only/primary assertion is `toHaveBeenCalled*` / `toHaveBeenCalledTimes` on an internal helper or a non-side-effecting collaborator, with no assertion on the returned value / resulting state / persisted row / emitted event.
218
245
  - **Tautological delegation assertion:** a test asserts the SUT result equals a direct call to the same pure helper/collaborator that the SUT delegates to, instead of asserting an independent literal value or observable state.
219
- - **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that writes/inserts/mutates; an adapter or repository name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*` / `findActive*`).
220
- - **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. The failure modes the plan lists are the floor of this trace, not its ceiling: a verdict scoped to "the modeled failures" is not a verdict on the file. For every `try` whose `catch` / `finally` cleans up, check at each call inside it that can throw (a property write, a read, a call that starts other work) whether the thing to clean up is already registered at that point; when the diff moves or restructures existing code, compare that order with the base version and cite the base `path:line` when it changed. A failure the test fakes cannot produce (a throwing setter or read the fake does not model) is recorded as unverified with the failure named, never folded into `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every file you excluded with its reason (lockfiles, generated code, pure config), and close the section with `general: <N> files — all verdicted, <M> excluded`.
221
- - **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that decides a business outcome inline — an `if`/`else` chain over domain fields, a business formula in arithmetic, a private method named for a domain concept — instead of calling a domain function (`architectures/hexagonal.md` Rule H6). Orchestration control flow, DTO mapping, and calling a domain predicate are not violations. Blocking when the embedded rule is substantial: money, permissions, a state machine.
222
- - **Hexagonal (only when the overlay is loaded):** business logic inside a port body; an adapter method that is not pure I/O (post-fetch JS filtering on domain state, domain-rule evaluation); a domain object declared outside the `domain/` boundary; a changed file under the domain folder importing an ORM / DB layer, a framework or its DI decorators, or anything under adapters / infrastructure / services (read the import list — this verdict is mechanical, not a judgment). **The routed pack's project-convention latitude does not reach this cell.** `architectures/hexagonal.md` lets a documented convention resolve conflicts in the project's favour elsewhere in that overlay; here the import list decides, and "matches existing convention" is not an answer to it (see that file's §"How far a project convention reaches"). A run that resolved exactly this finding as project convention returned `clean` and the team's PR review flagged the same import.
246
+ - **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that performs caller-visible mutations its name does not disclose, or an undefined or misleading business term. Inspect the port contract and governing policy before judging a domain-oriented query name; `findValid*` / `findActive*` and complex SQL alone do not establish a violation.
247
+ - **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. The failure modes the plan lists are the floor of this trace, not its ceiling: a verdict scoped to "the modeled failures" is not a verdict on the file. For every `try` whose `catch` / `finally` cleans up, check at each call inside it that can throw (a property write, a read, a call that starts other work) whether the thing to clean up is already registered at that point; when the diff moves or restructures existing code, compare that order with the base version and cite the base `path:line` when it changed. A failure the test fakes cannot produce (a throwing setter or read the fake does not model) is recorded as unverified with the failure named, never folded into `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every excluded file and its reason under the shared census exclusion policy, and close the section with `general: <N> files — all verdicted, <M> excluded`. Configuration that controls executable behavior is reviewed under that policy rather than excluded by extension alone.
248
+ - **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that implements a business decision instead of orchestrating a domain-owned one (`architectures/hexagonal.md` Rule H6). Inspect the implementation and governing rule; a private method's domain-oriented name alone is not evidence. Orchestration control flow, DTO mapping and calling a domain predicate are not violations. Apply shared grading when declaration or layout selects the overlay; a substantial embedded rule such as money, permissions or a state machine remains blocking.
249
+ - **Hexagonal (only when the overlay is loaded):** executable business decisions inside a port body; business policy invented or changed in an adapter rather than owned by the domain; misplaced domain objects or outward domain dependencies contrary to the applicable architecture. An adapter may translate domain-owned query specifications into efficient SQL, including compound predicates and joins. Complex SQL, a domain-oriented query name or post-fetch processing alone is not a violation; do not require `findAll` plus in-memory filtering. Inspect the governing policy, port contract and imports, and apply `overview.md` precedence and H1–H6 whether declaration or layout selected the overlay. Existing code conventions alone cannot waive an applicable boundary. Grade established current violations with the shared rubric; H5 alone retains its undeclared-style advisory exception.
223
250
  - **gitignored file committed to the branch:** any path in the `git diff --name-only <base>...HEAD` enumeration that `.gitignore` excludes — enumerate them by piping that list through `git check-ignore --stdin --no-index`. A committed ignored file means the executor bulk-added (`git add .`/`-A`) or force-staged (`git add -f`) it, leaking build output, scratch files, or verification artifacts into the eventual PR. This explicitly includes `.okstra/` paths (and `.project-docs/` when the legacy symlink is present): `.okstra/**` is gitignored, so a committed okstra file (qa scripts, conformance results) is always this defect. Cite each path; recommend `git rm --cached <path>` to untrack it while keeping the file on disk. Conformance/qa evidence belongs in the carry sidecar / verifier result, never in git history.
224
251
  - **Real-IO test in source tree:** a changed/added test under the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*` — that opens a **real** DB connection / DSN, makes a real `fetch` / `axios` / `http` request, or otherwise hits real external IO without mocking the injected collaborator (a live handle, not a stub/spy). Real-IO tests MUST live under `<task_root>/qa/scripts/` per the executor's *Real-IO test isolation* rule — a live-IO test in source silently breaks the project's CI suite and violates the artifact-home rule. Cite the test file + the real-IO line; recommend moving it to `<task_root>/qa/scripts/` (or declaring it as a Tier 3 conformance script). Mock-only unit tests in source are NOT a hit.
225
252
  - **Proxy-based identity decision:** a move / ownership / re-parenting decision taken from a status field or flag while the source and destination identifiers were available and never compared. Cite the condition and the identifiers it should have compared, and show the opposite case the condition also reads true for.
@@ -231,10 +258,11 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
231
258
  - **Positional mock-argument access:** `mock.calls[<n>][<m>]` (or the framework equivalent) used to inspect arguments instead of an intent-revealing `toHaveBeenCalledWith` / explicit-absence assertion. Detect with `rg 'mock\.calls'` over the changed test files.
232
259
  - **Non-separating test data:** two scenarios whose setup values and assertions are identical, so a wrong implementation passes both; or new test tooling added in this diff (mock, state setter, repository branch) that no test calls.
233
260
  - **Effect claimed under its own mock:** a test presented as covering an effect whose producing path is replaced by a mock inside that same test. The mock's presence in the harness is not evidence the branch behind it works.
234
- - **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape. Do NOT raise this on a function extracted purely to bring a body under the 50-line cap — that is principle 5 doing its job — nor on a pre-existing abstraction this diff merely edits.
261
+ - **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape. This targets reusable layers, not a local helper that names a cohesive step or separates mixed abstraction levels, nor a pre-existing abstraction this diff merely edits. Line count alone does not justify extraction.
235
262
  - **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:501 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 500 lines, or a file the diff took from 500 or fewer past 500. A file already over 500 at the stage base that the diff grows is not blocking; the command prints it as an advisory line. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target: a new file over 300, a file the diff took past 300, or a file already over 300 the diff grew, including one already over 500) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
236
263
  - **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
237
- - **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within 500), function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, weak-but-not-misleading names, priority-between-inputs policy inlined in a service condition instead of a named domain function, an error message asserting a cause the code never observed, a memory / concurrency / batching change with no test pinning the bound it claims, or (hexagonal overlay only) a service dependency this diff adds or modifies that injects a concrete adapter instead of a port — record it with the port sketch; advisory only while the project has not declared `architecture.style = hexagonal`, since that declaration — and only that one — promotes exactly this item to blocking per the declared-style bullet above, while a declared `layered` binds dependency direction instead and leaves this item advisory; an existing convention of concrete injections does not convert this one to `clean`, it is the debt the rule pays down. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
264
+ - **Shared grading:** use the captured catalog and `clean-code.md` "Finding evidence and grading". A clear M1/M2 violation (misleading name, mixed responsibility, excessive complexity or mixed abstraction levels) can be `should-fix` / `now` and forces `FAIL` even when commands pass. More than 50 effective function lines prompts inspection; it does not establish a violation or force a split. Name the rule, source and design consequence; a preferred alternative alone is not a finding. Apply the same evidence test to state policy, unobserved error causes and missing resource-bound tests rather than automatically downgrading them. Restrictive plan placement returns a plan conflict, never permission to pass a current violation.
265
+ - **Nonblocking findings:** `nit`, justified `park`, and size-only target advisories may accompany `PASS`. An already oversized file's size advisory does not exempt its added responsibilities from S3/M2. Architecture-specific latitude follows the declared style and the applicable project rule; record its cited basis. Do not demand unrelated legacy cleanup.
238
266
  - **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. Each item, advisory items included, carries an item id as `prompts/profiles/_common-contract.md` "Cross-worker traceability" defines it for worker output. The lead cites a finding by that id, and `okstra convergence seed` refuses a cited id that does not occur in the result, so an unnumbered item cannot enter convergence and drops out of the report. This is a guideline: nothing parses a verifier result for missing ids. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
239
267
 
240
268
  ### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
@@ -26,6 +26,19 @@
26
26
  {% for row in implementation.verifierResults %}<article class="summary-card tone-{{ row.verdict | lower }}"><p class="eyebrow">{{ row.verifier | inline_code }} · <span class="status status-{{ row.verdict | lower }}">{{ row.verdict }}</span></p>{% for label, text in ((t('tasks.implementation.independent-rerun'), row.get("independentValidationRerun")), (t('tasks.implementation.command-log'), row.get("readOnlyCommandLog"))) if text %}<details><summary><strong>{{ label }}</strong> {{ t('tasks.implementation.entry-count') | replace('{count}', text.strip().splitlines() | select | list | length | string) }}</summary><pre>{{ text }}</pre></details>{% endfor %}{% if row.get("executionEvidence") %}<p><strong>{{ t('tasks.implementation.execution-records') }}</strong></p><ul class="evidence-refs" data-report-field="implementation.verifierResults.executionEvidence">{% for ref in row.executionEvidence %}<li><code>{{ ref.checkRef }}</code> run {{ ref.checkRun }} · {% if ref.collection == "complete" %}{{ t('tasks.implementation.exit-code') }} {{ ref.exitCode if ref.exitCode is not none else ref.signal }}{% else %}<span class="status status-incomplete">{{ t('tasks.implementation.incomplete-collection') }}</span> {{ ref.defect | inline_code }}{% endif %} · <code>{{ ref.recordPath }}</code></li>{% endfor %}</ul>{% endif %}{% if row.get("discrepancy") %}<p class="evidence-refs">{{ t('tasks.implementation.discrepancy') }} {{ row.discrepancy | inline_code }}</p>{% endif %}{% if row.get("declinedFixRecommendations") %}<p>{{ row.declinedFixRecommendations | inline_code }}</p>{% endif %}</article>{% endfor %}
27
27
  </section>
28
28
 
29
+ {% for verifier in implementation.verifierResults if verifier.get("designReview") %}
30
+ <section data-report-field="implementation.verifierResults.designReview">
31
+ <h2>{{ verifier.verifier | e }} · Design review</h2>
32
+ {% set review = verifier.designReview %}
33
+ <p>{{ review.collection | e }} · {{ review.get("coveredCells", 0) | e }}/{{ review.get("expectedCells", 0) | e }} cells · {{ review.verdict | e }}</p>
34
+ {% if review.get("reason") %}<p>{{ review.reason | e }}</p>{% endif %}
35
+ {% for finding in review.get("findings", []) %}<article><h3>{{ finding.id | e }} · {{ finding.rule | e }} · {{ finding.severity | e }} · {{ finding.timing | e }}</h3><p>{{ finding.source | e }}: {{ finding.consequence | e }}</p><p>{{ finding.fix | e }}</p><p>{{ finding.disposition | e }} · {{ finding.basis | e }}</p></article>{% endfor %}
36
+ {% for disposition in review.get("carry", []) %}<p>{{ disposition.finding | e }} · {{ disposition.disposition | e }} · {{ disposition.basis | e }}</p>{% endfor %}
37
+ {% for prior in review.get("history", []) %}{% for finding in prior.get("findings", []) %}<p>Earlier {{ prior.generationNumber | e }}:{{ finding.id | e }} · {{ finding.rule | e }} · {{ finding.severity | e }} · {{ finding.timing | e }} · {{ finding.consequence | e }}</p>{% endfor %}{% endfor %}
38
+ {% if review.get("missing") %}<pre>{{ review.missing | e }}</pre>{% endif %}
39
+ </section>
40
+ {% endfor %}
41
+
29
42
  {% if implementation.get("leadFixes") %}<section data-report-section="lead-fixes" data-report-field="implementation.leadFixes">
30
43
  <h2>{{ t('tasks.implementation.lead-fixes') }}</h2>
31
44
  <p>{{ t('tasks.implementation.lead-fixes-intro') }}</p>
@@ -17,6 +17,31 @@
17
17
 
18
18
  `implementation` executes an approved `implementation-planning` final report into actual code changes and local commits. Source edit is allowed only in this phase, but scope is limited to the approved plan and recorded out-of-plan justification.
19
19
 
20
+ ### Independent design-review evidence
21
+
22
+ New approved-plan preparations use verification-input version 4.0. The frozen
23
+ policy, pre-execution base and generation head define every verifier's identical
24
+ file/function worklist. A missing cell/rule remains incomplete for that verifier;
25
+ another verifier or executor self-check cannot fill it. The existing Python AST
26
+ census includes named test helpers; other supported code languages require a
27
+ source-bound manual inventory before dispatch. Inventory completeness remains
28
+ lead judgment. `design_review.py` and generation capture check these contracts.
29
+
30
+ The shared catalog and grading reference classify clear naming/readability
31
+ violations without requiring runtime failure. `design_review_evidence.py`
32
+ authenticates the reserved invocation, latest attempt and sealed result bytes.
33
+ Report assembly derives the evidence and verdict rather than accepting a writer
34
+ summary; current blocking findings and incomplete accounting prevent acceptance.
35
+ `stage_done.py` and phase validation re-derive the same evidence. Final
36
+ verification checks the prepared source reports for consistency, without a
37
+ global style review. Existing input versions keep their resume contract.
38
+
39
+ Each correction generation re-inspects the full stage diff and dispositions
40
+ every earlier blocking finding in `Design Carry`. Old findings remain in the
41
+ machine-owned history, including nits and parked items. No rule judgments are
42
+ inherited without dependency evidence. Regression owners are
43
+ `tests/verification/test_design_review.py` and `tests/report/test_assembly.py`.
44
+
20
45
  ## 2. okstra-run wizard flow
21
46
 
22
47
  ```mermaid
@@ -428,6 +428,12 @@ def validate_verifier_execution_evidence(
428
428
  attempt of the invocation bound to the newest generation, with the bytes and
429
429
  observation it recorded; a `not-run` row is not read.
430
430
  """
431
+ from ...design_review_evidence import validate_design_review_report
432
+
433
+ try:
434
+ validate_design_review_report(data, project_root, manifest_path)
435
+ except (OSError, ValueError) as exc:
436
+ failures.append(f"design-review BLOCKING: {exc}")
431
437
  try:
432
438
  evidence = collect_report_evidence(project_root, manifest_path)
433
439
  except ValueError as exc:
@@ -25,7 +25,7 @@
25
25
  - In `candidate-comparison` mode, the lead merges overlapping candidates, then re-evaluates every merged candidate against the same criteria before ranking it.
26
26
  - In `candidate-comparison` mode, display at most three merged candidates and record every rejected candidate with its rejection reason and cited evidence for audit.
27
27
  - Map every displayed candidate or preselected direction to the stable brief end-state IDs it satisfies, preserves, or leaves unresolved.
28
- - **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --task-manifest <taskManifestPath> --narrative <report writer narrative>` before assembly. For each analyser it names, dispatch one vote-completion assignment asking for that analyser's own feasibility verdict, rationale, and counterevidence on the named candidate — no new candidate, so the run stays in `candidate-comparison` mode. The command reports no gap when a vote cannot settle the block (safety blockers, unresolved feasibility facts, too few feasible verdicts); that is the honest `blocked`.
28
+ - **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --run-manifest <current-run-manifest> --task-manifest <taskManifestPath> --narrative <reportNarrativePath>` before assembly. For each analyser it names, dispatch one vote-completion assignment asking for that analyser's own feasibility verdict, rationale, and counterevidence on the named candidate — no new candidate, so the run stays in `candidate-comparison` mode. The command reports no gap when a vote cannot settle the block (safety blockers, unresolved feasibility facts, too few feasible verdicts); that is the honest `blocked`.
29
29
  - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
30
30
  - Classify every `unresolvedFeasibilityFacts` entry with `resolutionKind`: `user-decision` requires nonempty `clarificationRefs` naming the actual C-NNN records for that fact; `technical-verification` requires source review, design evidence, or experiments and does not require a user question. `deferred-gate` marks a fact that no technical-verification run can close because closing it needs something that phase forbids, such as a deployed environment (for example, a cold-start measurement of a deployed Lambda); it requires `gate`, naming where the fact closes (a brief `External Gates` entry, or final-verification user-owned external QA), and it does not make the candidate invalid. A fact that a probe, a source read, or a disposable local service can close is `technical-verification`, not `deferred-gate`. The selected direction snapshot carries every remaining fact of the chosen option as `deferredFeasibilityFacts`, so planning schedules its gate. Enforced by `blocking_feasibility_facts` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`. Preserve `fact`, `whyItMatters`, and `evidence`. Reuse answered questions and their recorded dispositions; never reopen one merely to save the report. An unrelated open question does not satisfy a missing reference. Historical unclassified entries remain readable, but blocked report reassembly requires the writer to classify them explicitly. Enforced by `validate_blocked_answer_channel` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`. Saving preserves `routing: blocked` and does not make a candidate valid. In `humanSummary.actions`, `verdictCard.nextStep`, and selection guidance, distinguish pending user decisions from remaining technical verification; after the pilot route is answered, carry the selected route and remove the old answer-waiting instruction.
31
31
  - **A split vote ends in a user decision, not another run.** When no candidate is valid only because its votes split (at least one `feasible`, the others `uncertain` or `not-feasible`, no `safetyBlockers`), another option-selection or technical-verification run asks the same designers the same question and returns the same split (fontradar dev-11562: three runs, `feasible` against `uncertain` each time). Before you route `blocked` or `technical-verification` on such a candidate, open one approval decision for it with `okstra approval-decision open --ledger <approvalDecisionsPath> --candidate-ref <IO-NNN>` naming that candidate (classification `noncritical-dissent`): the recommended option is `accept-risk` (proceed with this direction and carry the dissent and the remaining facts into planning), the alternative is `request-revision` (keep the run blocked). Ask the user in-session; record the answer with `okstra approval-decision resolve`. On `accept-risk`, the writer sets `splitAcceptance.clarificationRef` on that candidate, which makes it valid with one `feasible` vote; it then follows the ordinary routing (`implementation-planning` for a validated preselected direction, `pending-direction-selection` in `candidate-comparison`). Leave the votes and facts on the row. The answer accepts that candidate only; no other candidate cites it. When the user is not present, publish the report `blocked` with that approval row open; the next run carries the answer. Enforced by `validate_split_acceptance` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`.
@@ -27,11 +27,9 @@ from collections.abc import Mapping
27
27
  from pathlib import Path
28
28
  from typing import Any
29
29
 
30
- from okstra_ctl.final_report_schema import load_schema_version
31
30
  from okstra_ctl.phases.implementation_option_selection.validation import VoteGap, vote_gaps
32
31
  from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
33
- from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION
34
- from okstra_ctl.report_narrative import parse_narrative_structure
32
+ from okstra_ctl.report_narrative import load_writer_input
35
33
 
36
34
 
37
35
  class OptionVotesError(ValueError):
@@ -45,7 +43,9 @@ def _record_from_report(path: Path) -> dict[str, Any]:
45
43
  raise OptionVotesError(f"report record is unreadable: {exc}") from exc
46
44
 
47
45
 
48
- def _record_from_narrative(path: Path) -> dict[str, Any]:
46
+ def _record_from_narrative(
47
+ path: Path, *, run_manifest: Path | None = None,
48
+ ) -> dict[str, Any]:
49
49
  """작성자 서사를 레코드 모양으로 읽는다.
50
50
 
51
51
  값 결함은 무시한다 — 교정 원장이 고칠 자리이고, 표 구멍을 세는 데에는
@@ -53,12 +53,11 @@ def _record_from_narrative(path: Path) -> dict[str, Any]:
53
53
  아직 교정 중인 run 은 이 명령을 쓸 수 없다.
54
54
  """
55
55
  try:
56
- markdown = path.read_text(encoding="utf-8")
57
- except OSError as exc:
56
+ return load_writer_input(
57
+ path, run_manifest=run_manifest, structure_only=True,
58
+ )
59
+ except (OSError, UnicodeError, ValueError) as exc:
58
60
  raise OptionVotesError(f"narrative is unreadable: {exc}") from exc
59
- schema = load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
60
- record, _defects = parse_narrative_structure(markdown, schema)
61
- return record
62
61
 
63
62
 
64
63
  def participating_analysers(manifest_path: Path) -> tuple[str, ...]:
@@ -131,7 +130,7 @@ def _gaps(args: argparse.Namespace) -> int:
131
130
  record = (
132
131
  _record_from_report(args.report)
133
132
  if args.report
134
- else _record_from_narrative(args.narrative)
133
+ else _record_from_narrative(args.narrative, run_manifest=args.run_manifest)
135
134
  )
136
135
  gaps = vote_gaps(
137
136
  _selection(record), participating_analysers(args.task_manifest)
@@ -176,7 +175,8 @@ def _parser() -> argparse.ArgumentParser:
176
175
  help="a published final-report `.data.json`")
177
176
  gaps_parser.add_argument(
178
177
  "--narrative", type=Path,
179
- help="the report writer's narrative markdown, before assembly")
178
+ help="the report writer's declared input, before assembly")
179
+ gaps_parser.add_argument("--run-manifest", type=Path)
180
180
  gaps_parser.add_argument("--json", action="store_true")
181
181
  return parser
182
182
 
@@ -69,8 +69,7 @@ from okstra_ctl.plan_review_context import render_review_context
69
69
  from okstra_ctl.stage_ledger import build_stage_ledger
70
70
  from okstra_ctl.claim_reproduction import NOT_RUNNABLE, reproduce
71
71
  from okstra_ctl.file_size_cap import headroom_text, planned_file_headroom
72
- from okstra_ctl.final_report_schema import load_schema_version
73
- from okstra_ctl.report_narrative import parse_narrative
72
+ from okstra_ctl.report_narrative import load_writer_input
74
73
  from okstra_ctl.report_assembly import validate_plan_draft
75
74
  from okstra_ctl.error_log_write import record_runtime_failure
76
75
  from okstra_ctl.user_response import parse_user_response_entries
@@ -194,9 +193,11 @@ def _parser() -> argparse.ArgumentParser:
194
193
  commands = parser.add_subparsers(dest="command", required=True)
195
194
  extract = commands.add_parser("extract")
196
195
  _add_plan_source(extract)
196
+ extract.add_argument("--run-manifest", type=Path)
197
197
  extract.add_argument("--output", type=Path, required=True)
198
198
  validate = commands.add_parser("validate")
199
199
  _add_plan_source(validate)
200
+ validate.add_argument("--run-manifest", type=Path)
200
201
  validate.add_argument("--items", type=Path, required=True)
201
202
  prepare = commands.add_parser("prepare")
202
203
  _add_plan_source(prepare)
@@ -425,13 +426,13 @@ def _plan_source(args: argparse.Namespace) -> dict[str, Any]:
425
426
  if args.data is not None:
426
427
  return _load_json_object(args.data)
427
428
  try:
428
- markdown = args.narrative.read_text(encoding="utf-8")
429
+ return load_writer_input(
430
+ args.narrative, run_manifest=getattr(args, "run_manifest", None),
431
+ )
429
432
  except (OSError, UnicodeError) as exc:
430
433
  raise PlanItemContractError(
431
434
  f"cannot read report narrative {args.narrative}: {exc}"
432
435
  ) from exc
433
- try:
434
- return parse_narrative(markdown, load_schema_version("3.0"))
435
436
  except ValueError as exc:
436
437
  raise PlanItemContractError(f"invalid report narrative: {exc}") from exc
437
438
 
@@ -1049,6 +1050,10 @@ def _render_file_size_headroom(rows: object) -> str:
1049
1050
  return ""
1050
1051
  lines = [
1051
1052
  "\n## File-size headroom\n",
1053
+ "\nA negative headroom identifies an already oversized file, not permission to add "
1054
+ "unrelated responsibilities. Apply S3/M2 to the proposed placement. If the plan's "
1055
+ "file restrictions prevent a conforming change, return a plan conflict with the "
1056
+ "proposed module/test location and the acceptance behavior it preserves.\n",
1052
1057
  "Existing files this plan writes, measured before any stage runs. Information "
1053
1058
  "only: it is not a verdict criterion.\n",
1054
1059
  ]
@@ -1187,12 +1192,14 @@ def validate_current_review(run_manifest: Path) -> PreparedPlanReview:
1187
1192
  name = authority.payload.get("reportNarrativePath")
1188
1193
  if not isinstance(name, str) or not name:
1189
1194
  raise PlanItemContractError("reportNarrativePath is missing")
1190
- narrative = (authority.project_root / name).resolve(strict=True)
1191
- if not narrative.is_relative_to(authority.run_dir):
1195
+ narrative = authority.project_root / name
1196
+ if not narrative.resolve(strict=True).is_relative_to(authority.run_dir):
1192
1197
  raise PlanItemContractError("plan narrative must stay inside the current run")
1193
1198
  items_path = _prepared_items_path(run_manifest, require_regular=True)
1194
1199
  prepared = _load_json_object(items_path)
1195
- source = _plan_source(argparse.Namespace(data=None, narrative=narrative))
1200
+ source = _plan_source(argparse.Namespace(
1201
+ data=None, narrative=narrative, run_manifest=run_manifest,
1202
+ ))
1196
1203
  items = _envelope(source)["items"]
1197
1204
  if prepared.get("items") != items:
1198
1205
  raise PlanItemContractError("prepared plan items do not match the current narrative")
@@ -1220,7 +1227,7 @@ def finish_verification_round(
1220
1227
  verified = subprocess.run(
1221
1228
  [sys.executable, str(assets.joinpath(*RUN_VALIDATOR_RELATIVE)),
1222
1229
  "--section", "plan-body", "--narrative", str(review.narrative),
1223
- "--state", str(review.state)],
1230
+ "--state", str(review.state), "--run-manifest", str(review.manifest)],
1224
1231
  capture_output=True, text=True, check=False, timeout=60,
1225
1232
  )
1226
1233
  if verified.returncode:
@@ -8,12 +8,9 @@ rules live in `prompts/profiles/`.
8
8
  ### Step 5.1 (implementation-planning only): user-confirmed TDD bypass offer
9
9
 
10
10
  Every plan stage must open with a `RED:` step whose outcome is FAIL and reach a
11
- later `GREEN:` step (validator S10c). `tddExemption` waives that, and until
12
- 2026-09-10 only for `doc-only`, `config-only`, or `pure-rename` work — so a
13
- stage that is truthfully none of the three had no passable value, and the plan
14
- got through by filing the nearest category. That is the failure this flag
15
- exists to remove: **a closed reason list with no escape makes the plan
16
- misdescribe itself.**
11
+ later `GREEN:` step (validator S10c). `tddExemption` waives that for
12
+ `doc-only`, `config-only`, `pure-rename`, or a user-granted `user-bypass`. A
13
+ stage that fits none of these is not filed under the nearest category.
17
14
 
18
15
  `render-bundle` accepts an optional `--tdd-bypass "<stage>:<reason>"` flag
19
16
  (implementation-planning only). It records a **user-acknowledged** bypass into
@@ -10,6 +10,8 @@ Use the absolute common-contract paths in the lead prompt's `Okstra Runtime Reso
10
10
 
11
11
  This contract defines a **second, independent** verification round that fires only for `task-type = implementation-planning`. The round verifies the *consolidated plan* that the report-writer worker has authored, not the worker findings that were already reconciled earlier.
12
12
 
13
+ Take every authoring input path below from the current run manifest's `reportNarrativePath`. Its declared `reportAuthoringFormat=json-v1` selects standard JSON with ordinary Markdown inside description strings; an absent field retains `markdown-v1` and its line grammar. Pass that same run manifest to `plan-items prepare`, `seed`, `extract`, `validate`, `validate-prepared`, `plan-verify`, and `incremental-carry` so each consumer selects the declared format. Keep the actual `.json` or `.md` extension when preserving a correction attempt. The final reader's Markdown and HTML remain derived outputs.
14
+
13
15
  ## Lifecycle position (BLOCKING)
14
16
 
15
17
  Plan-body verification runs **after** finding convergence and **after** the report-writer draft is written. Sequence inside a single implementation-planning run:
@@ -17,7 +19,7 @@ Plan-body verification runs **after** finding convergence and **after** the repo
17
19
  ```
18
20
  Phase 4 workers produce independent analyses (Findings F-001…)
19
21
  → Phase 5.5 FINDING convergence (`prompts/lead/convergence.md`, sections "Convergence Algorithm" through "Convergence State Artifact")
20
- → Phase 6 report-writer authors report-writer-narrative Markdown (consolidated Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)
22
+ → Phase 6 report-writer authors the manifest-declared input (consolidated Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)
21
23
  → okstra plan-items prepare + prompt + validate-prepared creates and projects the deterministic P-* queue
22
24
  → PLAN-BODY VERIFICATION ROUND ← this contract
23
25
  → final render/validation
@@ -64,9 +66,9 @@ Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (
64
66
  From the report-writer's draft of `## 5.4 Implementation Plan Deliverables`, the lead creates the verification queue only through this sequence (see also `templates/reports/final-report-v2.template.md` §5.5.9):
65
67
 
66
68
  ```text
67
- okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>
69
+ okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>
68
70
  → place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in every verifier prompt
69
- → okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>
71
+ → okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>
70
72
  ```
71
73
 
72
74
  The persisted `items[]` are the sole queue. The lead MUST NOT freely summarise,
@@ -413,11 +415,11 @@ round before any host or provider process starts.
413
415
 
414
416
  For contract 3.0, `prepare` checks the selected-direction draft with the same semantic validator as publication before writing the queue. Correct all reported references, coverage rows and planned commands through the writer correction procedure, then retry in this run. **Enforced:** `report_assembly.validate_plan_draft` and `plan_items_cli._prepare`; the retired Python suite previously checked that invalid coverage creates no prepared queue.
415
417
 
416
- 1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`. A `File-size headroom` line that prepare prints, and that `okstra plan-items prompt` carries under `## File-size headroom`, is a report only: it names an existing file the plan writes, its lines left before the 500-line implementation limit and the stages that write it. It does not block, open a correction or count as a verdict. After a self-fix rewrite, and after `okstra incremental-carry` on a re-run, pass `--state <plan-body-verification.json>` on prepare and validate-prepared; validate-prepared needs the same `--state` the last prepare used, or it refuses with `prepared dispatch queue does not match` or `prepared review evidence changed`. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and the retired Python suite. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
418
+ 1. Lead runs `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. A `File-size headroom` line that prepare prints, and that `okstra plan-items prompt` carries under `## File-size headroom`, is a report only: it names an existing file the plan writes, its lines left before the 500-line implementation limit and the stages that write it. It does not block, open a correction or count as a verdict. After a self-fix rewrite, and after `okstra incremental-carry` on a re-run, pass `--state <plan-body-verification.json>` on prepare and validate-prepared; validate-prepared needs the same `--state` the last prepare used, or it refuses with `prepared dispatch queue does not match` or `prepared review evidence changed`. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and the retired Python suite. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
417
419
 
418
- **Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <report-writer-narrative.md> --state <plan-body-verification.json> --run-manifest <run-manifest.json>`. `apply-verdicts` in step 8 refuses a verdict whose item has no `planBodyVerification.planItems[]` row. The report writer never owns that state, so the deterministic seed is the only creator of its rows. The seed is idempotent by id and never touches existing verdicts, so it is safe to re-run between rounds and after a self-fix re-extraction. It does refresh `contentHash` from the current extract. Skipping it makes step 8 fail with `plan-body state has no row for [...]`.
420
+ **Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <reportNarrativePath> --state <plan-body-verification.json> --run-manifest <run-manifest.json>`. `apply-verdicts` in step 8 refuses a verdict whose item has no `planBodyVerification.planItems[]` row. The report writer never owns that state, so the deterministic seed is the only creator of its rows. The seed is idempotent by id and never touches existing verdicts, so it is safe to re-run between rounds and after a self-fix re-extraction. It does refresh `contentHash` from the current extract. Skipping it makes step 8 fail with `plan-body state has no row for [...]`.
419
421
 
420
- **On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry` and repeats prepare, prompt and validate-prepared with `--state` before dispatch (launch prompt "Incremental re-verification" step 7). A newly seeded item inherits verdicts only when its body and verified evidence fingerprint match the prepared snapshot for the same task. Reused rows carry `carriedForwardFromSeq`; their full verdicts are preserved. Legacy body-only records re-enter verification. A matching id alone never carries: `P-*` ids are positional. The flag requires `--state` and refuses another task's state. **Enforced:** `implementation_planning.authoring._carry_prior_run_verdicts` and `plan_item_evidence.reusable_item_ids`.
422
+ **On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> ...` and repeats prepare, prompt and validate-prepared with `--state` before dispatch (launch prompt "Incremental re-verification" step 7). A newly seeded item inherits verdicts only when its body and verified evidence fingerprint match the prepared snapshot for the same task. Reused rows carry `carriedForwardFromSeq`; their full verdicts are preserved. Legacy body-only records re-enter verification. A matching id alone never carries: `P-*` ids are positional. The flag requires `--state` and refuses another task's state. **Enforced:** `implementation_planning.authoring._carry_prior_run_verdicts` and `plan_item_evidence.reusable_item_ids`.
421
423
 
422
424
  **`--run-manifest` is what scopes the gate to the stage you are starting.** Seed uses it to overlay disk `done` / `active` onto `planBodyVerification.stageLedger`. The current plan's depends-on fills `ready` / `blocked` when no prior plan exists, so a first run does not treat every stage as in-scope. **Enforced:** `okstra_ctl.plan_items.planning_stage_ledger`.
423
425
  2. For each analyser worker in the roster, use `okstra plan-items prompt` output verbatim as the instruction body in the materialization sequence above. Read §"Re-verification rounds (round 2+)" before preparing a later round; read §"Plan-body reverify prompt" only when diagnosing a prompt-contract failure.
@@ -446,10 +448,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
446
448
  - any advisory `dissent-isolated` / `needs-reverify` present, no `majority-disagree` → `passed-with-dissent`
447
449
  - all items `full-consensus` → `passed`
448
450
 
449
- **Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are in the data.json, lead runs
451
+ **Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are recorded in the convergence-owned plan-body state, lead runs
450
452
 
451
453
  ```
452
- okstra plan-verify --report <the launch prompt's `## Run Paths` → `Final report` value>
454
+ okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>
453
455
  ```
454
456
 
455
457
  and records what it returns: `gate.recomputed` is the round's gate value, `gate.blockedBy` its `gateBlockedBy` causes, `gate.blockingItems` the items that block. The same call runs every plan-body check a round can be judged on alone — provenance, fixability, subject substance, self-fix grouping, round recording, clarification matching, state-file rounds — and exits 2 with `failures[]` when the round is not contract-clean. **A round is not complete while that exit code is non-zero.**
@@ -485,10 +487,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
485
487
  - **Group the targets by cause before instructing (BLOCKING).** Blocked items are usually several derivatives of one defect. Lead partitions this round's targets into cause groups and instructs each group as **"remove this cause"**, naming the derivatives it accounts for. The convergence command owns the persisted group and correction fields; the lead does not edit JSON state.
486
488
  - lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration): one `rewrite` entry per item in a corrections ledger, whose `rule` states the cause group's required outcome; procedure in `prompts/lead/report-writer.md` §"Corrective report-writer dispatch (ledger required)".
487
489
  - missing or weak `P-Prep-*` contracts are repaired by adding kind-specific inline detail or an AI-prepared PREP item with a concrete proposal. Facts that require user or external authority remain `blocked` and keep their request material; never invent those facts during self-fix.
488
- - **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract` and re-verify any item whose `subject` no longer matches; never carry the old vote forward across a shift. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdicts_match_current_subjects` (re-pointing) and `_validate_plan_item_extraction_completeness` (dangling ids).
490
+ - **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --output <extract-path>` and re-verify any item whose `subject` no longer matches; never carry the old vote forward across a shift. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdicts_match_current_subjects` (re-pointing) and `_validate_plan_item_extraction_completeness` (dangling ids).
489
491
  - **Classify each cause group before instructing it (BLOCKING).** A group is either an *authoring* defect — the plan says something wrong, incomplete, or self-contradictory, which self-fix owns — or a *citation* defect, where the plan points at an analysis artifact incorrectly. Only the first is self-fix work. For the second the finding already exists and already went through convergence, so the fix is to re-cite the converged artifact; instructing report-writer to re-derive the fact means the author reads the source material and produces a **finding that never went through convergence**, which the plan then carries as if it had. That is the role boundary the lead contract draws ("keep analysis, execution, verification, and report authoring responsibilities distinct; return defects to the role that owns them"), and report-writer is authoring-only by its own contract. `P-Req-*` items with breakage kind `f` are where this goes wrong most often: the question is usually whether a coverage row points correctly at something already measured, not whether the measurement is right. State the classification in the group's instruction so the author knows which of the two it is being asked to do.
490
492
  - **A verdict older than the last self-fix is not a verdict unless the item's content is unchanged (BLOCKING).** A verdict cast in round 1 judged the text before the only automatic rewrite. Once that rewrite runs, a changed item's judgement is about a plan that no longer exists. `--round <N>` on `apply-verdicts` stamps each row and copies `contentHash` onto `verifiedContentHash`. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdict_rounds_outlive_self_fix` fails an in-scope item whose verdict round is at or before `selfFixRoundsApplied` **and** whose `contentHash` does not match `verifiedContentHash`. Matching hashes keep the prior verdict — that is what avoids a sweep round over unchanged stages. Deferred and observed items are out of the gate and do not need a post-self-fix verdict. **Enforced:** `_validate_verdict_rounds_outlive_self_fix`.
491
- - Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --narrative <report-writer-narrative.md> --state <plan-body-verification.json>`, then call `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. These commands fail on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a duplicate worker result. `apply-verdicts` without `--append` replaces every recorded row of the queued items, so it also refuses — before writing — when a row belongs to a round that `complete-round` never closed, naming the round to close first; the votes of a closed round live in `planItems[].rounds`. Skipping `complete-round` between rounds and applying the next one lost 19 items' round-1 votes (2026-09-09). `--discard-open-rounds` is only for re-applying the lost rounds from their result files in order: it also restores `dispatchQueue` to the items those result files answer, because the persisted queue is the latest round's and a verdict for an earlier, wider queue is otherwise refused as outside it (round 1 = 26 items, critic tie = 8, round 3 = 19 on that same run — only the 19 survived). Re-apply each lost round with the flag, `complete-round` it, then the next. **Enforced:** `okstra_ctl.plan_items_cli._reject_uncompleted_round_loss` and `_restore_queue_from_results`.
493
+ - Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>`, then call `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. These commands fail on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a duplicate worker result. `apply-verdicts` without `--append` replaces every recorded row of the queued items, so it also refuses — before writing — when a row belongs to a round that `complete-round` never closed, naming the round to close first; the votes of a closed round live in `planItems[].rounds`. Skipping `complete-round` between rounds and applying the next one lost 19 items' round-1 votes (2026-09-09). `--discard-open-rounds` is only for re-applying the lost rounds from their result files in order: it also restores `dispatchQueue` to the items those result files answer, because the persisted queue is the latest round's and a verdict for an earlier, wider queue is otherwise refused as outside it (round 1 = 26 items, critic tie = 8, round 3 = 19 on that same run — only the 19 survived). Re-apply each lost round with the flag, `complete-round` it, then the next. **Enforced:** `okstra_ctl.plan_items_cli._reject_uncompleted_round_loss` and `_restore_queue_from_results`.
492
494
  - For a self-fix, record the correction through the typed convergence command rather than writing `selfFixNote` or `selfFixGroups` JSON. A resolved item does not create a clarification.
493
495
  - **Each round is a worker batch.** Before dispatching round N ≥ 2, reclaim the previous round's completed verifiers exactly as at any other batch boundary (`prompts/lead/okstra-lead-contract.md` "Run-scoped worker-resource lifecycle") and emit `PROGRESS: phase-batch-cleanup panes=<n>`, then announce the round with `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>`. Saying a round will "reuse" the previous verifiers and then dispatching under fresh names leaves every prior round holding its panes — five rounds of that is what exhausts the pane budget and blocks the next dispatch. **Enforced:** `validators/validate_session_conformance.py` `_check_plan_verify_cleanup_checkpoints` requires both lines once the state file records two or more rounds.
494
496
  - **Round completion.** A round is complete only after `okstra plan-verify` exits 0 and `okstra plan-items complete-round` succeeds. A round left with a non-zero exit carries its defect into the next round's inputs. Exit 0 with a non-empty `advisories[]` is a complete round: those findings are recorded, not round-blocking (step 5, §"`failures[]` carries only the blocking findings"). Report assembly and rendering occur only after the convergence state is terminal. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_plan_body_state_rounds` requires one stored round per round number and a corresponding item vote.
@@ -63,7 +63,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
63
63
  - **Follow established patterns**: in existing codebases, conform to current conventions. Targeted cleanup of a file you are already modifying is acceptable; unrelated refactors are not.
64
64
  - **Variation-point extraction (OCP)**: when the same behavior is served by two or more resources / implementations — stated in the brief, or foreseeable from a sibling task or the code you inspected — the plan MUST record it in `variationPointAnalysis` and make an evidence-backed `extractionDecision` that preserves the chosen direction's architecture boundaries. Reject a realization that branches on resource identity inside a service (one `if` / `switch` arm per implementation): adding the next implementation then means editing that same call site again, which is the closed-for-extension shape this principle exists to catch. This does not contradict YAGNI below: YAGNI drops *speculative* variation (a second implementation nobody named), while a behavior with two implementations already on the table is a present fact, not a forecast. **Enforced:** the `variationPointAnalysis` bullet under `Required deliverable shape` names the schema / validator / `P-Var-*` enforcement points.
65
65
  - **YAGNI ruthlessly**: drop features, abstractions, and configuration knobs that do not serve the stated requirement. The test is a *present* caller, not a plausible one — an abstraction whose only justification is a requirement nobody has stated is this rule's target, while a behavior with two implementations already on the table belongs to `Variation-point extraction` above. **Enforced:** the §5.5.9 plan-body verification round raises a hidden direction expansion on selected-direction `P-Dir-1`, and retains legacy `P-Opt-*` `DISAGREE(e)` semantics. One phase later the `implementation` verifier's Static design gate fails the stage on a caller-less identifier.
66
- - **Project review-rule preflight**: a pack applies when either source names it — the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or `<PROJECT_ROOT>/.okstra/project.json` lists it under `reviewRulePacks` (the project's standing standard, applying whether or not the brief mentions it). The two sources are a union. Read only those files and the `references/*.md` files they directly name. Do not search parent directories or host skill catalogs. Do not run the PR-review workflow here; extract only the rules. For Fonts Ninja-style TS/NestJS review packs, this means planning away known review findings before code exists: shared transforms instead of duplicate helper stacks, behavioral tests instead of collaborator-tautology assertions, domain rules in domain modules rather than repositories/adapters, domain objects under `domain/`, plain-English functions, truthful/specific names, and no dead APIs introduced by the plan.
66
+ - **Project review-rule preflight**: use the Frozen Review Policy when verification inputs supplies one; legacy inputs retain the union of declared packs and exact brief-cited paths. Apply `clean-code.md` "Finding evidence and grading" and the shared catalog. Plan conforming names, function responsibilities, module placement and behavioral tests before code exists. A file restriction or test-preservation instruction that conflicts with a rule returns a plan conflict naming the proposed location and preserved acceptance behavior; it does not waive the rule. Do not run the PR-review workflow or search host skill catalogs here. Semantic conformance is judged by plan-body verification; freezing and input validity are checked by verification-input preparation.
67
67
  - Expected output emphasis:
68
68
  - feasible realization of the selected direction or legacy choice
69
69
  - dependency and risk visibility
@@ -86,7 +86,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
86
86
  - §5.5.9 plan-body verification runs with an **adversarial posture** (`scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is majority-based for kinds `b`/`c`/`e`, but a single `DISAGREE` blocks on its own for the concrete, safety-critical kind `a` (path/symbol mismatch) — and `f` on `P-Req-*` items. `P-Var-*` items are excepted from the kind-`a` exception: a variation-point defect takes a majority. Rollback ordering (`d`) is advisory and never blocks the gate — a rollback is executed by a human, not by okstra's workers or verifiers. A majority also needs ≥2 participating votes, so a lone dissent whose peer returned a non-result does not block on a majority-gated kind (see that contract's §"Adversarial plan-body posture").
87
87
  - **Incremental re-verification scope (clarification re-runs):** when the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), workers re-analyze ONLY the stages listed in `reverify_stages` (the downstream closure of the impacted stages). Workers MUST NOT re-open, re-score, or re-judge any stage in `carry_stages` — those stages' prior plan-item verdicts are carried forward verbatim, and a worker never overwrites a carried verdict with its own judgement. When the decision is `mode == "full"` (the default), every stage is re-analyzed as usual.
88
88
  - **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. **When this run only ADDS stages** — every prior stage is `done` and none of them is being re-opened — there are no stage numbers to give: pass `--carry-all-reason` instead. Pinning any prior stage as impacted makes `incremental-carry` demand plan-item verdicts from the current snapshot, which no longer holds them (a `done` stage's plan items are `observed`, so they are never dispatched or scored in this run), so that path has no answer that works. The stage's own row is still declared in the narrative — that is the numbering rule above, not a re-verification. `--carry-all-reason` still applies the base-ref check: if the branch moved, the decision degrades to `full` because the prior stages are no longer "as written". Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, `carry-all` supplies the `--carry-all-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
89
- - **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --cur-narrative ... --state ... --out-state ...` against that record. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
89
+ - **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> --state ... --out-state ...` against that record. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
90
90
  {{INCLUDE:_coverage-critic.md}}
91
91
  - Non-goals:
92
92
  - code-level micro-optimization unless it changes the implementation approach
@@ -115,8 +115,8 @@ Plan for the actual worktree layout before approval. Shared documentation direct
115
115
  - **`user-bypass` — the stage that is honestly none of the three.** Some stages have no failing-before state to write and no category that describes them (measured 2026-09-10: a stage whose product change was already committed and conformance-proved under a previous run of the same stage, so the only truthful reason was "this stage reconciles that stage's QA declaration"). Do **not** file the closest of the three; that makes the plan misdescribe itself and S10e passes on a reason that is not true. Declare `tddExemption: user-bypass — <the user's own words>` and stop: the value holds only while `<task-root>/qa/tdd-bypass.json` records the user's grant for that stage number. **You cannot write that record.** Ask the user, in your report's clarification row or directly, to re-run prepare with `--tdd-bypass "<stage>:<reason>"`; their reason is stored verbatim and the record shows the stage as bypassed by the user rather than as one of the three canned categories. **Enforced (S10e):** `collect_data_validation_errors` takes the granted stage numbers from `okstra_ctl.tdd_bypass.granted_stages`; a stage naming the token with no grant fails exactly as an arbitrary reason does, and the failure message carries the flag that produces a passing value.
116
116
  - `stageMap[].dependsOn` must form a DAG (no self-dependency, no unknown stage, no cycle), each row's `stepCount` must equal its stage's actual `stepwiseExecution` row count, and two `(none)`-dependency stages must not name the same file in their `exitContract` — they run as concurrent implementation runs in separate worktrees. **Enforced (S8/S4/S9):** same function.
117
117
  - Legacy candidate-comparison-only deliverable:
118
- - The report writer records the plan body in report narrative Markdown under `implementationPlanning`. Report assembly adds machine-owned `designPreparation`, `designSurfaceCoverage`, and `planBodyVerification`, then validates the completed `data.json` against `schemas/final-report-v3.0.schema.json`.
119
- - **Narrative field names under `Implementation Planning` (the only ones accepted):** `Coverage Summary`, `Cross Project Dependencies`, `Decision Drafts`, `Dependency Migration Risk`, `Direction Invalidation`, `Direction Realization`, `Incremental Decision`, `Option Candidates`, `Outcome`, `Planning Contract`, `Recommended Option`, `Requirement Coverage`, `Rollback Strategy`, `Routing`, `Selected Direction Ref`, `Skipped ADR Candidates`, `Stage Map`, `Stages`, `Stepwise Execution`, `Supersession Ledger`, `Tradeoff Matrix`, `User Narrative`, `Validation Checklist`, `Variation Point Analysis`. The `## 5.5.<i>` headings, the `step | action | ...` tables, and the `Slice value:` / `Test case (...):` lines described below are the shape of the **rendered report a reader sees**, not narrative syntax — the narrative carries the same content as `- **Field**` / `- Item <N>` / `> value` rows under these names. `Design Preparation` and `Plan Body Verification` belong to report assembly and are rejected here.
118
+ - The report writer records the plan body under `implementationPlanning` in the input at the run manifest's `reportNarrativePath`, using its declared `reportAuthoringFormat`. `json-v1` uses exact JSON schema keys and native values, with ordinary Markdown allowed inside description strings. An absent field retains the `markdown-v1` line grammar. Report assembly adds machine-owned `designPreparation`, `designSurfaceCoverage`, and `planBodyVerification`, then validates the completed `data.json` against the frozen final-report schema.
119
+ - **Legacy Markdown field labels under `Implementation Planning`:** `Coverage Summary`, `Cross Project Dependencies`, `Decision Drafts`, `Dependency Migration Risk`, `Direction Invalidation`, `Direction Realization`, `Incremental Decision`, `Option Candidates`, `Outcome`, `Planning Contract`, `Recommended Option`, `Requirement Coverage`, `Rollback Strategy`, `Routing`, `Selected Direction Ref`, `Skipped ADR Candidates`, `Stage Map`, `Stages`, `Stepwise Execution`, `Supersession Ledger`, `Tradeoff Matrix`, `User Narrative`, `Validation Checklist`, `Variation Point Analysis`. For `json-v1`, use the exact keys in the synthesis packet's writer-owned schema instead, such as `implementationPlanning.requirementCoverage`. The `## 5.5.<i>` headings, the `step | action | ...` tables, and the `Slice value:` / `Test case (...):` lines described below are the shape of the **rendered report a reader sees**. JSON carries that content as structured values; only `markdown-v1` uses `- **Field**` / `- Item <N>` / `> value` rows. `designPreparation` and `planBodyVerification` belong to report assembly and are rejected in either format.
120
120
  - Legacy candidate-comparison requires at least two implementation options. **Each option must include**:
121
121
  - **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.
122
122
  - **Two-tier change description.** Each `fileStructure` row carries `summary` **and** optional `details`, and they are not interchangeable:
@@ -208,7 +208,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
208
208
  - Selected-direction plans omit `implementation-option:` because `selectedDirectionRef` already fixes the direction; the legacy-only selector rule is owned by the legacy deliverable section above.
209
209
  - **the frontmatter `approved: false` line is rendered unconditionally; if the plan-body verification gate (§5.5.9) returns `blocked-by-disagreement` or `aborted-non-result`, the writer MUST keep `approved: false` and the validator refuses any report that ships with `approved: true` under such a gate result.**
210
210
  - every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (the unified table is the single home for these — the "no separate `Open Questions` block" rule is in the shared `_common-contract.md` clarification policy)
211
- - **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <report-narrative.md> --run-manifest <run-manifest>`, place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in the verifier prompt, then run `okstra plan-items validate-prepared --narrative <report-narrative.md> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. Do not freely summarise, select, omit, reorder, or renumber the queue. Prompt headings use the compact subject and include the lossless payload. For every item, ask:
211
+ - **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in the verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. Do not freely summarise, select, omit, reorder, or renumber the queue. Prompt headings use the compact subject and include the lossless payload. For every item, ask:
212
212
 
213
213
  ```text
214
214
  What concrete false-positive input, failure ordering, or omitted dependency
@@ -284,7 +284,7 @@ Lead's responsibilities in this sub-step (in order):
284
284
 
285
285
  For a new `implementation-planning` run, the fixed order is initial verification → one planner self-fix → targeted re-verification → lead decision or immediate user confirmation. The initial verification is round 1 and the targeted re-verification is round 2. A second automatic self-fix is a contract violation. When `okstra plan-items prepare` reports `"gating": false` (one-stage `no-design-inputs` plan), skip the self-fix loop and the sweep batch: extraction and round 1 still run, then go to the user gate. Two-or-more stages, a PREP item, or non-empty `designPreparation.items` keep `gating: true` and the full order.
286
286
 
287
- 1. Build the queue with `okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`, place the output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then run `okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. The lead MUST NOT summarise, select, omit, reorder, or renumber the queue. Each prompt uses the compact subject plus the lossless payload, and asks every item:
287
+ 1. Build the queue with `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place the output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. The lead MUST NOT summarise, select, omit, reorder, or renumber the queue. Each prompt uses the compact subject plus the lossless payload, and asks every item:
288
288
 
289
289
  ```text
290
290
  What concrete false-positive input, failure ordering, or omitted dependency