okstra 0.232.0 → 0.234.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 (205) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/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 +55 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +320 -3
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +34 -43
  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/business_flow/cli.py +60 -6
  77. package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
  78. package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
  79. package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
  80. package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
  81. package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
  82. package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
  83. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  84. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  85. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  86. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  87. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  88. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  89. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  90. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  91. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  92. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  93. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  94. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  95. package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
  96. package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
  97. package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
  98. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
  99. package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
  100. package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
  101. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  102. package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
  103. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  104. package/runtime/python/okstra_ctl/fixed_text.py +10 -0
  105. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  106. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  107. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  108. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  109. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  110. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  111. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  112. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  113. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  114. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  115. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  116. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  117. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  118. package/runtime/python/okstra_ctl/material.py +2 -0
  119. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  120. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  121. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  122. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  123. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  124. package/runtime/python/okstra_ctl/paths.py +6 -1
  125. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  126. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  127. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  128. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  129. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  130. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  131. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  132. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  133. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  134. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  135. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  136. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  137. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  138. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  139. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  140. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  141. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  142. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  143. package/runtime/python/okstra_ctl/project_group.py +175 -0
  144. package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
  145. package/runtime/python/okstra_ctl/render.py +28 -2
  146. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  147. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  148. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  149. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  150. package/runtime/python/okstra_ctl/report_language.py +4 -1
  151. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  152. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  153. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  154. package/runtime/python/okstra_ctl/run.py +43 -35
  155. package/runtime/python/okstra_ctl/run_context.py +10 -1
  156. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  157. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  158. package/runtime/python/okstra_ctl/task_query.py +239 -0
  159. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  160. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  161. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  162. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  163. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  164. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  165. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  166. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  167. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  168. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  169. package/runtime/python/okstra_project/state.py +20 -0
  170. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  171. package/runtime/python/okstra_token_usage/cli.py +23 -10
  172. package/runtime/python/okstra_token_usage/collect.py +25 -22
  173. package/runtime/python/okstra_token_usage/policy.py +193 -0
  174. package/runtime/schemas/business-flow-v1.schema.json +3 -0
  175. package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
  176. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  177. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  178. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  179. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  180. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  181. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  182. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  183. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  184. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  185. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  186. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  187. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  188. package/runtime/skills/okstra-explain-flow/SKILL.md +33 -4
  189. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  190. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  191. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  192. package/runtime/skills/okstra-run/SKILL.md +55 -183
  193. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  194. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  195. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  196. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  197. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  198. package/runtime/templates/doyouknow/group-view.css +103 -0
  199. package/runtime/templates/doyouknow/group-view.js +317 -0
  200. package/runtime/templates/doyouknow/group-view.template.html +72 -0
  201. package/runtime/templates/manager/view.template.html +4 -0
  202. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  203. package/runtime/templates/trace/trace.template.md +42 -0
  204. package/runtime/validators/checks/fixtures-02.py +25 -33
  205. package/runtime/validators/validate-run.py +93 -36
@@ -23,6 +23,7 @@ from ..ports.verification_inputs import VerificationInputStore
23
23
  from ..review_policy import render_review_policy, review_policy_context
24
24
  from ..phases.catalog import PhaseAssetError, profile_markdown
25
25
  from ..recap import assemble_group_recap, assemble_recap
26
+ from ..report_contract import report_authoring_format
26
27
  from ..role_requirements import RoleProfileError, load_role_profile
27
28
  from ..timeline_runs import current_run_facts
