okstra 0.226.0 → 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 (44) hide show
  1. package/README.md +1 -0
  2. package/dist/commands/execute/wizard.mjs +12 -15
  3. package/dist/commands/execute/wizard.mjs.map +1 -1
  4. package/docs/cli.md +29 -5
  5. package/docs/project-structure-overview.md +1 -1
  6. package/package.json +1 -1
  7. package/runtime/BUILD.json +2 -2
  8. package/runtime/agents/operations/code-review.json +1 -1
  9. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  10. package/runtime/prompts/wizard/prompts.ko.json +44 -0
  11. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
  12. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
  13. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
  14. package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
  15. package/runtime/python/okstra_ctl/code_review_target.py +77 -53
  16. package/runtime/python/okstra_ctl/correction_cli.py +6 -5
  17. package/runtime/python/okstra_ctl/correction_round.py +1 -1
  18. package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
  19. package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
  20. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  21. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  22. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  23. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
  24. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
  25. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  26. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  27. package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
  28. package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
  29. package/runtime/python/okstra_ctl/run.py +15 -1
  30. package/runtime/python/okstra_ctl/stage_done.py +5 -4
  31. package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
  32. package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
  33. package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
  34. package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
  35. package/runtime/python/okstra_ctl/wizard/render.py +2 -2
  36. package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
  37. package/runtime/python/okstra_ctl/wizard/state.py +55 -14
  38. package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
  39. package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
  40. package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
  41. package/runtime/python/okstra_ctl/write_policy.py +33 -18
  42. package/runtime/skills/okstra-code-review/SKILL.md +25 -23
  43. package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
  44. package/runtime/skills/okstra-run/SKILL.md +21 -1
@@ -148,7 +148,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
148
148
  **Pick the cases by distinct outcome, not by line coverage.** When the stage writes or reconciles state, its meaningfully different outcomes are usually more than three — normal success, target already in the desired state (resume), existing data reused rather than created, a conflicting concurrent state, target absent, and mid-way failure with rollback. Enumerate the ones this stage actually implements and route them across the three lines (the `boundary` line is where resume / already-done / reuse belongs; `failure` carries conflict, absence, and rollback), naming each in the cell rather than collapsing them into "edge input". An implemented outcome with no declared case is a coverage gap the executor will not backfill.
149
149
  - **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
