okstra 0.229.0 → 0.231.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 (150) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +168 -18
  9. package/docs/architecture.md +15 -14
  10. package/docs/coding-rules.md +15 -0
  11. package/docs/contributor-change-matrix.md +5 -5
  12. package/docs/project-structure-overview.md +13 -19
  13. package/package.json +2 -3
  14. package/runtime/BUILD.json +2 -2
  15. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  16. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  17. package/runtime/prompts/coding-preflight/overview.md +1 -0
  18. package/runtime/prompts/launch.template.md +7 -5
  19. package/runtime/prompts/lead/convergence.md +4 -4
  20. package/runtime/prompts/lead/okstra-lead-contract.md +19 -18
  21. package/runtime/prompts/lead/phase-routing.md +1 -1
  22. package/runtime/prompts/lead/report-writer.md +3 -3
  23. package/runtime/prompts/lead/team-contract.md +3 -3
  24. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  25. package/runtime/python/okstra_ctl/agent/invocation.py +190 -9
  26. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  27. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  28. package/runtime/python/okstra_ctl/cmux.py +4 -2
  29. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  30. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  31. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  32. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  33. package/runtime/python/okstra_ctl/conformance.py +30 -0
  34. package/runtime/python/okstra_ctl/conformance_evidence.py +316 -0
  35. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  36. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  37. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  38. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  39. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  40. package/runtime/python/okstra_ctl/ids.py +1 -41
  41. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  42. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  43. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  44. package/runtime/python/okstra_ctl/locks.py +28 -1
  45. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  46. package/runtime/python/okstra_ctl/paths.py +90 -33
  47. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  48. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  50. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  51. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  53. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +5 -4
  55. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  57. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +5 -4
  58. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  59. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +6 -2
  60. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +4 -2
  61. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +23 -7
  63. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  65. package/runtime/python/okstra_ctl/phases/implementation/spec.md +6 -4
  66. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  67. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  68. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  69. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -12
  70. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  71. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  72. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  73. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  74. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  75. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  76. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  77. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  78. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  79. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  80. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  81. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  82. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  83. package/runtime/python/okstra_ctl/process_group.py +26 -3
  84. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  85. package/runtime/python/okstra_ctl/recap.py +1 -2
  86. package/runtime/python/okstra_ctl/render.py +25 -2
  87. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  88. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  89. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  90. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  91. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  92. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  93. package/runtime/python/okstra_ctl/run.py +40 -20
  94. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  95. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  96. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  97. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  98. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  99. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  100. package/runtime/python/okstra_ctl/verification_dispatch.py +136 -0
  101. package/runtime/python/okstra_ctl/verification_evidence.py +671 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +34 -16
  103. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  104. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  105. package/runtime/python/okstra_ctl/verification_inputs.py +83 -2
  106. package/runtime/python/okstra_ctl/verification_invocation.py +140 -0
  107. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  108. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  109. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  110. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  111. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  112. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  113. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  114. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  115. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  116. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  117. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  118. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  119. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  120. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  121. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  122. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  123. package/runtime/skills/okstra-run/SKILL.md +11 -7
  124. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  125. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  126. package/runtime/templates/reports/html/i18n/en.json +7 -0
  127. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  128. package/runtime/validators/validate-run.py +130 -20
  129. package/runtime/validators/validate-workflow.sh +1 -1
  130. package/docs/cli.md +0 -1060
  131. package/docs/container.md +0 -100
  132. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  133. package/docs/performance-improvement-plan-v2.md +0 -369
  134. package/runtime/python/okstra_ctl/container.py +0 -702
  135. package/runtime/python/okstra_ctl/rollup.py +0 -241
  136. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  137. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  138. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  139. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  140. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  141. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  142. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  143. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  144. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  145. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  146. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  147. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  148. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  149. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  150. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -3,9 +3,16 @@ from __future__ import annotations
3
3
 
4
4
  import re
5
5
  from collections.abc import Callable, Mapping
6
+ from pathlib import Path
6
7
  from typing import Any
7
8
 
8
9
  from ...correction_round import correction_round
10
+ from ...report_execution_evidence import (
11
+ EXECUTION_EVIDENCE_BLOCKING, collect_report_evidence, omitted_records, reference_errors,
12
+ )
13
+ from ...paths import RunRef
14
+ from ...verification_dispatch import generation_sealed_after_round
15
+ from ...verification_evidence import roster_verifier_role_execution_ref
9
16
 
10
17
  _PASSING_VERDICT_TOKENS = frozenset({"accepted", "conditional-accept"})
11
18
  _CHECKLIST_ID_RE = re.compile(r"\bVC-\d{3,}\b")
@@ -192,13 +199,18 @@ def _lead_fix_rows(implementation: dict) -> list[dict]:
192
199
  return [row for row in implementation.get("leadFixes") or [] if isinstance(row, dict)]
193
200
 
194
201
 
195
- def lead_fixed_verifiers(implementation: dict) -> frozenset[str]:
202
+ def lead_fixed_verifiers(
203
+ implementation: dict, *, evidence_contract: bool = False,
204
+ ) -> frozenset[str]:
196
205
  """정착된 stage 에서 통과한 리드 수정이 답한 FAIL 검증자 이름.
197
206
 
198
207
  stage 가 `withheld` 이면 리드 수정은 아무것도 해소하지 않는다 — 다음 run 은
199
208
  그 FAIL 행을 그대로 fix-run carry 로 받아야 한다.
209
+
210
+ An evidence-contract run settles a FAIL only through a correction round, so
211
+ its lead fixes answer none.
200
212
  """
201
- if not _stage_settled(implementation):
213
+ if evidence_contract or not _stage_settled(implementation):
202
214
  return frozenset()
203
215
  return frozenset(
204
216
  str(name)
@@ -208,43 +220,78 @@ def lead_fixed_verifiers(implementation: dict) -> frozenset[str]:
208
220
  )
209
221
 
210
222
 
211
- def _validate_lead_fixes(data: dict, failures: list[str]) -> None:
223
+ def _validate_lead_fixes(
224
+ data: dict, failures: list[str], *, evidence_contract: bool = False,
225
+ ) -> None:
212
226
  """리드 수정 기록과, FAIL 이 남은 채 정착된 stage 를 검사한다.
213
227
 
214
228
  `_implementation-deliverable.md` "Lead minor fix": 검증자 FAIL 이 있는 stage 를
215
229
  `done` 으로 정착시킬 수 있는 길은 재실행 검사가 전부 통과한 리드 수정뿐이다.
216
230
  finding 단위 대응은 검사하지 않는다 — `verifierResults[]` 에 구조화된 finding
217
231
  id 가 없어 계산할 수 없다. 검증자 행 단위(`verifiers`)까지만 본다.
232
+
233
+ An evidence-contract run has no lead-fix path: its `commands` are written by
234
+ the lead, and the fix commit was never sealed into a generation a verifier
235
+ re-checked.
218
236
  """
219
237
  implementation = data.get("implementation")
220
238
  if not isinstance(implementation, dict):
221
239
  return
222
240
  fixes = _lead_fix_rows(implementation)
