okstra 0.234.1 → 0.236.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 (171) hide show
  1. package/dist/cli-registry.mjs +7 -0
  2. package/dist/cli-registry.mjs.map +1 -1
  3. package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
  4. package/dist/commands/implementation-report/implementation-report.mjs +73 -0
  5. package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
  6. package/dist/commands/trace/comparison.d.mts +39 -0
  7. package/dist/commands/trace/comparison.mjs +138 -0
  8. package/dist/commands/trace/comparison.mjs.map +1 -0
  9. package/dist/commands/trace/document.d.mts +8 -0
  10. package/dist/commands/trace/document.mjs +37 -0
  11. package/dist/commands/trace/document.mjs.map +1 -0
  12. package/dist/commands/trace/line-counts.d.mts +15 -0
  13. package/dist/commands/trace/line-counts.mjs +107 -0
  14. package/dist/commands/trace/line-counts.mjs.map +1 -0
  15. package/dist/commands/trace/model.d.mts +2 -1
  16. package/dist/commands/trace/model.mjs +13 -1
  17. package/dist/commands/trace/model.mjs.map +1 -1
  18. package/dist/commands/trace/progression.mjs +7 -3
  19. package/dist/commands/trace/progression.mjs.map +1 -1
  20. package/dist/commands/trace/task-link.d.mts +3 -0
  21. package/dist/commands/trace/task-link.mjs.map +1 -1
  22. package/dist/commands/trace/trace.mjs +64 -44
  23. package/dist/commands/trace/trace.mjs.map +1 -1
  24. package/dist/lib/host-registry-client.d.mts +9 -2
  25. package/dist/lib/host-registry-client.mjs +29 -3
  26. package/dist/lib/host-registry-client.mjs.map +1 -1
  27. package/dist/lib/python-helper.d.mts +1 -1
  28. package/dist/lib/python-helper.mjs +11 -5
  29. package/dist/lib/python-helper.mjs.map +1 -1
  30. package/dist/lib/runtime-payload.mjs +1 -0
  31. package/dist/lib/runtime-payload.mjs.map +1 -1
  32. package/dist/lib/types.d.mts +1 -0
  33. package/docs/architecture/storage-model.md +50 -0
  34. package/docs/architecture.md +1 -1
  35. package/docs/cli.md +37 -15
  36. package/docs/project-structure-overview.md +6 -1
  37. package/package.json +1 -1
  38. package/runtime/BUILD.json +2 -2
  39. package/runtime/agents/operations/trace-tests-review.json +6 -0
  40. package/runtime/bin/lib/okstra/usage.sh +8 -8
  41. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  42. package/runtime/prompts/duties/test-reviewer.json +32 -0
  43. package/runtime/prompts/lead/convergence.md +4 -1
  44. package/runtime/prompts/lead/okstra-lead-contract.md +3 -3
  45. package/runtime/prompts/lead/report-writer.md +13 -1
  46. package/runtime/prompts/profiles/_common-contract.md +10 -1
  47. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  48. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  49. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  50. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  51. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  52. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  53. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  54. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  55. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  56. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  57. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  58. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  59. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  60. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  61. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  62. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  63. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  64. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  65. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  66. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  67. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  68. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  69. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  70. package/runtime/python/okstra_ctl/consumers.py +6 -1
  71. package/runtime/python/okstra_ctl/convergence.py +95 -5
  72. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  73. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  74. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  75. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  76. package/runtime/python/okstra_ctl/design_review.py +6 -26
  77. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  78. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  79. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  80. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  81. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  82. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  83. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  84. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  85. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  86. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  87. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  88. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  89. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  90. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  91. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  92. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  93. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  94. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  95. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  96. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  97. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  98. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  99. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  100. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  101. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  102. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  103. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  104. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  105. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  106. package/runtime/python/okstra_ctl/models.py +2 -2
  107. package/runtime/python/okstra_ctl/paths.py +7 -4
  108. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  109. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  110. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  111. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  112. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  113. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  114. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  115. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  116. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  117. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  118. package/runtime/python/okstra_ctl/render.py +4 -0
  119. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  120. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  121. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  122. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  123. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  124. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  125. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  126. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  127. package/runtime/python/okstra_ctl/run.py +17 -1
  128. package/runtime/python/okstra_ctl/run_context.py +18 -3
  129. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  130. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  131. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  132. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  133. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  134. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  135. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  136. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  137. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  138. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  139. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  140. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  141. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  142. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  143. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  144. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  145. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  146. package/runtime/python/okstra_ctl/wizard/state.py +67 -20
  147. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  148. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  149. package/runtime/python/okstra_ctl/worker_audit_ledger.py +44 -8
  150. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  151. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  152. package/runtime/python/okstra_token_usage/claude.py +5 -1
  153. package/runtime/python/okstra_token_usage/collect.py +3 -3
  154. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  155. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  156. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  157. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  158. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  159. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  160. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  161. package/runtime/skills/okstra-run/SKILL.md +33 -2
  162. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  163. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  164. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  165. package/runtime/templates/reports/html/i18n/en.json +113 -0
  166. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  167. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  168. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  169. package/runtime/templates/trace/trace.template.md +2 -0
  170. package/runtime/templates/worker-prompt-preamble.md +12 -2
  171. package/runtime/validators/validate-report-views.py +4 -36
@@ -8,6 +8,7 @@ from okstra_project import project_json_path
8
8
  from okstra_ctl.assignment_environment import load_assignment_context
9
9
  from okstra_ctl.assignment_resolver import AssignmentContext
10
10
  from okstra_ctl.dispatch_state import detect_terminal_backend
