okstra 0.232.0 → 0.233.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +8 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +36 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +279 -2
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +31 -41
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  77. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  78. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  79. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  80. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  81. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  82. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  83. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  84. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  85. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  86. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  87. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  88. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  89. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  90. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  91. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  92. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  93. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  94. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  95. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  96. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  97. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  98. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  99. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  100. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  101. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  102. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  103. package/runtime/python/okstra_ctl/material.py +2 -0
  104. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  105. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  106. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  107. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  108. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  109. package/runtime/python/okstra_ctl/paths.py +6 -1
  110. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  111. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  112. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  113. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  114. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  115. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  116. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  117. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  118. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  119. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  120. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  121. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  122. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  123. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  124. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  125. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  126. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  127. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  128. package/runtime/python/okstra_ctl/render.py +28 -2
  129. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  130. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  131. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  132. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  133. package/runtime/python/okstra_ctl/report_language.py +4 -1
  134. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  135. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  136. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  137. package/runtime/python/okstra_ctl/run.py +43 -35
  138. package/runtime/python/okstra_ctl/run_context.py +10 -1
  139. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  140. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  141. package/runtime/python/okstra_ctl/task_query.py +239 -0
  142. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  143. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  144. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  145. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  146. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  147. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  148. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  149. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  150. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  151. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  152. package/runtime/python/okstra_project/state.py +20 -0
  153. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  154. package/runtime/python/okstra_token_usage/cli.py +23 -10
  155. package/runtime/python/okstra_token_usage/collect.py +25 -22
  156. package/runtime/python/okstra_token_usage/policy.py +193 -0
  157. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  158. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  159. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  160. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  161. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  162. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  163. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  164. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  165. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  166. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  167. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  168. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  169. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  170. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  171. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  172. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  173. package/runtime/skills/okstra-run/SKILL.md +55 -183
  174. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  175. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  176. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  177. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  178. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  179. package/runtime/templates/manager/view.template.html +4 -0
  180. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  181. package/runtime/templates/trace/trace.template.md +42 -0
  182. package/runtime/validators/checks/fixtures-02.py +25 -33
  183. package/runtime/validators/validate-run.py +93 -36
@@ -19,6 +19,7 @@ from .paths import (
19
19
  task_timeline_file,
20
20
  )
21
21
  from .worker_artifacts import worker_artifact_paths
22
+ from .report_contract import report_authoring_format, report_authoring_suffix
22
23
  from .verification_input_ref import (
23
24
  VerificationInputReference, artifact_fields, artifact_fields_from_context,
24
25
  )
@@ -322,6 +323,8 @@ def _hydrate_active_source_artifacts(ctx: Mapping[str, str]) -> dict[str, str]:
322
323
 
323
324
  def _compact_run_hints(ctx: Mapping[str, Any]) -> dict[str, Any]:
324
325
  return {
326
+ "reportAuthoringFormat": ctx.get("REPORT_AUTHORING_FORMAT", "markdown-v1"),
327
+ "usageAccountingPolicy": ctx.get("USAGE_ACCOUNTING_POLICY", "strict"),
325
328
  "runRoot": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
326
329
  "stage": ctx.get("RUN_STAGE", ""),
327
330
  "fileSuffix": ctx.get("RUN_FILE_SUFFIX", ""),
@@ -342,10 +345,14 @@ def _hydrate_from_hints(
342
345
  hints: Mapping[str, Any],
343
346
  timestamps: Any,
344
347
  ) -> dict[str, Any]:
348
+ from okstra_token_usage.policy import usage_accounting_policy
349
+
345
350
  paths = _build_path_set(identity, hints)
346
351
  filenames = _filename_fields(paths)
347
352
  relative = _relative_fields(paths["project_root"], paths)
348
353
  return {
354
+ "REPORT_AUTHORING_FORMAT": paths["report_authoring_format"],
355
+ "USAGE_ACCOUNTING_POLICY": usage_accounting_policy(_mapping(hints.get("run"))),
349
356
  **_identity_fields(identity),
350
357
  **_runtime_fields(paths),
351
358
  **_absolute_fields(paths),
@@ -361,12 +368,14 @@ def _build_path_set(identity: Mapping[str, Any], hints: Mapping[str, Any]) -> di
361
368
  workspace_root = Path(str(identity.get("workspaceRoot", "")))
362
369
  project_hints = _mapping(hints.get("project"))
363
370
  run_hints = _mapping(hints.get("run"))
371
+ authoring_format = report_authoring_format(run_hints)
364
372
  task_root = _project_path(project_root, _task_root_hint(hints))
365
373
  run_root = _project_path(project_root, str(run_hints.get("runRoot", "")))
366
374
  task_type_segment = _segment(identity, "taskType")
367
375
  sequences = _sequences(run_hints)
368
376
  suffixes = _suffixes(task_type_segment, sequences)
369
377
  paths = {
378
+ "report_authoring_format": authoring_format,
370
379
  "project_root": project_root,
371
380
  "workspace_root": workspace_root,
372
381
  "okstra_root": _project_path(project_root, str(project_hints.get("okstraRoot", OKSTRA_RELATIVE))),
@@ -382,7 +391,7 @@ def _build_path_set(identity: Mapping[str, Any], hints: Mapping[str, Any]) -> di
382
391
  "suffixes": suffixes,
383
392
  }
384
393
  paths.update(_task_path_set(task_root))
385
- paths.update(_run_path_set(run_root, task_type_segment, sequences, suffixes))
394
+ paths.update(_run_path_set(run_root, task_type_segment, sequences, suffixes, authoring_format))
386
395
  paths.update(_discovery_path_set(paths["discovery_dir"]))
387
396
  return paths
388
397
 
@@ -413,6 +422,7 @@ def _run_path_set(
413
422
  task_type_segment: str,
414
423
  sequences: Mapping[str, str],
415
424
  suffixes: Mapping[str, str],
425
+ authoring_format: str,
416
426
  ) -> dict[str, Path]:
417
427
  run_prompts = run_dir / "prompts"
418
428
  worker_results = run_dir / "worker-results"
@@ -434,7 +444,7 @@ def _run_path_set(
434
444
  if task_type_segment == "implementation"
435
445
  else run_dir / "carry"
436
446
  ),
437
- **_run_files(run_dir, run_prompts, worker_results, task_type_segment, sequences, suffixes),
447
+ **_run_files(run_dir, run_prompts, worker_results, task_type_segment, sequences, suffixes, authoring_format),
438
448
  }
439
449
 
440
450
 
@@ -445,6 +455,7 @@ def _run_files(
445
455
  task_type_segment: str,
446
456
  sequences: Mapping[str, str],
447
457
  suffixes: Mapping[str, str],
458
+ authoring_format: str,
448
459
  ) -> dict[str, Path]:
449
460
  run_manifests = run_dir / "manifests"
450
461
  run_state = run_dir / "state"
@@ -478,7 +489,7 @@ def _run_files(
478
489
  "codex_worker_result": worker_results / f"codex-worker{suffixes['worker_results']}.md",
479
490
  "antigravity_worker_result": worker_results / f"antigravity-worker{suffixes['worker_results']}.md",
480
491
  "report_writer_worker_result": worker_results / f"report-writer-worker{suffixes['worker_results']}.md",
481
- "report_writer_narrative": worker_results / f"report-writer-narrative{suffixes['worker_results']}.md",
492
+ "report_writer_narrative": worker_results / f"report-writer-narrative{suffixes['worker_results']}{report_authoring_suffix(authoring_format)}",
482
493
  "approval_decisions": run_state / f"approval-decisions-{task_type_segment}-{sequences['state']}.json",
483
494
  "design_preparation": run_state / f"design-preparation-{task_type_segment}-{sequences['state']}.json",
484
495
  "plan_body_verification": run_state / f"plan-body-verification-{task_type_segment}-{sequences['state']}.json",
@@ -557,6 +557,7 @@ def compute_run_paths(
557
557
  task_type: str,
558
558
  run_seq_override: Optional[int] = None,
559
559
  stage: Optional[int] = None,
560
+ report_authoring_format: str = "markdown-v1",
560
561
  ) -> dict:
561
562
  """주어진 identity 와 task-type 에 대해 모든 path/segment 값을 계산해
562
563
  dict 로 돌려준다. 부수효과 없음.
@@ -688,7 +689,10 @@ def compute_run_paths(
688
689
  codex_worker_result = worker_results / f"codex-worker{suffixes['worker_results']}.md"
689
690
  antigravity_worker_result = worker_results / f"antigravity-worker{suffixes['worker_results']}.md"
690
691
  report_writer_worker_result = worker_results / f"report-writer-worker{suffixes['worker_results']}.md"
691
- report_writer_narrative = worker_results / f"report-writer-narrative{suffixes['worker_results']}.md"
692
+ from .report_contract import report_authoring_suffix
693
+
694
+ authoring_suffix = report_authoring_suffix(report_authoring_format)
695
+ report_writer_narrative = worker_results / f"report-writer-narrative{suffixes['worker_results']}{authoring_suffix}"
692
696
  approval_decisions = run_state / f"approval-decisions-{task_type_segment}-{seqs['state']}.json"
693
697
  design_preparation = run_state / f"design-preparation-{task_type_segment}-{seqs['state']}.json"
694
698
  plan_body_verification = run_state / f"plan-body-verification-{task_type_segment}-{seqs['state']}.json"
@@ -714,6 +718,7 @@ def compute_run_paths(
714
718
  ).joinpath(*RUN_VALIDATOR_RELATIVE)
715
719
 
716
720
  abs_paths = {
721
+ "REPORT_AUTHORING_FORMAT": report_authoring_format,
717
722
  "PROJECT_ID": project_id,
718
723
  "PROJECT_ROOT": str(project_root),
719
724
  "WORKSPACE_ROOT": str(workspace_root),
@@ -31,6 +31,7 @@ class PhaseRecord:
31
31
  migrated: bool
32
32
  view_module: str
33
33
  view_function: str
34
+ requires_host_rules: bool
34
35
 
35
36
 
36
37
  def _view(package_name: str, function: str, *, phase_package: bool) -> tuple[str, str]:
@@ -44,9 +45,11 @@ def _record(
44
45
  package_name: str,
45
46
  migrated: bool,
46
47
  view_function: str,
48
+ *,
49
+ requires_host_rules: bool = False,
47
50
  ) -> PhaseRecord:
48
51
  module, function = _view(package_name, view_function, phase_package=migrated)
49
- return PhaseRecord(task_type, package_name, migrated, module, function)
52
+ return PhaseRecord(task_type, package_name, migrated, module, function, requires_host_rules)
50
53
 
51
54
 
52
55
  # 이전되지 않은 단계는 기존 ``prompts/profiles`` 위치를 명시적으로 쓴다.
@@ -67,8 +70,14 @@ PHASES: tuple[PhaseRecord, ...] = (
67
70
  True,
68
71
  "build_implementation_option_selection_view",
69
72
  ),
70
- _record("implementation-planning", "implementation_planning", True, "build_implementation_planning_view"),
71
- _record("implementation", "implementation", True, "build_implementation_view"),
73
+ _record(
74
+ "implementation-planning", "implementation_planning", True,
75
+ "build_implementation_planning_view", requires_host_rules=True,
76
+ ),
77
+ _record(
78
+ "implementation", "implementation", True,
79
+ "build_implementation_view", requires_host_rules=True,
80
+ ),
72
81
  _record("final-verification", "final_verification", True, "build_final_verification_view"),
73
82
  _record("release-handoff", "release_handoff", True, "build_release_handoff_view"),
74
83
  _record("discussion", "discussion", True, "build_discussion_view"),
@@ -224,13 +233,21 @@ def _report_template_filename(task_type: str, logical_name: str) -> str | None:
224
233
 
225
234
 
226
235
 
227
- def host_rules(asset_root: Path, task_type: str) -> Path:
228
- """선택된 단계의 호스트 지침을 같은 자산 루트에서 찾는다."""
236
+ def host_rules(asset_root: Path, task_type: str) -> Path | None:
237
+ """선언된 단계의 호스트 지침을 같은 자산 루트에서 찾고 누락을 거부한다."""
229
238
  record = phase_record(task_type)
239
+ if not record.requires_host_rules:
240
+ return None
230
241
  root = package_root(asset_root) if record.migrated else None
231
242
  if root is not None:
232
- return root / "phases" / record.package_name / "host-rules.md"
233
- return asset_root / "prompts" / "host-orchestration" / f"{task_type}.md"
243
+ path = root / "phases" / record.package_name / "host-rules.md"
244
+ else:
245
+ path = asset_root / "prompts" / "host-orchestration" / f"{task_type}.md"
246
+ if not path.is_file():
247
+ raise PhaseAssetError(
248
+ f"host orchestration rules file not found for task-type {task_type}: {path}"
249
+ )
250
+ return path
234
251
 
235
252
 
236
253
  def profile_sidecar(asset_root: Path, logical_name: str) -> Path:
@@ -6,9 +6,9 @@ to recover a stale stage SHA, and what the chaining queue does when the next
6
6
  stage is not ready. They are not lead phase rules — the lead's rules live in
7
7
  `prompts/profiles/`.
8
8
 
9
- This file is the single source. Two surfaces are generated from it: the
10
- `okstra-run` skill body (marker block, synced by `tools/sync-skill-fragments.mjs`)
11
- and each run's `instruction-set/host-orchestration-rules.md`. Edit here.
9
+ This file is the single source. The wizard returns its path for the host to read
10
+ before preparation. Each run's `instruction-set/host-orchestration-rules.md` is
11
+ generated from it at prepare time. Edit here.
12
12
 
13
13
  ### Step 5.1 (implementation only): blocking local conformance waiver offer
14
14
 
@@ -29,8 +29,10 @@ Do not scan holistically and stop when it "looks fine". Work the matrix exhausti
29
29
 
30
30
  Use the captured `review-rules.json` IDs and `clean-code.md` "Finding evidence
31
31
  and grading" for every finding. Apply M1 and M2 to each changed function, including
32
- named test helpers. Execution correctness does not downgrade a clear naming or
33
- readability violation. Return a plan conflict when the authorized placement cannot
32
+ named test helpers. Establish an observable defect, an explicit applicable project
33
+ rule breach or a concrete design or maintenance impact; a preferred name or flow
34
+ alone is insufficient. Correct execution does not waive an established violation.
35
+ Return a plan conflict when the authorized placement cannot
34
36
  satisfy the rules; do not retain a violation solely to obey a file restriction.
35
37
  Resolve conflicts by `overview.md` policy precedence: explicit repository
36
38
  instructions and declared architecture, the common pack, then surrounding code
@@ -38,19 +40,19 @@ conventions. Existing violations alone do not waive an explicit rule.
38
40
 
39
41
  1. **List every changed file:** `git diff --name-only <stage-base>..HEAD`. Apply the shared census exclusion policy and record each exclusion with its reason; executable configuration is not excluded by extension alone. Cover the retained worklist to the end; no sampling.
40
42
  2. **Classify each file and select its rule set** from the conventions the preflight already loaded (do NOT re-derive the rules here — read them from the routed pack):
41
- - any file retained by the shared census exclusion policy → applicable `clean-code.md` checks: truthful + standalone names, one identifier one meaning per file (a key parameter must not take the name a sibling signature gives the entity), plain-English summary test, cohesive responsibility, manageable complexity and consistent abstraction levels, DRY (incl. scattered domain literals + documented forks), YAGNI, no magic numbers, shallow nesting, comments explain why. More than 50 effective function lines prompts closer review; length alone is not a finding or a reason to split.
43
+ - any file retained by the shared census exclusion policy → applicable `clean-code.md` checks: truthful + standalone names, one identifier one meaning per file (a key parameter must not take the name a sibling signature gives the entity), cohesive responsibility, manageable complexity and consistent abstraction levels, DRY (incl. scattered domain literals + documented forks), YAGNI, meaningful names for policy values and units, control flow whose decisions and exit paths can be followed, comments explain why. Function size, deep nesting and inline phases prompt closer review; counts alone are not findings or reasons to extract code.
42
44
  - The YAGNI cell also counts callers, not just their existence: an abstraction layer this diff *introduces* — helper module, strategy / factory / builder, indirection or wrapper layer, interface or abstract base — with exactly **one** caller after the change is an inline candidate under `overview.md` core principle 2 ("name the second caller now, or inline"). Collapse it into that call site unless one of four exits applies and you record which: the approved plan declares it as a test seam or variation-point extraction, the project-context preflight projection declares hexagonal architecture and it is a port at the domain boundary, it breaks a real import cycle, or its single caller is a published package's public API. This targets reusable layers, not a local helper that names a cohesive step or separates mixed abstraction levels; line count alone does not justify extraction.
43
45
  - The YAGNI cell is a grep, not an impression: for every identifier this diff adds — and every one whose last caller it removes — search the whole repository and name the caller you found. A declaration-only, test-only, or commented-out hit is not a caller. Zero callers means delete it here (or fold an added parameter back into its single call site), unless the approved plan reserves it for a named later stage or something outside project code calls it (framework entrypoint, implemented interface method, migration hook, published-package API) — in which case record that justification in the audit note. Fixing it now is cheaper than the verifier's Static design gate, where the same finding is blocking and fails the stage (`_implementation-verifier.md` "Caller-less identifier").
44
46
  - a file that wraps a third-party / library call → `clean-code.md` "Wrapping a third-party call": the wrapper adds behaviour the library does not already provide (read the installed library source before keeping a recovery branch — a `catch` repeating the library's own retry recovers nothing), no comment names a condition the call site does not establish, and a rethrow keeps the original error as `cause`.
45
47
  - a file that decides, mutates, or persists state → `clean-code.md` "Mutation and state boundaries": decide on the direct identifier rather than a status/flag proxy, capture before-state in one snapshot ahead of the mutating boundary, update only this work's owned fields on an existing row, re-read state before calling a zero-affected-rows write success or failure, put priority-between-inputs in a named domain function, and keep error messages to what was actually observed. Also check that no state union/enum was re-declared beside an authoritative one the domain or a dependency exports.
46
- - test file (`*.spec.*` / `*.test.*` / `test_*.py` / `*_test.go` …) → `clean-code.md` "Testing discipline": no self-mocking of the SUT, behavioral (outcome) assertions not interaction-only, no tautological delegation assertion, no effect claimed under its own mock, shared-fixture defaults left on the ordinary path, setup values that actually separate the scenarios, every new test helper/mock used by a test in this same diff, no positional mock-argument access (`rg 'mock\.calls'`), every branch this diff adds covered by a test that fails when the branch body is deleted, assertions on the last write to a record rather than an intermediate one, and test titles naming their unit plus the single condition each case isolates.
48
+ - test file (`*.spec.*` / `*.test.*` / `test_*.py` / `*_test.go` …) → `clean-code.md` "Testing discipline": no self-mocking of the SUT, behavioral (outcome) assertions not interaction-only, no tautological delegation assertion, no effect claimed under its own mock, shared-fixture defaults left on the ordinary path, setup values that actually separate the scenarios, every new test helper/mock used by a test in this same diff, no positional mock-argument access (`rg 'mock\.calls'`), retained or strengthened tests distinguishing changed core behavior and meaningful failures, selective mutation checks where regression detection is uncertain or project rules require them, assertions on the last write to a record rather than an intermediate one, and test titles naming their unit plus the single condition each case isolates.
47
49
  - port / adapter / domain file, when the hexagonal overlay is loaded → `architectures/hexagonal.md`: ports declare contracts rather than implement business decisions; the domain owns policy, and adapters may execute its query specifications efficiently. Do not infer a violation from complex SQL, domain-oriented query names or post-fetch processing alone, or require `findAll` plus in-memory filtering. Check domain placement, inward dependencies and touched concrete-adapter dependencies under the policy precedence above. Apply H1–H6 when the overlay is selected by declaration or layout; H5 alone retains its undeclared-style advisory exception.
48
50
  - a service file, when the hexagonal overlay is loaded → `architectures/hexagonal.md` Rule H6: inspect whether changed service code implements a business decision rather than orchestrating a domain-owned one. A private method's domain-oriented name alone is not evidence. Orchestration control flow, DTO mapping and calling a domain predicate are not violations.
49
51
  - a file that reads input from outside the process (request body, query, header, upload, message, webhook) or acts on its behalf → `clean-code.md` "Untrusted input and security": a size/count bound rejects oversized input before any check that grows faster than the input (a validator that runs every rule, such as class-validator without `stopAtFirstError`, does not stop at a failed `@ArrayMaxSize`), input reaches SQL / shell / paths / server-side fetches / templates / regexes only through parameters, allowlists or escaping, a new entry point carries the auth guard and compares the caller with the owner of an input-chosen id, no secret or personal data reaches code, logs or responses, and nothing evaluates or unsafely deserializes input.
50
52
  - every changed source file → `clean-code.md` "Trace what this change can do wrong": walk the error, partial, concurrent and selection paths this diff creates to their end — past the failures the plan lists, and including where a cleaning `try` registers its cleanup target relative to each call that can throw — and fix wherever a wrong result comes out. Name the input that produces it — if you cannot name one, there is nothing to fix here and you move on rather than restructuring code that works.
51
53
  A file can hold several roles — apply every rule set that fits it.
52
54
  3. **Decide clean-or-finding for each cell.** Read the full file when a rule needs context (never judge a port/adapter/domain or a naming rule from the hunk alone).
53
- 4. **Fix each finding in place** before the commit. When a readability finding is real, the fix is a named helper or named intermediate value — sketch the cleaner shape (a few lines) in your audit note, then apply it. When the fix is genuinely out of this stage's scope, record it as an `Out-of-plan` note instead of silently leaving it.
55
+ 4. **Fix each finding in place** before the commit. For an evidenced readability problem, sketch how the fix resolves its concrete consequence in your audit note, then apply it. Choose the smallest suitable change, such as a clearer condition, a named value or a cohesive helper. When the fix is genuinely out of this stage's scope, record it as an `Out-of-plan` note instead of silently leaving it.
54
56
 
55
57
  ## Coverage footer (BLOCKING deliverable)
56
58
 
@@ -60,7 +62,7 @@ Account for excluded files with their shared-census exclusion reasons in the sam
60
62
  footer. Examined files plus excluded files cover the complete changed-file list;
61
63
  an exclusion does not claim a clean inspection.
62
64
 
63
- `Coverage: users.service.ts [names: clean, plain-english: fixed 1], users.repository.adapter.ts [hexagonal: fixed 1, names: clean], users.service.spec.ts [testing-discipline: clean]; excluded: README.md [prose documentation]`
65
+ `Coverage: users.service.ts [names: clean, cohesion: fixed 1], users.repository.adapter.ts [hexagonal: fixed 1, names: clean], users.service.spec.ts [testing-discipline: clean]; excluded: README.md [prose documentation]`
64
66
 
65
67
  `clean` is a result you assert, not a blank you leave. Naming the rule set without its outcome reads identically whether you checked it or skipped it, which is exactly what this footer exists to distinguish — the completion self-check and any reviewer read it to confirm nothing in the diff was skipped. A sweep with no footer, or a footer whose entries carry no outcome, is an unfinished sweep.
66
68
 
@@ -24,7 +24,7 @@ fails, fix it or surface the violation — do not claim done on a failing item.
24
24
  - verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"
25
25
  - acceptance: each implemented plan step's `Acceptance:` condition is observably met — cite the RED→GREEN test (or the command output) proving it per step, not one global "acceptance met"; and each `Test case (success|boundary|failure)` the plan declared for this stage has a matching test in the diff (name the test), so declared edge/failure cases are not silently uncovered
26
26
  - quality outcomes: apply the captured `clean-code.md` "Five simultaneous quality outcomes" to the actual diff. Preserve each applicable expectation, performance/resource bound, safety/security check and its evidence in the acceptance and verification results above. Name missing or waived evidence; do not infer all five outcomes from a green command or complete coverage table
27
- - mutation check: enumerate every branch this diff adds (`catch`, guard, early return, `else`), plus at least one test it added or changed. For each entry, break what it covers on purpose — delete the branch body, return the wrong value, skip the write — confirm a test FAILS, then restore; cite the branch (or test) and the observed failure per entry, not one global "mutation verified". A branch whose deletion leaves the suite green is untested, not covered — an untested recovery path is indistinguishable from one that cannot fire. "Verified" claimed without this check plus the real command output above is not a verified claim
27
+ - regression evidence: map changed core behavior and meaningful failure outcomes to retained or strengthened tests and their actual command results. Use targeted mutation checks where regression detection remains uncertain, especially for security, concurrency or recovery, or where explicit project rules require them. For each selected mutation, cite the changed behavior and focused test failure, restore the source and rerun the test; preserve selected or required checks not performed as unverified. Follow `clean-code.md` "Testing discipline" rather than enumerating every syntactic branch for manual mutation
28
28
  - cleanup: no dead or commented-out code left behind, and no caller-less identifier — list every identifier this diff added or whose last caller it removed, and cite the caller you grepped for each one (or the plan step / non-project-code contract point that justifies keeping it with none). "No new identifiers" is a valid answer; a global "cleaned up" is not
29
29
 
30
30
  Close with a `Self-check coverage:` line naming the files you verified the
@@ -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
 
@@ -1191,12 +1192,14 @@ def validate_current_review(run_manifest: Path) -> PreparedPlanReview:
1191
1192
  name = authority.payload.get("reportNarrativePath")
1192
1193
  if not isinstance(name, str) or not name:
1193
1194
  raise PlanItemContractError("reportNarrativePath is missing")
1194
- narrative = (authority.project_root / name).resolve(strict=True)
1195
- 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):
1196
1197
  raise PlanItemContractError("plan narrative must stay inside the current run")
1197
1198
  items_path = _prepared_items_path(run_manifest, require_regular=True)
1198
1199
  prepared = _load_json_object(items_path)
1199
- 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
+ ))
1200
1203
  items = _envelope(source)["items"]
1201
1204
  if prepared.get("items") != items:
1202
1205
  raise PlanItemContractError("prepared plan items do not match the current narrative")
@@ -1224,7 +1227,7 @@ def finish_verification_round(
1224
1227
  verified = subprocess.run(
1225
1228
  [sys.executable, str(assets.joinpath(*RUN_VALIDATOR_RELATIVE)),
1226
1229
  "--section", "plan-body", "--narrative", str(review.narrative),
1227
- "--state", str(review.state)],
1230
+ "--state", str(review.state), "--run-manifest", str(review.manifest)],
1228
1231
  capture_output=True, text=True, check=False, timeout=60,
1229
1232
  )
1230
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.
@@ -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