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
@@ -8,8 +8,8 @@
8
8
  1. Read the frozen technical input linked in the analysis packet. Preserve the source hash, candidate IDs and fact identities. `resolve_technical_verification_input` enforces same-task source ownership, schema validity, eligible technical facts and unresolved user-decision gates.
9
9
  2. Before executing a probe, write its plan under `experiments/<seq>/<worker-id>/`: hypothesis, procedure, commands, confirming and rejecting signals, environment, and inconclusive criteria. Retain the plan with the evidence.
10
10
  3. Create a separate source copy in that directory. Record the source commit and any uncommitted input differences. Read the project and task worktree as inputs; perform source edits, installations and builds only in your own copy. Do not share writable dependency directories or use real credentials. Use synthetic local accounts for request-boundary experiments.
11
- 4. Phase 7 removes every `node_modules` and `.next` directory under the run directory, so evidence must not live inside them. Preserve the baseline lockfile. When the hypothesis needs a deliberate dependency change, retain the resulting lockfile and diff, then use a frozen install against that experimental lockfile. Record command, working directory, stdout/stderr and exit code in run-local logs. Distinguish infrastructure failure from a falsified compatibility claim.
12
- 5. Classify each fact as `supported`, `refuted`, `inconclusive` or `not-run` using the declared signals. A zero exit code alone does not establish compatibility. Record limitations and all failed or unavailable probes.
11
+ 4. Phase 7 removes every `node_modules` and `.next` directory under the run directory, so evidence must not live inside them. Preserve the baseline lockfile. When the hypothesis needs a deliberate dependency change, retain the resulting lockfile and diff, then use a frozen install against that experimental lockfile. Record command, working directory, stdout/stderr and exit code in run-local logs. End every log with an `exit_code=<n>` line so a command that prints nothing on success, such as `tsc --noEmit`, still leaves a non-empty log; the report validator rejects an empty log. Record as `cwd` the project-relative directory the command ran in: when the command starts with `cd <dir> &&`, that is `<dir>`, not the shell's starting directory. Run every cited command inside `experiments/<seq>/`; a probe run from the project root is not admissible command evidence. Distinguish infrastructure failure from a falsified compatibility claim.
12
+ 5. Classify each fact as `supported`, `refuted`, `inconclusive` or `not-run` using the declared signals. A zero exit code alone does not establish compatibility. A `supported` check cites only commands that exited 0. When a command fails for a reason outside the hypothesis, such as a baseline failure that repeats identically on both sides of the comparison, do not cite it under a supported check: cite a command whose exit code expresses the confirming signal, such as `cmp` of the two logs, and name the failing logs in `limitations`. If no such command separates the outcomes, classify the fact `inconclusive`. Record limitations and all failed or unavailable probes.
13
13
  6. During convergence, inspect plans and logs; rerun disputed probes in a separate copy when feasible. An independent report is not a substitute for command evidence.
14
14
 
15
15
  Copy boundaries and pre-execution plans are worker instructions reviewed during convergence. The report validator checks fact completeness, run-local log files, experiment working directories and zero exit codes for supported results. It does not sandbox arbitrary shell commands or prove that a declared command produced its log.
@@ -0,0 +1,25 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Mapping
4
+ from pathlib import Path
5
+ from typing import Protocol
6
+
7
+ from ..domain.worker_defaults import (
8
+ WorkerDefaultScopes,
9
+ WorkerDefaultUpdates,
10
+ WorkerScope,
11
+ )
12
+
13
+
14
+ class WorkerDefaultsStore(Protocol):
15
+ def scope_path(self, scope: WorkerScope, project_root: Path | None) -> Path: ...
16
+
17
+ def load_scopes(self, project_root: Path | None) -> WorkerDefaultScopes: ...
18
+
19
+ def save_scope(
20
+ self,
21
+ scope: WorkerScope,
22
+ project_root: Path | None,
23
+ updates: WorkerDefaultUpdates,
24
+ before: Mapping[str, object],
25
+ ) -> dict[str, object]: ...
@@ -0,0 +1,8 @@
1
+ from __future__ import annotations
2
+
3
+ from ..adapters.worker_defaults import JsonWorkerDefaultsStore
4
+ from ..ports.worker_defaults import WorkerDefaultsStore
5
+
6
+
7
+ def default_worker_defaults_store() -> WorkerDefaultsStore:
8
+ return JsonWorkerDefaultsStore()
@@ -27,12 +27,16 @@ from .report_synthesis_packet import (
27
27
  )
28
28
  from .conformance import strip_stage_declaration_label
29
29
  from .coverage_census import census_warning_rows, read_census_state