11
+ from okstra_ctl.registry.provider_registry import provider_display_order
11
12
  from okstra_ctl.domain.worker_defaults import (
12
13
  WorkerDefaultError,
13
14
  WorkerDefaultsConflict,
@@ -22,13 +23,21 @@ from okstra_ctl.worker_defaults import (
22
23
  )
23
24
 
24
25
  from .prompts import _msg
25
- from .roles import _executable_role_models, _host_session_context
26
+ from .roles import (
27
+ _executable_role_models,
28
+ _host_session_context,
29
+ _provider_of,
30
+ free_input_providers,
31
+ resolve_typed_models,
32
+ )
26
33
  from .state import Option, Prompt, WizardError, WizardState
27
34
 
28
35
  _INHERIT = "__inherit__"
29
36
  _DISABLE = "__disable__"
30
37
  _SCREENS_AFTER_SCOPE_PICK = 2
31
38
  _SCREENS_AFTER_MODEL_EDIT = 2
39
+ _SCREENS_FOR_ACTION_PICK = 1
40
+ _CHOOSE_MODELS = "__choose_models__"
32
41
  _SCREENS_AFTER_ROLE_MENU = 1
33
42
  _SCREENS_AFTER_REVIEW = 0
34
43
 
@@ -66,7 +75,9 @@ def remaining_settings_screens(state: WizardState) -> int:
66
75
  if state.worker_settings_scope is None:
67
76
  return _SCREENS_AFTER_SCOPE_PICK
68
77
  if state.worker_settings_role:
69
- return _SCREENS_AFTER_MODEL_EDIT
78
+ if state.worker_settings_choosing:
79
+ return _SCREENS_AFTER_MODEL_EDIT
80
+ return _SCREENS_AFTER_MODEL_EDIT + _SCREENS_FOR_ACTION_PICK
70
81
  return _SCREENS_AFTER_ROLE_MENU
71
82
 
72
83
 
@@ -155,12 +166,14 @@ def worker_settings_summary(state: WizardState) -> str:
155
166
  return "\n".join(lines)
156
167
 
157
168
 
158
- def _settings_model_prompt(state: WizardState) -> Prompt:
159
- text = partial(_text, state)
169
+ def _settings_candidates(
170
+ state: WizardState,
171
+ ) -> tuple[StaticRoleRequirement, list[str], list[str], bool]:
172
+ """(requirement, candidates in provider order, preferred models, disabled now)."""
160
173
  role = state.worker_settings_role
161
174
  requirement = common_worker_requirements(Path(state.workspace_root))[role]
162
175
  context = _settings_context(state)
163
- candidates = _executable_role_models(
176
+ executable = _executable_role_models(
164
177
  state, RoleProfile((requirement,)), requirement, context
165
178
  )
166
179
  scopes = _draft_scopes(state)
@@ -168,43 +181,102 @@ def _settings_model_prompt(state: WizardState) -> Prompt:
168
181
  role, scopes.get("project", {}), scopes.get("global", {})
169
182
  )
170
183
  current = selected[0] if selected and isinstance(selected[0], list) else []
171
- preferred = list(dict.fromkeys(model for model in current if model in candidates))
184
+ preferred = list(dict.fromkeys(model for model in current if model in executable))
172
185
  if not preferred:
173
- preferred = list(candidates[: requirement.recommended_count])
174
- ordered = [*preferred, *(model for model in candidates if model not in preferred)]
175
- multi = requirement.max_count > 1
176
- if not multi:
186
+ preferred = list(executable[: requirement.recommended_count])
187
+ if requirement.max_count <= 1:
177
188
  preferred = preferred[:1]
189
+ disabled = requirement.min_count == 0 and (
190
+ not executable or (selected is not None and selected[0] == [])
191
+ )
192
+ candidates = sorted(
193
+ executable, key=lambda model: provider_display_order(_provider_of(model))
194
+ )
195
+ return requirement, candidates, preferred, disabled
196
+
197
+
198
+ def _settings_action_prompt(state: WizardState) -> Prompt:
199
+ """First screen of a role edit: choose models, or end it without models."""
200
+ requirement, candidates, _preferred, disabled = _settings_candidates(state)
201
+ inherit = not candidates and not disabled
178
202
  options = [
179
- Option(model, model, recommended=model in preferred) for model in ordered
203
+ Option(
204
+ _CHOOSE_MODELS, _text(state, "choose_models"),
205
+ recommended=bool(candidates) and not disabled,
206
+ ),
207
+ *_settings_without_models(state, requirement, disabled=disabled, inherit=inherit),
180
208
  ]
181
- disabled = requirement.min_count == 0 and (
182
- not ordered or (selected is not None and selected[0] == [])
209
+ options.sort(key=lambda option: not option.recommended)
210
+ return Prompt(
211
+ step="worker_settings_action",
212
+ kind="pick",
213
+ options=options,
214
+ label=_text(
215
+ state,
216
+ "action_label",
217
+ role=_text(state, f"role_{state.worker_settings_role}"),
218
+ minimum=str(requirement.min_count),
219
+ maximum=str(requirement.max_count),
220
+ ),
183
221
  )
184
- if disabled:
185
- for option in options:
186
- option.recommended = False
222
+
223
+
224
+ def _settings_without_models(
225
+ state: WizardState,
226
+ requirement: StaticRoleRequirement,
227
+ *,
228
+ disabled: bool,
229
+ inherit: bool,
230
+ ) -> list[Option]:
231
+ """Rows that end a role edit without models: disable, inherit or clear, cancel."""
232
+ rows = []
187
233
  if requirement.min_count == 0:
188
- options.append(Option(_DISABLE, text("disabled"), recommended=disabled))
189
- inherited = text("inherit" if state.worker_settings_scope == "project" else "clear")
190
- inherit_default = not ordered and not disabled
191
- options.append(Option(_INHERIT, inherited, recommended=inherit_default))
192
- options.append(Option("cancel", text("cancel")))
193
- options.sort(key=lambda option: not option.recommended)
234
+ rows.append(Option(_DISABLE, _text(state, "disabled"), recommended=disabled))
235
+ inherited = "inherit" if state.worker_settings_scope == "project" else "clear"
236
+ rows.append(Option(_INHERIT, _text(state, inherited), recommended=inherit))
237
+ rows.append(Option("cancel", _text(state, "cancel")))
238
+ return rows
239
+
240
+
241
+ def _settings_model_prompt(state: WizardState) -> Prompt:
242
+ """The role's models in provider order; the engine shows them as vendor tabs."""
243
+ text = partial(_text, state)
244
+ requirement, candidates, preferred, _disabled = _settings_candidates(state)
245
+ options = [Option(model, model, recommended=model in preferred) for model in candidates]
194
246
  return Prompt(
195
247
  step="worker_settings_models",
196
248
  kind="pick",
197
- multi=multi,
249
+ multi=requirement.max_count > 1,
198
250
  options=options,
199
251
  label=text(
200
252
  "models_label",
201
- role=text(f"role_{role}"),
253
+ role=text(f"role_{state.worker_settings_role}"),
202
254
  minimum=str(requirement.min_count),
203
255
  maximum=str(requirement.max_count),
204
256
  ),
205
257
  )
206
258
 
207
259
 
260
+ def _settings_model_input_prompt(state: WizardState) -> Prompt:
261
+ draft = state.worker_settings_draft
262
+ assert draft is not None
263
+ _requirement, candidates, _preferred, _disabled = _settings_candidates(state)
264
+ return Prompt(
265
+ step="worker_settings_model_input",
266
+ kind="text",
267
+ label=_text(
268
+ state,
269
+ "model_input_label",
270
+ role=_text(state, f"role_{state.worker_settings_role}"),
271
+ providers=", ".join(draft["providers"]),
272
+ chosen=", ".join(draft["models"]) or "-",
273
+ candidates=", ".join(
274
+ model for model in candidates if _provider_of(model) in draft["providers"]
275
+ ),
276
+ ),
277
+ )
278
+
279
+
208
280
  def next_worker_settings_prompt(state: WizardState) -> Prompt:
209
281
  if state.worker_settings_saved:
210
282
  return Prompt(step="done", kind="done", label=worker_settings_summary(state))
@@ -235,6 +307,10 @@ def next_worker_settings_prompt(state: WizardState) -> Prompt:
235
307
  ],
236
308
  )