223
- for index, row in enumerate(fixes):
224
- ids = ", ".join(str(item) for item in row.get("findingIds") or []) or "no finding id"
225
- label = f"implementation.leadFixes[{index}] ({ids})"
226
- commands = [cmd for cmd in row.get("commands") or [] if isinstance(cmd, dict)]
227
- failed = [cmd for cmd in commands if cmd.get("exitCode") != 0]
228
- if row.get("result") == "pass" and (failed or not commands):
229
- evidence = (
230
- f"`{str(failed[0].get('command'))[:120]}` exited {failed[0].get('exitCode')}"
231
- if failed else "no re-run command is recorded"
232
- )
233
- failures.append(
234
- f"{_LEAD_FIX_BLOCKING} {label} records `result: pass` but {evidence}. "
235
- "A lead fix passes only when every re-run check exits 0; otherwise "
236
- "record `result: fail` and withhold the stage."
237
- )
238
- lines = row.get("changedLines")
239
- if isinstance(lines, int) and lines > LEAD_FIX_LINE_LIMIT:
240
- failures.append(
241
- f"{_LEAD_FIX_BLOCKING} {label} changed {lines} lines; a lead minor fix "
242
- f"is limited to {LEAD_FIX_LINE_LIMIT}. A larger change belongs to a fix "
243
- "run, where the verifiers review it."
244
- )
245
- if not _stage_settled(implementation):
246
- return
247
- unsettled = [index for index, row in enumerate(fixes) if row.get("result") != "pass"]
241
+ if evidence_contract:
242
+ _reject_evidence_contract_lead_fixes(fixes, failures)
243
+ else:
244
+ for index, row in enumerate(fixes):
245
+ _check_lead_fix(index, row, failures)
246
+ if _stage_settled(implementation):
247
+ _check_settled_stage(data, implementation, fixes, evidence_contract, failures)
248
+
249
+
250
+ def _reject_evidence_contract_lead_fixes(fixes: list[dict], failures: list[str]) -> None:
251
+ for index, _row in enumerate(fixes):
252
+ failures.append(
253
+ f"{_LEAD_FIX_BLOCKING} implementation.leadFixes[{index}] records a lead "
254
+ "fix in an evidence-contract run. Its re-run commands are self-written "
255
+ "and its commit was never sealed into a generation a verifier "
256
+ "re-checked; send the fix through a correction round instead."
257
+ )
258
+
259
+
260
+ def _check_lead_fix(index: int, row: dict, failures: list[str]) -> None:
261
+ ids = ", ".join(str(item) for item in row.get("findingIds") or []) or "no finding id"
262
+ label = f"implementation.leadFixes[{index}] ({ids})"
263
+ commands = [cmd for cmd in row.get("commands") or [] if isinstance(cmd, dict)]
264
+ failed = [cmd for cmd in commands if cmd.get("exitCode") != 0]
265
+ if row.get("result") == "pass" and (failed or not commands):
266
+ evidence = (
267
+ f"`{str(failed[0].get('command'))[:120]}` exited {failed[0].get('exitCode')}"
268
+ if failed else "no re-run command is recorded"
269
+ )
270
+ failures.append(
271
+ f"{_LEAD_FIX_BLOCKING} {label} records `result: pass` but {evidence}. "
272
+ "A lead fix passes only when every re-run check exits 0; otherwise "
273
+ "record `result: fail` and withhold the stage."
274
+ )
275
+ lines = row.get("changedLines")
276
+ if isinstance(lines, int) and lines > LEAD_FIX_LINE_LIMIT:
277
+ failures.append(
278
+ f"{_LEAD_FIX_BLOCKING} {label} changed {lines} lines; a lead minor fix "
279
+ f"is limited to {LEAD_FIX_LINE_LIMIT}. A larger change belongs to a fix "
280
+ "run, where the verifiers review it."
281
+ )
282
+
283
+
284
+ def _check_settled_stage(
285
+ data: dict, implementation: dict, fixes: list[dict], evidence_contract: bool,
286
+ failures: list[str],
287
+ ) -> None:
288
+ """A settled stage holds no failed lead fix, and each FAIL row is answered.
289
+
290
+ An evidence-contract run's lead fixes were already rejected, so none of
291
+ them is read as failed or as answering a FAIL.
292
+ """
293
+ unsettled = [] if evidence_contract else [
294
+ index for index, row in enumerate(fixes) if row.get("result") != "pass"]
248
295
  if unsettled:
249
296
  failures.append(
250
297
  f"{_LEAD_FIX_BLOCKING} implementation.leadFixes{unsettled} recorded "
@@ -256,7 +303,8 @@ def _validate_lead_fixes(data: dict, failures: list[str]) -> None:
256
303
  who for who, row in _verifier_rows(data)
257
304
  if str(row.get("verdict") or "").strip() == "FAIL"
258
305
  }
259
- uncovered = sorted(rejected - lead_fixed_verifiers(implementation))
306
+ uncovered = sorted(rejected - lead_fixed_verifiers(
307
+ implementation, evidence_contract=evidence_contract))
260
308
  if uncovered:
261
309
  # 권고로 둔다 — 정착 여부는 종합 판정이 정하고, 수렴에서 반박된 한 검증자의
262
310
  # FAIL 위에 PASS 로 정착한 run 은 계약대로다. 막으면 그런 run 이 전부 멈춘다.
@@ -268,7 +316,6 @@ def _validate_lead_fixes(data: dict, failures: list[str]) -> None:
268
316
  "been withheld or answered by a passing lead minor fix."
269
317
  )
270
318
 
271
-
272
319
  _CORRECTION_BLOCKING = "correction-round BLOCKING:"
273
320
 
274
321
 
@@ -360,3 +407,78 @@ def _validate_verifier_fail_blocks_verdict(data: dict, failures: list[str]) -> N
360
407
  "the lead's to substitute "
361
408
  '(`_implementation-verifier.md` "All-verifier-failure policy").'
362
409
  )
410
+
411
+
412
+
413
+ def validate_verifier_execution_evidence(
414
+ data: dict, project_root: Path, manifest_path: Path,
415
+ manifest: Mapping[str, Any], failures: list[str],
416
+ ) -> None:
417
+ """Each verifier's `executionEvidence` in an evidence-contract run is its
418
+ current execution records.
419
+
420
+ A reference must be the latest run of a check under the verifier's latest
421
+ attempt of the invocation bound to the newest generation, with the bytes and
422
+ observation it recorded; a `not-run` row is not read.
423
+ """
424
+ try:
425
+ evidence = collect_report_evidence(project_root, manifest_path)
426
+ except ValueError as exc:
427
+ failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} verification execution "
428
+ f"evidence could not be collected: {exc}")
429
+ return
430
+ implementation = data.get("implementation")
431
+ rows = implementation.get("verifierResults") if isinstance(implementation, dict) else None
432
+ for index, row in enumerate(rows if isinstance(rows, list) else []):
433
+ if not isinstance(row, dict) or row.get("verdict") == "not-run":
434
+ continue
435
+ where = f"implementation.verifierResults[{index}]"
436
+ role_execution_ref = roster_verifier_role_execution_ref(manifest, row.get("verifier"))
437
+ if role_execution_ref is None:
438
+ failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} {where}.verifier "
439
+ f"`{row.get('verifier')}` names no roster verifier")
440
+ continue
441
+ verifiers = [evidence[role_execution_ref]] if role_execution_ref in evidence else []
442
+ matched: set[str] = set()
443
+ reported = row.get("executionEvidence") or []
444
+ for position, reference in enumerate(reported if isinstance(reported, list) else []):
445
+ errors, paths = reference_errors(
446
+ f"{where}.executionEvidence[{position}]", reference, verifiers,
447
+ )
448
+ failures.extend(f"{EXECUTION_EVIDENCE_BLOCKING} {error}" for error in errors)
449
+ matched |= paths
450
+ omitted = omitted_records(verifiers, matched)
451
+ if omitted:
452
+ failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} {where} omits the "
453
+ f"verifier's execution records {omitted}")
454
+
455
+
456
+ def validate_settled_round_was_reverified(
457
+ data: dict, project_root: Path, manifest_path: Path,
458
+ manifest: Mapping[str, Any], failures: list[str],
459
+ ) -> None:
460
+ """A stage settled after correction round N in an evidence-contract run
461
+ shows each verifier's records of generation N + 1, the one sealed after the
462
+ executor's fix."""
463
+ implementation = data.get("implementation")
464
+ if not isinstance(implementation, dict) or not _stage_settled(implementation):
465
+ return
466
+ rounds = [row.get("round") for row in implementation.get("correctionRounds") or []
467
+ if isinstance(row, dict) and isinstance(row.get("round"), int)]
468
+ if not rounds:
469
+ return
470
+ generation = generation_sealed_after_round(max(rounds))
471
+ expected = RunRef.from_manifest(manifest_path, manifest).verification_generation(
472
+ generation).resolve().relative_to(project_root.resolve()).as_posix()
473
+ for who, row in _verifier_rows(data):
474
+ if row.get("verdict") == "not-run":
475
+ continue
476
+ references = [reference for reference in row.get("executionEvidence") or []
477
+ if isinstance(reference, dict)]
478
+ if not references or any((reference.get("generation") or {}).get("path")
479
+ != expected for reference in references):
480
+ failures.append(
481
+ f"{_CORRECTION_BLOCKING} {who} settled the stage after correction "
482
+ f"round {max(rounds)} without execution records of generation "
483
+ f"{generation} (`{expected}`), the one sealed after the fix."
484
+ )
@@ -8,8 +8,8 @@ This directory owns candidate evaluation, vote completion, comparison projection
8
8
  |---|---|---|
