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
@@ -296,7 +296,10 @@ verifiers may have missed:
296
296
  - requirements / acceptance points with no covering evidence,
297
297
  - DB / IO / SQL changes lacking real-execution evidence,
298
298
  - regressions or broken error paths,
299
- - scope / contract violations.
299
+ - scope / contract violations,
300
+ - other locations or cases of a mechanism the analysers already raised (for
301
+ example the same stale-copy defect in a sibling editor, or after the version
302
+ changed) — a cell of that class they did not judge is a new candidate.
300
303
  A finding that would not stop the release is not a blocker — say so, and it is
301
304
  recorded as a conditional-acceptance condition instead. Do NOT restate an existing
302
305
  Acceptance Blocker. If you find none, write `No candidate blockers.`
@@ -21,12 +21,13 @@ _CLI_EPILOG = r"""Usage:
21
21
  Findings are read from the convergence record that preceded the round: the run's
22
22
  initial one for round 1, round N-1's re-convergence (`convergence-correction-r<N-1>-…`)
23
23
  for round N; --stage-base adds the file-size
24
- findings of `<stage-base>..<base>` (the 400-line limit only). Exit 1 on a refusal.
24
+ findings of `<stage-base>..<base>` (the 500-line limit only). Exit 1 on a refusal.
25
25
 
26
- `file-size` prints one `FILE-SIZE:<path>:401` line per file the stage diff leaves over
27
- the 400-line limit (blocking) and one `FILE-SIZE-ADVISORY:<path>:301` line per file it
28
- leaves over only the 300-line target, then `QA-RESULT: PASS|FAIL`; only a limit line
29
- fails. Exit 1 on FAIL, 2 when git cannot read the range.
26
+ `file-size` prints one `FILE-SIZE:<path>:501` line per file the stage diff adds over the
27
+ 500-line limit or takes past it (blocking) and one `FILE-SIZE-ADVISORY:<path>:301` line per
28
+ file it adds over, takes past or grows over the 300-line target without such a limit
29
+ breach, a file already over 500 at the stage base included, then `QA-RESULT: PASS|FAIL`;
30
+ only a limit line fails. Exit 1 on FAIL, 2 when git cannot read the range.
30
31
  """
31
32
 
32
33
 
