okstra 0.225.1 → 0.227.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 (99) hide show
  1. package/README.md +1 -0
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.mjs +5 -0
  5. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  6. package/dist/commands/execute/wizard.mjs +12 -15
  7. package/dist/commands/execute/wizard.mjs.map +1 -1
  8. package/docs/cli.md +46 -6
  9. package/docs/project-structure-overview.md +3 -1
  10. package/package.json +1 -1
  11. package/runtime/BUILD.json +2 -2
  12. package/runtime/agents/operations/code-review.json +1 -1
  13. package/runtime/bin/lib/okstra/cli.sh +5 -1
  14. package/runtime/bin/lib/okstra/globals.sh +1 -0
  15. package/runtime/bin/lib/okstra/usage.sh +3 -0
  16. package/runtime/bin/okstra.sh +2 -0
  17. package/runtime/prompts/duties/technical-verification-worker.json +2 -1
  18. package/runtime/prompts/lead/convergence.md +4 -1
  19. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  20. package/runtime/prompts/lead/phase-routing.md +7 -3
  21. package/runtime/prompts/lead/team-contract.md +1 -1
  22. package/runtime/prompts/wizard/prompts.ko.json +59 -0
  23. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +5 -0
  24. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
  25. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
  26. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
  27. package/runtime/python/okstra_ctl/analysis_packet.py +108 -2
  28. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +206 -0
  29. package/runtime/python/okstra_ctl/brief_sources.py +200 -0
  30. package/runtime/python/okstra_ctl/business_flow/store.py +15 -2
  31. package/runtime/python/okstra_ctl/cmux.py +18 -3
  32. package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
  33. package/runtime/python/okstra_ctl/code_review_target.py +77 -53
  34. package/runtime/python/okstra_ctl/convergence_critic_prompt.py +4 -1
  35. package/runtime/python/okstra_ctl/correction_cli.py +6 -5
  36. package/runtime/python/okstra_ctl/correction_round.py +1 -1
  37. package/runtime/python/okstra_ctl/design_surfaces.py +19 -7
  38. package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
  39. package/runtime/python/okstra_ctl/execution_mutation_audit.py +20 -18
  40. package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
  41. package/runtime/python/okstra_ctl/implementation_direction.py +10 -0
  42. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +41 -0
  43. package/runtime/python/okstra_ctl/manager_split.py +185 -27
  44. package/runtime/python/okstra_ctl/next_phase.py +3 -1
  45. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +128 -0
  46. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +8 -5
  47. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +1 -1
  48. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +84 -0
  49. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  50. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +2 -2
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
  53. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +13 -5
  54. package/runtime/python/okstra_ctl/phases/implementation_option_selection/boundary.json +1 -1
  55. package/runtime/python/okstra_ctl/phases/implementation_option_selection/entry.py +67 -0
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +4 -2
  57. package/runtime/python/okstra_ctl/phases/implementation_option_selection/report_assets/implementation-option-selection.template.html +2 -1
  58. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +127 -18
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +2 -1
  62. package/runtime/python/okstra_ctl/phases/technical_verification/profile.md +2 -2
  63. package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
  64. package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
  65. package/runtime/python/okstra_ctl/report_assembly.py +23 -2
  66. package/runtime/python/okstra_ctl/report_views.py +2 -1
  67. package/runtime/python/okstra_ctl/run.py +61 -2
  68. package/runtime/python/okstra_ctl/run_context.py +13 -8
  69. package/runtime/python/okstra_ctl/stage_done.py +5 -4
  70. package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
  71. package/runtime/python/okstra_ctl/wizard/confirmation.py +27 -0
  72. package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
  73. package/runtime/python/okstra_ctl/wizard/ids.py +29 -0
  74. package/runtime/python/okstra_ctl/wizard/registry.py +21 -0
  75. package/runtime/python/okstra_ctl/wizard/render.py +6 -2
  76. package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
  77. package/runtime/python/okstra_ctl/wizard/sources.py +33 -11
  78. package/runtime/python/okstra_ctl/wizard/state.py +59 -14
  79. package/runtime/python/okstra_ctl/wizard/steps_options.py +74 -9
  80. package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
  81. package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
  82. package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
  83. package/runtime/python/okstra_ctl/worker_prompt_body.py +21 -1
  84. package/runtime/python/okstra_ctl/worker_prompt_headers.py +11 -4
  85. package/runtime/python/okstra_ctl/worker_prompt_policy.py +3 -0
  86. package/runtime/python/okstra_ctl/write_policy.py +33 -18
  87. package/runtime/schemas/final-report-v2.0.schema.json +74 -0
  88. package/runtime/schemas/final-report-v3.0.schema.json +99 -2
  89. package/runtime/skills/okstra-brief-gen/SKILL.md +26 -0
  90. package/runtime/skills/okstra-code-review/SKILL.md +25 -23
  91. package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
  92. package/runtime/skills/okstra-manager/SKILL.md +15 -2
  93. package/runtime/skills/okstra-run/SKILL.md +21 -1
  94. package/runtime/templates/reports/brief.template.md +10 -1
  95. package/runtime/templates/reports/html/i18n/en.json +8 -0
  96. package/runtime/templates/reports/html/i18n/ko.json +8 -0
  97. package/runtime/templates/worker-prompt-preamble.md +1 -1
  98. package/runtime/validators/validate-brief.py +39 -1
  99. package/runtime/validators/validate-run.py +5 -0