150
150
  - `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
151
- - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** **File size:** the implementation run aims for 300 physical lines per source and test file and enforces 400 — a new file over 400, an existing file taken past 400, and a file already over 400 that grows are blocking findings the executor must split in a correction round; the same conditions at 300 are advisory. When a step would add code or tests to a file near or over 300 lines (`wc -l`), plan a new module or test file for that responsibility in `plannedPaths` instead of appending to the existing one. **Enforced at implementation, not here:** `okstra correction file-size` (`scripts/okstra_ctl/file_size_cap.py`), re-run by `okstra stage-done`. `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. The design-surface detector maps every selected-option `fileStructure` path to the stage whose `files` or `plannedPaths` names it; a path neither names fails the draft check that correction preflight and `plan-items prepare` share (`scripts/okstra_ctl/report_assembly.py` `validate_plan_draft`). When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
151
+ - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** **File size:** the implementation run aims for 300 physical lines per source and test file and enforces 500 — a new file over 500 and an existing file taken from 500 or fewer past 500 are blocking findings the executor must split in a correction round; a file already over 500 that grows is advisory, as is a new, crossing or growing file over 300. When a step would add code or tests to a file near or over 300 lines (`wc -l`), plan a new module or test file for that responsibility in `plannedPaths` instead of appending to the existing one. **Enforced at implementation:** `okstra correction file-size` (`scripts/okstra_ctl/file_size_cap.py`), re-run by `okstra stage-done`. A plan does not say how many lines a step adds, so planning cannot apply the limit; instead `okstra plan-items prepare`, correction preflight (`check-corrections`) and the plan verifier prompt report one `File-size headroom` line per existing source or test file the plan's `plannedPaths` name that has more than 300 and at most 500 lines, with the lines left before 500 and every stage that writes it (`file_size_cap.planned_file_headroom`). The report is information for the plan's readers: it never blocks, and it is not a verdict criterion or a reason for a correction. Files the plan creates and files already over 500 are not listed. `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. The design-surface detector maps every selected-option `fileStructure` path to the stage whose `files` or `plannedPaths` names it; a path neither names fails the draft check that correction preflight and `plan-items prepare` share (`scripts/okstra_ctl/report_assembly.py` `validate_plan_draft`). When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
152
152
  - **Real-IO tests stay out of the plan's committed steps (BLOCKING).** A step never creates, edits, or runs a test that opens a real database connection, makes a real network call, or talks to a real external service inside the project source test tree (`src/**`, `test/**`, `tests/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, `*.e2e-spec.*`), and no step's `PASS` depends on a reachable database or service. The implementation executor refuses such a step before its first edit (`_implementation-executor.md` "Real-IO test isolation"), so a plan that contains one stops the stage with zero changes (observed 2026-10-18, dev-11374: a live-MySQL `test/font-pairing.e2e-spec.ts` planned in steps 1, 4 and 5). The committed RED/GREEN steps test the adapter with its injected collaborator stubbed — the exact query text, its replacements, and the returned rows — and run without any backend. Real-backend verification is declared only as this stage's `Conformance tests:` line below (`requires=[db|http|external]`): the implementation run writes that script under `<task_root>/qa/scripts/`, runs it against a local or replica backend when one is reachable, never commits it, and records a non-PASS or unreachable backend as advisory. Read a brief line such as `verify: integration test against a test database` as that conformance declaration, not as a committed test. Do not plan a shared real-DB guard, a test DDL fixture, or an edit to an existing real-IO suite in source to support it. **Enforced:** every `P-Step-*` item of the §5.5.9 plan-body round carries this rule to its verifiers (`okstra_ctl.phases.implementation_planning.authoring._REAL_IO_STEP_NOTE`), which vote `DISAGREE(b)` on a step that breaks it; no path pattern tells a mocked test from a live one, so no validator checks it.
153
153
  - **The `command` cell runs inside an okstra task worktree, not a bare checkout (BLOCKING).** okstra provisions `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and — for `implementation` — a nested `stage-<N>/` worktree into the tree the step executes in. Two consequences bind every command you write:
154
154
  - **Clean-tree assertions use `okstra worktree-status --check-clean`.** A bare `git status --porcelain` is never empty there, so an assertion built on one fails on okstra's scaffolding rather than on the stage's work. The okstra command asks the same question over source paths only and exits 1 when dirty, so it stands alone as a step's assertion: `okstra worktree-status --check-clean`. Validator S13 rejects the bare form. Do not add a `git tag stage-<N>-exit` to the step. Stage completion records the commit in the consumer ledger without creating or moving git tags.
@@ -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()
@@ -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,
@@ -1838,7 +1842,17 @@ def _normalize_prepare_model_selection(
1838
1842
  "antigravity": inp.antigravity_model,
1839
1843
  },
1840
1844
  )
1841
- 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:
1842
1856
  raise PrepareError(str(exc)) from exc
1843
1857
  return selection, profile
1844
1858
 
@@ -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
 
@@ -218,6 +218,9 @@ def _reverify_scope_line(state: WizardState) -> Optional[str]:
218
218
 
219
219
  def confirmation_block(state: WizardState) -> str:
220
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)
221
224
  header = _msg(state.workspace_root, "confirmation", "header")
222
225
  lines: list[str] = [header]
223
226
  lines.append(f" task-type : {state.task_type}")
@@ -280,6 +283,10 @@ def confirmation_block(state: WizardState) -> str:
280
283
  for requirement in _selectable_static_requirements(state, profile):
281
284
  count = _selected_role_count(state, requirement)
282
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))
283
290
  for ordinal in range(1, count + 1):
284
291
  model_ref = (
285
292
  selected[ordinal - 1]
@@ -295,6 +302,20 @@ def confirmation_block(state: WizardState) -> str:
295
302
  model=model_ref,
296
303
  ))
297
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
+ )
298
319
  if not requirement.dynamic:
299
320
  continue
300
321
  lines.append(_msg(
@@ -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 -----------------------------------------------------------
@@ -345,3 +346,25 @@ _REUSE_FILLED_STEPS = (
345
346
  S_ANALYSIS_TARGET_PICK, S_ANALYSIS_TARGET,
346
347
  S_DIRECTIVE_PICK, S_DIRECTIVE, S_RELATED_TASKS_PICK, S_RELATED_TASKS,
347
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)
@@ -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"
@@ -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
@@ -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 = ""
@@ -148,7 +165,6 @@ class WizardState:
148
165
 
149
166
  # bookkeeping
150
167
  answered: list[str] = field(default_factory=list)
151
- # Steps the user came back to through Edit; their auto_value no longer applies.
152
168
  manual_steps: list[str] = field(default_factory=list)
153
169
 
154
170
  def to_json(self) -> dict[str, Any]:
@@ -420,9 +436,10 @@ def _role_selections_from_run_inputs(
420
436
  pool = ModelPool.from_registry(default_provider_registry())
421
437
  cross_requirement = _initial_cross_verification_requirement(profile)
422
438
  assigned = _assigned_models_by_role(payload)
439
+ if assigned:
440
+ _restore_recorded_role_selections(state, profile, pool, assigned)
441
+ return
423
442
  providers = _legacy_worker_providers(payload)
424
- if cross_requirement is not None and cross_requirement.role in assigned:
425
- providers = [provider for provider, _ in assigned[cross_requirement.role]]
426
443
  if cross_requirement is not None:
427
444
  selected_count = cross_requirement.recommended_count
428
445
  if providers and cross_requirement.min_count < cross_requirement.max_count:
@@ -437,13 +454,8 @@ def _role_selections_from_run_inputs(
437
454
  model.provider_id
438
455
  for model in pool.default_candidates(cross_requirement.role)
439
456
  ]
440
- assigned_models = [model for _, model in assigned.get(cross_requirement.role, ())]
441
- for ordinal, provider in enumerate(providers[:selected_count], start=1):
442
- raw_model = (
443
- assigned_models[ordinal - 1]
444
- if ordinal <= len(assigned_models)
445
- else payload.get(f"{provider}Model", "")
446
- )
457
+ for provider in providers[:selected_count]:
458
+ raw_model = payload.get(f"{provider}Model", "")
447
459
  model_ref = _legacy_model_ref(
448
460
  pool,
449
461
  provider,
@@ -455,7 +467,9 @@ def _role_selections_from_run_inputs(
455
467
  state.role_models.setdefault(cross_requirement.role, []).append(model_ref)
456
468
  if cross_requirement.role in state.role_models:
457
469
  # 여러 인스턴스 역할의 답은 체크박스 한 장이다.
458
- 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
+ )
459
473
 
460
474
  executor = payload.get("executor") or "claude"
461
475
  critic = payload.get("critic") or ""
@@ -475,15 +489,41 @@ def _role_selections_from_run_inputs(
475
489
  if not requirement.dynamic and requirement.min_count > 0
476
490
  }
477
491
  for role, provider, raw_model in provider_rows:
478
- if assigned.get(role):
479
- provider, raw_model = assigned[role][0]
480
492
  if role not in static_roles or not isinstance(provider, str) or not provider:
481
493
  continue
482
494
  model_ref = _legacy_model_ref(pool, provider, role, raw_model)
483
495
  if model_ref is None:
484
496
  continue
485
497
  state.role_models[role] = [model_ref]
486
- 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)
487
527
 
488
528
 
489
529
  class StaleWizardStateError(WizardError):
@@ -622,6 +662,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
622
662
  "selected_stages": "",
623
663
  "handoff_stages": "",
624
664
  "role_counts": {}, "role_models": {}, "role_selection_order": [],
665
+ "role_sources": {},
625
666
  "reuse_previous": None,
626
667
  "directive": "",
627
668
  "directive_pending_text": False,