9
9
  | IOS-1 | Candidate scores, coverage, votes and ranking are recomputed | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::validate_implementation_option_selection` |
10
10
  | IOS-2 | Blocked facts retain their user decision or technical evidence channel | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::validate_blocked_answer_channel` |
11
- | IOS-3 | A valid candidate needs two `feasible` votes, or the single vote when the user selected one designer | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::required_feasible_votes`; `scripts/okstra_ctl/phases/implementation_option_selection/tests/test_implementation_options.py::test_a_single_designer_vote_validates_its_candidate` |
12
- | IOS-4 | Candidate fingerprints deduplicate equivalent mechanisms | `scripts/okstra_ctl/phases/implementation_option_selection/tests/test_implementation_options.py::test_duplicate_candidates_share_a_fingerprint` |
11
+ | IOS-3 | A valid candidate needs two `feasible` votes, or the single vote when the user selected one designer | `scripts/okstra_ctl/phases/implementation_option_selection/validation.py::required_feasible_votes` |
12
+ | IOS-4 | Candidate fingerprints deduplicate equivalent mechanisms | unenforced |
13
13
 
14
14
  Report schemas remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json`, under `implementationOptionSelection`. Next-phase decisions belong to `prompts/lead/phase-routing.md`.
15
15
 
@@ -48,10 +48,11 @@ from okstra_ctl.plan_items import (
48
48
  lead_decision_basis,
49
49
  next_dispatch,
50
50
  planning_stage_ledger,
51
- reverify_item_ids,
51
+ queue_candidate_ids,
52
52
  reverify_prompt_text,
53
53
  self_fix_rounds,
54
54
  tie_vote_item_ids,
55
+ verified_content_hashes,
55
56
  voting_analyser_keys,
56
57
  with_rendered_by,
57
58
  with_response_format,
@@ -114,14 +115,9 @@ def _merged_ledger(
114
115
  def _previous_hashes(state_path: Path | None) -> dict[str, str]:
115
116
  if state_path is None or not state_path.is_file():
116
117
  return {}
117
- rows = _state_plan_body_items(_load_json_object(state_path), state_path)
118
- return {
119
- str(row["id"]): str(row["verifiedContentHash"])
120
- for row in rows
121
- if isinstance(row, Mapping)
122
- and isinstance(row.get("id"), str)
123
- and isinstance(row.get("verifiedContentHash"), str)
124
- }
118
+ return verified_content_hashes(
119
+ _state_plan_body_items(_load_json_object(state_path), state_path)
120
+ )
125
121
 
126
122
 
127
123
  def _queue_for(
@@ -138,9 +134,7 @@ def _queue_for(
138
134
  return tie_vote_item_ids(items, ledger, tied_ids)
139
135
  inputs = review_inputs or _review_inputs(items, planning, run_manifest, previous_rows)
140
136
  reusable = reusable_item_ids(previous_rows, inputs)
141
- candidates = set(dispatch_item_ids(items, ledger))
142
- if previous_hashes:
143
- candidates.update(reverify_item_ids(items, previous_hashes, ledger))
137
+ candidates = queue_candidate_ids(items, ledger, previous_hashes or {})
144
138
  return [item["id"] for item in items if item["id"] in candidates - reusable]
145
139
 
146
140
 
@@ -1148,13 +1142,20 @@ def _validate_prepared(args: argparse.Namespace) -> dict[str, Any]:
1148
1142
  **_queue_kwargs(args),
1149
1143
  )
1150
1144
  if actual.get("dispatchQueue") != expected_queue:
1151
- raise PlanItemContractError("prepared dispatch queue does not match")
1145
+ raise PlanItemContractError(
1146
+ "prepared dispatch queue does not match the queue derived from "
1147
+ "the current plan and state; prepare again, and pass "
1148
+ "validate-prepared the same --state that prepare used"
1149
+ )
1152
1150
  current_inputs = _review_inputs(
1153
1151
  expected["items"], _planning(source), args.run_manifest,
1154
1152
  _queue_kwargs(args).get("previous_rows", []),
1155
1153
  )
1156
1154
  if actual.get("reviewInputs") != current_inputs:
1157
- raise PlanItemContractError("prepared review evidence changed; prepare again")
1155
+ raise PlanItemContractError(
1156
+ "prepared review evidence changed; prepare again, and pass "
1157
+ "validate-prepared the same --state that prepare used"
1158
+ )
1158
1159
  if not getattr(args, "tie_vote", False):
1159
1160
  # 라운드 2+ 의 반대 의견 반입은 여기서만 검사된다. 봉투에서 빠지면
1160
1161
  # 프롬프트에도 빠지고, 반대한 워커는 자기 판정을 그대로 다시 적는다.
@@ -1648,18 +1649,11 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
1648
1649
  ledger = _merged_ledger(_planning(source), getattr(args, "run_manifest", None))
1649
1650
  if ledger:
1650
1651
  verification["stageLedger"] = ledger
1651
- previous = {
1652
- str(row["id"]): str(row["verifiedContentHash"])
1653
- for row in recorded
1654
- if isinstance(row, Mapping)
1655
- and isinstance(row.get("id"), str)
1656
- and isinstance(row.get("verifiedContentHash"), str)
1657
- }
1658
1652
  verification["dispatchQueue"] = _queue_for(
1659
1653
  extracted,
1660
1654
  _planning(source),
1661
1655
  getattr(args, "run_manifest", None),
1662
- previous,
1656
+ verified_content_hashes(recorded),
1663
1657
  previous_rows=recorded,
1664
1658
  )
1665
1659
  verification["gating"] = (
@@ -368,7 +368,7 @@ assignment. Keep the selected critic's existing model assignment.
368
368
  accepts the planning critic's verification audience; materialization resolves
369
369
  the declared assignment and reports the correct critic reference when the
370
370
  invented `reverify/critic-worker` reference is used.
371
- `tests/run/test_agent_prompt_cli.py` verifies the declared critic's reservation
371
+ the retired Python suite verifies the declared critic's reservation
372
372
  and dispatch identity plus this recovery diagnostic.
373
373
  That kind, not `reverify-r<N>`, is what this round takes: the verification
374
374
  prompt contract requires the renderer signature of the queue's canonical renderer,
@@ -411,22 +411,22 @@ CLI-wrapper calls follow the planned execution surface after
411
411
  consume only `modelExecutionValue`. A missing or invalid invocation contract blocks the
412
412
  round before any host or provider process starts.
413
413
 
414
- 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`; `tests/report/test_report_assembly.py` checks that invalid coverage creates no prepared queue.
414
+ 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
415
 
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, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. 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 `tests/run/test_plan_items.py`. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
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.
417
417
 
418
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 [...]`.
419
419
 
420
- **On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** 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`.
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`.
421
421
 
422
422
  **`--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
423
  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.
424
- 3. Dispatch uses the same wrapper infrastructure as finding convergence, so the `--role-slug` is the same canonical `<role>-worker` that convergence uses — not a round-specific slug. Result file path: `runs/<task-type>/worker-results/<role>-worker-plan-verify-r<N>-implementation-planning-<seq>.md` (e.g. `codex-worker-plan-verify-r1-implementation-planning-003.md`). **`<seq>` is the report's sequence** — the one in this run's `final-report-<task-type>-<seq>` filename, NOT the `workerResults` sequence the initial analysis results carry. The two are equal in most runs and diverge in some (`reports: 004` alongside `workerResults: 005` is a real case). Provenance no longer globs by either seq: it resolves the expected filenames from this run's team-state `workerDispatches[]` rows — the paths the dispatches actually recorded — and falls back to the seq glob only when no team-state is readable, saying so in its finding. The `-worker-` token is load-bearing twice over: §"Plan-body reverify prompt" requires the same anchor headers as convergence, whose `**Audit sidecar path:**` is derived by `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` inserting `-audit-` after that token — a slug without it makes the header underivable and the helper raises. Record each `planItems[].verdicts[].worker` as the same `<role>-worker` string, because provenance compares it to this filename's prefix. **Enforced:** `tests/contract/test_reverify_dispatch_anchors.py` derives the sidecar from the documented name and re-extracts the prefix the provenance resolver uses.
424
+ 3. Dispatch uses the same wrapper infrastructure as finding convergence, so the `--role-slug` is the same canonical `<role>-worker` that convergence uses — not a round-specific slug. Result file path: `runs/<task-type>/worker-results/<role>-worker-plan-verify-r<N>-implementation-planning-<seq>.md` (e.g. `codex-worker-plan-verify-r1-implementation-planning-003.md`). **`<seq>` is the report's sequence** — the one in this run's `final-report-<task-type>-<seq>` filename, NOT the `workerResults` sequence the initial analysis results carry. The two are equal in most runs and diverge in some (`reports: 004` alongside `workerResults: 005` is a real case). Provenance no longer globs by either seq: it resolves the expected filenames from this run's team-state `workerDispatches[]` rows — the paths the dispatches actually recorded — and falls back to the seq glob only when no team-state is readable, saying so in its finding. The `-worker-` token is load-bearing twice over: §"Plan-body reverify prompt" requires the same anchor headers as convergence, whose `**Audit sidecar path:**` is derived by `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()` inserting `-audit-` after that token — a slug without it makes the header underivable and the helper raises. Record each `planItems[].verdicts[].worker` as the same `<role>-worker` string, because provenance compares it to this filename's prefix. **Enforced:** the retired Python suite derives the sidecar from the documented name and re-extracts the prefix the provenance resolver uses.
425
425
  **Verdict provenance.** Every verdict recorded in `planItems[].verdicts[]` MUST trace back to a dispatch that actually returned a result file. The whole gate — classification, self-fix eligibility, promotion, `gateBlockedBy` — is computed from these votes, so an unbacked vote lets the round be skipped while the gate still reads `passed`. **Enforced (advisory):** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_plan_body_verdict_provenance` reports any `verdicts[].worker` with no recorded reverify dispatch whose result file exists; the finding is not in the blocking allowlist, so it surfaces as an advisory rather than failing the run — record it, never dismiss it. Recording a `verification-error` for a dispatch that produced no result is the correct way to represent a failed worker — inventing an `AGREE` is a contract violation, and renaming a result file to make provenance match destroys the link the check reads.
426
426
 
427
- 4. After all dispatches return, first read `planVerification` in the `worker-dispatch`, `team await --json`, or `agent-prompt link-result --json` response. When its `status` is `completed`, the runtime has already parsed all accepted verifier results, run the plan-body contract validator, and recorded the round. Use its `gateResult`, `verification` (including advisories), and `nextDispatch`; skip the separate collect/apply/plan-verify/complete/next-dispatch calls and continue with the decisions and self-fix procedure below. `pending` means the complete prepared verifier roster has not returned. `failed` stops automatic completion and returns the error; preserve the result files and repair the named defect. `needs-lead`, or a response without this field, uses the manual procedure below. In particular, self-fix re-verification retains the lead-owned cause groups and completion metadata. **Enforced:** `phases/implementation_planning/round_completion.py` and the automatic-round and execution-boundary tests in `tests/run/test_plan_items.py`.
427
+ 4. After all dispatches return, first read `planVerification` in the `worker-dispatch`, `team await --json`, or `agent-prompt link-result --json` response. When its `status` is `completed`, the runtime has already parsed all accepted verifier results, run the plan-body contract validator, and recorded the round. Use its `gateResult`, `verification` (including advisories), and `nextDispatch`; skip the separate collect/apply/plan-verify/complete/next-dispatch calls and continue with the decisions and self-fix procedure below. `pending` means the complete prepared verifier roster has not returned. `failed` stops automatic completion and returns the error; preserve the result files and repair the named defect. `needs-lead`, or a response without this field, uses the manual procedure below. In particular, self-fix re-verification retains the lead-owned cause groups and completion metadata. **Enforced:** `phases/implementation_planning/round_completion.py` and the automatic-round and execution-boundary tests in the retired Python suite.
428
428
 
429
- A critic correction sharing the analysers' round also returns `needs-lead`; retain the original round queue and use the manual `--append` procedure. The automatic-round tests in `tests/run/test_plan_items.py` enforce this boundary.
429
+ A critic correction sharing the analysers' round also returns `needs-lead`; retain the original round queue and use the manual `--append` procedure. The automatic-round tests in the retired Python suite enforce this boundary.
430
430
 
431
431
  In the manual procedure, lead aggregates verdicts per `P-*` item across workers and classifies each:
432
432
 
@@ -437,7 +437,7 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
437
437
  - `dissent-isolated` — only one worker `DISAGREE`s, others `AGREE`. On a blocking kind (`b` / `c` / `e`, and kind `a` on `P-Var-*`) this is scored `majority-disagree` and **blocks approval**. Advisory-only `DISAGREE(d)` and `P-Rb-*` stay recorded dissent and do not block. (Distinct from finding-convergence `worker-unique`, which means the *opposite*: only one worker AGREEs.)
438
438
  - `majority-disagree` — a *majority* of analysers `DISAGREE` (majority needs ≥2 participating non-error votes; rollback-ordering `DISAGREE(d)` votes are advisory and excluded from the tally), OR any blocking-kind dissent with ≥2 participating votes (a minority `DISAGREE` is not outvoted), OR an unresolved single-vote-blocking kind fires: one reproduced `DISAGREE(a)` on any item other than a `P-Var-*` one, or one reproduced `DISAGREE(f)` on a `P-Req-*` item (see §"Single-vote-blocking kinds"). This classification **blocks approval**. A valid critic correction is scored before these blocking rules, whether or not the analysers split evenly.
439
439
  - `needs-reverify` — one of two shapes the round could not settle.
440
- - **An even split on a blocking kind.** A panel splitting evenly (1-AGREE / 1-DISAGREE, 2-2, …) needs a critic decision. An unresolved single-vote-blocking kind remains `majority-disagree`; other unresolved splits are `needs-reverify`. Do **not** re-run the original two. Dispatch `critic-worker` immediately on those items only (`okstra plan-items prepare --tie-vote ...`, then `okstra plan-items prompt ...`). The prompt carries the analyser split and no other plan items. Read the answer with `okstra plan-items collect-verdicts --items <the --tie-vote plan-items artifact> --result critic-worker=<path> --output <envelope>` — `--items` takes that artifact, whose `dispatchQueue` is the tie items, so pointing the next step at the raw result is refused against this round's full queue. Record the critic vote as `verdicts[].worker = critic-worker` with `okstra plan-items apply-verdicts --state <plan-body-verification.json> --round <N> --append --items <the --tie-vote plan-items artifact> --result critic-worker=<path>` — `--items` persists the exact partial `dispatchQueue` used by verdict validation and `complete-round`. Earlier verdicts and completed-round history outside that queue remain unchanged. If a previous version saved the critic votes but left the full queue in state, the ordinary `okstra plan-items complete-round --state <state> --run-manifest <manifest> --round <N>` automatically reads this run's canonical prepared queue. It uses that queue when all votes recorded for this round are included, preserving a wider recorded batch when a later prepared queue excludes its votes. An explicit `--items <prepared artifact>` remains available for selecting an artifact. Enforced by `plan_items_cli._round_inputs` and `tests/run/test_plan_items.py` completion coverage. Do not fabricate new-round votes for already agreed items. Without it the result is checked against the whole persisted round queue and refused for every item the critic was never given (measured 2026-09-10: a 7-item tie round refused against 44 items), and the only way through was `--verdicts`, which the CLI's own help calls a historical envelope. Critic `AGREE` / `SUPPLEMENT` settles the split to `has-dissent`, including an earlier `DISAGREE(a)` or `DISAGREE(f)` on `P-Req-*`. This decision corrects the disputed judgement before single-vote blocking is evaluated; it does not delete the original dissent. Critic `DISAGREE` on a blocking kind is `majority-disagree`. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` fails an in-scope item that carries an even split on a blocking kind and has neither a `critic-worker` vote nor a `blocks: approval` clarification row, `_classify_plan_item_gate` scores the tie shape and fails a settled classification the votes do not support, and `okstra_ctl.plan_items.next_dispatch` returns kind `critic-tie` for exactly these items, so the tie round is the queue the CLI hands you rather than one you assemble. **With no critic on the roster the split is a user decision, not another round.** `okstra plan-items next-dispatch --state <plan-body-verification.json> --run-manifest <current-run-manifest.json>` answers `user-decision` (not `critic-tie`) when the run's `invocationAssignments` carries no `critic/*` entry, and its `itemIds` are the tie items. For each of them do what step 8 does for a surviving `majority-disagree`: `okstra approval-decision open` with `approvalContext.classification` set to `correctness-critical` when `_is_correctness_critical` is true, or `noncritical-dissent` otherwise, plus the matching `## 1. Clarification Items` row at `Blocks=approval`. Dispatch no further verification for those items. The `Blocks=approval` row is what withholds approval until the user disposes, exactly as for any other approval row; the gate retains unresolved single-vote blockers as `majority-disagree` and folds other `needs-reverify` items into `passed-with-dissent`, so the round closes on the gate it actually scored. A tie left with neither a critic vote nor a decision row surfaces as recorded dissent plus an `advisories[]` entry, not a round-blocking failure. **Enforced:** `okstra_ctl.plan_items.critic_is_rostered` reads the roster and `next_dispatch` returns the kind; `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` reads a `blocks: approval` row linked to the item as the settlement and emits its advisory only when neither settlement is recorded.
440
+ - **An even split on a blocking kind.** A panel splitting evenly (1-AGREE / 1-DISAGREE, 2-2, …) needs a critic decision. An unresolved single-vote-blocking kind remains `majority-disagree`; other unresolved splits are `needs-reverify`. Do **not** re-run the original two. Dispatch `critic-worker` immediately on those items only (`okstra plan-items prepare --tie-vote ...`, then `okstra plan-items prompt ...`). The prompt carries the analyser split and no other plan items. Read the answer with `okstra plan-items collect-verdicts --items <the --tie-vote plan-items artifact> --result critic-worker=<path> --output <envelope>` — `--items` takes that artifact, whose `dispatchQueue` is the tie items, so pointing the next step at the raw result is refused against this round's full queue. Record the critic vote as `verdicts[].worker = critic-worker` with `okstra plan-items apply-verdicts --state <plan-body-verification.json> --round <N> --append --items <the --tie-vote plan-items artifact> --result critic-worker=<path>` — `--items` persists the exact partial `dispatchQueue` used by verdict validation and `complete-round`. Earlier verdicts and completed-round history outside that queue remain unchanged. If a previous version saved the critic votes but left the full queue in state, the ordinary `okstra plan-items complete-round --state <state> --run-manifest <manifest> --round <N>` automatically reads this run's canonical prepared queue. It uses that queue when all votes recorded for this round are included, preserving a wider recorded batch when a later prepared queue excludes its votes. An explicit `--items <prepared artifact>` remains available for selecting an artifact. Enforced by `plan_items_cli._round_inputs` and the retired Python suite completion coverage. Do not fabricate new-round votes for already agreed items. Without it the result is checked against the whole persisted round queue and refused for every item the critic was never given (measured 2026-09-10: a 7-item tie round refused against 44 items), and the only way through was `--verdicts`, which the CLI's own help calls a historical envelope. Critic `AGREE` / `SUPPLEMENT` settles the split to `has-dissent`, including an earlier `DISAGREE(a)` or `DISAGREE(f)` on `P-Req-*`. This decision corrects the disputed judgement before single-vote blocking is evaluated; it does not delete the original dissent. Critic `DISAGREE` on a blocking kind is `majority-disagree`. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` fails an in-scope item that carries an even split on a blocking kind and has neither a `critic-worker` vote nor a `blocks: approval` clarification row, `_classify_plan_item_gate` scores the tie shape and fails a settled classification the votes do not support, and `okstra_ctl.plan_items.next_dispatch` returns kind `critic-tie` for exactly these items, so the tie round is the queue the CLI hands you rather than one you assemble. **With no critic on the roster the split is a user decision, not another round.** `okstra plan-items next-dispatch --state <plan-body-verification.json> --run-manifest <current-run-manifest.json>` answers `user-decision` (not `critic-tie`) when the run's `invocationAssignments` carries no `critic/*` entry, and its `itemIds` are the tie items. For each of them do what step 8 does for a surviving `majority-disagree`: `okstra approval-decision open` with `approvalContext.classification` set to `correctness-critical` when `_is_correctness_critical` is true, or `noncritical-dissent` otherwise, plus the matching `## 1. Clarification Items` row at `Blocks=approval`. Dispatch no further verification for those items. The `Blocks=approval` row is what withholds approval until the user disposes, exactly as for any other approval row; the gate retains unresolved single-vote blockers as `majority-disagree` and folds other `needs-reverify` items into `passed-with-dissent`, so the round closes on the gate it actually scored. A tie left with neither a critic vote nor a decision row surfaces as recorded dissent plus an `advisories[]` entry, not a round-blocking failure. **Enforced:** `okstra_ctl.plan_items.critic_is_rostered` reads the roster and `next_dispatch` returns the kind; `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_unresolved_tie_was_reverified` reads a `blocks: approval` row linked to the item as the settlement and emits its advisory only when neither settlement is recorded.
441
441
  - **A lone dissent nobody cross-verified** — a single-vote-blocking kind fired but the item has **fewer than 2 participating non-error votes**, i.e. the lone dissent was never cross-verified because its peer returned `verification-error`. A single-vote-blocking kind means "one *confirmed* DISAGREE is enough"; an unconfirmed one is not, and on a `P-Var-*` item none fires at all — its kind `a` never blocks on one vote and takes a majority like `b` / `e`. This does **not** block approval — blocking on it would make a worker failure produce a stricter gate than a healthy roster, the same paradox the ≥2-vote majority rule already rules out. The item is re-dispatched in the next round (step 7); if it survives the round budget it is promoted per step 8 with a Statement that says verification never completed. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_classify_plan_item_gate` returns `needs-reverify` for this shape and `_recompute_plan_body_gate` folds it into `passed-with-dissent`.
442
442
  - `contested` only meaningful when `maxRounds > 1`; at default `maxRounds=1`, fold any unresolved item into `partial-consensus`.
443
443
  5. Gate result resolution:
@@ -492,7 +492,7 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
492
492
  - 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
493
  - **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
494
  - **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.
495
- - **Loop termination.** The convergence command owns the round count and stop reason; the lead never edits either field in the state file. Both are recorded by `okstra plan-items complete-round`, and its two self-fix flags are not interchangeable. `--self-fix-group` is a claim that this round rewrote something, so it sets `selfFixGroups` and `selfFixRoundsApplied` and **requires** `--self-fix-stop-reason` — there is no default, because the value that used to fill in (`all-resolved`) is the one value step 8 reads as "nothing was left unresolved", which then forbids promoting the items the round did leave unresolved. `--self-fix-stop-reason` on its own is how a round that rewrote nothing records that the loop stops there; it writes `selfFixStopReason` and touches neither `selfFixGroups` nor `selfFixRoundsApplied`, because `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_self_fix_grouping` requires the highest `selfFixGroups[].round` to equal `selfFixRoundsApplied` — a round number raised without a group has no value that passes. That stop-only call is refused while a planner-fixable majority `DISAGREE` remains and no self-fix rewrite is recorded, because validate-run requires at least one rewrite before such an item may be promoted; the fix is the rewrite, recorded with `--self-fix-group`. **Enforced:** `okstra_ctl.plan_items_cli._reject_unbacked_self_fix_stop` runs validate-run's `_validate_self_fix_before_clarification` before writing; `tests/run/test_plan_items.py::test_complete_round_refuses_a_stop_reason_with_no_rewrite_behind_it`. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop:
495
+ - **Loop termination.** The convergence command owns the round count and stop reason; the lead never edits either field in the state file. Both are recorded by `okstra plan-items complete-round`, and its two self-fix flags are not interchangeable. `--self-fix-group` is a claim that this round rewrote something, so it sets `selfFixGroups` and `selfFixRoundsApplied` and **requires** `--self-fix-stop-reason` — there is no default, because the value that used to fill in (`all-resolved`) is the one value step 8 reads as "nothing was left unresolved", which then forbids promoting the items the round did leave unresolved. `--self-fix-stop-reason` on its own is how a round that rewrote nothing records that the loop stops there; it writes `selfFixStopReason` and touches neither `selfFixGroups` nor `selfFixRoundsApplied`, because `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_self_fix_grouping` requires the highest `selfFixGroups[].round` to equal `selfFixRoundsApplied` — a round number raised without a group has no value that passes. That stop-only call is refused while a planner-fixable majority `DISAGREE` remains and no self-fix rewrite is recorded, because validate-run requires at least one rewrite before such an item may be promoted; the fix is the rewrite, recorded with `--self-fix-group`. **Enforced:** `okstra_ctl.plan_items_cli._reject_unbacked_self_fix_stop` runs validate-run's `_validate_self_fix_before_clarification` before writing; the retired Python suite. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop:
496
496
  - `all-resolved` — no planner-fixable `majority-disagree` item remains. Exit.
497
497
  - `no-progress` — the round resolved **zero** planner-fixable items relative to the previous round. Exit even with budget left: the same rewrite would repeat. Newly *introduced* defects count against progress, so a rewrite that trades one defect for another stops the loop rather than churning. A round that re-targets only what the previous round left unresolved is this same conclusion reached one dispatch earlier — exit on it under this reason rather than paying for the round that proves it. **Enforced (advisory):** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_detect_self_fix_recurrence` warns on that shape and names this stop reason.
498
498
  - `max-rounds-reached` — the single automatic rewrite has been used. Exit to step 8. Count distinct `selfFixGroups[].round` values; `selfFixRoundsApplied` is the last verification round number, not the rewrite count. Extra verification batches before the rewrite do not increase the self-fix budget.
@@ -712,7 +712,7 @@ their text without adding foreign items to the plan-verification queue.
712
712
 
713
713
  Enforcement: `render_review_context` in `okstra_ctl.plan_review_context` selects
714
714
  the context; `test_plan_review_context_preserves_facts_and_falls_back_for_unknown_dependencies`
715
- in `tests/run/test_plan_items.py` checks retained facts and conservative fallback.
715
+ in the retired Python suite previously checked retained facts and conservative fallback.
716
716
 
717
717
  Carrying the packet does not license re-analysis. It is there so the verifier
718
718
  can resolve a plan item back to the requirement it claims to satisfy; the
@@ -721,7 +721,7 @@ not revisit the requirements themselves.
721
721
 
722
722
  **Enforced:** only by the renderer — `_render_inputs` in
723
723
  `scripts/okstra_ctl/phases/implementation_planning/authoring.py`, asserted by
724
- `_assert_input_paths` in `tests/run/test_plan_items.py`. No dispatch check counts
724
+ `_assert_input_paths` in the retired Python suite. No dispatch check counts
725
725
  the packet line for this round: the `Primary analysis packet` count in
726
726
  `scripts/okstra_ctl/worker_prompt_contract.py` `_validate_prompt_for_plan` runs
727
727
  only for the `analysis` audience, and a plan-verify dispatch is a
@@ -911,4 +911,4 @@ An item with no recorded vote carrying a round number gets no block, and an enve
911
911
 
912
912
  The two spellings are different anchors for different artifacts: `**Prior round dissent**` is the block `prompt` puts in the prompt, `**Prior dissent**` is the line the worker puts in its result. `scripts/okstra_ctl/verdict_blocks.py` parses the result line into the verdict block when it is present and leaves it empty when it is not, so an omitted answer line is still silent — the prompt is what is now guaranteed, not the response.
913
913
 
914
- The analyser round limit is enforced by `plan_items_cli._validate_advisory_round` at verdict application and completion. It does not limit critic correction rounds or require an even split. `apply-verdicts --append` can update the critic’s current verdict in a later round while preserving analyser votes and completed round history. Normal invocation identity and result-provenance checks still apply. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_critic_gate_class` applies valid critic corrections before analyser voting rules. `tests/run/test_plan_items.py` covers second and third critic rounds on tied and majority-dissent items; `tests/contract/test_plan_body_verification.py` covers critic correction of both agreement and disagreement.
914
+ The analyser round limit is enforced by `plan_items_cli._validate_advisory_round` at verdict application and completion. It does not limit critic correction rounds or require an even split. `apply-verdicts --append` can update the critic’s current verdict in a later round while preserving analyser votes and completed round history. Normal invocation identity and result-provenance checks still apply. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_critic_gate_class` applies valid critic corrections before analyser voting rules. the retired Python suite covers second and third critic rounds on tied and majority-dissent items; the retired Python suite covers critic correction of both agreement and disagreement.
@@ -1677,6 +1677,9 @@ def _manifest_seq_for_report(report_path: Path, category: str) -> set[str]:
1677
1677
  배정한다(`paths.next_run_seq`). 같은 run dir 로 재실행하면 카테고리마다
1678
1678
  다른 속도로 올라가 reports 017 / state 025 같은 분기가 실제로 생긴다.
1679
1679
  매니페스트의 `runSequencesByCategory` 만이 그 분기를 한 런으로 묶는 기록이다.
1680
+ The divergence above describes runs prepared before `compute_run_paths`
1681
+ gave every category one seq; newer runs share one seq across categories,
1682
+ and this mapping still resolves the older ones.
1680
1683
  """
1681
1684
  seq = _report_run_seq(report_path)
1682
1685
  manifests_dir = report_path.parent.parent / "manifests"
@@ -2985,6 +2988,16 @@ def _validate_planning_conformance_declared(
2985
2988
  )
2986
2989
 
2987
2990
  failures.extend(stage_validation_executability_errors(ip))
2991
+ from okstra_ctl.stage_command_commits import stage_command_commit_errors_from_task_state
2992
+
2993
+ failures.extend(stage_command_commit_errors_from_task_state(data_path, data))
2994
+ failures.extend(_surface_declaration_failures(data, surface_patterns, implemented))
2995
+
2996
+
2997
+ def _surface_declaration_failures(
2998
+ data: dict, surface_patterns: object, implemented: frozenset[int],
2999
+ ) -> list[str]:
3000
+ failures: list[str] = []
2988
3001
  for conflict in exempt_stage_surface_conflicts(data, surface_patterns):
2989
3002
  if conflict["stage"] in implemented:
2990
3003
  continue
@@ -3013,6 +3026,7 @@ def _validate_planning_conformance_declared(
3013
3026
  "the wider set after the work is done, where the approved plan can "
3014
3027
  "no longer be corrected."
3015
3028
  )
3029
+ return failures
3016
3030
 
3017
3031
 
3018
3032
  def _is_activity_contract_v1_planning(run_manifest: dict) -> bool:
@@ -2,7 +2,7 @@
2
2
 
3
3
  Keep `commandOrObservation` executable when the checklist calls for a command. Put explanations and existing-helper citations in the checklist's `check` text, outside the command. Do not append prose after a semicolon. The plan-item renderer separates legacy `existing helper: <file>:<lines>` suffixes, and `verification-target` supplies the same executable command to every verifier.
4
4
 
5
- Validation commands are executable inputs: preserve their newlines, quotes, and code bodies. Use frozen dependency installation (`npm ci`, `pnpm install --frozen-lockfile`, or the package manager's equivalent). Name QA scripts with absolute task-artifact paths when a command runs from a stage worktree; `.okstra/tasks/...` relative to that worktree does not point to the project task. `stage_validation_executability_errors` enforces command restrictions at planning validation, implementation entry, and report preflight, including advisory plan-body runs.
5
+ Validation commands are executable inputs: preserve their newlines, quotes, and code bodies. Use frozen dependency installation (`npm ci`, `pnpm install --frozen-lockfile`, or the package manager's equivalent). Name QA scripts with absolute task-artifact paths when a command runs from a stage worktree; `.okstra/tasks/...` relative to that worktree does not point to the project task. `stage_validation_executability_errors` enforces command restrictions at planning validation, implementation entry, and report preflight, including advisory plan-body runs. A commit a stage-gating command names must be in that stage's worktree, which holds only the implementation anchor and the stages in its `dependsOn` closure; comparing against another branch's head fails before any edit. `stage_command_commit_errors` rejects such a row at planning validation and implementation entry.
6
6
 
7
7
  Plan for the actual worktree layout before approval. Shared documentation directories can be links to the main checkout. Choose a build command compatible with those links (for example, an installed Next.js version may provide `next build --webpack`); verify the available option rather than assuming it. Do not plan for a verifier to move links or repair its environment. Compare negative-case assertions with the brief and the script body: a requirement to cache existing assets does not establish that missing assets should be cached. Record any changed expectation in a new plan revision; preserve the earlier approved plan.
8
8
 
@@ -48,7 +48,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
48
48
  - Every stage number in the ledger is taken. This report declares every one of them — rows run `1..N` with no gap — and a new stage takes the next number after the highest one listed; numbers are never reused or reordered. A report that declares only its new stages satisfies neither rule and is refused twice over. **Enforced:** `okstra_ctl.stage_map._validate_stage_numbers` rejects the gap in every published plan it parses, so `okstra prepare` refuses the implementation run (`okstra_ctl.run._parse_stage_map_into_ctx`) and the Stage Ledger of every later run reads as `unreadable`; `validators/validate-implementation-plan-stages.py` check **S2** reports the same defect at authoring time. To drop a stage that has not started — `ready` or `blocked` in the ledger — keep its row and body in place in both `stageMap[]` and `stages[]` and set that `stageMap[]` row's `status` to `cancelled`; its number stays taken, and stage selection, whole-task final-verification, integration and release-handoff skip it. A `done` or `active` stage is never cancelled: to change finished work, keep that stage and add a correction stage numbered after the highest one. No remaining stage may depend on a cancelled one — point it at the stage that replaces it. **Enforced:** `validators/validate-implementation-plan-stages.py` check **S14** rejects a cancelled stage the ledger records `done` or `active` and a dependency on a cancelled stage.
49
49
  - The ledger answers two questions from two sources, and the block names both. `sourcePlan` is the plan the completed stages were actually built against; `latestPlan` is the plan the `stages` list came from and is therefore the numbering authority. When they differ, the completed work followed the former and the highest taken number comes from the latter.
50
50
  - A `planDivergence` entry means one of two things: the two plans disagree about a stage that is already `done` — the same number naming different work, or a completed stage the latest plan no longer declares — or the plan the completed stages were built against could not be read at all, so that comparison never ran. Both block the same way: do not pick one of the two plans yourself; register it as a `Blocks=approval` clarification row and assign no new stage number until it is resolved. Completed stages built against an *earlier* plan are not a divergence — that is the normal shape of an amended plan and the ledger folds it silently.
51
- - The block is absent ONLY on a task's first planning run. Its absence then means there is no prior plan, not that no stage is done. When the ledger could not be read, the packet names the source and reason. Continue planning to repair unambiguous dependency notation in the new report, retaining every stage number and title and every completed stage body. Record the original and corrected values with their source. Do not overwrite the prior report or select an older plan. Assign no new stage number until the corrected Stage Map validates; unresolved dependency meaning remains a blocker. The preparation behavior is covered by `tests/run/test_stage_ledger_prepare.py`; preservation of author intent remains a review guideline.
51
+ - The block is absent ONLY on a task's first planning run. Its absence then means there is no prior plan, not that no stage is done. When the ledger could not be read, the packet names the source and reason. Continue planning to repair unambiguous dependency notation in the new report, retaining every stage number and title and every completed stage body. Record the original and corrected values with their source. Do not overwrite the prior report or select an older plan. Assign no new stage number until the corrected Stage Map validates; unresolved dependency meaning remains a blocker. The preparation behavior is covered by the retired Python suite; preservation of author intent remains a review guideline.
52
52
  - **Prior Planning Run (read before re-deriving anything):** on a re-run the packet carries a `## Prior Planning Run` block with the previous planning run's clarification rows, its Stage Map one line per stage, the findings its convergence left `contested` / `worker-unique`, and the path to the report itself. It is context, not an approved plan — the previous run did not reach approval. Use it so a stage you are not changing keeps the wording it already had and a settled question is not re-opened under a new `P-*` number; where the brief, the directive, or a clarification answer disagrees with it, they win. The block is absent on a first planning run and on a clarification re-run, which receives the same rows through `## Clarification Carry-In Extract` instead. **Enforced:** `okstra_ctl.prior_planning.build_prior_planning_summary` assembles it and `okstra_ctl.analysis_packet._prior_planning_block` renders it; nothing checks that a worker read it.
53
53
  - Primary focus areas:
54
54
  - requirement gaps
@@ -272,7 +272,7 @@ Follow the conditional reading table for later rounds and validation failures.
272
272
  The command keeps the filename in the read trace used by
273
273
  `validators/validate_session_conformance.py` `_ENTRY_GUARD_READS`.
274
274
  The bounded output is checked by
275
- `tests/contract/test_contract_examples_execute.py::test_plan_body_common_read_keeps_gate_rules`.
275
+ the retired Python suite.
276
276
 
277
277
  Distinct from Phase 5.5 finding convergence:
278
278
 
@@ -293,7 +293,7 @@ For a new `implementation-planning` run, the fixed order is initial verification
293
293
 
294
294
  An `AGREE` response records the considered counterexample and exclusion reason in its note; unverified external material is `verification-error`, not `DISAGREE`.
295
295
  2. Dispatch a single plan-body reverify round to every analyser worker in the run's roster. `Report writer worker` is NOT a participant in this round.
296
- Read `planVerification` in the dispatch, await, or native result-link response. `status=completed` means the runtime has already applied the accepted results, checked the plan-body contract, and completed the round. Use its gate, advisories, and next dispatch and skip steps 3–4. `pending` waits for the remaining verifiers; `failed` stops for the returned defect; `needs-lead` retains the manual path, including self-fix cause-group recording. Enforcement: `phases/implementation_planning/round_completion.py` and automatic-round integration tests in `tests/run/test_plan_items.py`.
296
+ Read `planVerification` in the dispatch, await, or native result-link response. `status=completed` means the runtime has already applied the accepted results, checked the plan-body contract, and completed the round. Use its gate, advisories, and next dispatch and skip steps 3–4. `pending` waits for the remaining verifiers; `failed` stops for the returned defect; `needs-lead` retains the manual path, including self-fix cause-group recording. Enforcement: `phases/implementation_planning/round_completion.py` and automatic-round integration tests in the retired Python suite.
297
297
  3. Record each verifier Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker-id>=<result.md> --round <N>`. Python validates every submitted `P-*` identifier against the current convergence state and overwrites only that round's verdicts. Then resolve the gate result to one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`.
298
298
  4. After `okstra plan-verify` succeeds, run `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. Python reads the current worker assignments, atomically appends the convergence-owned history, and updates its nested final projection. This state is the only plan-verification input report assembly reads.
299
299
  5. Record every *in-scope execution* `majority-disagree` decision through `okstra approval-decision`; record its plan and clarification links only on activities. Do not promote `observed` / `deferred` / `record` items, and do not append `clarificationItems[]` directly.
@@ -53,7 +53,7 @@ taskType: "{{FM_TASK_TYPE}}"
53
53
 
54
54
  > Analysers MUST NOT expand option candidates, file lists, or step plans into items listed here. If an analyser believes an excluded item must be addressed to satisfy the requirement, it is reported as a recommended follow-up task in the final report — never silently folded into a candidate option. If this section is left empty, analysers treat any change beyond what `Requirement Summary` explicitly demands as out of scope by default.
55
55
 
56
- **Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
56
+ **Enforced (delivery only):** the retired Python suite pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
57
57
 
58
58
  ## Planning Concerns
59
59
 
@@ -192,7 +192,7 @@ Phase-local tests exercise planning guidance and input selection. Shared tests r
192
192
  | ID | Guarantee | Enforcement |
193
193
  |---|---|---|
194
194
  | P-1 | Direction realization preserves the selected mechanism, boundaries, planning invariants and user constraints. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_direction_realization_errors` |
195
- | P-2 | Phase packages do not import other phases or the common run assembler. | `tests/contract/test_phase_catalog.py::test_a_phase_package_does_not_import_another_phase_or_the_assembler` |
195
+ | P-2 | Phase packages do not import other phases or the common run assembler. | unenforced |
196
196
  | P-3 | Each planned stage traces to an explicitly enumerated requirement coverage citation. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_validate_stage_has_requirement` |
197
197
  | P-4 | Requirement sources resolve through admissible provenance and match declared brief references. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_validate_requirement_provenance` |
198
198
  | P-5 | Detector snapshot evidence matches a fresh detection over the plan and rejects duplicate stage/kind rows. | `scripts/okstra_ctl/phases/implementation_planning/report.py::project_design` |
@@ -216,13 +216,20 @@ def _submit_selected_direction_pick(state: WizardState, value: str) -> Optional[
216
216
  resolve_selected_direction(report, expected_task_key=_task_key(state))
217
217
  except (DirectionSelectionError, UserResponseError) as exc:
218
218
  raise WizardError(str(exc)) from exc
219
+ if _settle_selected_direction(state, path):
220
+ return t["echo_variants"]["cleared_clarification"].format(value=path) + recorded
221
+ return f"selected-direction: {path}{recorded}"
222
+
223
+
224
+ def _settle_selected_direction(state: WizardState, path: str) -> bool:
225
+ """Returns whether a clarification response was cleared."""
219
226
  state.selected_direction_path = path
220
227
  # 두 입력은 상호 배타다 — 방향이 정해진 순간 이 런은 새 계획이고,
221
228
  # clarification 자리에 남은 값은 render-bundle 이 거절할 이유일 뿐이다.
222
229
  # 거절을 여기서 앞당기는 대신 값을 비우고, 무엇이 비워졌는지 echo 로
223
230
  # 알린다. 사용자 답변은 손실되지 않는다: 그 사이드카는
224
231
  # `--selected-direction` 경로로 계획 런에 첨부된다(`run.py` 참조).
225
- if state.clarification_response_path:
226
- state.clarification_response_path = ""
227
- return t["echo_variants"]["cleared_clarification"].format(value=path) + recorded
228
- return f"selected-direction: {path}{recorded}"
232
+ if not state.clarification_response_path:
233
+ return False
234
+ state.clarification_response_path = ""
235
+ return True