237
309
  if state.worker_settings_role:
310
+ if state.worker_settings_draft is not None:
311
+ return _settings_model_input_prompt(state)
312
+ if not state.worker_settings_choosing:
313
+ return _settings_action_prompt(state)
238
314
  return _settings_model_prompt(state)
239
315
  return Prompt(
240
316
  step="worker_settings_roles",
@@ -265,6 +341,25 @@ def _stage_worker_models(state: WizardState, value: str) -> None:
265
341
  _validate_staged_models(state, requirement, models, _settings_context(state))
266
342
  state.worker_settings_updates[role] = models
267
343
  state.worker_settings_role = ""
344
+ state.worker_settings_choosing = False
345
+ state.worker_settings_draft = None
346
+
347
+
348
+ def _stage_picked_worker_models(state: WizardState, value: str) -> None:
349
+ picked = [part.strip() for part in value.split(",") if part.strip()]
350
+ chosen, typed_from = free_input_providers(picked)
351
+ if typed_from:
352
+ state.worker_settings_draft = {"models": chosen, "providers": typed_from}
353
+ return
354
+ _stage_worker_models(state, value)
355
+
356
+
357
+ def _stage_typed_worker_models(state: WizardState, value: str) -> None:
358
+ draft = state.worker_settings_draft
359
+ assert draft is not None
360
+ _requirement, candidates, _preferred, _disabled = _settings_candidates(state)
361
+ typed = resolve_typed_models(value, draft["providers"], candidates)
362
+ _stage_worker_models(state, ",".join(dict.fromkeys([*draft["models"], *typed])))
268
363
 
269
364
 
270
365
  def _save_worker_settings(state: WizardState) -> None:
@@ -321,8 +416,17 @@ def submit_worker_settings(state: WizardState, prompt: Prompt, value: str) -> st
321
416
  state.worker_settings_role = value
322
417
  else:
323
418
  raise WizardError(_text(state, "choose_role"))
419
+ elif prompt.step == "worker_settings_action":
420
+ if value == _CHOOSE_MODELS:
421
+ state.worker_settings_choosing = True
422
+ elif value in (_INHERIT, _DISABLE):
423
+ _stage_worker_models(state, value)
424
+ else:
425
+ raise WizardError(_text(state, "choose_action"))
324
426
  elif prompt.step == "worker_settings_models":
325
- _stage_worker_models(state, value)
427
+ _stage_picked_worker_models(state, value)
428
+ elif prompt.step == "worker_settings_model_input":
429
+ _stage_typed_worker_models(state, value)
326
430
  elif prompt.step == "worker_settings_save":
327
431
  if value == "save":
328
432
  _save_worker_settings(state)
@@ -104,7 +104,48 @@ def _cited_file_paths(content: str) -> set[str]:
104
104
  return paths
105
105
 
106
106
 
107
- def _audit_evidence_read_paths(content: str) -> set[str]:
107
+ # A file that a citation, an evidence note or an Opened list names:
108
+ # `src/a_b.ts:4-9`, **src/a.ts**, [packet](.okstra/x/p.md:3), /abs/src/a.ts.
109
+ # A name counts only with a directory or a line, so prose such as `e.g.` or a
110
+ # version number is not a file.
111
+ _NAMED_FILE_RE = re.compile(
112
+ r"(?<![\w./@-])(?P<path>[\w.@-]*(?:/[\w.@-]+)*\.[A-Za-z]\w*"
113
+ r"|(?:[\w.@-]+/)+(?:Dockerfile|Justfile|Makefile|Procfile|Rakefile))"
114
+ r"(?P<line>:\d+(?:-\d+)?)?"
115
+ )
116
+
117
+
118
+ def named_files(text: str) -> tuple[str, ...]:
119
+ """The file paths *text* names, in order, without line suffixes."""
120
+ paths: dict[str, None] = {}
121
+ for match in _NAMED_FILE_RE.finditer(text):
122
+ path = match.group("path")
123
+ if match.group("line") or "/" in path:
124
+ paths.setdefault(path, None)
125
+ return tuple(paths)
126
+
127
+
128
+ def recorded_as_opened(path: str, ledger: frozenset[str] | set[str]) -> bool:
129
+ """Whether a ledger row names *path*, project-relative or absolute on either side.
130
+
131
+ A bare filename matches only when exactly one row has that name.
132
+ """
133
+ if path in ledger:
134
+ return True
135
+ if "/" not in path:
136
+ return len([row for row in ledger if row.rsplit("/", 1)[-1] == path]) == 1
137
+ return any(path.endswith("/" + row) or row.endswith("/" + path) for row in ledger)
138
+
139
+
140
+ def ledger_required(prompt_path: Path) -> bool:
141
+ """Whether the prompt asked its worker for an Evidence read ledger."""
142
+ try:
143
+ return EVIDENCE_LEDGER_HEADER in prompt_path.read_text(encoding="utf-8").splitlines()
144
+ except OSError:
145
+ return False
146
+
147
+
148
+ def audit_evidence_read_paths(content: str) -> set[str]:
108
149
  return {
109
150
  match.group("path")
110
151
  for match in _EVIDENCE_READ_RE.finditer(content)
@@ -230,19 +271,14 @@ def _evidence_read_ledger_failures(
230
271
  ) -> list[str]:
231
272
  if worker_role == "report-writer-worker":
232
273
  return []
233
- prompt_path = _worker_prompt_path(run_dir, worker_role, task_type, seq)
234
- try:
235
- prompt_content = prompt_path.read_text(encoding="utf-8")
236
- except OSError:
237
- return []
238
- if EVIDENCE_LEDGER_HEADER not in prompt_content.splitlines():
274
+ if not ledger_required(_worker_prompt_path(run_dir, worker_role, task_type, seq)):
239
275
  return []
240
276
  try:
241
277
  audit_content = audit_path.read_text(encoding="utf-8")
242
278
  except OSError as exc:
243
279
  return [f"worker audit sidecar unreadable: {audit_path.name} ({exc})"]
244
280
 
245
- read_paths = _audit_evidence_read_paths(audit_content)
281
+ read_paths = audit_evidence_read_paths(audit_content)
246
282
  missing_paths = sorted(_cited_file_paths(result_content) - read_paths)
247
283
  return [
248
284
  f"worker `{worker_role}` result `{result_name}` cites "
@@ -3,7 +3,25 @@ from __future__ import annotations
3
3
 
4
4
  from typing import Any, Mapping, Sequence
5
5
 
6
- from .worker_prompt_policy import PromptPlan
6
+ from .worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE, PromptPlan
7
+
8
+ # The duty contract ahead of this body is shared across task types and says what
9
+ # a result must be, not what to open in which order; a worker that follows only
10
+ # its wording reads the packet and writes. Requirements discovery is answered
11
+ # from code, so its analysers get the order of work in front of the inputs.
12
+ _INVESTIGATION_PROCEDURE: dict[str, tuple[str, ...]] = {
13
+ "requirements-discovery": (
14
+ "1. List every open question in the brief and every expected end-state "
15
+ "row (EB, PB, EO) the packet carries.",
16
+ "2. For each, open the code that answers it: the endpoint or handler, the "
17
+ "service, the repository or query, the model or type (installed dependency "
18
+ "packages included) and the existing tests or specs. Read the bodies, not "
19
+ "only the file names.",
20
+ "3. Record every file you open as an `Evidence read` row in the audit sidecar.",
21
+ "4. Judge every Coverage Census cell from what you opened.",
22
+ "5. Run the preamble's \"Before writing the result\" check, then write the result.",
23
+ ),
24
+ }
7
25
 
8
26
 
9
27
  def analysis_worker_label(worker_id: str) -> str:
@@ -28,6 +46,11 @@ def analysis_prompt_body(
28
46
  ) -> list[str]:
29
47
  """Render the provider-neutral body for an initial analysis audience."""
30
48
  label = analysis_worker_label(worker_id)
49
+ task_type = _require_string(manifest, "taskType")
50
+ procedure = (
51
+ _INVESTIGATION_PROCEDURE.get(task_type, ())
52
+ if plan.duty_audience == ANALYSIS_DUTY_BY_TASK_TYPE.get(task_type) else ()
53
+ )
31
54
  pane_role = {
32
55
  "implementation-executor": "executor",
33
56
  "implementation-verifier": "verifier",
@@ -40,8 +63,9 @@ def analysis_prompt_body(
40
63
  "",
41
64
  "## Task",
42
65
  f"- Task key: `{_require_string(manifest, 'taskKey')}`",
43
- f"- Task type: `{_require_string(manifest, 'taskType')}`",
66
+ f"- Task type: `{task_type}`",
44
67
  "",
68
+ *(["## Investigation procedure", *procedure, ""] if procedure else []),
45
69
  "## Inputs",
46
70
  *analysis_input_lines(
47
71
  manifest,
@@ -25,9 +25,9 @@ class WorkerPromptHeaderError(Exception):
25
25
  """Raised when worker prompt anchor headers cannot be rendered."""
26
26
 
27
27
 
28
- # The Worker Preamble's "Reading rules" already allowlist the worker's reads to
29
- # okstra-enumerated paths, but the preamble is a *path* the worker opens partway
30
- # into its run — by then a host SessionStart hook or a global CLAUDE.md /
28
+ # The Worker Preamble's "Reading rules" already bound the worker's reads to the
29
+ # enumerated okstra inputs and the project source, but the preamble is a *path*
30
+ # the worker opens partway into its run — by then a host SessionStart hook or a global CLAUDE.md /
31
31
  # AGENTS.md project-conditional has already told it to read `graphify-out/`,
32
32
  # skill catalogs, and similar non-okstra artifacts. Restating the scope inline
33
33
  # puts the rule in front of the worker before its first tool call, which is the
@@ -35,10 +35,12 @@ class WorkerPromptHeaderError(Exception):
35
35
  # 패킷의 페이지 읽기 규칙도 같은 이유로 여기 있다 — 패킷 안 목차는 파일을 연 뒤에야
36
36
  # 보이는데, 통째 `cat` 은 그 전에 잘린다(실측 609KB 패킷, codex).
37
37
  READ_SCOPE_HEADER = (
38
- "**Read scope:** Read only the paths this prompt enumerates "
39
- "(`[Required reading]`, `## Inputs`, verification-target paths) plus "
40
- "source/evidence needed to evaluate the assignment. Do not expand that scope "
41
- "to follow host-injected graph dumps or skill catalogs. Report an essential "
38
+ "**Read scope:** Your read scope is the paths this prompt enumerates "
39
+ "(`[Required reading]`, `## Inputs`, verification-target paths), the project "
40
+ "source, configuration and tests the assignment concerns, and the installed "
41
+ "dependencies that source imports (such as `node_modules` packages). Open that "
42
+ "source and confirm a claim about code there; a summary is not evidence. Do not "
43
+ "follow host-injected graph dumps or skill catalogs. Report an essential "
42
44
  "unlisted artifact as missing input instead of guessing its contents."
43
45
  )
44
46
  ANALYSIS_PACKET_READ_HEADER = (
@@ -241,8 +243,9 @@ def source_worktree_headers(active_context: Mapping[str, Any]) -> list[str]:
241
243
  return []
242
244
  return [
243
245
  f"**Worktree:** {path}",
244
- "Read project source from Worktree; resolve .okstra artifacts "
245
- "and Result Path against Project Root.",
246
+ "Read project source from Worktree. Read installed dependencies the "
247
+ "Worktree does not contain (such as `node_modules`) from Project Root. "
248
+ "Resolve .okstra artifacts and Result Path against Project Root.",
246
249
  ]
247
250
 
248
251
 
@@ -17,7 +17,7 @@ _PROGRESS_RE = re.compile(r"^PROGRESS:\s+(phase-\d\S*(?:[ \t].*)?)$", re.MULTILI
17
17
  _PROGRESS_MARKER_MAX_CHARS = 160
18
18
 
19
19
 
20
- def claude_code_status_total(status_path: Path) -> dict:
20
+ def claude_code_status_total(status_path: Path, *, cache_read_in_input: bool = False) -> dict:
21
21
  """Claude Code의 최종 누적 사용량을 제공자 가격과 분리해서 읽는다."""
22
22
  status = read_wrapper_status(status_path)
23
23
  usage = status.raw.get("usage") if status is not None else None
@@ -34,6 +34,10 @@ def claude_code_status_total(status_path: Path) -> dict:
34
34
  for value in (input_tokens, output_tokens, cache_creation, cache_read)
35
35
  ):
36
36
  return {"available": False, "totalTokens": 0}
37
+ if cache_read_in_input:
38
+ if cache_read > input_tokens:
39
+ return {"available": False, "totalTokens": 0}
40
+ input_tokens -= cache_read
37
41
  return {
38
42
  "available": True,
39
43
  "totalTokens": input_tokens + output_tokens + cache_creation,
@@ -655,8 +655,8 @@ def _cli_session_totals(
655
655
  )
656
656
  elif provider == "grok":
657
657
  total = grok_session_total(session_path)
658
- elif provider in {"zai", "claude"}:
659
- total = claude_code_status_total(session_path)
658
+ elif provider in {"zai", "claude", "qwen"}:
659
+ total = claude_code_status_total(session_path, cache_read_in_input=provider == "qwen")
660
660
  else:
661
661
  continue
662
662
  if total.get("available"):
@@ -921,7 +921,7 @@ def _worker_cli_usage_block(
921
921
  provider, project_root, worker, records, windows, status_paths,
922
922
  )
923
923
  status_path = status_paths[-1] if status_paths else None
924
- if provider == "zai":
924
+ if provider in {"zai", "qwen"}:
925
925
  session_paths = list(dict.fromkeys(
926
926
  path for path in status_paths if path is not None and path.is_file()
927
927
  ))
@@ -31,6 +31,7 @@ from okstra_ctl.models import catalog_pricing
31
31
  # entries below carry the 5m tier; the 1h price is derived as base_input * 2x
32
32
  # at call time so the table stays compact.
33
33
  CLAUDE_PRICING = {
34
+ "fable-5-2": (8.0, 10.0, 0.20, 40.0),
34
35
  # model substring -> (input, cache_creation_5m, cache_read, output) USD/1M.
35
36
  #
36
37
  # _match_pricing picks the longest matching key (most specific), so ordering
@@ -36,6 +36,23 @@
36
36
  ],
37
37
  "additionalProperties": false,
38
38
  "properties": {
39
+ "implementationComparison": {
40
+ "type": "object",
41
+ "required": ["schemaVersion", "owner", "baselineRef", "targetRef", "notesPath", "generation", "recordIds", "evidence", "notesGuide", "limitations"],
42
+ "additionalProperties": false,
43
+ "properties": {
44
+ "schemaVersion": {"const": "1.0"},
45
+ "owner": {"type": ["object", "null"]},
46
+ "baselineRef": {"type": ["object", "null"]},
47
+ "targetRef": {"type": ["object", "null"]},
48
+ "notesPath": {"type": ["string", "null"]},
49
+ "notesGuide": {"type": ["string", "null"]},
50
+ "generation": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"},
51
+ "recordIds": {"type": "array", "maxItems": 1000, "items": {"type": "string", "minLength": 1}},
52
+ "evidence": {"type": "array", "maxItems": 1000, "items": {"type": "object"}},
53
+ "limitations": {"type": "array", "items": {"type": "string"}}
54
+ }
55
+ },
39
56
  "resultPath": {
40
57
  "type": "string",
41
58
  "minLength": 1
@@ -37,4 +37,4 @@ The final `confirm` step is a normal `pick` step with three options — `Proceed
37
37
 
38
38
  Never invent additional questions. Relay every `pick` / `pick_group` option the wizard sends, in order, including the flagged recommendation: the wizard's arrays are the complete choice set whatever the host UI's usual option limit, and the run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
39
39
 
40
- **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` steps), or that marks the free-input / abort escape as a recommendation.
40
+ **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`, `worker_settings_models`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` / `worker_settings_models` steps), or that marks the free-input / abort escape as a recommendation.
@@ -102,7 +102,7 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
102
102
  1. **Read [census rules](references/census-rules.md).** Resolve `<okstraHome>` with `okstra paths --field home`; use its `prompts/coding-preflight/review-rules.json` as `<rules-path>`, without retyping a parallel catalog.
103
103
  2. Collect the diff from Step 1's Git root: `git -C <gitRoot> diff --name-status <baseCommit>..<headCommit>` for files and `git -C <gitRoot> diff <baseCommit>..<headCommit>` for hunks. First run `git -C <gitRoot> rev-list --count <headCommit>..<baseCommit>`: a nonzero count is the divergence case in Exceptions. An empty diff dispatches no reviewers.
104
104
  3. **Capture and select one policy.** Set `<census-path>` to `<projectRoot>/.okstra/agent-invocations/code-review/<review-id>.census.md`, where `<review-id>` names this review and round (for example `pr<N>-r<round>`). `code-review census` refuses a census whose `.policy.json` would fall outside the project's `.okstra/`, and reuses the immutable policy already published beside an existing `<census-path>`, so give every new review round its own `<review-id>`. Step 3's `code-review prepare` writes the specialists' assigned censuses, slots, brief and batch in the same directory. Run `okstra code-review census --project-root <projectRoot> --base <baseCommit> --head <headCommit> --rules <rules-path> --out <census-path>`. The command captures canonical coding rules, declared project policy and protocol/calibration, then selects resources from the fixed range; declared architecture precedes layout signals. When resolved stage inputs explicitly name a run manifest, add `--run-manifest <run-manifest>` to reuse its author's captured policy. Never infer a latest run or claim policy equality without that source. Additional applied project policy uses repeated `--policy <path>` inputs in the same capture.
105
- 4. Inspect the actual diff for embedded SQL, ORM queries and other resource needs automatic path/manifest routing misses. Add repeated `--resource <pack-relative-id>` inputs for applicable resources present in the archive; do not route again for a specialist. Review selection excludes author-only source-writing procedures. Add `--previous-census <prior-census-path>` only for [ID continuity](references/census-rules.md#follow-up-review). Exit 1 identifies unresolved non-Python function boundaries: complete their manual inventory before dispatch.
105
+ 4. Inspect the actual diff for embedded SQL, ORM queries and other resource needs automatic path/manifest routing misses. Add repeated `--resource <pack-relative-id>` inputs for applicable resources present in the archive; do not route again for a specialist. Review selection excludes author-only source-writing procedures. Add `--previous-census <prior-census-path>` only for [ID continuity](references/census-rules.md#follow-up-review). Exit 1 lists unresolved non-Python function boundaries: rerun with `--function-inventory <projectRoot>/.okstra/agent-invocations/code-review/<review-id>.functions.json`. The first run writes a template naming those files and exits 2; replace each null entry with `functions: [{start, end, name}]` spans read from the frozen head and a nonblank whole-file `rationale` (an empty list still needs one), then run it again. Do not add function cells to the census by hand.
106
106
  5. Carry the returned literal `Review policy` path as `<review-policy-path>`; the shared snapshot is `<census-path>.policy.json`. Preserve its `Review policy digest` and `Review resources` metadata lines in every full or assigned census. `-` resources means no explicit additions. Keep the same snapshot and resource values for every specialist and gap-fill, passing additions to `code-review prepare` as the same repeated `--resource` inputs. Materialization routes language and framework bodies from the assignment's own targets, so a specialist can receive fewer packs than the census selection lists; the rule catalog and architecture routing stay identical because architecture detection reads the whole frozen tree. Mutable installed skill or calibration paths are capture inputs, never replacements for delivered frozen guidance.
107
107
  6. Verify [both completion criteria](references/census-rules.md#completion-criteria) and follow [What to emit](references/census-rules.md#what-to-emit). Preserve the complete census and policy selection. Report a large census's size without truncation; dispatch follows the [authorization boundary](#authorization-and-recovery), not another confirmation based on size alone.
108
108
 
@@ -23,7 +23,7 @@ Membership follows the mechanical tests below, never an expected violation or a
23
23
  | `state-and-tests` | non-test source file × `state-and-tests`, test file × `state-and-tests` | every changed non-test source file gets one cell; every changed test file gets one cell |
24
24
  | `general` | non-test source file × `general` | every changed non-test source file |
25
25
 
26
- Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) receive `state-and-tests` cells and semantic cells for changed named functions/helpers. Test-case bodies remain subject to test-quality review; named helper readability is not exempt. `code_review_census.py` enumerates Python functions; other supported code suffixes remain unresolved until a manual inventory supplies their spans.
26
+ Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) receive `state-and-tests` cells and semantic cells for changed named functions/helpers. Test-case bodies remain subject to test-quality review; named helper readability is not exempt. `code_review_census.py` enumerates Python functions; other supported code suffixes remain unresolved until the lead's `--function-inventory` supplies their spans.
27
27
 
28
28
  Intersect frozen signature/body spans with changed lines, including enclosing and nested functions. Use base-side spans for deletion-only changes and map surviving functions to head positions. Removed functions and changes outside functions (imports, wiring, declarations and class-level constants) belong to file-level cells. If boundaries cannot be established, stop before dispatch with an incomplete census. Boundary completeness remains a lead source-inspection check.
29
29
 
@@ -64,7 +64,7 @@ Return one compact Coverage Verdicts row per cell under `## Coverage Verdicts`.
64
64
  | C-CR-0003 | - | T1=no state mutation; T2=non-test source; T3=non-test source; T4=no tests or new branches | - | src/orders/schema.py:1 |
65
65
  ```
66
66
 
67
- `Checked` means inspected with no actionable finding. A criterion includes all applicable subconditions; one inapplicable bullet does not make the whole criterion N/A. List every expected ID exactly once across `Checked`, `N/A` (`rule=reason`) and `Findings` (`rule=finding-id`). `all`, counts and ID ranges are invalid. Separate assignments with semicolons and finding IDs for one rule with commas; only a semicolon before the next `RULE=` starts a new assignment. Use `-` for empty fields and never infer omitted rules as clean.
67
+ `Checked` means inspected with no actionable finding. A criterion includes all applicable subconditions; one inapplicable bullet does not make the whole criterion N/A. List every rule the Rules table assigns to the cell's Group exactly once across `Checked`, `N/A` (`rule=reason`) and `Findings` (`rule=finding-id`), and no rule of another Group: the parser rejects the whole row. A specialist covering several quality dimensions still records them under its own Group's rules. `all`, counts and ID ranges are invalid. Separate assignments with semicolons and finding IDs for one rule with commas; only a semicolon before the next `RULE=` starts a new assignment. Use `-` for empty fields and never infer omitted rules as clean.
68
68
 
69
69
  Every row supplies one literal repository-relative source `path:line` for that cell's target file. The citation may be backtick-quoted and followed by a short observation, separated by a space or ` — `, before any ` :: ` rule observations. A bare citation remains valid. Do not use line ranges or substitute a rule-pack citation such as `cc:5`, a global alias such as `E01`, or another target's path. The checker verifies the declared source side and location; `base:` requires the frozen `--base`, and line 0 requires an empty regular file. These explicit forms override the head-line default above. Additional definitions and evidence remain in finding bodies. `review_verdicts.py` enforces the source grammar; `tests/verification/test_design_review.py` covers described anchors and invalid source rejection.
70
70
 
@@ -64,7 +64,7 @@ The final `confirm` step is a normal `pick` step with three options — `Proceed
64
64
 
65
65
  Never invent additional questions. Relay every `pick` / `pick_group` option the wizard sends, in order, including the flagged recommendation: the wizard's arrays are the complete choice set whatever the host UI's usual option limit, and the run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
66
66
 
67
- **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` steps), or that marks the free-input / abort escape as a recommendation.
67
+ **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`, `worker_settings_models`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` / `worker_settings_models` steps), or that marks the free-input / abort escape as a recommendation.
68
68
  <!-- END FRAGMENT: wizard-relay-protocol -->
69
69
 
70
70
  <!-- BEGIN FRAGMENT: wizard-preflight -->
@@ -108,7 +108,7 @@ The final `confirm` step is a normal `pick` step with three options — `Proceed
108
108
 
109
109
  Never invent additional questions. Relay every `pick` / `pick_group` option the wizard sends, in order, including the flagged recommendation: the wizard's arrays are the complete choice set whatever the host UI's usual option limit, and the run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)".
110
110
 
111
- **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` steps), or that marks the free-input / abort escape as a recommendation.
111
+ **One recommendation, shown in one place, and it is option 1.** Wizard labels carry no recommendation marker of their own. The option carrying `recommended: true` is what this run computed, and the wizard already placed it first — except on model-selection steps (`role-models:*`, `role-model:*`, `worker_settings_models`), which keep provider display order, so the flagged model may sit anywhere in the list. Append ` (추천)` to that option's label when you render it, and to no other. A checkbox step (`multi: true`) may flag several leading options: they are the recommended set, rendered the same way. Your prose recommendation names one of the flagged options. If you believe a different option is right, do not quietly recommend it in prose while the flagged one still reads as recommended on screen: say you disagree, name both, and let the user pick. When no option carries the flag, the run computed nothing for this step — recommend one from what you read and mark that one, and do not present the first option as a default just because it is first. **Enforced:** `scripts/okstra_ctl/wizard/state.py` `Prompt.__post_init__` refuses a step whose free-input option is not last, whose single-select recommendation is not exactly one option, whose recommendation is not placed first on a single-select step or is not the leading run on a checkbox step (both position checks are skipped on `role-models:*` / `role-model:*` / `worker_settings_models` steps), or that marks the free-input / abort escape as a recommendation.
112
112
  <!-- END FRAGMENT: wizard-relay-protocol -->
113
113
 
114
114
  <!-- BEGIN FRAGMENT: wizard-preflight -->
@@ -259,7 +259,7 @@ That is the entire interactive flow. The wizard handles:
259
259
  - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
260
260
  - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number). Implementer slots use role-count / role-model like every other role (`executor` is only a compatibility alias for `implementer`). When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
261
261
  - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose the eligible stages to open a PR for, one PR per stage; the result goes out as render-args' `stages` key (csv; empty takes every eligible stage),
262
- - launch selection after identity/worktree steps: one screen per static role, in profile order. A role that can run several instances (`max > 1`) is a checkbox step `role-models:<role>` (`multi: true`) — the number of models checked is the number of instances, there is no separate count question; the label states the profile range and recommended count, every executable candidate is listed on that one screen (defaults first, the recommended set flagged), and when the list exceeds the host's native checkbox limit the runtime either splits it into several checkbox questions on one `pick_group` screen (interaction plan `native-group`; the question steps are `role-models:<role>#1`, `#2`, … and the answer is one JSON object keyed by them, each value a CSV) when the host's native question group holds every option, or returns the interaction plan `numbered-multi` — render the whole list, never a shortlist or pages. An optional role (`min = 0`, e.g. critic) carries a `추가 안 함` row. A fixed single role (`min = max = 1`, e.g. report-writer) is a single pick `role-model:<role>:1`, and a role capped at one model (`max = 1`, e.g. critic) is a single pick on its `role-models:<role>` step; both split the same way when they exceed the native option limit — the tabs are checkbox questions, the answer is the same keyed JSON object, and the wizard rejects a screen whose tabs together name more than one value. current-session lead is this session and is listed on the confirmation summary, not as a wizard step. The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Dynamic verifiers are not chosen at launch. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
262
+ - launch selection after identity/worktree steps: one screen per static role, in profile order. A role that can run several instances (`max > 1`) is a checkbox step `role-models:<role>` (`multi: true`) — the number of models checked is the number of instances, there is no separate count question; the label states the profile range and recommended count, every executable candidate is on that screen (defaults first, the recommended set flagged). When the host has a native question group, the runtime always shows a model screen as one `pick_group` of vendor tabs (interaction plan `native-group`; the question steps are `role-models:<role>#1`, `#2`, … and the answer is one JSON object keyed by them, each value a CSV): a vendor with at least as many models as a tab shows (claude-code: 3) gets its own tab, the others share one mixed tab, each tab lists up to that many models keeping the recommended ones and ends with a `직접 입력 (<vendors>)` row. Ticking that row makes the next step `role-model-input:<role>`, a text step that takes model ids of those vendors (`provider/model` or the model id, comma-separated); the wizard joins them to the ticked models. Without a question group the runtime returns the whole list (`numbered-multi` / `numbered-single`) — render every option, never a shortlist or pages. An optional role (`min = 0`, e.g. critic) carries a `추가 안 함` row on the full list; vendor tabs have no such row, and an answer with nothing ticked skips the role. A fixed single role (`min = max = 1`, e.g. report-writer) is a single pick `role-model:<role>:1`, and a role capped at one model (`max = 1`, e.g. critic) is a single pick on its `role-models:<role>` step; both are shown as the same vendor tabs — the tabs are checkbox questions, the answer is the same keyed JSON object, and the wizard rejects a screen whose tabs together name more than one value. current-session lead is this session and is listed on the confirmation summary, not as a wizard step. The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Worker settings edit a role in up to three steps: `worker_settings_action` (choose models, or inherit/clear, disable, cancel), `worker_settings_models` shown as the same vendor tabs, and `worker_settings_model_input` when a typed row was ticked. Dynamic verifiers are not chosen at launch. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
263
263
  - reasoning effort (`reasoning_effort`) after the role screens and the directive, for every task type whose profile starts workers (not `release-handoff`): `high` (recommended) / `low` / `medium` / `xhigh`. The answer goes out as `--reasoning-effort`, is stored as the run manifest's `reasoningEffort`, and every claude, codex and grok worker CLI of the run starts with it; antigravity, kimi and zai keep their own configuration.
264
264
  - **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning` / `project-analysis` / `feature-analysis` / `change-impact-analysis`, only when prior run-inputs exist): YES prefills role-count·role-model·directive·related-tasks at once (and, for the analysis types, the target and evidence inputs). (2) `clarification_pick`: a `revision-requested` analysis report for the selected analysis type is recommended first; otherwise the **task-type's own** previous `final-report` is auto-recommended as the carry-in input (for `technical-verification`, the `implementation-option-selection` report), falling back to the newest by mtime across all phases when absent — except for `implementation-planning` and `technical-verification`, which get no cross-phase fallback. The approved plan is never recommended here. The same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
265
265
  - **re-verification scope (`reverify_scope_pick`, `implementation-planning` clarification re-runs only)** — asked right before `confirm` when the re-run is narrowable **or** an answered `C-NNN` traces to no stage. When every answered id traces to a stage: 3 options — `auto` (recommended — leave it to the lead's `okstra incremental-scope` decision) / `full` (re-verify every stage) / Enter directly (a stage-number CSV, validated against the prior report's Stage Map). When an id is unlinked, `auto` is omitted and the user names stages or picks `full`; that unlinked id does not freeze the run at full. The answer goes out as `--reverify-scope` and reaches the lead prompt as the `REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` tokens; it shapes that CLI's inputs rather than replacing the decision. The confirmation block's `reverify-scope` line names unlinked ids as needing stage numbers, not as a forced full re-run,
@@ -350,6 +350,37 @@ After successful preparation of a single run, delete the literal state-file path
350
350
  If the file disappears before a remaining stage is prepared, stop that chain and report the completed and remaining stages. Reopen the wizard for the remaining scope; do not rebuild its inputs or approval receipt from a previous run. Already prepared runs resume from their run manifest without this file. After an interrupted or uncertain preparation, inspect the task's existing runs before retrying: this command does not promise exactly-once preparation.
351
351
  <!-- END FRAGMENT: wizard-render-bundle -->
352
352
 
353
+ New implementation manifests retain `implementationComparison` for the actual
354
+ stage source and the first task baseline. Preserve its capture limitations when
355
+ reporting progress. Existing runs reuse their saved baseline; runs without this
356
+ declaration retain their original contract without a retrospective capture.
357
+
358
+ For a declared implementation comparison, report-writer materialization preserves
359
+ the current completed verification generation before writing. Its synthesis
360
+ packet supplies the exact optional notes path, common authoring guide, original
361
+ references, observed execution evidence and limitations. Reuse that context;
362
+ do not add a separate implementation, verification, or model round for the
363
+ comparison. Corrective writing reuses the preserved target.
364
+
365
+ After a successful implementation `report-finalize`, present the returned
366
+ `comparison` HTML/status and capture limitations alongside the original report.
367
+ Keep `comparisonWarnings` and `linkStatus` separate from implementation completion:
368
+ an optional comparison or existing-HTML link failure does not undo the completed
369
+ implementation. A source change detected between target preservation and automatic
370
+ publication leaves the previous comparison current. Recover from saved inputs
371
+ with `okstra implementation-report render --run-manifest <RUN_MANIFEST_PATH>`;
372
+ do not repeat implementation, tests, stage completion, or baseline capture.
373
+
374
+ After actual `stage-done`, also present its `comparison` result: the shared publisher
375
+ refreshes the whole-task view from the latest plan, valid stored completions and
376
+ preserved stage evidence. An optional report failure leaves the saved done row
377
+ and carry intact. Recover only that view with
378
+ `okstra implementation-report render --run-manifest <RUN_MANIFEST_PATH> --scope task`.
379
+ It retains separate stage contexts and uses one cumulative target only when stored
380
+ source identities and read-only Git ancestry establish that it includes all selected
381
+ stages. Parallel or unproven targets stay separate; never sum stage effects or run
382
+ merge, rebase, implementation, tests or models to generate this report.
383
+
353
384
  <!-- BEGIN FRAGMENT: wizard-lead-takeover -->
354
385
  ## Step 6: Take over as Okstra lead
355
386