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
@@ -0,0 +1,334 @@
1
+ from __future__ import annotations
2
+
3
+ from functools import partial
4
+ from pathlib import Path
5
+
6
+ from okstra_project import project_json_path
7
+
8
+ from okstra_ctl.assignment_environment import load_assignment_context
9
+ from okstra_ctl.assignment_resolver import AssignmentContext
10
+ from okstra_ctl.dispatch_state import detect_terminal_backend
11
+ from okstra_ctl.domain.worker_defaults import (
12
+ WorkerDefaultError,
13
+ WorkerDefaultsConflict,
14
+ WorkerDefaultScopes,
15
+ select_worker_default,
16
+ )
17
+ from okstra_ctl.registry.worker_defaults_store import default_worker_defaults_store
18
+ from okstra_ctl.role_requirements import RoleProfile, StaticRoleRequirement
19
+ from okstra_ctl.worker_defaults import (
20
+ common_worker_requirements,
21
+ resolve_executable_worker_default,
22
+ )
23
+
24
+ from .prompts import _msg
25
+ from .roles import _executable_role_models, _host_session_context
26
+ from .state import Option, Prompt, WizardError, WizardState
27
+
28
+ _INHERIT = "__inherit__"
29
+ _DISABLE = "__disable__"
30
+ _SCREENS_AFTER_SCOPE_PICK = 2
31
+ _SCREENS_AFTER_MODEL_EDIT = 2
32
+ _SCREENS_AFTER_ROLE_MENU = 1
33
+ _SCREENS_AFTER_REVIEW = 0
34
+
35
+
36
+ def _text(state: WizardState, key: str, **values: str) -> str:
37
+ return _msg(state.workspace_root, "worker_settings", key, **values)
38
+
39
+
40
+ def _settings_context(state: WizardState) -> AssignmentContext:
41
+ return load_assignment_context(
42
+ host_runtime=state.host_runtime,
43
+ terminal_backend=detect_terminal_backend(),
44
+ )
45
+
46
+
47
+ def _validate_staged_models(
48
+ state: WizardState,
49
+ requirement: StaticRoleRequirement,
50
+ models: list[str],
51
+ context: AssignmentContext,
52
+ ) -> None:
53
+ scope = state.worker_settings_scope
54
+ assert scope is not None
55
+ resolve_executable_worker_default(
56
+ requirement,
57
+ {scope: {requirement.role: models}},
58
+ context,
59
+ _host_session_context(state),
60
+ )
61
+
62
+
63
+ def remaining_settings_screens(state: WizardState) -> int:
64
+ if state.worker_settings_review:
65
+ return _SCREENS_AFTER_REVIEW
66
+ if state.worker_settings_scope is None:
67
+ return _SCREENS_AFTER_SCOPE_PICK
68
+ if state.worker_settings_role:
69
+ return _SCREENS_AFTER_MODEL_EDIT
70
+ return _SCREENS_AFTER_ROLE_MENU
71
+
72
+
73
+ def _draft_scopes(state: WizardState) -> WorkerDefaultScopes:
74
+ scopes: WorkerDefaultScopes = {
75
+ key: dict(values)
76
+ for key, values in (state.worker_defaults_snapshot or {}).items()
77
+ }
78
+ scope = state.worker_settings_scope
79
+ assert scope is not None
80
+ values = scopes.setdefault(scope, {})
81
+ for role, models in state.worker_settings_updates.items():
82
+ if models is None:
83
+ values.pop(role, None)
84
+ else:
85
+ values[role] = models
86
+ if state.worker_settings_scope == "global":
87
+ scopes.pop("project", None)
88
+ return scopes
89
+
90
+
91
+ def _configuration_text(
92
+ state: WizardState, role: str, scopes: WorkerDefaultScopes
93
+ ) -> str:
94
+ selected = select_worker_default(
95
+ role, scopes.get("project", {}), scopes.get("global", {})
96
+ )
97
+ if selected is None:
98
+ return _text(state, "unset")
99
+ models, scope = selected
100
+ source = _text(state, f"source_{scope}")
101
+ if not isinstance(models, list):
102
+ return _text(state, "invalid_models", source=source, models=repr(models))
103
+ return _text(
104
+ state,
105
+ "configured",
106
+ count=str(len(models)),
107
+ source=source,
108
+ models=", ".join(map(str, models)) or _text(state, "disabled"),
109
+ )
110
+
111
+
112
+ def worker_settings_summary(state: WizardState) -> str:
113
+ root = Path(state.project_root) if state.project_root else None
114
+ scope = state.worker_settings_scope
115
+ assert scope is not None
116
+ scopes = _draft_scopes(state)
117
+ lines = [
118
+ _text(
119
+ state,
120
+ "summary_header",
121
+ scope=_text(state, f"source_{scope}"),
122
+ path=str(default_worker_defaults_store().scope_path(scope, root)),
123
+ )
124
+ ]
125
+ context = _settings_context(state)
126
+ for role, requirement in common_worker_requirements(
127
+ Path(state.workspace_root)
128
+ ).items():
129
+ value = _configuration_text(state, role, scopes)
130
+ try:
131
+ resolve_executable_worker_default(
132
+ requirement, scopes, context, _host_session_context(state)
133
+ )
134
+ except WorkerDefaultError as exc:
135
+ value = _text(state, "issue", value=value, error=str(exc))
136
+ lines.append(
137
+ _text(
138
+ state,
139
+ "role_summary",
140
+ role=role,
141
+ label=_text(state, f"role_{role}"),
142
+ value=value,
143
+ )
144
+ )
145
+ if state.worker_settings_review and not state.worker_settings_saved:
146
+ before = dict(state.worker_defaults_snapshot or {})
147
+ if scope == "global":
148
+ before.pop("project", None)
149
+ lines.append(_text(state, "changes"))
150
+ lines.extend(
151
+ _text(state, key, role=role, value=_configuration_text(state, role, values))
152
+ for role in state.worker_settings_updates
153
+ for key, values in (("before", before), ("after", scopes))
154
+ )
155
+ return "\n".join(lines)
156
+
157
+
158
+ def _settings_model_prompt(state: WizardState) -> Prompt:
159
+ text = partial(_text, state)
160
+ role = state.worker_settings_role
161
+ requirement = common_worker_requirements(Path(state.workspace_root))[role]
162
+ context = _settings_context(state)
163
+ candidates = _executable_role_models(
164
+ state, RoleProfile((requirement,)), requirement, context
165
+ )
166
+ scopes = _draft_scopes(state)
167
+ selected = select_worker_default(
168
+ role, scopes.get("project", {}), scopes.get("global", {})
169
+ )
170
+ current = selected[0] if selected and isinstance(selected[0], list) else []
171
+ preferred = list(dict.fromkeys(model for model in current if model in candidates))
172
+ if not preferred:
173
+ preferred = list(candidates[: requirement.recommended_count])
174
+ ordered = [*preferred, *(model for model in candidates if model not in preferred)]
175
+ multi = requirement.max_count > 1
176
+ if not multi:
177
+ preferred = preferred[:1]
178
+ options = [
179
+ Option(model, model, recommended=model in preferred) for model in ordered
180
+ ]
181
+ disabled = requirement.min_count == 0 and (
182
+ not ordered or (selected is not None and selected[0] == [])
183
+ )
184
+ if disabled:
185
+ for option in options:
186
+ option.recommended = False
187
+ if requirement.min_count == 0:
188
+ options.append(Option(_DISABLE, text("disabled"), recommended=disabled))
189
+ inherited = text("inherit" if state.worker_settings_scope == "project" else "clear")
190
+ inherit_default = not ordered and not disabled
191
+ options.append(Option(_INHERIT, inherited, recommended=inherit_default))
192
+ options.append(Option("cancel", text("cancel")))
193
+ options.sort(key=lambda option: not option.recommended)
194
+ return Prompt(
195
+ step="worker_settings_models",
196
+ kind="pick",
197
+ multi=multi,
198
+ options=options,
199
+ label=text(
200
+ "models_label",
201
+ role=text(f"role_{role}"),
202
+ minimum=str(requirement.min_count),
203
+ maximum=str(requirement.max_count),
204
+ ),
205
+ )
206
+
207
+
208
+ def next_worker_settings_prompt(state: WizardState) -> Prompt:
209
+ if state.worker_settings_saved:
210
+ return Prompt(step="done", kind="done", label=worker_settings_summary(state))
211
+ if not state.worker_settings_scope:
212
+ options = [Option("global", _text(state, "scope_global"), recommended=True)]
213
+ if (
214
+ state.project_root
215
+ and state.project_id
216
+ and project_json_path(Path(state.project_root)).is_file()
217
+ ):
218
+ options.append(Option("project", _text(state, "scope_project")))
219
+ options.append(Option("cancel", _text(state, "cancel")))
220
+ return Prompt(
221
+ step="worker_settings_scope",
222
+ kind="pick",
223
+ label=_text(state, "scope_label"),
224
+ options=options,
225
+ )
226
+ if state.worker_settings_review:
227
+ return Prompt(
228
+ step="worker_settings_save",
229
+ kind="pick",
230
+ label=worker_settings_summary(state),
231
+ options=[
232
+ Option("save", _text(state, "save"), recommended=True),
233
+ Option("edit", _text(state, "edit")),
234
+ Option("cancel", _text(state, "cancel")),
235
+ ],
236
+ )
237
+ if state.worker_settings_role:
238
+ return _settings_model_prompt(state)
239
+ return Prompt(
240
+ step="worker_settings_roles",
241
+ kind="pick",
242
+ label=worker_settings_summary(state),
243
+ options=[
244
+ Option("review", _text(state, "review"), recommended=True),
245
+ *(
246
+ Option(role, f"{_text(state, f'role_{role}')} ({role})")
247
+ for role in common_worker_requirements(Path(state.workspace_root))
248
+ ),
249
+ Option("cancel", _text(state, "cancel")),
250
+ ],
251
+ )
252
+
253
+
254
+ def _stage_worker_models(state: WizardState, value: str) -> None:
255
+ role = state.worker_settings_role
256
+ values = [part.strip() for part in value.split(",") if part.strip()]
257
+ if _INHERIT in values or _DISABLE in values:
258
+ if len(values) != 1:
259
+ raise WizardError(_text(state, "exclusive"))
260
+ models = None if values[0] == _INHERIT else []
261
+ else:
262
+ models = values
263
+ if models is not None:
264
+ requirement = common_worker_requirements(Path(state.workspace_root))[role]
265
+ _validate_staged_models(state, requirement, models, _settings_context(state))
266
+ state.worker_settings_updates[role] = models
267
+ state.worker_settings_role = ""
268
+
269
+
270
+ def _save_worker_settings(state: WizardState) -> None:
271
+ if not state.worker_settings_updates:
272
+ state.worker_settings_saved = True
273
+ return
274
+ scope = state.worker_settings_scope
275
+ assert scope is not None
276
+ assert state.worker_defaults_snapshot is not None
277
+ root = Path(state.project_root) if state.project_root else None
278
+ requirements = common_worker_requirements(Path(state.workspace_root))
279
+ context = _settings_context(state)
280
+ for role, models in state.worker_settings_updates.items():
281
+ if models is not None:
282
+ _validate_staged_models(state, requirements[role], models, context)
283
+ store = default_worker_defaults_store()
284
+ try:
285
+ values = store.save_scope(
286
+ scope,
287
+ root,
288
+ state.worker_settings_updates,
289
+ state.worker_defaults_snapshot.get(scope, {}),
290
+ )
291
+ except WorkerDefaultsConflict as exc:
292
+ raise WizardError(
293
+ _text(
294
+ state,
295
+ "conflict",
296
+ path=str(store.scope_path(scope, root)),
297
+ role=exc.role,
298
+ )
299
+ ) from exc
300
+ state.worker_defaults_snapshot[scope] = values
301
+ state.worker_settings_updates.clear()
302
+ state.worker_settings_saved = True
303
+
304
+
305
+ def submit_worker_settings(state: WizardState, prompt: Prompt, value: str) -> str:
306
+ if value == "cancel":
307
+ state.aborted = True
308
+ return _text(state, "cancelled")
309
+ if prompt.step == "worker_settings_scope":
310
+ if value not in {option.value for option in prompt.options}:
311
+ raise WizardError(_text(state, "choose_scope"))
312
+ root = Path(state.project_root) if state.project_root else None
313
+ state.worker_defaults_snapshot = default_worker_defaults_store().load_scopes(
314
+ root
315
+ )
316
+ state.worker_settings_scope = "global" if value == "global" else "project"
317
+ elif prompt.step == "worker_settings_roles":
318
+ if value == "review":
319
+ state.worker_settings_review = True
320
+ elif value in common_worker_requirements(Path(state.workspace_root)):
321
+ state.worker_settings_role = value
322
+ else:
323
+ raise WizardError(_text(state, "choose_role"))
324
+ elif prompt.step == "worker_settings_models":
325
+ _stage_worker_models(state, value)
326
+ elif prompt.step == "worker_settings_save":
327
+ if value == "save":
328
+ _save_worker_settings(state)
329
+ elif value == "edit":
330
+ state.worker_settings_review = False
331
+ else:
332
+ raise WizardError(_text(state, "choose_save"))
333
+ state.worker_settings_answers += 1
334
+ return _text(state, "saved" if state.worker_settings_saved else "editing")
@@ -0,0 +1,135 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import replace
4
+ from pathlib import Path
5
+
6
+ from .assignment_resolver import (
7
+ AssignmentContext,
8
+ RoleInstance,
9
+ resolve_model_assignment,
10
+ )
11
+ from .domain.host import HostSessionContext
12
+ from .domain.worker_defaults import (
13
+ WorkerCountRange,
14
+ WorkerDefault,
15
+ WorkerDefaultError,
16
+ WorkerDefaultScopes,
17
+ intersect_worker_count_ranges,
18
+ role_uses_worker_defaults,
19
+ select_worker_default,
20
+ validate_worker_models,
21
+ )
22
+ from .legacy_model_selection import CanonicalModelSelection
23
+ from .model_pool import ModelPool
24
+ from .phases.catalog import profile_markdown, task_types
25
+ from .role_requirements import RoleProfile, StaticRoleRequirement, load_role_profile
26
+
27
+
28
+ def common_worker_requirements(
29
+ workspace_root: Path,
30
+ ) -> dict[str, StaticRoleRequirement]:
31
+ requirements: dict[str, StaticRoleRequirement] = {}
32
+ for task_type in task_types():
33
+ profile = load_role_profile(profile_markdown(workspace_root, task_type))
34
+ for row in profile.roles:
35
+ if (
36
+ not role_uses_worker_defaults(row.role, row.dynamic, frozenset())
37
+ or row.max_count == 0
38
+ ):
39
+ continue
40
+ previous = requirements.get(row.role, row)
41
+ counts = intersect_worker_count_ranges(
42
+ WorkerCountRange(
43
+ previous.min_count, previous.max_count, previous.recommended_count
44
+ ),
45
+ WorkerCountRange(row.min_count, row.max_count, row.recommended_count),
46
+ )
47
+ requirements[row.role] = replace(
48
+ row,
49
+ min_count=counts.minimum,
50
+ max_count=counts.maximum,
51
+ recommended_count=counts.recommended,
52
+ )
53
+ return requirements
54
+
55
+
56
+ def configured_worker_default(
57
+ requirement: StaticRoleRequirement,
58
+ scopes: WorkerDefaultScopes,
59
+ pool: ModelPool,
60
+ ) -> WorkerDefault | None:
61
+ selected = select_worker_default(
62
+ requirement.role,
63
+ scopes.get("project", {}),
64
+ scopes.get("global", {}),
65
+ )
66
+ if selected is None:
67
+ return None
68
+ raw, scope = selected
69
+ try:
70
+ models = validate_worker_models(
71
+ raw,
72
+ requirement.min_count,
73
+ requirement.max_count,
74
+ )
75
+ for model in models:
76
+ availability = pool.availability(model, requirement.role)
77
+ if not availability.available:
78
+ raise WorkerDefaultError(f"{model}: {availability.reason}")
79
+ except ValueError as exc:
80
+ raise WorkerDefaultError(
81
+ f"{scope} workerDefaults for {requirement.role}: {exc}"
82
+ ) from exc
83
+ return WorkerDefault(models, scope)
84
+
85
+
86
+ def apply_worker_defaults(
87
+ selection: CanonicalModelSelection,
88
+ profile: RoleProfile,
89
+ scopes: WorkerDefaultScopes,
90
+ pool: ModelPool,
91
+ ) -> CanonicalModelSelection:
92
+ explicit = (
93
+ selection.role_counts.keys()
94
+ | selection.role_models.keys()
95
+ | selection.provider_constraints.keys()
96
+ )
97
+ counts, models = dict(selection.role_counts), dict(selection.role_models)
98
+ for requirement in profile.roles:
99
+ if not role_uses_worker_defaults(
100
+ requirement.role, requirement.dynamic, explicit
101
+ ):
102
+ continue
103
+ configured = configured_worker_default(requirement, scopes, pool)
104
+ if configured is None:
105
+ continue
106
+ if requirement.min_count != requirement.max_count:
107
+ counts[requirement.role] = len(configured.models)
108
+ if configured.models:
109
+ models[requirement.role] = configured.models
110
+ return replace(selection, role_counts=counts, role_models=models)
111
+
112
+
113
+ def resolve_executable_worker_default(
114
+ requirement: StaticRoleRequirement,
115
+ scopes: WorkerDefaultScopes,
116
+ context: AssignmentContext,
117
+ host: HostSessionContext,
118
+ ) -> WorkerDefault | None:
119
+ configured = configured_worker_default(requirement, scopes, context.pool)
120
+ if configured is None:
121
+ return None
122
+ try:
123
+ for ordinal, model in enumerate(configured.models, 1):
124
+ resolve_model_assignment(
125
+ instance=RoleInstance(requirement.role, requirement.duty, ordinal),
126
+ model_ref=model,
127
+ pool=context.pool,
128
+ host=host,
129
+ environment=context.environment,
130
+ )
131
+ except (ValueError, RuntimeError) as exc:
132
+ raise WorkerDefaultError(
133
+ f"{configured.scope} workerDefaults for {requirement.role}: {exc}"
134
+ ) from exc
135
+ return configured
@@ -24,6 +24,7 @@ def analysis_prompt_body(
24
24
  plan: PromptPlan,
25
25
  approved_plan_path: str = "",
26
26
  selected_direction_path: str = "",
27
+ stage_extract_path: str = "",
27
28
  ) -> list[str]:
28
29
  """Render the provider-neutral body for an initial analysis audience."""
29
30
  label = analysis_worker_label(worker_id)
@@ -43,7 +44,12 @@ def analysis_prompt_body(
43
44
  "",
44
45
  "## Inputs",
45
46
  *analysis_input_lines(
46
- manifest, active_context, plan, approved_plan_path, selected_direction_path
47
+ manifest,
48
+ active_context,
49
+ plan,
50
+ approved_plan_path,
51
+ selected_direction_path,
52
+ stage_extract_path,
47
53
  ),
48
54
  "",
49
55
  mcp_pointer_line(),
@@ -60,7 +66,21 @@ def analysis_input_lines(
60
66
  plan: PromptPlan,
61
67
  approved_plan_path: str = "",
62
68
  selected_direction_path: str = "",
69
+ stage_extract_path: str = "",
63
70
  ) -> list[str]:
71
+ if plan.audience == "implementation-executor":
72
+ # The packet already carries the brief extract, the reference
73
+ # expectations, the profile prelude and the directive; the task brief,
74
+ # analysis material, profile and reference files repeat them in full.
75
+ # Measured 2026-10-30 (dev-11562): those four files were 1,929 lines
76
+ # beside a 4,865-line packet. The clarification file stays: the
77
+ # packet keeps only its extract, and a lazy-delivery prompt has no
78
+ # inlined authority block.
79
+ return existing_input_lines((
80
+ ("Primary analysis packet", instruction_path(manifest, active_context, "analysisPacketPath")),
81
+ ("Approved plan stage extract", stage_extract_path),
82
+ ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
83
+ ))
64
84
  if plan.packet_only:
65
85
  packet_path = instruction_path(manifest, active_context, "analysisPacketPath")
66
86
  # 승인 계획은 `## Inputs` 에 실어야 한다. 워커의 읽기 범위는 이 절과
@@ -27,6 +27,8 @@ class WorkerPromptHeaderError(Exception):
27
27
  # skill catalogs, and similar non-okstra artifacts. Restating the scope inline
28
28
  # puts the rule in front of the worker before its first tool call, which is the
29
29
  # only point at which it can still win over those host instructions.
30
+ # 패킷의 페이지 읽기 규칙도 같은 이유로 여기 있다 — 패킷 안 목차는 파일을 연 뒤에야
31
+ # 보이는데, 통째 `cat` 은 그 전에 잘린다(실측 609KB 패킷, codex).
30
32
  READ_SCOPE_HEADER = (
31
33
  "**Read scope:** Read only the paths this prompt enumerates "
32
34
  "(`[Required reading]`, `## Inputs`, verification-target paths) plus "
@@ -39,7 +41,11 @@ READ_SCOPE_HEADER = (
39
41
  "NOT apply inside an okstra worker run: do not auto-read `graphify-out/`, "
40
42
  "`SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an "
41
43
  "un-enumerated file seems essential, record it under *Missing Information "
42
- "or Assumptions* instead of reading it."
44
+ "or Assumptions* instead of reading it. Read the primary analysis packet "
45
+ "in pages of at most 200 lines (`sed -n '1,200p'`, then `'201,400p'`, …), "
46
+ "never with one whole-file `cat` or view: worker CLIs cut long output "
47
+ "without saying so, and the packet's `## Section Index` gives each "
48
+ "section's line range."
43
49
  )
44
50
  EVIDENCE_LEDGER_HEADER = "**Evidence ledger:** required-v1"
45
51
 
@@ -63,12 +69,13 @@ EVIDENCE_CITATION_HEADER = (
63
69
  # 구현 워커는 명령 행을 쓰지 못한다.
64
70
  EVIDENCE_COMMANDS_HEADER = (
65
71
  "**Evidence commands:** Append one `- Evidence command: "
66
- "{\"command\":\"<exact command>\",\"cwd\":\"<project-root>\","
72
+ "{\"command\":\"<exact command>\",\"cwd\":\"<directory the command ran in>\","
67
73
  "\"exitCode\":0,\"outputSummary\":\"<one-line result>\"}` row to the audit "
68
74
  "sidecar for each command that produced or verified a conclusion. Do not "
69
75
  "record exploratory `rg`, `ls`, or file-opening commands. Write the command "
70
- "as you ran it. A value that must not be written down is yours to omit or "
71
- "pass as a `$VAR` reference."
76
+ "as you ran it. When it starts with `cd <dir> &&`, `cwd` is that `<dir>`, "
77
+ "not the shell's starting directory. A value that must not be written down "
78
+ "is yours to omit or pass as a `$VAR` reference."
72
79
  )
73
80
 
74
81
  # `agy`'s write tool validates the target against the Gemini artifact store
@@ -34,6 +34,9 @@ ERRORS_PATH_HEADERS = (
34
34
  # itself: the lead's launch prompt carries them, and no worker reads that.
35
35
  APPROVED_PLAN_HEADER = "**Approved plan:**"
36
36
  IMPLEMENTATION_STAGE_HEADER = "**Stage for this implementation run:**"
37
+ # Executor-only and optional: a prompt published before it, or a run whose plan
38
+ # is a Markdown report, has no extract and the executor reads the plan itself.
39
+ APPROVED_PLAN_STAGE_EXTRACT_HEADER = "**Approved plan stage extract:**"
37
40
  # A stage's verifiers share one worktree and run as one batch. The Tier 3 script
38
41
  # (builds, fixed ports) and the self-mock mutation probe (edits sources in place)
39
42
  # must each run once, by the verifier named here.
@@ -5,7 +5,7 @@ import hashlib
5
5
  import json
6
6
  import re
7
7
  import subprocess
8
- from collections.abc import Mapping, Sequence
8
+ from collections.abc import Iterator, Mapping, Sequence
9
9
  from dataclasses import dataclass
10
10
  from pathlib import Path, PurePosixPath
11
11
  from typing import Any, Literal
@@ -595,29 +595,44 @@ def _planned_paths_from_report(
595
595
  return (), False
596
596
 
597
597
 
598
- def planned_path_declaration_errors(data: Mapping[str, Any]) -> list[str]:
599
- """검사 단계의 빈 선언은 보존하고 저장소 전체를 쓰기 대상으로 승인하지 않는다."""
600
- planning = data.get("implementationPlanning")
598
+ @dataclass(frozen=True)
599
+ class PlannedPathEntry:
600
+ stage_index: int
601
+ stage: Mapping[str, Any]
602
+ step_index: int
603
+ path_index: int
604
+ value: str
605
+ path: Path
606
+
607
+
608
+ def planned_path_entries(planning: object) -> Iterator[PlannedPathEntry]:
609
+ """계획 단계의 문자열 `plannedPaths` 항목을 선언 순서대로 정규화해 낸다."""
601
610
  stages = planning.get("stages") if isinstance(planning, Mapping) else None
602
- errors: list[str] = []
603
611
  for si, stage in enumerate(stages if isinstance(stages, list) else []):
604
612
  steps = stage.get("stepwiseExecution") if isinstance(stage, Mapping) else None
605
613
  for ti, step in enumerate(steps if isinstance(steps, list) else []):
606
614
  paths = step.get("plannedPaths") if isinstance(step, Mapping) else None
607
615
  for pi, value in enumerate(paths if isinstance(paths, list) else []):
608
- if not isinstance(value, str):
609
- continue
610
- path = Path(value.strip().strip("`"))
611
- # 절대 경로는 디스패치와 같은 실제 작업트리를 가리킨다. 새 파일은 없어도 된다.
612
- root = path == Path(".") or path == Path(path.anchor or ".")
613
- if path.is_absolute():
614
- root = root or (path / ".git").exists()
615
- if root:
616
- field = f"implementationPlanning.stages[{si}].stepwiseExecution[{ti}].plannedPaths[{pi}]"
617
- errors.append(
618
- f"{field}: planned path must name a file or a scoped subdirectory, "
619
- f"not a repository/worktree root: {value!r}; use [] for a read-only step"
620
- )
616
+ if isinstance(value, str):
617
+ yield PlannedPathEntry(si, stage, ti, pi, value, Path(value.strip().strip("`")))
618
+
619
+
620
+ def planned_path_declaration_errors(data: Mapping[str, Any]) -> list[str]:
621
+ """검사 단계의 빈 선언은 보존하고 저장소 전체를 쓰기 대상으로 승인하지 않는다."""
622
+ errors: list[str] = []
623
+ for entry in planned_path_entries(data.get("implementationPlanning")):
624
+ path = entry.path
625
+ # 절대 경로는 디스패치와 같은 실제 작업트리를 가리킨다. 새 파일은 없어도 된다.
626
+ root = path == Path(".") or path == Path(path.anchor or ".")
627
+ if path.is_absolute():
628
+ root = root or (path / ".git").exists()
629
+ if root:
630
+ field = (f"implementationPlanning.stages[{entry.stage_index}].stepwiseExecution"
631
+ f"[{entry.step_index}].plannedPaths[{entry.path_index}]")
632
+ errors.append(
633
+ f"{field}: planned path must name a file or a scoped subdirectory, "
634
+ f"not a repository/worktree root: {entry.value!r}; use [] for a read-only step"
635
+ )
621
636
  return errors
622
637
 
623
638