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
@@ -9,6 +9,7 @@ from okstra_ctl.phases.feature_analysis.entry import resolve_analysis_target
9
9
  from okstra_ctl.models import UnknownModelError, resolve_model_metadata
10
10
 
11
11
  from .ids import S_REUSE_PREVIOUS, _REUSE_FILLED_STEPS
12
+ from .roles import _clear_role_selection
12
13
  from .state import (
13
14
  Prompt,
14
15
  WizardError,
@@ -90,10 +91,11 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
90
91
  conversion_payload = dict(inputs)
91
92
  conversion_payload.setdefault("grokModel", _assignment_model(inputs, "grok", "grok"))
92
93
  conversion_payload.setdefault("kimiModel", _assignment_model(inputs, "kimi", "kimi"))
93
- state.role_counts.clear()
94
- state.role_models.clear()
95
- state.role_selection_order.clear()
94
+ _clear_role_selection(state)
96
95
  _role_selections_from_run_inputs(state, conversion_payload)
96
+ state.role_sources = {
97
+ role: "previous" for role in state.role_models.keys() | state.role_counts.keys()
98
+ }
97
99
  directive = inputs.get("directive")
98
100
  state.directive = directive if isinstance(directive, str) else ""
99
101
  related = inputs.get("relatedTasks")
@@ -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
@@ -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