@@ -52,8 +52,6 @@ def render_role_args(state: WizardState) -> list[str]:
52
52
  if requirement.role not in state.role_counts:
53
53
  continue
54
54
  count = state.role_counts[requirement.role]
55
- if count <= 0:
56
- continue
57
55
  role_argv.extend([
58
56
  "--role-count",
59
57
  f"{requirement.role}={count}",
@@ -72,6 +70,8 @@ def render_role_args(state: WizardState) -> list[str]:
72
70
 
73
71
  def render_args(state: WizardState) -> dict[str, Any]:
74
72
  """Convert finalized state into ``okstra render-bundle`` argument map."""
73
+ if state.worker_settings_mode:
74
+ raise WizardError("worker settings cannot launch a task")
75
75
  if state.aborted:
76
76
  raise WizardError(
77
77
  "wizard was aborted by the user — render-args is unavailable"
@@ -112,6 +112,10 @@ def render_args(state: WizardState) -> dict[str, Any]:
112
112
  "related-tasks": state.related_tasks_raw,
113
113
  "clarification-response": state.clarification_response_path,
114
114
  "selected-direction": state.selected_direction_path,
115
+ "preselected-direction": (
116
+ state.preselected_direction
117
+ if state.task_type == "implementation-option-selection" else ""
118
+ ),
115
119
  "reverify-scope": (
116
120
  state.reverify_scope
117
121
  if state.task_type == "implementation-planning" else ""
@@ -36,6 +36,9 @@ from okstra_ctl.registry.provider_registry import provider_display_order
36
36
  from okstra_ctl.dispatch_state import detect_terminal_backend
37
37
  from okstra_ctl.registry.host_registry import default_host_registry
38
38
  from okstra_ctl.model_defaults import ModelDefaultScopes, default_candidates
39
+ from okstra_ctl.domain.worker_defaults import WorkerDefaultError
40
+ from okstra_ctl.worker_defaults import resolve_executable_worker_default
41
+ from okstra_ctl.registry.worker_defaults_store import default_worker_defaults_store
39
42
  from okstra_ctl.model_pool import ModelPool
40
43
  from okstra_ctl.role_requirements import RoleProfile, RoleRequirement
41
44
  from okstra_ctl.run import (
@@ -53,23 +56,19 @@ from .state import (
53
56
  _is_role_selection_step,
54
57
  _load_role_profile_for_state,
55
58
  )
56
- from .prompts import _opt, _p
59
+ from .prompts import _msg, _opt, _p
60
+ from .ids import (
61
+ _MODELS_PREFIX,
62
+ _SINGLE_PREFIX,
63
+ _fixed_single,
64
+ _role_model_prompt_id,
65
+ _role_models_prompt_id,
66
+ _role_prompt_id,
67
+ )
57
68
 
58
69
  # 선택 역할의 "추가 안 함" 값. 모델 참조는 `<provider>/<model>` 꼴이라 겹치지 않는다.
59
70
  ROLE_SKIP_TOKEN = "0"
60
71
 
61
- _MODELS_PREFIX = "role-models:"
62
- _SINGLE_PREFIX = "role-model:"
63
-
64
-
65
- def _role_models_prompt_id(role: str) -> str:
66
- return f"{_MODELS_PREFIX}{role}"
67
-
68
-
69
- def _role_model_prompt_id(role: str, ordinal: int) -> str:
70
- return f"{_SINGLE_PREFIX}{role}:{ordinal}"
71
-
72
-
73
72
  def _step_role(step_id: str) -> str:
74
73
  """역할 선택 step id 가 가리키는 역할. 역할 선택 step 이 아니면 빈 문자열."""
75
74
  for prefix in (_MODELS_PREFIX, _SINGLE_PREFIX):
@@ -78,11 +77,6 @@ def _step_role(step_id: str) -> str:
78
77
  return ""
79
78
 
80
79
 
81
- def _fixed_single(requirement: RoleRequirement) -> bool:
82
- """정확히 한 인스턴스만 두는 역할 — 단일 선택 화면이다."""
83
- return requirement.min_count == requirement.max_count == 1
84
-
85
-
86
80
  def _selected_role_count(
87
81
  state: WizardState,
88
82
  requirement: RoleRequirement,
@@ -215,6 +209,44 @@ def _skip_option(requirement: RoleRequirement, t: dict, *, recommended: bool) ->
215
209
  )
216
210
 
217
211
 
212
+ def _apply_configured_role_defaults(
213
+ state: WizardState,
214
+ requirement: RoleRequirement,
215
+ context: AssignmentContext,
216
+ profile: RoleProfile,
217
+ scopes: ModelDefaultScopes,
218
+ ) -> Prompt:
219
+ configured = None
220
+ error = ""
221
+ try:
222
+ configured = resolve_executable_worker_default(
223
+ requirement,
224
+ state.worker_defaults_snapshot or {},
225
+ context,
226
+ _host_session_context(state),
227
+ )
228
+ except WorkerDefaultError as exc:
229
+ error = str(exc)
230
+ step = _role_prompt_id(requirement)
231
+ if configured is not None and step not in state.manual_steps:
232
+ state.role_sources[requirement.role] = configured.scope
233
+ values = configured.models or (ROLE_SKIP_TOKEN,)
234
+ return Prompt(
235
+ step=step, kind="pick", multi=requirement.max_count > 1,
236
+ options=[Option(value, value) for value in values],
237
+ auto_value=",".join(values),
238
+ )
239
+ prompt = (
240
+ _model_prompt(state, profile, requirement, context, scopes)
241
+ if _fixed_single(requirement)
242
+ else _role_models_prompt(state, profile, requirement, context, scopes)
243
+ )
244
+ if error:
245
+ prompt.label = _msg(state.workspace_root, "worker_settings", "run_invalid",
246
+ error=error, label=prompt.label)
247
+ return prompt
248
+
249
+
218
250
  def _role_models_prompt(
219
251
  state: WizardState,
220
252
  profile: RoleProfile,
@@ -316,13 +348,14 @@ def _model_prompt(
316
348
  scopes: ModelDefaultScopes,
317
349
  ) -> Prompt:
318
350
  prompt = _p(state.workspace_root, "role_model", role=requirement.role)
351
+ options = _single_model_options(
352
+ state, profile, requirement.role, context, scopes,
353
+ )
319
354
  return Prompt(
320
355
  step=_role_model_prompt_id(requirement.role, 1),
321
356
  kind="pick",
322
357
  label=prompt["label"],
323
- options=_single_model_options(
324
- state, profile, requirement.role, context, scopes,
325
- ),
358
+ options=options,
326
359
  echo_template=prompt["echo_template"],
327
360
  )
328
361
 
@@ -332,6 +365,7 @@ def _drop_role_selection(state: WizardState, roles: set[str]) -> None:
332
365
  for role in roles:
333
366
  state.role_models.pop(role, None)
334
367
  state.role_counts.pop(role, None)
368
+ state.role_sources.pop(role, None)
335
369
  state.role_selection_order = [
336
370
  step_id for step_id in state.role_selection_order
337
371
  if _step_role(step_id) not in roles
@@ -376,6 +410,9 @@ def _discard_invalid_previous_models(
376
410
  _drop_role_selection(
377
411
  state, {later.role for later in requirements[index:]},
378
412
  )
413
+ step = _role_prompt_id(requirement)
414
+ if step not in state.manual_steps:
415
+ state.manual_steps.append(step)
379
416
  return
380
417
  prefix[requirement.role] = tuple(selected)
381
418
 
@@ -513,6 +550,10 @@ def _validate_role_selection_feasibility(
513
550
  def _load_context(state: WizardState) -> tuple[AssignmentContext, ModelDefaultScopes]:
514
551
  try:
515
552
  scopes = _model_default_scopes(Path(state.project_root))
553
+ if state.worker_defaults_snapshot is None:
554
+ state.worker_defaults_snapshot = (
555
+ default_worker_defaults_store().load_scopes(Path(state.project_root))
556
+ )
516
557
  except (PrepareError, ValueError) as exc:
517
558
  raise WizardError(str(exc)) from exc
518
559
  context = load_assignment_context(
@@ -535,10 +576,14 @@ def next_role_prompt(state: WizardState) -> Prompt | None:
535
576
  selected = state.role_models.get(role, [])
536
577
  if _fixed_single(requirement):
537
578
  if not selected:
538
- return _model_prompt(state, profile, requirement, context, scopes)
579
+ return _apply_configured_role_defaults(
580
+ state, requirement, context, profile, scopes
581
+ )
539
582
  continue
540
583
  if role not in state.role_counts:
541
- return _role_models_prompt(state, profile, requirement, context, scopes)
584
+ return _apply_configured_role_defaults(
585
+ state, requirement, context, profile, scopes
586
+ )
542
587
  count = state.role_counts[role]
543
588
  if count != len(selected) or not (
544
589
  (0 if requirement.min_count == 0 else requirement.min_count)
@@ -680,6 +725,11 @@ def _clear_role_selection(state: WizardState) -> None:
680
725
  state.role_counts.clear()
681
726
  state.role_models.clear()
682
727
  state.role_selection_order.clear()
728
+ state.role_sources.clear()
729
+ state.manual_steps = [
730
+ step_id for step_id in state.manual_steps
731
+ if not _is_role_selection_step(step_id)
732
+ ]
683
733
  state.answered = [
684
734
  step_id
685
735
  for step_id in state.answered
@@ -25,6 +25,7 @@ from okstra_ctl.final_report_paths import final_report_data_path
25
25
  from okstra_ctl.plan_run_root import list_implementation_planning_reports
26
26
  from okstra_ctl.stage_map import StageMapError, parse_stage_map_file
27
27
  from okstra_ctl.workflow import PHASE_SEQUENCE
28
+ from okstra_ctl.wizard_stage_intent import WHOLE_TASK_STAGE
28
29
  from okstra_ctl import worktree_registry
29
30
  from okstra_ctl.worktree import is_git_work_tree, main_worktree_path
30
31
  from okstra_ctl.paths import RunRef, task_runs_dir
@@ -362,14 +363,32 @@ def _contained_final_report_data_path(report: Path, task_root: Path) -> Path:
362
363
  )
363
364
 
364
365
 
366
+ def _stage_scoped_report_patterns(
367
+ segment: str, selected_stage: str
368
+ ) -> tuple[str, ...]:
369
+ """`segment` 아래에서 이 run 의 stage 범위에 속한 보고서 glob.
370
+
371
+ 숫자 stage 는 `stage-<N>/` 만, 전체 작업(flat run 디렉터리)은 flat 만 본다 —
372
+ 다른 범위의 답변은 이 run 의 clarification 이 아니다. stage 를 고르지 않는
373
+ run(release-handoff 등)은 둘 다 본다.
374
+ """
375
+ report = "reports/final-report-*.data.json"
376
+ if selected_stage.isdigit():
377
+ return (f"{segment}/stage-{selected_stage}/{report}",)
378
+ if selected_stage == WHOLE_TASK_STAGE:
379
+ return (f"{segment}/{report}",)
380
+ return (f"{segment}/{report}", f"{segment}/stage-*/{report}")
381
+
382
+
365
383
  def _newest_contained_final_report(
366
384
  runs_base: Path,
367
385
  task_root: Path,
368
- glob_pattern: str,
386
+ glob_patterns: tuple[str, ...],
369
387
  project_root: Path,
370
388
  ) -> Path | None:
371
389
  candidates: list[Path] = []
372
- for report in runs_base.glob(glob_pattern):
390
+ reports = (path for pattern in glob_patterns for path in runs_base.glob(pattern))
391
+ for report in reports:
373
392
  if not report.is_file():
374
393
  continue
375
394
  try:
@@ -513,7 +532,7 @@ def _technical_evidence_for_comparison(
513
532
  project_root = Path(state.project_root)
514
533
  report = _newest_contained_final_report(
515
534
  task_root / "runs", task_root,
516
- "technical-verification/reports/final-report-*.data.json", project_root,
535
+ ("technical-verification/reports/final-report-*.data.json",), project_root,
517
536
  )
518
537
  if report is None:
519
538
  return source
@@ -531,10 +550,11 @@ def _suggest_latest_final_report(state: WizardState) -> str:
531
550
  """clarification carry-in 으로 추천할 직전 final-report 의 relpath.
532
551
 
533
552
  resume-clarification 은 "같은 phase 를 답변과 함께 재실행" 이므로 재실행
534
- task-type **자신의** 보고서(``runs/<task-type>/reports/final-report-*.md``)를
535
- 우선한다. 그 phase 에 보고서가 없을 때만(예: 다음 phase 로 진행) 전체 phase 의
536
- mtime 최신으로 폴백한다 — 과거엔 무조건 전체 mtime 최신이라 더 최근에 재렌더된
537
- 다른 phase 보고서를 잘못 집을 수 있었다. 못 찾으면 빈 문자열.
553
+ task-type **자신의** 보고서(``runs/<task-type>[/stage-<N>]/reports/``)를
554
+ 우선한다(stage 범위는 ``_stage_scoped_report_patterns``). 그 phase 에 보고서가
555
+ 없을 때만(예: 다음 phase 로 진행) 전체 phase 의 mtime 최신으로 폴백한다 —
556
+ 과거엔 무조건 전체 mtime 최신이라 더 최근에 재렌더된 다른 phase 보고서를 잘못
557
+ 집을 수 있었다. 못 찾으면 빈 문자열.
538
558
  """
539
559
  if not state.task_group or not state.task_id or not state.project_root:
540
560
  return ""
@@ -560,7 +580,7 @@ def _suggest_latest_final_report(state: WizardState) -> str:
560
580
  best = _newest_contained_final_report(
561
581
  runs_base,
562
582
  task_root,
563
- f"{seg}/reports/final-report-*.data.json",
583
+ _stage_scoped_report_patterns(seg, state.selected_stage),
564
584
  Path(state.project_root),
565
585
  )
566
586
  # implementation-planning 의 `--clarification-response` 는 같은 phase 의
@@ -572,7 +592,9 @@ def _suggest_latest_final_report(state: WizardState) -> str:
572
592
  best = _newest_contained_final_report(
573
593
  runs_base,
574
594
  task_root,
575
- "*/reports/final-report-*.data.json",
595
+ # 다른 phase 의 flat 보고서(계획서 등)는 stage 범위와 무관하게 후보다.
596
+ ("*/reports/final-report-*.data.json",
597
+ *_stage_scoped_report_patterns("*", state.selected_stage)),
576
598
  Path(state.project_root),
577
599
  )
578
600
  best = _technical_evidence_for_comparison(state, best, task_root)
@@ -592,12 +614,12 @@ def _suggest_latest_final_report(state: WizardState) -> str:
592
614
 
593
615
 
594
616
  def _latest_run_inputs(
595
- state: WizardState, *, phase_segment: str = ""
617
+ state: WizardState, *, phase_segment: str = "", stage: Optional[int] = None
596
618
  ) -> dict:
597
619
  """직전 run 의 입력 스냅샷. 위치/구조 지식은 run_context.latest_run_inputs 가 SSOT."""
598
620
  return latest_run_inputs(
599
621
  state.project_root, state.task_group, state.task_id,
600
- phase_segment=phase_segment)
622
+ phase_segment=phase_segment, stage=stage)
601
623
 
602
624
 
603
625
  def _clarification_pick_required(state: WizardState) -> bool:
@@ -7,6 +7,11 @@ from typing import Any, Callable, Optional
7
7
 
8
8
  from okstra_ctl.registry.provider_registry import default_provider_registry
9
9
  from okstra_ctl.model_pool import ModelPool
10
+ from okstra_ctl.domain.worker_defaults import (
11
+ WorkerDefaultScopes,
12
+ WorkerDefaultUpdates,
13
+ WorkerScope,
14
+ )
10
15
  from okstra_ctl.role_requirements import (
11
16
  RoleProfile,
12
17
  RoleProfileError,
@@ -23,6 +28,9 @@ from .ids import (
23
28
  _ABORT_OPTION,
24
29
  _SLUG_OK,
25
30
  _STAGE_SCOPED_TASK_TYPES,
31
+ _role_model_prompt_id,
32
+ _role_models_prompt_id,
33
+ _role_prompt_id,
26
34
  )
27
35
 
28
36
 
@@ -34,6 +42,15 @@ class WizardState:
34
42
  role_counts: dict[str, int] = field(default_factory=dict)
35
43
  role_models: dict[str, list[str]] = field(default_factory=dict)
36
44
  role_selection_order: list[str] = field(default_factory=list)
45
+ role_sources: dict[str, str] = field(default_factory=dict)
46
+ worker_defaults_snapshot: WorkerDefaultScopes | None = None
47
+ worker_settings_mode: bool = False
48
+ worker_settings_scope: WorkerScope | None = None
49
+ worker_settings_updates: WorkerDefaultUpdates = field(default_factory=dict)
50
+ worker_settings_role: str = ""
51
+ worker_settings_review: bool = False
52
+ worker_settings_saved: bool = False
53
+ worker_settings_answers: int = 0
37
54
 
38
55
  # bootstrap
39
56
  workspace_root: str = ""
@@ -120,6 +137,9 @@ class WizardState:
120
137
  clarification_pending_text: bool = False
121
138
  last_final_report_cached: str = ""
122
139
  selected_direction_path: str = ""
140
+ # implementation-option-selection: 리드가 미리 정한 방향과 근거. 비면 candidate-comparison.
141
+ preselected_direction: str = ""
142
+ preselected_direction_pending_text: bool = False
123
143
  # "" | "auto" | "full" | "<stage csv>" — 사용자가 고른 이번 재실행의 재검증
124
144
  # 범위. implementation-planning 재실행에서 좁힐 여지가 있을 때만 채워진다.
125
145
  reverify_scope: str = ""
@@ -145,7 +165,6 @@ class WizardState:
145
165
 
146
166
  # bookkeeping
147
167
  answered: list[str] = field(default_factory=list)
148
- # Steps the user came back to through Edit; their auto_value no longer applies.
149
168
  manual_steps: list[str] = field(default_factory=list)
150
169
 
151
170
  def to_json(self) -> dict[str, Any]:
@@ -417,9 +436,10 @@ def _role_selections_from_run_inputs(
417
436
  pool = ModelPool.from_registry(default_provider_registry())
418
437
  cross_requirement = _initial_cross_verification_requirement(profile)
419
438
  assigned = _assigned_models_by_role(payload)
439
+ if assigned:
440
+ _restore_recorded_role_selections(state, profile, pool, assigned)
441
+ return
420
442
  providers = _legacy_worker_providers(payload)
421
- if cross_requirement is not None and cross_requirement.role in assigned:
422
- providers = [provider for provider, _ in assigned[cross_requirement.role]]
423
443
  if cross_requirement is not None:
424
444
  selected_count = cross_requirement.recommended_count
425
445
  if providers and cross_requirement.min_count < cross_requirement.max_count:
@@ -434,13 +454,8 @@ def _role_selections_from_run_inputs(
434
454
  model.provider_id
435
455
  for model in pool.default_candidates(cross_requirement.role)
436
456
  ]
437
- assigned_models = [model for _, model in assigned.get(cross_requirement.role, ())]
438
- for ordinal, provider in enumerate(providers[:selected_count], start=1):
439
- raw_model = (
440
- assigned_models[ordinal - 1]
441
- if ordinal <= len(assigned_models)
442
- else payload.get(f"{provider}Model", "")
443
- )
457
+ for provider in providers[:selected_count]:
458
+ raw_model = payload.get(f"{provider}Model", "")
444
459
  model_ref = _legacy_model_ref(
445
460
  pool,
446
461
  provider,
@@ -452,7 +467,9 @@ def _role_selections_from_run_inputs(
452
467
  state.role_models.setdefault(cross_requirement.role, []).append(model_ref)
453
468
  if cross_requirement.role in state.role_models:
454
469
  # 여러 인스턴스 역할의 답은 체크박스 한 장이다.
455
- state.role_selection_order.append(f"role-models:{cross_requirement.role}")
470
+ state.role_selection_order.append(
471
+ _role_models_prompt_id(cross_requirement.role)
472
+ )
456
473
 
457
474
  executor = payload.get("executor") or "claude"
458
475
  critic = payload.get("critic") or ""
@@ -472,15 +489,41 @@ def _role_selections_from_run_inputs(
472
489
  if not requirement.dynamic and requirement.min_count > 0
473
490
  }
474
491
  for role, provider, raw_model in provider_rows:
475
- if assigned.get(role):
476
- provider, raw_model = assigned[role][0]
477
492
  if role not in static_roles or not isinstance(provider, str) or not provider:
478
493
  continue
479
494
  model_ref = _legacy_model_ref(pool, provider, role, raw_model)
480
495
  if model_ref is None:
481
496
  continue
482
497
  state.role_models[role] = [model_ref]
483
- state.role_selection_order.append(f"role-model:{role}:1")
498
+ state.role_selection_order.append(_role_model_prompt_id(role, 1))
499
+
500
+
501
+ def _restore_recorded_role_selections(
502
+ state: WizardState,
503
+ profile: RoleProfile,
504
+ pool: ModelPool,
505
+ assigned: dict[str, list[tuple[str, str]]],
506
+ ) -> None:
507
+ for requirement in profile.roles:
508
+ if requirement.dynamic or requirement.role == "leader":
509
+ continue
510
+ role = requirement.role
511
+ rows = assigned.get(role, [])
512
+ if not rows and requirement.min_count > 0:
513
+ continue
514
+ models = [
515
+ model for provider, raw in rows
516
+ if (model := _legacy_model_ref(pool, provider, role, raw)) is not None
517
+ ]
518
+ step = _role_prompt_id(requirement)
519
+ if len(models) != len(rows):
520
+ state.manual_steps.append(step)
521
+ continue
522
+ if models:
523
+ state.role_models[role] = models
524
+ if requirement.min_count != requirement.max_count:
525
+ state.role_counts[role] = len(rows)
526
+ state.role_selection_order.append(step)
484
527
 
485
528
 
486
529
  class StaleWizardStateError(WizardError):
@@ -619,12 +662,14 @@ _FIELD_DEFAULTS: dict[str, Any] = {
619
662
  "selected_stages": "",
620
663
  "handoff_stages": "",
621
664
  "role_counts": {}, "role_models": {}, "role_selection_order": [],
665
+ "role_sources": {},
622
666
  "reuse_previous": None,
623
667
  "directive": "",
624
668
  "directive_pending_text": False,
625
669
  "related_tasks_raw": "", "related_tasks_pending_text": False,
626
670
  "clarification_response_path": "", "clarification_pending_text": False,
627
671
  "selected_direction_path": "",
672
+ "preselected_direction": "", "preselected_direction_pending_text": False,
628
673
  "reverify_scope": "", "reverify_scope_pending_text": False,
629
674
  "pr_template_path": "", "pr_template_pending_text": False,
630
675
  "pr_template_scope": "",
@@ -8,10 +8,17 @@ from typing import Callable, Optional
8
8
 
9
9
  from okstra_ctl.clarification_items import user_response_sidecars
10
10
  from okstra_ctl.domain.worker_exec import REASONING_EFFORTS
11
+ from okstra_ctl.ids import slugify_task_segment
11
12
  from okstra_ctl.manager_paths import MANAGER_CONTEXT_DIRECTIVE_PREFIX
12
13
  from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
13
14
  from okstra_ctl.report_language import is_language_tag
15
+ from okstra_ctl.phases.implementation_option_selection.entry import (
16
+ CANDIDATE_COMPARISON,
17
+ PRESELECTED_VALIDATION,
18
+ upstream_next_steps,
19
+ )
14
20
  from okstra_ctl.phases.implementation_planning.entry import is_existing_planning_report
21
+ from okstra_ctl.prepare_error import PrepareError
15
22
  from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
16
23
  from okstra_project.dirs import project_json_path
17
24
  from okstra_project.state import StateError, list_project_tasks
@@ -23,6 +30,7 @@ from .ids import (
23
30
  S_CLARIFICATION_PICK,
24
31
  S_DIRECTIVE,
25
32
  S_DIRECTIVE_PICK,
33
+ S_PRESELECTED_DIRECTION,
26
34
  S_PR_TEMPLATE,
27
35
  S_PR_TEMPLATE_PICK,
28
36
  S_PR_TEMPLATE_SCOPE,
@@ -30,6 +38,7 @@ from .ids import (
30
38
  S_RELATED_TASKS,
31
39
  S_RELATED_TASKS_PICK,
32
40
  S_REPORT_LANGUAGE,
41
+ S_SELECTION_MODE_PICK,
33
42
  _LATEST_REPORT_TOKEN,
34
43
  _PROJECT_DEFAULT_TOKEN,
35
44
  _REUSE_LAST_TOKEN,
@@ -97,7 +106,13 @@ def _clarification_sidecar_note(state: WizardState, suggestion: str) -> str:
97
106
 
98
107
  def _suggest_last_directive(state: WizardState) -> str:
99
108
  """같은 task 의 가장 최근 run-inputs-*.json 에서 directive 값을 자동 추출."""
100
- val = _latest_run_inputs(state).get("directive") or ""
109
+ inputs: dict = {}
110
+ if state.task_type and state.selected_stage.isdigit():
111
+ # stage run 의 directive 는 그 stage 범위로 쓰였다 — 형제 stage 것은 남의 것이다.
112
+ inputs = _latest_run_inputs(
113
+ state, phase_segment=slugify_task_segment(state.task_type),
114
+ stage=int(state.selected_stage))
115
+ val = (inputs or _latest_run_inputs(state)).get("directive") or ""
101
116
  return val if isinstance(val, str) else ""
102
117
 
103
118
 
@@ -129,9 +144,9 @@ class _OptionalCachedPickSpec:
129
144
  # 추천 옵션 라벨·echo 뒤에 덧붙일 동적 안내(예: 함께 첨부될 사이드카 개수).
130
145
  # (state, 추천 relpath) -> note. 미설정 picker 는 영향 없음.
131
146
  recommend_note: Optional[Callable[["WizardState", str], str]] = None
132
- # Whether the wizard takes the suggestion without asking. A previous directive
133
- # is an instruction written for another run, so reusing it stays a question.
134
- auto_take_suggestion: bool = True
147
+ # Whether the screen is always shown. No recorded value tells the wizard that a
148
+ # run needs no directive, and a previous one was written for another run.
149
+ always_ask: bool = False
135
150
 
136
151
 
137
152
  def _build_optional_cached_pick(state: WizardState, spec: _OptionalCachedPickSpec) -> Prompt:
@@ -149,12 +164,12 @@ def _build_optional_cached_pick(state: WizardState, spec: _OptionalCachedPickSpe
149
164
  setattr(state, spec.cache_attr, suggestion)
150
165
  options.append(_opt(PICK_SKIP, t["options"][PICK_SKIP]))
151
166
  options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
152
- if not suggestion:
167
+ if spec.always_ask:
168
+ auto_value = ""
169
+ elif not suggestion:
153
170
  auto_value = PICK_SKIP
154
- elif spec.auto_take_suggestion:
155
- auto_value = spec.recommend_token
156
171
  else:
157
- auto_value = ""
172
+ auto_value = spec.recommend_token
158
173
  return Prompt(
159
174
  step=spec.step, kind="pick",
160
175
  label=t["label"], options=options,
@@ -218,7 +233,7 @@ _DIRECTIVE_PICK_SPEC = _OptionalCachedPickSpec(
218
233
  cache_attr="last_directive_cached", target_attr="directive",
219
234
  pending_attr="directive_pending_text",
220
235
  recommend_note=_directive_context_note,
221
- auto_take_suggestion=False,
236
+ always_ask=True,
222
237
  )
223
238
 
224
239
 
@@ -393,6 +408,56 @@ def _submit_clarification(state: WizardState, value: str) -> Optional[str]:
393
408
  return f"clarification: {p}"
394
409
 
395
410
 
411
+ def _build_selection_mode_pick(state: WizardState) -> Prompt:
412
+ """The mode is the lead's decision; the upstream report's routing is shown beside it."""
413
+ t = _p(state.workspace_root, "selection_mode_pick")
414
+ label = t["label"]
415
+ if state.clarification_response_path:
416
+ try:
417
+ steps = upstream_next_steps(Path(state.clarification_response_path))
418
+ except PrepareError as exc:
419
+ raise WizardError(str(exc)) from exc
420
+ if steps:
421
+ label += t["labels"]["upstream"].format(steps=" / ".join(steps))
422
+ return Prompt(
423
+ step=S_SELECTION_MODE_PICK, kind="pick", label=label,
424
+ options=[_opt(value, text) for value, text in t["options"].items()],
425
+ echo_template=t["echo_template"],
426
+ )
427
+
428
+
429
+ def _submit_selection_mode_pick(state: WizardState, value: str) -> Optional[str]:
430
+ if value == CANDIDATE_COMPARISON:
431
+ state.preselected_direction = ""
432
+ state.preselected_direction_pending_text = False
433
+ return f"selection-mode: {CANDIDATE_COMPARISON}"
434
+ if value == PRESELECTED_VALIDATION:
435
+ state.preselected_direction_pending_text = True
436
+ return None
437
+ raise WizardError(
438
+ f"expected {CANDIDATE_COMPARISON!r} or {PRESELECTED_VALIDATION!r}, got: {value!r}"
439
+ )
440
+
441
+
442
+ def _build_preselected_direction(state: WizardState) -> Prompt:
443
+ t = _p(state.workspace_root, "preselected_direction")
444
+ return Prompt(
445
+ step=S_PRESELECTED_DIRECTION, kind="text",
446
+ label=t["label"], echo_template=t["echo_template"],
447
+ )
448
+
449
+
450
+ def _submit_preselected_direction(state: WizardState, value: str) -> Optional[str]:
451
+ direction = (value or "").strip()
452
+ if not direction:
453
+ raise WizardError(
454
+ f"{PRESELECTED_VALIDATION} needs the direction and the citation that fixed it"
455
+ )
456
+ state.preselected_direction = direction
457
+ state.preselected_direction_pending_text = False
458
+ return f"preselected-direction: {direction}"
459
+
460
+
396
461
  def _build_pr_template(state: WizardState) -> Prompt:
397
462
  t = _p(state.workspace_root, "pr_template")
398
463
  return Prompt(
@@ -9,6 +9,7 @@ from okstra_ctl.phases.feature_analysis.entry import resolve_analysis_target
9
9
  from okstra_ctl.models import UnknownModelError, resolve_model_metadata
10
10
 
11
11
  from .ids import S_REUSE_PREVIOUS, _REUSE_FILLED_STEPS
12
+ from .roles import _clear_role_selection
12
13
  from .state import (
13
14
  Prompt,
14
15
  WizardError,
@@ -90,10 +91,11 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
90
91
  conversion_payload = dict(inputs)
91
92
  conversion_payload.setdefault("grokModel", _assignment_model(inputs, "grok", "grok"))
92
93
  conversion_payload.setdefault("kimiModel", _assignment_model(inputs, "kimi", "kimi"))
93
- state.role_counts.clear()
94
- state.role_models.clear()
95
- state.role_selection_order.clear()
94
+ _clear_role_selection(state)
96
95
  _role_selections_from_run_inputs(state, conversion_payload)
96
+ state.role_sources = {
97
+ role: "previous" for role in state.role_models.keys() | state.role_counts.keys()
98
+ }
97
99
  directive = inputs.get("directive")
98
100
  state.directive = directive if isinstance(directive, str) else ""
99
101
  related = inputs.get("relatedTasks")