28
29
  from .lines import (
@@ -214,6 +215,7 @@ def render_run_input(run_manifest: Path) -> str:
214
215
  + _line("Task type", run.get("taskType"))
215
216
  + _line("Run ID", run.get("runDateTimeSegment"))
216
217
  + _line("Work category", run.get("workCategory"))
218
+ + _line("Report authoring format", report_authoring_format(run))
217
219
  + _line("Lead runtime", run.get("leadRuntime"))
218
220
  + _line("Lead adapter name", adapter.get("name"))
219
221
  + _line("Lead dispatch mode", adapter.get("dispatchMode"))
@@ -229,6 +231,7 @@ def render_run_input(run_manifest: Path) -> str:
229
231
  + _worker_prompt_lines(run)
230
232
  + _line("Worker results directory", run.get("workerResultsDirectoryPath"))
231
233
  + _line("Expected report", run.get("expectedReportRecordPath"))
234
+ + _line("Report writer input", run.get("reportNarrativePath"))
232
235
  + _line("Expected status", run.get("expectedStatusPath"))
233
236
  + _line("Validator", run.get("validatorScriptPath"))
234
237
  + _line("Resume command", run.get("resumeCommandPath"))
@@ -17,7 +17,7 @@ from .contract_graph import (
17
17
  ContractGraphValidator,
18
18
  ContractSelection,
19
19
  )
20
- from .model_pool import ModelPool
20
+ from .model_pool import ModelPool, ResolvedModel
21
21
 
22
22
 
23
23
  class OperationPreparationError(ValueError):
@@ -37,20 +37,8 @@ class OperationSlot:
37
37
  display_name: str
38
38
 
39
39
 
40
- def resolve_operation_slots(
41
- operation_id: str,
42
- *,
43
- contract_root: Path,
44
- pool: ModelPool,
45
- count: int | None = None,
46
- ) -> Sequence[OperationSlot]:
47
- """작업 계약이 요구하는 칸과 각 칸의 모델.
48
-
49
- 모델은 런과 같은 기본값 사슬에서 고른다. 서로 다른 모델 참조를 요구한
50
- 수만큼 채우지 못하면 여기서 멈춘다 — 같은 모델을 반복하거나 워커 수를
51
- 몰래 줄이면 그 작업이 요구한 교차검증이 조용히 사라진다. `count` 는
52
- 호출자가 계약 상한 안에서 명시적으로 고른 수다.
53
- """
40
+ def _operation_contract(operation_id: str, contract_root: Path) -> tuple[str, str, int]:
41
+ """The operation's duty, role and worker ceiling."""
54
42
  graph_root = ContractGraphRoot.from_base(contract_root)
55
43
  try:
56
44
  graph = ContractGraphValidator().validate(
@@ -65,31 +53,222 @@ def resolve_operation_slots(
65
53
  f"unknown operation: {operation_id} (known: {known})"
66
54
  )
67
55
  duty_id = str(operation.payload["dutyId"])
56
+ return duty_id, graph.duties[duty_id].role_id, int(operation.payload["count"])
57
+
58
+
59
+ def operation_ceiling(operation_id: str, *, contract_root: Path) -> int:
60
+ """The most workers the operation contract allows."""
61
+ return _operation_contract(operation_id, contract_root)[2]
62
+
63
+
64
+ def resolve_operation_slots(
65
+ operation_id: str,
66
+ *,
67
+ contract_root: Path,
68
+ pool: ModelPool,
69
+ count: int | None = None,
70
+ deprioritized_provider: str | None = None,
71
+ ) -> Sequence[OperationSlot]:
72
+ """작업 계약이 요구하는 칸과 각 칸의 모델.
73
+
74
+ 모델은 런과 같은 기본값 사슬에서 고른다. 서로 다른 모델 참조를 요구한
75
+ 수만큼 채우지 못하면 여기서 멈춘다 — 같은 모델을 반복하거나 워커 수를
76
+ 몰래 줄이면 그 작업이 요구한 교차검증이 조용히 사라진다. `count` 는
77
+ 호출자가 계약 상한 안에서 명시적으로 고른 수다. `deprioritized_provider`
78
+ 의 모델은 다른 공급자의 후보 뒤로 미룬다(같은 공급자 안의 순서는 유지).
79
+ """
80
+ duty_id, role_id, ceiling = _operation_contract(operation_id, contract_root)
68
81
  # 계약의 수는 상한이다. 더 적게 여는 것은 호출자가 명시할 때만이다.
69
- ceiling = int(operation.payload["count"])
70
82
  if count is None:
71
83
  count = ceiling
72
84
  elif not 1 <= count <= ceiling:
73
85
  raise OperationPreparationError(
74
86
  f"operation {operation_id!r} takes a count from 1 to {ceiling}, got {count}"
75
87
  )
76
- role_id = graph.duties[duty_id].role_id
77
88
 
78
89
  candidates = pool.default_candidates(role_id)
90
+ if deprioritized_provider is not None:
91
+ candidates = tuple(sorted(candidates, key=lambda model: model.provider_id == deprioritized_provider))
79
92
  if len(candidates) < count:
80
93
  raise OperationPreparationError(
81
94
  f"operation {operation_id!r} requires {count} distinct models for role "
82
95
  f"{role_id!r}, available {len(candidates)}"
83
96
  )
84
- slots = []
85
- for ordinal, model in enumerate(candidates[:count], start=1):
86
- slots.append(OperationSlot(
87
- operation_id=operation_id,
88
- duty_id=duty_id,
89
- role_id=role_id,
90
- ordinal=ordinal,
91
- model_ref=str(model.model_ref),
92
- provider_id=model.provider_id,
97
+ return _numbered_slots(operation_id, duty_id, role_id, candidates[:count])
98
+
99
+
100
+ def _numbered_slots(
101
+ operation_id: str, duty_id: str, role_id: str, models: Sequence[ResolvedModel],
102
+ ) -> tuple[OperationSlot, ...]:
103
+ return tuple(
104
+ OperationSlot(
105
+ operation_id=operation_id, duty_id=duty_id, role_id=role_id, ordinal=ordinal,
106
+ model_ref=str(model.model_ref), provider_id=model.provider_id,
93
107
  display_name=model.display_name,
94
- ))
95
- return tuple(slots)
108
+ )
109
+ for ordinal, model in enumerate(models, start=1)
110
+ )
111
+
112
+
113
+ def operation_contract_root() -> Path:
114
+ """The directory holding `operations/<id>.json` contracts for this runtime."""
115
+ from .paths import find_asset_root
116
+
117
+ root = find_asset_root(("agents", "operations"), is_present=Path.is_dir)
118
+ if root is None:
119
+ raise OperationPreparationError(
120
+ "operation contracts not found: no agents/operations under OKSTRA_HOME or this checkout"
121
+ )
122
+ return root
123
+
124
+
125
+ def require_distinct_providers(providers: Sequence[str]) -> None:
126
+ """Every team needs its own provider.
127
+
128
+ The operation asks for cross-model verification, and two models of one
129
+ provider do not provide it.
130
+ """
131
+ if len(set(providers)) != len(providers):
132
+ raise OperationPreparationError(
133
+ "every team needs a different provider, got " + ", ".join(providers)
134
+ )
135
+
136
+
137
+ def resolve_model_reference(pool: ModelPool, value: str) -> ResolvedModel:
138
+ """A `provider/model` reference, or a provider alias such as `claude/opus`."""
139
+ from .domain.provider import UnknownModelError
140
+
141
+ try:
142
+ return pool.resolve(value)
143
+ except UnknownModelError:
144
+ provider, sep, alias = value.partition("/")
145
+ if not sep or not alias:
146
+ raise
147
+ return pool.resolve_alias(provider, alias)
148
+
149
+
150
+ def resolve_operation_models(
151
+ operation_id: str, references: Sequence[str], *, contract_root: Path, pool: ModelPool,
152
+ ) -> tuple[str, str, tuple[ResolvedModel, ...]]:
153
+ """The duty, role and models a caller chose for an operation, one per team, in order."""
154
+ from .domain.provider import UnknownModelError
155
+
156
+ duty_id, role_id, ceiling = _operation_contract(operation_id, contract_root)
157
+ if not references:
158
+ raise OperationPreparationError(f"operation {operation_id!r} needs at least one model")
159
+ if len(references) > ceiling:
160
+ raise OperationPreparationError(
161
+ f"operation {operation_id!r} takes at most {ceiling} models, got {len(references)}"
162
+ )
163
+ try:
164
+ models = [resolve_model_reference(pool, value) for value in references]
165
+ except UnknownModelError as exc:
166
+ raise OperationPreparationError(str(exc)) from exc
167
+ require_distinct_providers([model.provider_id for model in models])
168
+ for model in models:
169
+ if not pool.resolve_provider(model.provider_id).supports_role(role_id):
170
+ raise OperationPreparationError(
171
+ f"provider {model.provider_id!r} does not support role {role_id!r}"
172
+ )
173
+ availability = pool.availability(str(model.model_ref), role_id)
174
+ if not availability.available:
175
+ raise OperationPreparationError(
176
+ f"model {model.model_ref} is not available: {availability.reason}"
177
+ )
178
+ return duty_id, role_id, tuple(models)
179
+
180
+
181
+ def select_operation_models(
182
+ operation_id: str, flags: Sequence[str], count: int | None, *, contract_root: Path, cwd: Path,
183
+ ) -> tuple[tuple[str, ...], str]:
184
+ """Which model references an operation's teams use, and where they came from.
185
+
186
+ Flags win, then project and then global `operationModels`, then adapter
187
+ defaults (an empty tuple with source `bundled`). A count is checked
188
+ against the contract range first; with flags it must equal their number,
189
+ with a config list it takes that many from the front.
190
+ """
191
+ ceiling = operation_ceiling(operation_id, contract_root=contract_root)
192
+ if count is not None and not 1 <= count <= ceiling:
193
+ raise OperationPreparationError(
194
+ f"operation {operation_id!r} takes a count from 1 to {ceiling}, got {count}"
195
+ )
196
+ if flags:
197
+ if count is not None and count != len(flags):
198
+ raise OperationPreparationError("--count differs from the number of --model values")
199
+ return tuple(flags), "flag"
200
+ configured, scope = operation_model_defaults(operation_id, cwd)
201
+ if not configured or count is None:
202
+ return configured, scope
203
+ if count > len(configured):
204
+ raise OperationPreparationError(
205
+ f"{scope} operationModels names {len(configured)} models, fewer than --count {count}"
206
+ )
207
+ return configured[:count], scope
208
+
209
+
210
+ def resolve_operation_team(
211
+ operation_id: str, flags: Sequence[str], count: int | None, *,
212
+ contract_root: Path, pool: ModelPool, cwd: Path,
213
+ ) -> tuple[tuple[OperationSlot, ...], str]:
214
+ """The operation's slots for the selected models, and the models' source."""
215
+ references, source = select_operation_models(
216
+ operation_id, flags, count, contract_root=contract_root, cwd=cwd,
217
+ )
218
+ if not references:
219
+ return tuple(resolve_operation_slots(
220
+ operation_id, contract_root=contract_root, pool=pool, count=count,
221
+ )), source
222
+ duty_id, role_id, models = resolve_operation_models(
223
+ operation_id, references, contract_root=contract_root, pool=pool,
224
+ )
225
+ return _numbered_slots(operation_id, duty_id, role_id, models), source
226
+
227
+
228
+ def operation_model_defaults(operation_id: str, cwd: Path) -> tuple[tuple[str, ...], str]:
229
+ """The models `operationModels` names for an operation, and the scope that named them.
230
+
231
+ Project config wins over global config; neither merges with the other.
232
+ An empty tuple with scope `bundled` means no config names the operation.
233
+ """
234
+ from okstra_project.dirs import okstra_home
235
+
236
+ from .model_defaults import ModelDefaultScopes, default_candidates, default_scope
237
+
238
+ scopes = ModelDefaultScopes(
239
+ project=_operation_models(_project_config(cwd)),
240
+ global_=_operation_models(okstra_home() / "config.json"),
241
+ bundled={},
242
+ )
243
+ refs = default_candidates(operation_id, scopes)
244
+ return refs, default_scope(operation_id, scopes) or "bundled"
245
+
246
+
247
+ def _project_config(cwd: Path) -> Path:
248
+ from okstra_project import project_json_path, resolve_project_root
249
+
250
+ try:
251
+ return project_json_path(resolve_project_root(cwd=str(cwd)))
252
+ except Exception:
253
+ return cwd / ".okstra" / "project.json"
254
+
255
+
256
+ def _operation_models(path: Path) -> dict[str, tuple[str, ...]]:
257
+ from .json_boundary import load_owned_object
258
+ from .model_defaults import ModelDefaultError, parse_model_lists
259
+
260
+ payload = load_owned_object(path, artifact="model configuration") if path.is_file() else {}
261
+ try:
262
+ return parse_model_lists(payload, "operationModels", path)
263
+ except ModelDefaultError as exc:
264
+ raise OperationPreparationError(str(exc)) from exc
265
+
266
+
267
+ def slot_payload(slot: OperationSlot) -> dict[str, object]:
268
+ """The JSON row callers print for one slot."""
269
+ return {
270
+ "ordinal": slot.ordinal,
271
+ "provider": slot.provider_id,
272
+ "modelRef": slot.model_ref,
273
+ "model": slot.display_name,
274
+ }
@@ -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