30
+ from .design_surfaces import DesignSurfaceError, detect_design_surfaces
30
31
  from .design_prep import (
31
32
  DesignPrepError,
32
33
  canonicalize_request_paths,
33
34
  materialize_design_prep_requests,
34
35
  )
35
- from .phases.implementation_option_selection.validation import validate_blocked_answer_channel
36
+ from .phases.implementation_option_selection.validation import (
37
+ validate_blocked_answer_channel,
38
+ validate_split_acceptance,
39
+ )
36
40
  from .phases.discussion.report import discussion_report_block, discussion_report_errors
37
41
  from .phases.discussion.store import DiscussionStore, DiscussionStoreError
38
42
  from .phases.technical_verification.validation import validate_technical_verification_report
@@ -522,7 +526,7 @@ def _compose(
522
526
  data["crossVerification"]["correctionRounds"] = rounds
523
527
  data["clarificationItems"] = _clarifications(ledger, activities, inputs["approval-decisions"].path)
524
528
  # 작성자의 사실 분류와 리드 원장의 질문 연결은 양쪽 입력을 합친 뒤 검사한다.
525
- for reason in validate_blocked_answer_channel(data):
529
+ for reason in [*validate_blocked_answer_channel(data), *validate_split_acceptance(data)]:
526
530
  _fail(
527
531
  "lead",
528
532
  inputs["approval-decisions"].path,
@@ -688,9 +692,26 @@ def validate_plan_draft(
688
692
  f"implementationPlanning: {error}"
689
693
  for error in selected_direction_plan_errors(draft, project_root, manifest)
690
694
  ],
695
+ *_design_surface_errors(draft),
691
696
  ]
692
697
 
693
698
 
699
+ def _design_surface_errors(draft: Mapping[str, Any]) -> list[str]:
700
+ """`plan-items prepare` 가 돌릴 설계 표면 탐지기를 초안 단계에서 미리 돌린다.
701
+
702
+ 탐지 실패는 서사를 고쳐야 풀리는데, 교정 원장 대조가 이를 몰라 ok 를 낸 뒤
703
+ prepare 에서야 드러났다.
704
+ """
705
+ planning = draft.get("implementationPlanning")
706
+ if not isinstance(planning, Mapping) or not planning.get("stages"):
707
+ return []
708
+ try:
709
+ detect_design_surfaces(planning)
710
+ except (DesignSurfaceError, TypeError, AttributeError) as exc:
711
+ return [f"implementationPlanning: design-surface detection failed: {exc}"]
712
+ return []
713
+
714
+
694
715
  def _identity(manifest: Mapping[str, Any]) -> tuple[str, str, str]:
695
716
  task_key = str(manifest.get("taskKey") or "")
696
717
  parts = task_key.split(":")
@@ -87,6 +87,7 @@ from .clarification_items import (
87
87
  section_1_present_but_unparsed,
88
88
  )
89
89
  from .md_table import is_separator_row as _is_separator_row
90
+ from .phases.implementation_option_selection.validation import blocking_feasibility_facts
90
91
 
91
92
 
92
93
  # --------------------------------------------------------------------------- #
@@ -1175,7 +1176,7 @@ def direction_candidate_ineligibility(option: Mapping[str, Any]) -> str:
1175
1176
  coverage = option.get("coverageSummary")
1176
1177
  if not isinstance(coverage, Mapping) or coverage.get("coverageVerdict") != "exact":
1177
1178
  return "selected candidate must have exact coverage"
1178
- if option.get("safetyBlockers") or option.get("unresolvedFeasibilityFacts"):
1179
+ if option.get("safetyBlockers") or blocking_feasibility_facts(option):
1179
1180
  return "selected candidate has a safety blocker"
1180
1181
  return ""
1181
1182
 
@@ -55,7 +55,7 @@ from .phases.implementation_planning.entry import (
55
55
  _validate_reverify_scope,
56
56
  )
57
57
  from . import fix_cycles
58
- from .analysis_packet import build_analysis_packet
58
+ from .analysis_packet import build_analysis_packet, cited_documents_block
59
59
  from .mcp_servers import NO_MCP_SERVERS_LINE, prepare_mcp
60
60
  from .coverage_census import (
61
61
  CensusError,
@@ -164,6 +164,10 @@ from .models import (
164
164
  from .schema_excerpt import build_schema_excerpt
165
165
  from .registry.host_registry import default_host_registry
166
166
  from .registry.provider_registry import default_provider_registry
167
+ from .model_pool import ModelPool
168
+ from .worker_defaults import apply_worker_defaults
169
+ from .domain.worker_defaults import role_uses_worker_defaults
170
+ from .registry.worker_defaults_store import default_worker_defaults_store
167
171
  from .role_requirements import RoleProfile, RoleProfileError, load_role_profile
168
172
  from .agent.invocation import (
169
173
  AgentInstruction,
@@ -236,6 +240,7 @@ from .locks import worktree_provision_mutex
236
240
  from . import stage_targets as _stage_targets
237
241
  from .phases.catalog import PhaseAssetError, profile_markdown, resolve_include
238
242
  from .phases.final_verification.target import acquire_final_verification_target
243
+ from .phases.final_verification.prior_blockers import prior_blockers_packet_block
239
244
  from .phases.final_verification.entry import (
240
245
  apply_verification_target,
241
246
  reject_prepare_flags,
@@ -534,6 +539,7 @@ def _set_data_json_approved_true_if_present(path: Path) -> bool:
534
539
  # 가 whole-task 통합 실패를 동일 타입으로 받는다. run.py 는 재노출만 한다.
535
540
  PrepareError = _stage_targets.PrepareError
536
541
  from .phases.implementation_option_selection.entry import (
542
+ selection_mode_packet_block,
537
543
  validate_brief_requirements,
538
544
  )
539
545
 
@@ -607,6 +613,9 @@ class PrepareInputs:
607
613
  clarification_response_path: str = "" # absolute or empty
608
614
  # implementation-planning 신규 실행 전용: 검증된 방향 선택 최종 보고서.
609
615
  selected_direction_path: str = ""
616
+ # implementation-option-selection 전용: 리드가 미리 정한 방향과 그 근거.
617
+ # 값이 있으면 이 run 은 `preselected-validation`, 없으면 `candidate-comparison`.
618
+ preselected_direction: str = ""
610
619
  # implementation-planning 전용: 사용자가 고른 이번 재실행의 재검증 범위.
611
620
  # "" / "auto" = 리드의 `okstra incremental-scope` 판정에 맡김, "full" =
612
621
  # 전체 재검증 강제, "<stage csv>" = 그 stage 들을 impacted 로 지정.
@@ -1136,6 +1145,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
1136
1145
  ("--implementation-option", inp.implementation_option),
1137
1146
  ("--clarification-response", inp.clarification_response_path),
1138
1147
  ("--selected-direction", inp.selected_direction_path),
1148
+ ("--preselected-direction", inp.preselected_direction),
1139
1149
  (
1140
1150
  "--lead-provider",
1141
1151
  inp.lead_provider or lead_fallbacks.get("LEAD_PROVIDER", ""),
@@ -1416,6 +1426,11 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
1416
1426
  raise PrepareError(f"task brief not found: {inp.brief_path}")
1417
1427
  elif inp.task_type == "implementation-option-selection":
1418
1428
  validate_brief_requirements(inp.brief_path)
1429
+ if inp.preselected_direction and inp.task_type != "implementation-option-selection":
1430
+ raise PrepareError(
1431
+ "--preselected-direction is only meaningful with --task-type "
1432
+ f"implementation-option-selection; got {inp.task_type}"
1433
+ )
1419
1434
  ctx_stage_map: list = []
1420
1435
  # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
1421
1436
  # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope).
@@ -1827,7 +1842,17 @@ def _normalize_prepare_model_selection(
1827
1842
  "antigravity": inp.antigravity_model,
1828
1843
  },
1829
1844
  )
1830
- except (ModelSelectionInputError, RoleProfileError) as exc:
1845
+ if any(
1846
+ role_uses_worker_defaults(row.role, row.dynamic, frozenset())
1847
+ for row in profile.roles
1848
+ ):
1849
+ selection = apply_worker_defaults(
1850
+ selection,
1851
+ profile,
1852
+ default_worker_defaults_store().load_scopes(Path(inp.project_root)),
1853
+ ModelPool.from_registry(default_provider_registry()),
1854
+ )
1855
+ except (ModelSelectionInputError, RoleProfileError, ValueError) as exc:
1831
1856
  raise PrepareError(str(exc)) from exc
1832
1857
  return selection, profile
1833
1858
 
@@ -3068,6 +3093,22 @@ def _write_instruction_set_sources(
3068
3093
  if inp.clarification_response_path else ""
3069
3094
  ),
3070
3095
  verification_target_path=ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
3096
+ selection_mode_text=(
3097
+ selection_mode_packet_block(
3098
+ inp.preselected_direction,
3099
+ Path(inp.clarification_response_path) if inp.clarification_response_path else None,
3100
+ Path(ctx["PROJECT_ROOT"]),
3101
+ )
3102
+ if inp.task_type == "implementation-option-selection" else ""
3103
+ ),
3104
+ cited_documents_text=cited_documents_block(
3105
+ (instruction_set / "task-brief.md").read_text(encoding="utf-8"),
3106
+ Path(ctx["PROJECT_ROOT"]),
3107
+ ),
3108
+ prior_verification_text=(
3109
+ prior_blockers_packet_block(Path(ctx["FINAL_REPORT_PATH"]))
3110
+ if inp.task_type == "final-verification" else ""
3111
+ ),
3071
3112
  )
3072
3113
  if inp.task_type == "technical-verification":
3073
3114
  packet += materialize_technical_input_packet(
@@ -3296,6 +3337,7 @@ def _persist_run_inputs(
3296
3337
  "approvedPlanPath": approved_plan_path,
3297
3338
  "clarificationResponsePath": inp.clarification_response_path,
3298
3339
  "selectedDirectionPath": inp.selected_direction_path,
3340
+ "preselectedDirection": inp.preselected_direction,
3299
3341
  "analysisTarget": json.loads(ctx.get("ANALYSIS_TARGET_JSON", "{}")).get(
3300
3342
  "requestedValue", ""
3301
3343
  ),
@@ -4060,6 +4102,11 @@ def _prepare_user_authorization(inp: PrepareInputs) -> dict:
4060
4102
  for key, value in expected.items():
4061
4103
  if record["scope"].get(key) != value:
4062
4104
  raise PrepareError(f"user authorization scope does not match --{key}; confirm the changed scope")
4105
+ # A record confirmed before this key existed scoped a run without a preselected direction.
4106
+ if record["scope"].get("preselected-direction", "") != inp.preselected_direction:
4107
+ raise PrepareError(
4108
+ "user authorization scope does not match --preselected-direction; confirm the changed scope"
4109
+ )
4063
4110
  for key, path in (
4064
4111
  ("task-brief", "" if inp.task_type in ("release-handoff", "discussion") else inp.brief_path),
4065
4112
  ("approved-plan", inp.approved_plan_path),
@@ -4537,6 +4584,7 @@ Usage:
4537
4584
  [--related-tasks <list>] [--base-ref <ref>] \
4538
4585
  [--clarification-response <path>] [--work-category <cat>] \
4539
4586
  [--selected-direction <selection-final-report.md>] \
4587
+ [--preselected-direction <direction and citation>] \
4540
4588
  [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \
4541
4589
  [--fix-cycle <yes|no>] [--discussion-start <link|text|task-key>]
4542
4590
 
@@ -4671,6 +4719,16 @@ def build_prepare_argument_parser():
4671
4719
  )
4672
4720
  p.add_argument("--clarification-response", default="", dest="clarification_response_path")
4673
4721
  p.add_argument("--selected-direction", default="", dest="selected_direction_path")
4722
+ p.add_argument(
4723
+ "--preselected-direction",
4724
+ default="",
4725
+ dest="preselected_direction",
4726
+ help=(
4727
+ "implementation-option-selection only: the one direction this run "
4728
+ "validates, with its citation. Sets the run to preselected-validation; "
4729
+ "omitted means candidate-comparison."
4730
+ ),
4731
+ )
4674
4732
  p.add_argument(
4675
4733
  "--reverify-scope",
4676
4734
  default="",
@@ -4907,6 +4965,7 @@ def main(argv: list[str]) -> int:
4907
4965
  stages=args.stages,
4908
4966
  clarification_response_path=clarification_abs,
4909
4967
  selected_direction_path=selected_direction_abs,
4968
+ preselected_direction=args.preselected_direction.strip(),
4910
4969
  reverify_scope=args.reverify_scope,
4911
4970
  pr_template_path=args.pr_template_path,
4912
4971
  render_only=args.render_only,
@@ -36,12 +36,15 @@ def latest_run_inputs(
36
36
  task_id: str,
37
37
  *,
38
38
  phase_segment: str = "",
39
+ stage: Optional[int] = None,
39
40
  ) -> dict:
40
41
  """가장 최근 ``run-inputs-*.json`` 의 ``inputs`` dict 를 반환 (부재 시 {}).
41
42
 
42
- ``phase_segment`` 가 주어지면 그 phase 의 ``runs/<seg>/manifests/`` 만 스캔한다
43
- (resume 는 같은 phase 를 재실행하므로 그 phase 의 직전 입력이 기준). 비어 있으면
44
- task 의 모든 phase 를 통틀어 가장 최근(mtime) 파일을 고른다.
43
+ ``phase_segment`` 가 주어지면 그 phase 의 ``runs/<seg>/manifests/`` 와
44
+ ``runs/<seg>/stage-*/manifests/`` 만 스캔한다 (resume 는 같은 phase 를 재실행하므로
45
+ 그 phase 의 직전 입력이 기준). 비어 있으면 task 의 모든 phase 를 통틀어 가장
46
+ 최근(mtime) 파일을 고른다. ``stage`` 는 ``phase_segment`` 와 함께 써서
47
+ ``runs/<seg>/stage-<N>/manifests/`` 하나로 좁힌다.
45
48
 
46
49
  페이로드 구조는 ``{"schemaVersion", "writtenAt", "inputs": {...}}`` 이며 실제
47
50
  입력은 top-level 이 아니라 ``inputs`` 아래에 있다. run-inputs 의 위치/구조 지식은
@@ -52,13 +55,15 @@ def latest_run_inputs(
52
55
  runs_base = task_runs_dir(Path(project_root), task_group, task_id)
53
56
  if not runs_base.is_dir():
54
57
  return {}
55
- if phase_segment:
56
- glob_iter = (runs_base / phase_segment / "manifests").glob(
57
- "run-inputs-*.json")
58
+ if phase_segment and stage is not None:
59
+ patterns = [f"{phase_segment}/stage-{int(stage)}/manifests/run-inputs-*.json"]
58
60
  else:
59
- glob_iter = runs_base.glob("*/manifests/run-inputs-*.json")
61
+ # implementation / final-verification run 은 stage-<N>/ 한 단계 아래에 있다.
62
+ scope = phase_segment or "*"
63
+ patterns = [f"{scope}/manifests/run-inputs-*.json",
64
+ f"{scope}/stage-*/manifests/run-inputs-*.json"]
60
65
  candidates: list[tuple[float, Path]] = []
61
- for inp in glob_iter:
66
+ for inp in (path for pattern in patterns for path in runs_base.glob(pattern)):
62
67
  try:
63
68
  candidates.append((inp.stat().st_mtime, inp))
64
69
  except OSError:
@@ -24,7 +24,7 @@ from .consumers import (
24
24
  carry_head_commit,
25
25
  read_consumers,
26
26
  )
27
- from .file_size_cap import file_size_violations
27
+ from .file_size_cap import FILE_LINE_LIMIT, file_size_violations
28
28
  from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
29
29
  from .paths import RunRef
30
30
  from .stage_reopen import resolve_planned_stage
@@ -71,7 +71,7 @@ def _check_file_size(project_root: Path, carry: dict, head: str) -> str:
71
71
  return f"not checked: git: {exc.stderr.decode(errors='replace').strip()}"
72
72
  if violations:
73
73
  raise StateError(
74
- "the stage diff breaks the 400-line file-size limit:\n"
74
+ f"the stage diff breaks the {FILE_LINE_LIMIT}-line file-size limit:\n"
75
75
  + "\n".join(v.line() for v in violations)
76
76
  + f"\nRun a correction round (`okstra correction prompt ... --base {head} "
77
77
  f"--stage-base {base}`) so the executor splits these files, or end the run FAIL "
@@ -164,8 +164,9 @@ canonical sidecar `runs/implementation/carry/stage-<N>.json`, then appends the
164
164
  the carry's head and the completion time. A reopened stage's previous sidecar
165
165
  is moved to `carry/superseded/stage-<N>-from-<task-type>-<seq>.json` first.
166
166
  Refuses a carry for another stage, a failed carry, a stage already done at
167
- another head, and a carry whose stageCommitRange diff leaves a source or test
168
- file over the 400-line limit (`okstra correction file-size`). Re-running with the
167
+ another head, and a carry whose stageCommitRange diff adds a source or test file
168
+ over the 500-line limit or takes one past it (`okstra correction file-size`); a
169
+ file already over 500 at the stage base may grow. Re-running with the
169
170
  same carry writes nothing new.
170
171
 
171
172
  Output: JSON { ok, taskKey, stage, headCommit, carryPath, supersededCarryPath,
@@ -41,8 +41,9 @@ def main(argv: list[str]) -> int:
41
41
  p_init = sub.add_parser("init")
42
42
  p_init.add_argument("--state-file", required=True)
43
43
  p_init.add_argument("--workspace-root", required=True)
44
- p_init.add_argument("--project-root", required=True)
45
- p_init.add_argument("--project-id", required=True)
44
+ p_init.add_argument("--project-root", default="")
45
+ p_init.add_argument("--project-id", default="")
46
+ p_init.add_argument("--worker-settings", action="store_true")
46
47
  p_init.add_argument("--preferred-task-key", default="")
47
48
  p_init.add_argument(
48
49
  "--task-type",
@@ -84,6 +85,8 @@ def main(argv: list[str]) -> int:
84
85
  state_path = Path(args.state_file)
85
86
 
86
87
  if args.cmd == "init":
88
+ if not args.worker_settings and not (args.project_root and args.project_id):
89
+ parser.error("init requires --project-root and --project-id")
87
90
  state = init_state(
88
91
  workspace_root=args.workspace_root,
89
92
  project_root=args.project_root,
@@ -93,10 +96,19 @@ def main(argv: list[str]) -> int:
93
96
  host_runtime=args.host_runtime,
94
97
  host_entry_mode=args.entry_mode,
95
98
  available_functions=args.available_function,
99
+ worker_settings=args.worker_settings,
96
100
  )
97
- save_state_file(state_path, state)
98
101
  first = next_prompt(state)
99
- print(json.dumps({"ok": True, "next": prompt_payload(state, first)},
102
+ save_state_file(state_path, state)
103
+ result = {"ok": True, "next": prompt_payload(state, first)}
104
+ if args.worker_settings:
105
+ result["relayContract"] = (
106
+ default_host_registry()
107
+ .resolve(state.host_runtime)
108
+ .descriptor.relay_contract
109
+ )
110
+ result["runtime"] = state.host_runtime
111
+ print(json.dumps(result,
100
112
  ensure_ascii=False, indent=2))
101
113
  return 0
102
114
 
@@ -7,6 +7,7 @@ from typing import Optional
7
7
  from okstra_ctl.registry.host_registry import default_host_registry
8
8
  from okstra_ctl.clarification_items import sidecar_answers, user_response_sidecars
9
9
  from okstra_ctl.incremental_scope import CARRY_ALL_SCOPE
10
+ from okstra_ctl.phases.implementation_option_selection.entry import selection_mode
10
11
  from okstra_ctl.wizard_stage_intent import wizard_stage_confirmation_label, resolve_wizard_stage_intent
11
12
  from okstra_ctl.worktree import (
12
13
  compute_worktree_path,
@@ -217,6 +218,9 @@ def _reverify_scope_line(state: WizardState) -> Optional[str]:
217
218
 
218
219
  def confirmation_block(state: WizardState) -> str:
219
220
  """Human-readable echo of the resolved selections (for the Confirm step)."""
221
+ if state.worker_settings_mode:
222
+ from .worker_settings import worker_settings_summary
223
+ return worker_settings_summary(state)
220
224
  header = _msg(state.workspace_root, "confirmation", "header")
221
225
  lines: list[str] = [header]
222
226
  lines.append(f" task-type : {state.task_type}")
@@ -279,6 +283,10 @@ def confirmation_block(state: WizardState) -> str:
279
283
  for requirement in _selectable_static_requirements(state, profile):
280
284
  count = _selected_role_count(state, requirement)
281
285
  selected = state.role_models.get(requirement.role, [])
286
+ source = _msg(state.workspace_root, "worker_settings",
287
+ "source_" + state.role_sources.get(requirement.role, "once"))
288
+ lines.append(_msg(state.workspace_root, "worker_settings", "run_source",
289
+ role=requirement.role, count=str(count), source=source))
282
290
  for ordinal in range(1, count + 1):
283
291
  model_ref = (
284
292
  selected[ordinal - 1]
@@ -294,6 +302,20 @@ def confirmation_block(state: WizardState) -> str:
294
302
  model=model_ref,
295
303
  ))
296
304
  for requirement in profile.roles:
305
+ if not requirement.dynamic and state.role_counts.get(requirement.role) == 0:
306
+ source = state.role_sources.get(requirement.role, "once")
307
+ label = _msg(
308
+ state.workspace_root, "worker_settings", "source_" + source
309
+ )
310
+ lines.append(
311
+ _msg(
312
+ state.workspace_root,
313
+ "worker_settings",
314
+ "run_disabled",
315
+ role=requirement.role,
316
+ source=label,
317
+ )
318
+ )
297
319
  if not requirement.dynamic:
298
320
  continue
299
321
  lines.append(_msg(
@@ -325,6 +347,11 @@ def confirmation_block(state: WizardState) -> str:
325
347
  lines.append(reverify_line)
326
348
  if state.selected_direction_path:
327
349
  lines.append(f" selected-direction: {state.selected_direction_path}")
350
+ if state.task_type == "implementation-option-selection":
351
+ mode = selection_mode(state.preselected_direction)
352
+ lines.append(f" selection-mode: {mode}")
353
+ if state.preselected_direction:
354
+ lines.append(f" preselected-direction: {state.preselected_direction}")
328
355
  if state.task_type == "release-handoff" and state.handoff_stages:
329
356
  scope = _msg(state.workspace_root, "confirmation",
330
357
  "handoff_scope_stages", stages=state.handoff_stages)
@@ -38,9 +38,14 @@ from .picker_navigation import (
38
38
  present_picker,
39
39
  split_picker,
40
40
  )
41
- from .roles import _submit_role_prompt, next_role_prompt
41
+ from .roles import _step_role, _submit_role_prompt, next_role_prompt
42
42
  from .steps_analysis import _advance_design_prep_item
43
43
  from .registry import STEPS, STEP_BY_ID, _ROLE_SELECTION_BOUNDARY
44
+ from .worker_settings import (
45
+ next_worker_settings_prompt,
46
+ remaining_settings_screens,
47
+ submit_worker_settings,
48
+ )
44
49
 
45
50
 
46
51
  # ---- Public API ---------------------------------------------------------
@@ -52,6 +57,7 @@ def init_state(
52
57
  available_functions: Optional[list[str]] = None,
53
58
  preferred_task_key: str = "",
54
59
  requested_task_type: str = "",
60
+ worker_settings: bool = False,
55
61
  ) -> WizardState:
56
62
  """Bootstrap a new wizard state."""
57
63
  if requested_task_type and requested_task_type not in REQUESTABLE_TASK_TYPES:
@@ -68,6 +74,7 @@ def init_state(
68
74
  host_runtime=host_runtime,
69
75
  host_entry_mode=host_entry_mode,
70
76
  available_functions=list(available_functions or []),
77
+ worker_settings_mode=worker_settings,
71
78
  )
72
79
 
73
80
 
@@ -112,8 +119,16 @@ def _is_lone_choice_pick(prompt: Prompt) -> bool:
112
119
 
113
120
 
114
121
  def _apply_answer(state: WizardState, prompt: Prompt, value: str) -> str:
122
+ if state.worker_settings_mode:
123
+ try:
124
+ return submit_worker_settings(state, prompt, value)
125
+ except (ValueError, OSError) as exc:
126
+ raise WizardError(str(exc)) from exc
115
127
  if _is_role_selection_step(prompt.step):
116
128
  echo = _submit_role_prompt(state, prompt, value)
129
+ role = _step_role(prompt.step)
130
+ if prompt.step in state.manual_steps or role not in state.role_sources:
131
+ state.role_sources[role] = "once"
117
132
  if prompt.step not in state.role_selection_order:
118
133
  state.role_selection_order.append(prompt.step)
119
134
  else:
@@ -197,6 +212,8 @@ def _native_picker_screen(state: WizardState, prompt: Prompt) -> Prompt:
197
212
  def _next_prompt_screen(state: WizardState) -> Prompt:
198
213
  if state.aborted:
199
214
  return Prompt(step=S_ABORTED, kind="aborted")
215
+ if state.worker_settings_mode:
216
+ return next_worker_settings_prompt(state)
200
217
  if state.confirmed:
201
218
  return Prompt(step=S_DONE, kind="done")
202
219
  for step in STEPS:
@@ -319,8 +336,13 @@ def _remaining_screens(state: WizardState) -> int:
319
336
 
320
337
 
321
338
  def _screen_progress(state: WizardState) -> dict[str, Any]:
322
- passed = _passed_screens(state)
323
- total = passed + _remaining_screens(state)
339
+ if state.worker_settings_mode:
340
+ passed = state.worker_settings_answers
341
+ remaining_settings = remaining_settings_screens(state)
342
+ total = passed + 1 + remaining_settings
343
+ else:
344
+ passed = _passed_screens(state)
345
+ total = passed + _remaining_screens(state)
324
346
  index = passed + 1
325
347
  remaining = max(0, total - index)
326
348
  suffix = "마지막 단계" if remaining == 0 else f"앞으로 {remaining} 스텝 남음"
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
  import re
5
5
 
6
6
  from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
7
+ from okstra_ctl.role_requirements import RoleRequirement
7
8
 
8
9
 
9
10
  # ---- Constants -----------------------------------------------------------
@@ -220,6 +221,12 @@ S_CLARIFICATION_PICK = "clarification_pick"
220
221
  S_CLARIFICATION = "clarification"
221
222
 
222
223
 
224
+ S_SELECTION_MODE_PICK = "selection_mode_pick"
225
+
226
+
227
+ S_PRESELECTED_DIRECTION = "preselected_direction"
228
+
229
+
223
230
  S_REVERIFY_SCOPE_PICK = "reverify_scope_pick"
224
231
 
225
232
 
@@ -339,3 +346,25 @@ _REUSE_FILLED_STEPS = (
339
346
  S_ANALYSIS_TARGET_PICK, S_ANALYSIS_TARGET,
340
347
  S_DIRECTIVE_PICK, S_DIRECTIVE, S_RELATED_TASKS_PICK, S_RELATED_TASKS,
341
348
  S_CLARIFICATION_PICK, S_CLARIFICATION)
349
+
350
+
351
+ _MODELS_PREFIX = "role-models:"
352
+ _SINGLE_PREFIX = "role-model:"
353
+
354
+
355
+ def _role_models_prompt_id(role: str) -> str:
356
+ return f"{_MODELS_PREFIX}{role}"
357
+
358
+
359
+ def _role_model_prompt_id(role: str, ordinal: int) -> str:
360
+ return f"{_SINGLE_PREFIX}{role}:{ordinal}"
361
+
362
+
363
+ def _fixed_single(requirement: RoleRequirement) -> bool:
364
+ return requirement.min_count == requirement.max_count == 1
365
+
366
+
367
+ def _role_prompt_id(requirement: RoleRequirement) -> str:
368
+ if _fixed_single(requirement):
369
+ return _role_model_prompt_id(requirement.role, 1)
370
+ return _role_models_prompt_id(requirement.role)
@@ -56,6 +56,7 @@ from .ids import (
56
56
  S_HANDOFF_STAGE_PICK,
57
57
  S_PROJECT_EVIDENCE,
58
58
  S_PROJECT_EVIDENCE_PICK,
59
+ S_PRESELECTED_DIRECTION,
59
60
  S_PR_TEMPLATE,
60
61
  S_PR_TEMPLATE_PICK,
61
62
  S_REASONING_EFFORT,
@@ -67,6 +68,7 @@ from .ids import (
67
68
  S_REVERIFY_SCOPE_PICK,
68
69
  S_REVERIFY_SCOPE_STAGES,
69
70
  S_SELECTED_DIRECTION_PICK,
71
+ S_SELECTION_MODE_PICK,
70
72
  S_STAGE_PICK,
71
73
  S_TASK_GROUP,
72
74
  S_TASK_GROUP_TEXT,
@@ -185,6 +187,8 @@ from .steps_options import (
185
187
  _build_pr_template_scope,
186
188
  _build_related_tasks,
187
189
  _build_related_tasks_pick,
190
+ _build_preselected_direction,
191
+ _build_selection_mode_pick,
188
192
  _submit_clarification,
189
193
  _submit_clarification_pick,
190
194
  _submit_directive,
@@ -194,6 +198,8 @@ from .steps_options import (
194
198
  _submit_pr_template_scope,
195
199
  _submit_related_tasks,
196
200
  _submit_related_tasks_pick,
201
+ _submit_preselected_direction,
202
+ _submit_selection_mode_pick,
197
203
  )
198
204
  from .steps_roles import _build_reuse_previous, _submit_reuse_previous
199
205
  from .confirmation import _build_confirm, _submit_confirm
@@ -556,6 +562,19 @@ STEPS: list[Step] = [
556
562
  and S_CLARIFICATION not in s.answered),
557
563
  build=_build_clarification, submit=_submit_clarification,
558
564
  owns=("clarification_response_path", "clarification_pending_text")),
565
+ # clarification 뒤 — 이어받는 리포트의 다음 단계 지시를 라벨에 보여 준다.
566
+ Step(S_SELECTION_MODE_PICK,
567
+ applies=lambda s: (s.task_type == "implementation-option-selection"
568
+ and _identity_ready(s)
569
+ and not s.clarification_pending_text
570
+ and S_SELECTION_MODE_PICK not in s.answered),
571
+ build=_build_selection_mode_pick, submit=_submit_selection_mode_pick,
572
+ owns=("preselected_direction", "preselected_direction_pending_text")),
573
+ Step(S_PRESELECTED_DIRECTION,
574
+ applies=lambda s: (s.preselected_direction_pending_text
575
+ and S_PRESELECTED_DIRECTION not in s.answered),
576
+ build=_build_preselected_direction, submit=_submit_preselected_direction,
577
+ owns=("preselected_direction", "preselected_direction_pending_text")),
559
578
  # clarification 뒤에 온다. `_planning_rerun_selected` 는 clarification 답을 읽어
560
579
  # "이 런은 기존 계획서의 재실행" 인지 판정하는데, 이 단계가 clarification 앞에
561
580
  # 있던 동안 그 값은 언제나 비어 있었다 — 가드가 참이 될 수 없는 자리에 놓여
@@ -663,6 +682,8 @@ def _ready_for_confirm(s: WizardState) -> bool:
663
682
  S_RELATED_TASKS,
664
683
  S_CLARIFICATION_PICK,
665
684
  S_CLARIFICATION,
685
+ S_SELECTION_MODE_PICK,
686
+ S_PRESELECTED_DIRECTION,
666
687
  S_PR_TEMPLATE_PICK,
667
688
  S_PR_TEMPLATE,
668
689
  S_PR_TEMPLATE_SCOPE,