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.
- package/README.md +1 -0
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/cli.md +29 -5
- package/docs/project-structure-overview.md +1 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
- package/runtime/python/okstra_ctl/code_review_target.py +77 -53
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/run.py +15 -1
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/skills/okstra-code-review/SKILL.md +25 -23
- package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
- package/runtime/skills/okstra-run/SKILL.md +21 -1
|
@@ -2,14 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
두 모드를 한 진입점에 모아 스킬이 base 커밋도, 리뷰 파일 경로도, 회차도 다시
|
|
4
4
|
유도하지 않게 한다. stage 모드는 read side 에 그대로 위임하고, branch 모드만
|
|
5
|
-
여기서 해소한다 — caller 가
|
|
6
|
-
|
|
5
|
+
여기서 해소한다 — branch 모드는 caller 가 명시적으로 지정한 기준을 쓴다.
|
|
6
|
+
이 모듈은 인자 검증과 JSON 정형화만 하고, 경로·회차 조립은
|
|
7
7
|
code_review_paths 가, stage 규칙은 code_review_target_snapshot 이 소유한다.
|
|
8
8
|
"""
|
|
9
9
|
from __future__ import annotations
|
|
10
10
|
|
|
11
11
|
import argparse
|
|
12
12
|
import json
|
|
13
|
+
import os
|
|
13
14
|
import re
|
|
14
15
|
import subprocess
|
|
15
16
|
import sys
|
|
@@ -30,8 +31,6 @@ from .stage_map import StageMapError, load_latest_plan_stage_map
|
|
|
30
31
|
from .fixed_text import line, scalar
|
|
31
32
|
from .report_language import ReportLanguageError, resolve_report_language
|
|
32
33
|
|
|
33
|
-
DEFAULT_BRANCH_CANDIDATES = ("main", "master")
|
|
34
|
-
|
|
35
34
|
_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
|
|
36
35
|
|
|
37
36
|
|
|
@@ -45,29 +44,6 @@ def _git_out(repo: Path, *args: str) -> str:
|
|
|
45
44
|
return result.stdout.strip() if result.returncode == 0 else ""
|
|
46
45
|
|
|
47
46
|
|
|
48
|
-
def _default_branch_ref(repo: Path) -> str:
|
|
49
|
-
"""merge-base 를 잴 기준 ref — origin/HEAD 가 있으면 그것, 없으면 관례 이름."""
|
|
50
|
-
remote_head = _git_out(repo, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
|
|
51
|
-
if remote_head:
|
|
52
|
-
return remote_head
|
|
53
|
-
for candidate in DEFAULT_BRANCH_CANDIDATES:
|
|
54
|
-
if _git_out(repo, "rev-parse", "--verify", "--quiet", candidate):
|
|
55
|
-
return candidate
|
|
56
|
-
return ""
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
def _merge_base(repo: Path, branch: str) -> str:
|
|
60
|
-
default_ref = _default_branch_ref(repo)
|
|
61
|
-
merge_base = _git_out(repo, "merge-base", default_ref, branch) if default_ref else ""
|
|
62
|
-
if not merge_base:
|
|
63
|
-
raise StateError(
|
|
64
|
-
f"no merge-base for {branch!r} against the default branch — "
|
|
65
|
-
"pass --base explicitly",
|
|
66
|
-
stage="base_unresolved",
|
|
67
|
-
)
|
|
68
|
-
return merge_base
|
|
69
|
-
|
|
70
|
-
|
|
71
47
|
def _review_date(raw: str) -> str:
|
|
72
48
|
"""branch 결과 파일명에 쓸 날짜.
|
|
73
49
|
|
|
@@ -86,11 +62,20 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
|
|
|
86
62
|
head = _git_out(repo, "rev-parse", branch)
|
|
87
63
|
if not head:
|
|
88
64
|
raise StateError(f"branch {branch!r} not found", stage="branch_missing")
|
|
89
|
-
|
|
65
|
+
if not base:
|
|
66
|
+
raise StateError(
|
|
67
|
+
"branch reviews require --base <branch-or-commit>", stage="args"
|
|
68
|
+
)
|
|
69
|
+
base_commit = _git_out(
|
|
70
|
+
repo, "rev-parse", "--verify", "--quiet", "--end-of-options",
|
|
71
|
+
f"{base}^{{commit}}",
|
|
72
|
+
)
|
|
73
|
+
if not base_commit:
|
|
74
|
+
raise StateError(f"base {base!r} is not a commit", stage="base_missing")
|
|
90
75
|
review_path, seq = next_branch_review(branch_review_dir(repo, branch), review_date)
|
|
91
76
|
return {
|
|
92
77
|
"mode": "branch",
|
|
93
|
-
"worktreePath":
|
|
78
|
+
"worktreePath": "",
|
|
94
79
|
"branch": branch,
|
|
95
80
|
"baseCommit": base_commit,
|
|
96
81
|
"headCommit": head,
|
|
@@ -101,19 +86,21 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
|
|
|
101
86
|
|
|
102
87
|
_CLI_EPILOG = r"""Usage:
|
|
103
88
|
okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
|
|
104
|
-
okstra code-review target --branch <name>
|
|
105
|
-
okstra code-review check-coverage --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
|
|
89
|
+
okstra code-review target --branch <name> --base <ref> [--date <YYYY-MM-DD>] [--project-root <dir>] --json
|
|
90
|
+
okstra code-review check-coverage --head <ref> --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
|
|
106
91
|
okstra code-review check-lines --base <ref> --head <ref> --cite <path:line> [--cite ...] [--project-root <dir>]
|
|
107
92
|
|
|
108
93
|
Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
|
|
109
94
|
reviewPath, round, reportLanguage }. `check-lines` prints `ok`, `not-changed`
|
|
110
95
|
(with the file's changed lines) or `not-in-diff` per citation and exits 1 when
|
|
111
96
|
any citation is not a line the range changed. `--base` sets the base in either mode. Without it, stage
|
|
112
|
-
mode reads the base commit from the stage registry row
|
|
113
|
-
|
|
97
|
+
mode reads the base commit from the stage registry row. Branch mode requires
|
|
98
|
+
an explicit base branch or commit and resolves it to a fixed commit. An empty
|
|
99
|
+
worktreePath means the review reads the branch ref
|
|
114
100
|
instead of a checked-out tree. This is read-only — it never creates
|
|
115
|
-
directories or files. `check-coverage`
|
|
116
|
-
|
|
101
|
+
directories or files. `check-coverage` reads each evidence file at `--head`, not
|
|
102
|
+
the working tree, prints covered cells, missing rules and unknown cells, and exits
|
|
103
|
+
1 for incomplete coverage and 2 for invalid input or completion evidence.
|
|
117
104
|
"""
|
|
118
105
|
|
|
119
106
|
|
|
@@ -130,9 +117,13 @@ def _build_parser() -> argparse.ArgumentParser:
|
|
|
130
117
|
parser.add_argument("--branch", default="", help="branch to review")
|
|
131
118
|
parser.add_argument(
|
|
132
119
|
"--base", default="",
|
|
133
|
-
help="
|
|
120
|
+
help=("required base branch or commit in branch mode; "
|
|
121
|
+
"overrides the stage registry base"),
|
|
122
|
+
)
|
|
123
|
+
parser.add_argument(
|
|
124
|
+
"--head", default="",
|
|
125
|
+
help="check-lines, check-coverage: head ref of the reviewed range",
|
|
134
126
|
)
|
|
135
|
-
parser.add_argument("--head", default="", help="check-lines: head ref of the reviewed range")
|
|
136
127
|
parser.add_argument(
|
|
137
128
|
"--cite", action="append", default=[],
|
|
138
129
|
help="check-lines: a finding's `path:line` (repeatable)",
|
|
@@ -183,28 +174,59 @@ def render_code_review_target_text(payload: dict) -> str:
|
|
|
183
174
|
return "".join(rows)
|
|
184
175
|
|
|
185
176
|
|
|
186
|
-
_HUNK_RE = re.compile(
|
|
177
|
+
_HUNK_RE = re.compile(
|
|
178
|
+
r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", re.MULTILINE,
|
|
179
|
+
)
|
|
187
180
|
|
|
188
181
|
|
|
189
182
|
def changed_lines(repo: Path, base: str, head: str) -> dict[str, set[int]]:
|
|
190
183
|
"""Head-side line numbers each file's diff touched.
|
|
191
184
|
|
|
192
|
-
A
|
|
193
|
-
|
|
185
|
+
A deletion within a surviving file anchors on the line before the cut.
|
|
186
|
+
A deleted file has no head-side citation.
|
|
194
187
|
"""
|
|
195
|
-
|
|
188
|
+
options = (
|
|
189
|
+
"--no-ext-diff", "--no-color", "--submodule=short", "-M",
|
|
190
|
+
)
|
|
191
|
+
named = subprocess.run(
|
|
192
|
+
["git", "-C", str(repo), "diff", "--name-status", "-z", *options,
|
|
193
|
+
f"{base}..{head}", "--"],
|
|
194
|
+
capture_output=True, check=False,
|
|
195
|
+
)
|
|
196
|
+
if named.returncode != 0:
|
|
197
|
+
raise StateError(
|
|
198
|
+
os.fsdecode(named.stderr).strip() or "cannot list changed paths",
|
|
199
|
+
stage="diff",
|
|
200
|
+
)
|
|
201
|
+
fields = iter(named.stdout.rstrip(b"\0").split(b"\0"))
|
|
196
202
|
lines: dict[str, set[int]] = {}
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
203
|
+
for status in fields:
|
|
204
|
+
if not status:
|
|
205
|
+
continue
|
|
206
|
+
paths = [os.fsdecode(next(fields))]
|
|
207
|
+
selection = [f"{base}..{head}", "--", f":(literal){paths[0]}"]
|
|
208
|
+
if status.startswith((b"R", b"C")):
|
|
209
|
+
paths.append(os.fsdecode(next(fields)))
|
|
210
|
+
selection = [f"{base}:{paths[0]}", f"{head}:{paths[1]}", "--"]
|
|
211
|
+
if status == b"D":
|
|
202
212
|
continue
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
213
|
+
patch = subprocess.run(
|
|
214
|
+
["git", "-C", str(repo), "diff", "-U0", *options, *selection],
|
|
215
|
+
capture_output=True, check=False,
|
|
216
|
+
)
|
|
217
|
+
if patch.returncode != 0:
|
|
218
|
+
raise StateError(os.fsdecode(patch.stderr).strip(), stage="diff")
|
|
219
|
+
touched = lines.setdefault(paths[-1], set())
|
|
220
|
+
for section in os.fsdecode(patch.stdout).split("\ndiff --git "):
|
|
221
|
+
header_lines = section.partition("\n@@ ")[0].split("\n")
|
|
222
|
+
if "+++ /dev/null" in header_lines:
|
|
223
|
+
continue
|
|
224
|
+
for match in _HUNK_RE.finditer(section):
|
|
225
|
+
start = int(match[1])
|
|
226
|
+
count = 1 if match[2] is None else int(match[2])
|
|
227
|
+
touched.update(
|
|
228
|
+
range(start, start + count) if count else {max(start, 1)}
|
|
229
|
+
)
|
|
208
230
|
return lines
|
|
209
231
|
|
|
210
232
|
|
|
@@ -258,12 +280,14 @@ def _check_coverage(args: argparse.Namespace, project_root: Path) -> int:
|
|
|
258
280
|
from .agent.invocation import AgentInvocationError
|
|
259
281
|
from .code_review_coverage import check_review_coverage
|
|
260
282
|
|
|
261
|
-
if not args.census or not args.completion:
|
|
262
|
-
print("check-coverage: pass --census and at least one --completion",
|
|
283
|
+
if not args.census or not args.head or not args.completion:
|
|
284
|
+
print("check-coverage: pass --census, --head and at least one --completion",
|
|
285
|
+
file=sys.stderr)
|
|
263
286
|
return 2
|
|
264
287
|
try:
|
|
265
288
|
result = check_review_coverage(
|
|
266
289
|
project_root, Path(args.census), [Path(path) for path in args.completion],
|
|
290
|
+
args.head,
|
|
267
291
|
)
|
|
268
292
|
except (OSError, ValueError, AgentInvocationError) as exc:
|
|
269
293
|
print(f"check-coverage: {exc}", file=sys.stderr)
|
|
@@ -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
|
|
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>:
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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
|
|
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")
|
|
@@ -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)
|
|
@@ -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
|
|
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 =
|
|
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
|
|
124
|
-
already over
|
|
125
|
-
|
|
126
|
-
|
|
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})")
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md
CHANGED
|
@@ -86,12 +86,12 @@ Changing a test's expected value is allowed here when the finding shows the orac
|
|
|
86
86
|
|
|
87
87
|
1. Record the stage HEAD as `<base>` (`git rev-parse HEAD` in the stage worktree).
|
|
88
88
|
2. Write the executor instruction with `okstra correction prompt --run-manifest <path> --round <N> --role executor --base <base> --stage-base <stage base> --finding <F-id> [--finding <F-id> ...]` into a file under the run's `state/`, then materialize it with `okstra agent-prompt materialize` — `--audience implementation-executor`, `--assignment-ref initial/<executor worker id>`, `--dispatch-kind correction-r<N>`, a new `--invocation-id` ending `-correction-r<N>-<executor worker id>`, and a result path `<executor worker id>-worker-correction-r<N>-implementation-<seq>.md`. Build a jobs file with `okstra agent-prompt jobs --dispatch-kind correction-r<N>`, dispatch it alone with `okstra team dispatch --jobs-file <path> --dispatch-kind correction-r<N>`, and settle it with `okstra team await`.
|
|
89
|
-
`--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the
|
|
89
|
+
`--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the 500-line limit, computed by `okstra correction file-size`; a `FILE-SIZE-ADVISORY:` line (the 300-line target) never opens or joins a round; a round may hold only those findings, and `findingIds` records them by that id. Leave out a convergence finding id that restates a `FILE-SIZE:` line, or the executor reads it twice.
|
|
90
90
|
3. Do the same for every verifier with `--role verifier`, `--audience implementation-verifier`, its own `initial/<verifier worker id>` assignment, and result `<verifier worker id>-worker-correction-r<N>-implementation-<seq>.md`; dispatch the verifiers in one batch without the executor.
|
|
91
91
|
4. Converge the re-verification results in round `<N>`'s own namespace, leaving the initial convergence as written. Run Phase 5.5 again with `correction-r<N>` before `<task-type>` in every state name: `okstra convergence prepare-groups --correction-round <N>` writes `convergence-groups-correction-r<N>-<task-type>-<seq>.json`; seed it with `--work-state …/convergence-work-correction-r<N>-<task-type>-<seq>.json` and `--final-state …/convergence-correction-r<N>-<task-type>-<seq>.json`; name round plans and results `convergence-round-<k>-plan-correction-r<N>-<task-type>-<seq>.json`. A reverify round in it passes `--correction-round <N>` to `reverify-prompt` and `collect-results`, materializes with `--invocation-id` ending `-correction-r<N>-reverify-r<k>-<worker id>`, and names its result `<worker id>-worker-correction-r<N>-reverify-r<k>-<task-type>-<seq>.md`. Never reseed the initial paths: a terminal final there is reused, and `--restart-from-round0` refuses it. Round `<N+1>`'s `okstra correction prompt` reads its findings from this round's final, and the report writer's synthesis packet carries it as `Convergence state (correction-r<N>)` beside the initial `Convergence state` (`report_synthesis_packet._source_specs`); report assembly projects it into `crossVerification.correctionRounds[]` and appends the evidence it promotes to `evidence.primary` with source `convergence correction-r<N>` (`report_assembly._correction_round_convergence`).
|
|
92
92
|
5. No re-verification verdict is `FAIL`: the round `result` is `pass` and the run continues to persistence with the post-fix head. Otherwise `result: fail`; start round `<N+1>` if the cap allows and the entry rules still hold, or end the run `FAIL`.
|
|
93
93
|
|
|
94
|
-
**Enforced:** `okstra convergence seed` (`scripts/okstra_ctl/convergence.py` `_seed`) accepts state paths only in the initial or a `correction-r<N>` namespace, refuses a round grouping before every grouped verifier returned an `ok` round `<N>` result (`convergence_provenance.missing_scope_results`), and checks its cited items against that round's results (`discovery_attempts` per namespace); `convergence_migration.decide_seed_action` refuses `--restart-from-round0` without an invalid working state; `plan-round` refuses to overwrite a round plan whose namespace already dispatched that round (`_refuse_dispatched_plan_overwrite`); `collect-results` reads only the namespace's reverify invocations (`correction_round.reverify_invocation_in_scope`). `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the
|
|
94
|
+
**Enforced:** `okstra convergence seed` (`scripts/okstra_ctl/convergence.py` `_seed`) accepts state paths only in the initial or a `correction-r<N>` namespace, refuses a round grouping before every grouped verifier returned an `ok` round `<N>` result (`convergence_provenance.missing_scope_results`), and checks its cited items against that round's results (`discovery_attempts` per namespace); `convergence_migration.decide_seed_action` refuses `--restart-from-round0` without an invalid working state; `plan-round` refuses to overwrite a round plan whose namespace already dispatched that round (`_refuse_dispatched_plan_overwrite`); `collect-results` reads only the namespace's reverify invocations (`correction_round.reverify_invocation_in_scope`). `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the 500-line file-size limit and names the `--stage-base` to pass, so a size violation no verifier reported still reaches a correction round, or ends the run `FAIL` when no round is left.
|
|
95
95
|
|
|
96
96
|
## Self-review pass before finalising the report (the Okstra lead runs this; do not delegate it)
|
|
97
97
|
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md
CHANGED
|
@@ -92,7 +92,7 @@ template's check; that template is gone.
|
|
|
92
92
|
The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
|
|
93
93
|
- **Verifier gates are not yours to run (BLOCKING).** The self-mock detector (`validators/detect_self_mock.py`) belongs to the implementation verifier and is never delegated to you (`_implementation-verifier.md` §"Self-mock detection"). The coding-conventions preflight names it as the enforcement behind the no-self-mocking principle — that names who will check your diff, not a command for you to run. You MUST NOT invoke it and MUST NOT write `<task_root>/qa/self-mock-*.json`; running it early does not pre-satisfy the gate, because the verifier runs it again under its own duty. **Enforced:** that sidecar is not among the paths your attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so the write audit closes the attempt as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`) — a stage whose every gate passed still lands as a failed run. The same holds for the conformance results `<task_root>/qa/result-*.json`: you may run a conformance script to check your work — a baseline capture or `--compare` target goes under `<task_root>/qa/baseline/` and anything else it writes (build logs, measurements) under `<task_root>/qa/output/`, the only qa directories besides `qa/scripts/` your attempt may write — but the verifier records every result, including an earlier stage's result that your rewrite of its script made stale. When the approved plan tells you to write one, leave it and name it in your result as a plan step the verifier owns.
|
|
94
94
|
- **An external Tier 3 non-PASS does NOT withhold the carry evidence.** A Tier 3 entry whose `requires` include `http`, `external`, or `db` is advisory. Its FAIL, MISSING, no result, startup failure, or credential / network / service absence gets recorded honestly — exact command, exit code, output tail, marked `ADVISORY` in `Validation evidence` — and you emit the carry evidence anyway. Only Tier 1 and Tier 2 failures withhold it. Withholding on an external result is what actually blocks the stage: the carry file is the only thing that can mark a stage `done`, the verifier re-runs that same command from the host (where a call your sandbox could not complete often passes), and a stage the verifier then PASSes can never be closed because its evidence was never written.
|
|
95
|
-
- **File size: aim for 300 lines, never
|
|
95
|
+
- **File size: aim for 300 lines, never take a file past 500 (BLOCKING at 500).** The 500 limit is broken by a new file over it or an existing file taken from 500 or fewer past it; the 300 target is broken those two ways and by a file already over it that grows by any net line, including a file already over 500 at the stage base. Lines are physical lines. Breaking 500 is a blocking finding; breaking only 300 is an advisory recommendation the verifiers record. Put a new responsibility — a group of functions, a class, a `describe` block — in a new module or test file beside the existing one instead of appending, and when a file would pass 500, split it by responsibility; never compress code or drop comments to meet the number. Lockfiles, data (JSON / YAML), Markdown, fixtures, snapshots, generated and vendored files are exempt, as are languages okstra has no coding preflight for. Check with `okstra correction file-size --base <stage-base>` before you emit the carry evidence; it writes nothing, so you may run it. **Enforced:** every verifier runs the same command and reports each `FILE-SIZE:` line (500) as a blocking finding and each `FILE-SIZE-ADVISORY:` line (300) as a recommendation, and `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range still breaks 500, so the stage goes to a correction round.
|
|
96
96
|
- **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. The terminal row belongs to the lead's post-stage persistence and is verdict-gated — `status:"done"` with `carry_path` on a non-`FAIL` verdict, `status:"failed"` on `FAIL` (`_implementation-deliverable.md` §"Lead post-stage persistence").
|
|
97
97
|
- **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.
|
|
98
98
|
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md
CHANGED
|
@@ -17,7 +17,7 @@ fails, fix it or surface the violation — do not claim done on a failing item.
|
|
|
17
17
|
|
|
18
18
|
- diff-review done: the `Pre-commit diff review sweep` ran over the full diff and its `Coverage:` footer is in your audit sidecar — every changed file named, with each applied rule set carrying its outcome (`clean` or `fixed <n>`). No footer, or entries with no outcome → the sweep is unfinished; do not claim done.
|
|
19
19
|
- functions: every new/edited function ≤50 effective lines, single purpose — cite the longest function's actual line count, not "all under 50"
|
|
20
|
-
- file size: no source or test file this diff adds
|
|
20
|
+
- file size: no source or test file this diff adds ends over 500 physical lines, and no file at 500 or fewer at the stage base ends over 500 (a file already over 500 may grow; that is advisory) — paste the output of `okstra correction file-size --base <stage-base>`; it must end `QA-RESULT: PASS`. Aim for 300: for each `FILE-SIZE-ADVISORY:` line it prints, split the file or say why not. A responsibility that would push a file over goes into its own new module or test file
|
|
21
21
|
- conventions: applied the routed pack + project patterns (name which ones)
|
|
22
22
|
- names & comments: names say what, comments say why; no obvious-restatement comments; no truthful-name violations
|
|
23
23
|
- verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md
CHANGED
|
@@ -214,9 +214,9 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
|
|
|
214
214
|
- **Non-separating test data:** two scenarios whose setup values and assertions are identical, so a wrong implementation passes both; or new test tooling added in this diff (mock, state setter, repository branch) that no test calls.
|
|
215
215
|
- **Effect claimed under its own mock:** a test presented as covering an effect whose producing path is replaced by a mock inside that same test. The mock's presence in the harness is not evidence the branch behind it works.
|
|
216
216
|
- **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape. Do NOT raise this on a function extracted purely to bring a body under the 50-line cap — that is principle 5 doing its job — nor on a pre-existing abstraction this diff merely edits.
|
|
217
|
-
- **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:
|
|
217
|
+
- **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:501 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 500 lines, or a file the diff took from 500 or fewer past 500. A file already over 500 at the stage base that the diff grows is not blocking; the command prints it as an advisory line. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target: a new file over 300, a file the diff took past 300, or a file already over 300 the diff grew, including one already over 500) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
|
|
218
218
|
- **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
|
|
219
|
-
- **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within
|
|
219
|
+
- **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within 500), function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, weak-but-not-misleading names, priority-between-inputs policy inlined in a service condition instead of a named domain function, an error message asserting a cause the code never observed, a memory / concurrency / batching change with no test pinning the bound it claims, or (hexagonal overlay only) a service dependency this diff adds or modifies that injects a concrete adapter instead of a port — record it with the port sketch; advisory only while the project has not declared `architecture.style = hexagonal`, since that declaration — and only that one — promotes exactly this item to blocking per the declared-style bullet above, while a declared `layered` binds dependency direction instead and leaves this item advisory; an existing convention of concrete injections does not convert this one to `clean`, it is the debt the rule pays down. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
|
|
220
220
|
- **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
|
|
221
221
|
|
|
222
222
|
### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
|
|
@@ -67,6 +67,7 @@ from okstra_ctl.plan_item_evidence import (
|
|
|
67
67
|
from okstra_ctl.plan_review_context import render_review_context
|
|
68
68
|
from okstra_ctl.stage_ledger import build_stage_ledger
|
|
69
69
|
from okstra_ctl.claim_reproduction import NOT_RUNNABLE, reproduce
|
|
70
|
+
from okstra_ctl.file_size_cap import headroom_text, planned_file_headroom
|
|
70
71
|
from okstra_ctl.final_report_schema import load_schema_version
|
|
71
72
|
from okstra_ctl.report_narrative import parse_narrative
|
|
72
73
|
from okstra_ctl.report_assembly import validate_plan_draft
|
|
@@ -538,12 +539,16 @@ def _prepare(args: argparse.Namespace) -> dict[str, Any]:
|
|
|
538
539
|
envelope.update(_reverify_carry(args, envelope["dispatchQueue"]))
|
|
539
540
|
gating = not advisory_plan_body_gating(_planning(source), envelope["items"])
|
|
540
541
|
_sync_task_manifest_gating(args.run_manifest, gating)
|
|
542
|
+
envelope["fileSizeHeadroom"] = planned_file_headroom(
|
|
543
|
+
_planning(source), authority.project_root,
|
|
544
|
+
)
|
|
541
545
|
write_json_atomic(output, envelope)
|
|
542
546
|
return {
|
|
543
547
|
"ok": True,
|
|
544
548
|
"operation": "prepare",
|
|
545
549
|
"path": str(output),
|
|
546
550
|
"gating": gating,
|
|
551
|
+
"fileSizeHeadroom": envelope["fileSizeHeadroom"],
|
|
547
552
|
}
|
|
548
553
|
|
|
549
554
|
|
|
@@ -1045,6 +1050,20 @@ def _render_inputs(run_manifest: Path) -> str:
|
|
|
1045
1050
|
return "\n## Inputs\n\n" + "".join(rows) if rows else ""
|
|
1046
1051
|
|
|
1047
1052
|
|
|
1053
|
+
def _render_file_size_headroom(rows: object) -> str:
|
|
1054
|
+
if not isinstance(rows, list) or not rows:
|
|
1055
|
+
return ""
|
|
1056
|
+
lines = [
|
|
1057
|
+
"\n## File-size headroom\n",
|
|
1058
|
+
"Existing files this plan writes, measured before any stage runs. Information "
|
|
1059
|
+
"only: it is not a verdict criterion.\n",
|
|
1060
|
+
]
|
|
1061
|
+
lines.extend(
|
|
1062
|
+
line("File-size headroom", headroom_text(row)) for row in rows if isinstance(row, Mapping)
|
|
1063
|
+
)
|
|
1064
|
+
return "".join(lines)
|
|
1065
|
+
|
|
1066
|
+
|
|
1048
1067
|
def _prompt(args: argparse.Namespace) -> str:
|
|
1049
1068
|
inputs = _checked_review_inputs(args.run_manifest)
|
|
1050
1069
|
envelope = _load_json_object(
|
|
@@ -1074,6 +1093,7 @@ def _prompt(args: argparse.Namespace) -> str:
|
|
|
1074
1093
|
rows.append(render_review_context(
|
|
1075
1094
|
[item["id"] for item in items], inputs, authority.payload, authority.project_root,
|
|
1076
1095
|
))
|
|
1096
|
+
rows.append(_render_file_size_headroom(envelope.get("fileSizeHeadroom")))
|
|
1077
1097
|
_checked_review_inputs(args.run_manifest)
|
|
1078
1098
|
for index, item in enumerate(items, 1):
|
|
1079
1099
|
if not isinstance(item, Mapping):
|
|
@@ -2566,6 +2586,8 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
2566
2586
|
)
|
|
2567
2587
|
if "gating" in result:
|
|
2568
2588
|
rows += line("Gating", result["gating"])
|
|
2589
|
+
for row in result.get("fileSizeHeadroom", []):
|
|
2590
|
+
rows += line("File-size headroom", headroom_text(row))
|
|
2569
2591
|
print(rows, end="")
|
|
2570
2592
|
else:
|
|
2571
2593
|
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
@@ -413,7 +413,7 @@ round before any host or provider process starts.
|
|
|
413
413
|
|
|
414
414
|
For contract 3.0, `prepare` checks the selected-direction draft with the same semantic validator as publication before writing the queue. Correct all reported references, coverage rows and planned commands through the writer correction procedure, then retry in this run. **Enforced:** `report_assembly.validate_plan_draft` and `plan_items_cli._prepare`; `tests/report/test_report_assembly.py` checks that invalid coverage creates no prepared queue.
|
|
415
415
|
|
|
416
|
-
1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`. After a self-fix rewrite, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and `tests/run/test_plan_items.py`. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
|
|
416
|
+
1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`. A `File-size headroom` line that prepare prints, and that `okstra plan-items prompt` carries under `## File-size headroom`, is a report only: it names an existing file the plan writes, its lines left before the 500-line implementation limit and the stages that write it. It does not block, open a correction or count as a verdict. After a self-fix rewrite, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and `tests/run/test_plan_items.py`. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
|
|
417
417
|
|
|
418
418
|
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <report-writer-narrative.md> --state <plan-body-verification.json> --run-manifest <run-manifest.json>`. `apply-verdicts` in step 8 refuses a verdict whose item has no `planBodyVerification.planItems[]` row. The report writer never owns that state, so the deterministic seed is the only creator of its rows. The seed is idempotent by id and never touches existing verdicts, so it is safe to re-run between rounds and after a self-fix re-extraction. It does refresh `contentHash` from the current extract. Skipping it makes step 8 fail with `plan-body state has no row for [...]`.
|
|
419
419
|
|