@@ -177,7 +177,7 @@ def correction_instruction(
177
177
  if not finding_ids and not size_violations:
178
178
  raise CorrectionRoundError(
179
179
  "name at least one --finding, or pass --stage-base for a stage whose diff "
180
- "breaks the 400-line file-size limit"
180
+ f"breaks the {FILE_LINE_LIMIT}-line file-size limit"
181
181
  )
182
182
  if not base.strip():
183
183
  raise CorrectionRoundError("--base is required: the stage HEAD before this round")
@@ -242,12 +242,24 @@ def _split_declared_paths(raw: str) -> list[str]:
242
242
  return parts
243
243
 
244
244
 
245
- def _step_files_cells(step: Mapping[str, Any]) -> list[str]:
245
+ def _step_path_cells(step: Mapping[str, Any]) -> list[str]:
246
+ """step 이 건드리는 경로를 담은 칸들 — 독자용 `files` 와 쓰기 원장 `plannedPaths`.
247
+
248
+ `files` 는 문장이어도 되는 칸이라(profile §Stepwise Execution Order), 경로를
249
+ `plannedPaths` 에만 적은 계획도 스테이지에 매핑돼야 한다.
250
+ """
246
251
  raw = step.get("files")
247
252
  if isinstance(raw, list):
248
- return [_normalise(item) for item in raw if item]
249
- text = _normalise(raw)
250
- return [text] if text else []
253
+ cells = [_normalise(item) for item in raw if item]
254
+ else:
255
+ text = _normalise(raw)
256
+ cells = [text] if text else []
257
+ planned = step.get("plannedPaths")
258
+ for item in planned if isinstance(planned, list) else ():
259
+ path = _normalise(item).strip().strip("`") if isinstance(item, str) else ""
260
+ if path:
261
+ cells.append(path)
262
+ return cells
251
263
 
252
264
 
253
265
  def _files_cell_tokens(cell: str) -> list[str]:
@@ -282,7 +294,7 @@ def _stages_touching_path(
282
294
  cell
283
295
  for step in stage.get("stepwiseExecution") or []
284
296
  if isinstance(step, Mapping)
285
- for cell in _step_files_cells(step)
297
+ for cell in _step_path_cells(step)
286
298
  ]
287
299
  if any(_cell_covers_path(cell, path) for cell in cells):
288
300
  hits.append(stage_number)
@@ -293,7 +305,7 @@ def _stages_for_selected_path(
293
305
  path: str,
294
306
  stages: Mapping[int, Mapping[str, Any]],
295
307
  ) -> list[int]:
296
- """Every stage whose stepwise ``files`` cells touch *path*.
308
+ """Every stage whose stepwise ``files`` or ``plannedPaths`` cells touch *path*.
297
309
 
298
310
  A file legitimately edited by more than one stage — the task-level
299
311
  ``qa/conformance-manifest.json`` is the standard case, since each
@@ -321,7 +333,7 @@ def _stages_for_selected_path(
321
333
  hits = _stages_touching_path(part, stages)
322
334
  if not hits and "qa/scripts/" in part:
323
335
  # 적합성 스크립트는 executor 가 역할 권한으로 쓴다(write_policy
324
- # `_role_qa_artifact_paths`). 계획 step 의 files 칸에는 원래 없다.
336
+ # `_role_qa_artifact_paths`). 계획 step 의 files·plannedPaths 칸에는 원래 없다.
325
337
  continue
326
338
  if not hits:
327
339
  raise DesignSurfaceError(
@@ -0,0 +1,106 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Mapping
4
+ from collections.abc import Set as AbstractSet
5
+ from dataclasses import dataclass
6
+ from typing import Literal, TypedDict
7
+
8
+ WorkerScope = Literal["global", "project"]
9
+ WorkerDefaultScopes = TypedDict(
10
+ "WorkerDefaultScopes",
11
+ {"global": dict[str, object], "project": dict[str, object]},
12
+ total=False,
13
+ )
14
+ WorkerDefaultUpdates = dict[str, list[str] | None]
15
+
16
+
17
+ class WorkerDefaultError(ValueError):
18
+ pass
19
+
20
+
21
+ class WorkerDefaultsConflict(WorkerDefaultError):
22
+ def __init__(self, role: str) -> None:
23
+ self.role = role
24
+ super().__init__(f"worker defaults changed during editing: {role}")
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class WorkerDefault:
29
+ models: tuple[str, ...]
30
+ scope: WorkerScope
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class WorkerCountRange:
35
+ minimum: int
36
+ maximum: int
37
+ recommended: int
38
+
39
+
40
+ def intersect_worker_count_ranges(
41
+ previous: WorkerCountRange,
42
+ current: WorkerCountRange,
43
+ ) -> WorkerCountRange:
44
+ minimum = max(previous.minimum, current.minimum)
45
+ maximum = min(previous.maximum, current.maximum)
46
+ return WorkerCountRange(
47
+ minimum,
48
+ maximum,
49
+ max(minimum, min(maximum, current.recommended)),
50
+ )
51
+
52
+
53
+ def role_uses_worker_defaults(
54
+ role: str, dynamic: bool, explicit: AbstractSet[str]
55
+ ) -> bool:
56
+ return not dynamic and role != "leader" and role not in explicit
57
+
58
+
59
+ def merge_worker_default_updates(
60
+ current: Mapping[str, object],
61
+ before: Mapping[str, object],
62
+ updates: WorkerDefaultUpdates,
63
+ ) -> dict[str, object]:
64
+ values = dict(current)
65
+ missing = object()
66
+ for role, models in updates.items():
67
+ if values.get(role, missing) != before.get(role, missing):
68
+ raise WorkerDefaultsConflict(role)
69
+ if models is None:
70
+ values.pop(role, None)
71
+ else:
72
+ values[role] = models
73
+ return values
74
+
75
+
76
+ def select_worker_default(
77
+ role: str,
78
+ project: Mapping[str, object],
79
+ global_: Mapping[str, object],
80
+ ) -> tuple[object, WorkerScope] | None:
81
+ scopes: tuple[tuple[WorkerScope, Mapping[str, object]], ...] = (
82
+ ("project", project),
83
+ ("global", global_),
84
+ )
85
+ for scope, values in scopes:
86
+ if role in values:
87
+ return values[role], scope
88
+ return None
89
+
90
+
91
+ def validate_worker_models(
92
+ raw: object,
93
+ minimum: int,
94
+ maximum: int,
95
+ ) -> tuple[str, ...]:
96
+ if not isinstance(raw, list) or not all(
97
+ isinstance(model, str) and model for model in raw
98
+ ):
99
+ raise WorkerDefaultError("workerDefaults must be a modelRef array")
100
+ if not minimum <= len(raw) <= maximum:
101
+ raise WorkerDefaultError(
102
+ f"worker count must be in {minimum}..{maximum}: {len(raw)}"
103
+ )
104
+ if len(set(raw)) != len(raw):
105
+ raise WorkerDefaultError("duplicate worker model references")
106
+ return tuple(raw)
@@ -667,26 +667,34 @@ def _generated_paths(policies: Sequence[WritePolicy]) -> frozenset[str]:
667
667
 
668
668
 
669
669
  def _git_projection(root: Path) -> dict[str, Any]:
670
+ # 스냅샷은 워커 실행마다 두 번 찍힌다. rev-parse 는 여러 질의를 한 프로세스에서
671
+ # 줄 단위로 답하므로 질의마다 git 을 띄우지 않는다.
670
672
  probe = subprocess.run(
671
- ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
673
+ ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree",
674
+ "--path-format=absolute", "--git-dir", "--git-common-dir",
675
+ "--git-path", "index"],
672
676
  capture_output=True,
673
677
  text=True,
674
678
  check=False,
675
679
  )
676
680
  if probe.returncode != 0:
677
681
  return {"available": False}
678
- git_dir = Path(_git_output(root, "rev-parse", "--path-format=absolute", "--git-dir"))
679
- common_dir = Path(
680
- _git_output(root, "rev-parse", "--path-format=absolute", "--git-common-dir")
681
- )
682
+ lines = probe.stdout.splitlines()
683
+ if len(lines) == 4:
684
+ _inside, git_dir, common_dir, index_path = (Path(line) for line in lines)
685
+ else:
686
+ # 경로 속 줄바꿈은 질의 사이의 줄 경계와 구별되지 않는다. 그때만 경로를 하나씩 묻는다.
687
+ git_dir, common_dir, index_path = (
688
+ Path(_git_output(root, "rev-parse", "--path-format=absolute", *query))
689
+ for query in (("--git-dir",), ("--git-common-dir",), ("--git-path", "index"))
690
+ )
682
691
  branch_ref = _git_output(root, "symbolic-ref", "-q", "HEAD")
683
- head = _git_output(root, "rev-parse", "HEAD")
684
- index_path = Path(_git_output(root, "rev-parse", "--path-format=absolute", "--git-path", "index"))
692
+ head, branch_commit = _git_output(root, "rev-parse", "HEAD", branch_ref).splitlines()
685
693
  return {
686
694
  "available": True,
687
695
  "head": head,
688
696
  "allowedBranchRef": branch_ref,
689
- "branchCommit": _git_output(root, "rev-parse", branch_ref),
697
+ "branchCommit": branch_commit,
690
698
  "gitDir": str(git_dir.resolve()),
691
699
  "gitCommonDir": str(common_dir.resolve()),
692
700
  "indexDigest": _optional_file_digest(index_path),
@@ -879,21 +887,15 @@ def _branch_switch_paths(
879
887
 
880
888
 
881
889
  def _git_head(root: Path) -> str | None:
882
- probe = subprocess.run(
883
- ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
884
- capture_output=True,
885
- text=True,
886
- check=False,
887
- )
888
- if probe.returncode != 0:
889
- return None
890
890
  head = subprocess.run(
891
- ["git", "-C", str(root), "rev-parse", "HEAD"],
891
+ ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree", "HEAD"],
892
892
  capture_output=True,
893
893
  text=True,
894
894
  check=False,
895
895
  )
896
- return head.stdout.strip() or None if head.returncode == 0 else None
896
+ if head.returncode != 0:
897
+ return None
898
+ return head.stdout.splitlines()[-1].strip() or None
897
899
 
898
900
 
899
901
  def _allowed_artifact_paths(policies: Sequence[WritePolicy]) -> set[str]:
@@ -3,7 +3,7 @@
3
3
  Every later agent that touches a file loads all of it into context, so a stage that
4
4
  grows one file past a few hundred lines makes every following run pay for it. Both
5
5
  thresholds are measured on the stage diff: 300 lines is the target, reported as an
6
- advisory finding, and 400 lines is the limit, a blocking finding the correction round
6
+ advisory finding, and 500 lines is the limit, a blocking finding the correction round
7
7
  fixes by splitting the file (`_implementation-deliverable.md` §"Correction round").
8
8
 
9
9
  A line is a physical line, as `wc -l` and an editor's line numbers count it, plus an
@@ -15,17 +15,24 @@ the languages okstra's coding preflight has rules for. Lockfiles, JSON / YAML da
15
15
  snapshots, Markdown, SQL and config fall outside by extension. Inside that set, vendored,
16
16
  fixture, snapshot, generated and `.okstra` paths are exempt, and so is a file whose head
17
17
  declares itself generated.
18
+
19
+ A plan cannot be checked against the limit: it does not say how many lines a step adds,
20
+ and a file it creates does not exist yet. `planned_file_headroom` reports what can be
21
+ measured before implementation, the existing files a stage plans to write that sit
22
+ between the target and the limit, so the plan's reviewers see how few lines are left.
18
23
  """
19
24
  from __future__ import annotations
20
25
 
21
26
  import subprocess
22
27
  from dataclasses import dataclass
23
28
  from pathlib import Path, PurePosixPath
29
+ from typing import Any, Mapping
24
30
 
25
31
  from .self_mock_signals import EXT_TO_LANG
32
+ from .write_policy import planned_path_entries
26
33
 
27
34
  FILE_LINE_TARGET = 300
28
- FILE_LINE_LIMIT = 400
35
+ FILE_LINE_LIMIT = 500
29
36
 
30
37
  _EXEMPT_SEGMENTS = frozenset({
31
38
  ".okstra", "node_modules", "vendor", "fixtures", "__fixtures__", "__snapshots__",
@@ -114,16 +121,21 @@ def _breach(before: int | None, after: int, threshold: int) -> str:
114
121
  return f"new file over {threshold}"
115
122
  if before <= threshold:
116
123
  return f"crossed {threshold}"
124
+ if threshold == FILE_LINE_LIMIT:
125
+ # stage base 에서 이미 한도를 넘던 파일은 이 stage 가 만든 것이 아니고, 계획이 그 줄의
126
+ # 이동을 금지할 수 있다. 그래서 성장은 차단하지 않고 권고(목표치)로 넘긴다.
127
+ return ""
117
128
  return f"grew a file over {threshold}" if after > before else ""
118
129
 
119
130
 
120
131
  def file_size_violations(repo: Path, base: str, head: str = "HEAD") -> list[FileSizeViolation]:
121
132
  """Files the `base..head` diff leaves over a threshold, in diff order.
122
133
 
123
- A new file over a threshold, an existing file the diff takes over it, and a file
124
- already over it that the diff grows. A file already over it that the diff leaves the
125
- same size or shrinks is not this stage's to split. A file that breaks the limit is
126
- reported once, as blocking; one that breaks only the target is advisory.
134
+ A new file over a threshold and an existing file the diff takes over it. A file
135
+ already over the target that the diff grows breaks the target too, and so does a file
136
+ already over the limit: the limit blocks only what this stage took past it. A file the
137
+ diff leaves the same size or shrinks is not this stage's to split. A file that breaks
138
+ the limit is reported once, as blocking; one that breaks only the target is advisory.
127
139
  """
128
140
  violations: list[FileSizeViolation] = []
129
141
  for _status, old_path, path in _changed(repo, base, head):
@@ -140,3 +152,41 @@ def file_size_violations(repo: Path, base: str, head: str = "HEAD") -> list[File
140
152
  violations.append(FileSizeViolation(path, before, after, kind, threshold))
141
153
  break
142
154
  return violations
155
+
156
+
157
+ def _planned_files(planning: Mapping[str, Any], project_root: Path) -> dict[str, tuple[Path, list[Any]]]:
158
+ """Each capped planned path, keyed as the stage diff would name it, with its stages in order."""
159
+ files: dict[str, tuple[Path, list[Any]]] = {}
160
+ for entry in planned_path_entries(planning):
161
+ absolute = entry.path if entry.path.is_absolute() else project_root / entry.path
162
+ try:
163
+ rel = absolute.relative_to(project_root).as_posix()
164
+ except ValueError:
165
+ rel = entry.path.as_posix()
166
+ if not capped_path(rel):
167
+ continue
168
+ stages = files.setdefault(rel, (absolute, []))[1]
169
+ if entry.stage.get("stage") not in stages:
170
+ stages.append(entry.stage.get("stage"))
171
+ return files
172
+
173
+
174
+ def planned_file_headroom(planning: Mapping[str, Any], project_root: Path) -> list[dict[str, Any]]:
175
+ """Existing capped planned files with more than the target and at most the limit, one row
176
+ per file with every stage that writes it and the lines left before the limit."""
177
+ rows: list[dict[str, Any]] = []
178
+ for rel, (absolute, stages) in _planned_files(planning, project_root).items():
179
+ if not absolute.is_file():
180
+ continue
181
+ data = absolute.read_bytes()
182
+ lines = physical_lines(data)
183
+ if FILE_LINE_TARGET < lines <= FILE_LINE_LIMIT and not _declares_generated(data):
184
+ rows.append({"path": rel, "stages": stages, "lines": lines,
185
+ "headroom": FILE_LINE_LIMIT - lines})
186
+ return rows
187
+
188
+
189
+ def headroom_text(row: Mapping[str, Any]) -> str:
190
+ stages = ", ".join(str(stage) for stage in row.get("stages") or [])
191
+ return (f"{row.get('path')}: {row.get('lines')} lines, {row.get('headroom')} left before "
192
+ f"the {FILE_LINE_LIMIT}-line limit (stages {stages})")
@@ -67,6 +67,8 @@ class SelectedDirection:
67
67
  direction: dict[str, Any]
68
68
  requirement_coverage: tuple[dict[str, Any], ...]
69
69
  planning_invariants: tuple[dict[str, Any], ...]
70
+ deferred_feasibility_facts: tuple[dict[str, Any], ...] = ()
71
+ split_acceptance: dict[str, Any] | None = None
70
72
 
71
73
 
72
74
  @dataclass(frozen=True)
@@ -400,6 +402,8 @@ def resolve_selected_direction(
400
402
  direction=_direction_payload(option),
401
403
  requirement_coverage=tuple(_copy_json(option.get("requirementCoverage") or ())),
402
404
  planning_invariants=tuple(_copy_json(option.get("planningInvariants") or ())),
405
+ deferred_feasibility_facts=tuple(_copy_json(option.get("unresolvedFeasibilityFacts") or ())),
406
+ split_acceptance=_copy_json(option["splitAcceptance"]) if "splitAcceptance" in option else None,
403
407
  )
404
408
 
405
409
 
@@ -424,6 +428,12 @@ def write_selected_direction_snapshot(
424
428
  "requirementCoverage": list(direction.requirement_coverage),
425
429
  "planningInvariants": list(direction.planning_invariants),
426
430
  }
431
+ # 방향이 유효한 채로 남긴 사실(이후 게이트에서 닫힐 사실, 사용자가 감수한
432
+ # 위험)은 계획이 일정에 올려야 하므로 스냅샷에 실어 보낸다.
433
+ if direction.deferred_feasibility_facts:
434
+ payload["deferredFeasibilityFacts"] = list(direction.deferred_feasibility_facts)
435
+ if direction.split_acceptance is not None:
436
+ payload["splitAcceptance"] = direction.split_acceptance
427
437
  write_owned_object_atomic(
428
438
  destination,
429
439
  payload,
@@ -40,8 +40,10 @@ from .worker_prompt_body import (
40
40
  )
41
41
  from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
42
42
  from .worker_prompt_headers import source_worktree_headers, worker_prompt_headers
43
+ from .approved_plan_stage_extract import StageExtractError, materialize_stage_extract
43
44
  from .worker_prompt_policy import (
44
45
  APPROVED_PLAN_HEADER,
46
+ APPROVED_PLAN_STAGE_EXTRACT_HEADER,
45
47
  IMPLEMENTATION_STAGE_HEADER,
46
48
  STAGE_QA_OWNER_HEADER,
47
49
  PromptPlan,
@@ -720,6 +722,11 @@ def _prompt_body(
720
722
  plan,
721
723
  _optional_approved_plan_path(context) if plan.include_approved_plan else "",
722
724
  _selected_direction_path(context) if plan.include_selected_direction else "",
725
+ (
726
+ _approved_plan_stage_extract(context)
727
+ if plan.audience == "implementation-executor"
728
+ else ""
729
+ ),
723
730
  )
724
731
 
725
732
 
@@ -1466,6 +1473,10 @@ def _implementation_anchor_lines(
1466
1473
  lines.append(
1467
1474
  f"{APPROVED_PLAN_HEADER} {_required_approved_plan_path(context)}"
1468
1475
  )
1476
+ if plan.audience == "implementation-executor":
1477
+ extract = _approved_plan_stage_extract(context)
1478
+ if extract:
1479
+ lines.append(f"{APPROVED_PLAN_STAGE_EXTRACT_HEADER} {extract}")
1469
1480
  lines.append(
1470
1481
  f"{IMPLEMENTATION_STAGE_HEADER} {_required_stage_number(context)}"
1471
1482
  )
@@ -1526,6 +1537,36 @@ def _required_approved_plan_path(context: _MaterializationContext) -> str:
1526
1537
  return str(_resolve_input_path(context.project_root, Path(value)))
1527
1538
 
1528
1539
 
1540
+ def _approved_plan_stage_extract(context: _MaterializationContext) -> str:
1541
+ """Write this run's stage extract of the approved plan; its project path.
1542
+
1543
+ Empty when the plan is not a report record (see `materialize_stage_extract`),
1544
+ and the executor then reads the plan itself.
1545
+ """
1546
+ stage = _required_stage_number(context)
1547
+ if not stage.isdigit():
1548
+ raise InitialPromptMaterializationError(
1549
+ "required_input_missing",
1550
+ f"implementation stage is not a stage number: {stage}",
1551
+ )
1552
+ active_context_path = _resolve_input_path(
1553
+ context.project_root,
1554
+ Path(_required_string(context.manifest, "activeRunContextPath")),
1555
+ )
1556
+ suffix = active_context_path.name.removeprefix("active-run-context-")
1557
+ output = active_context_path.with_name(f"approved-plan-stage-{stage}-{suffix}")
1558
+ try:
1559
+ written = materialize_stage_extract(
1560
+ Path(_required_approved_plan_path(context)), int(stage), output
1561
+ )
1562
+ except (StageExtractError, JsonBoundaryError) as exc:
1563
+ raise InitialPromptMaterializationError(
1564
+ "required_input_missing",
1565
+ f"cannot project the approved plan onto stage {stage}: {exc}",
1566
+ ) from exc
1567
+ return _project_relative(context.project_root, output) if written else ""
1568
+
1569
+
1529
1570
  def _optional_approved_plan_path(context: _MaterializationContext) -> str:
1530
1571
  """The approved plan path when this run recorded one, otherwise empty.
1531
1572