okstra 0.234.1 → 0.235.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 (108) hide show
  1. package/dist/cli-registry.mjs +7 -0
  2. package/dist/cli-registry.mjs.map +1 -1
  3. package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
  4. package/dist/commands/implementation-report/implementation-report.mjs +73 -0
  5. package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
  6. package/dist/commands/trace/comparison.d.mts +39 -0
  7. package/dist/commands/trace/comparison.mjs +138 -0
  8. package/dist/commands/trace/comparison.mjs.map +1 -0
  9. package/dist/commands/trace/document.d.mts +8 -0
  10. package/dist/commands/trace/document.mjs +37 -0
  11. package/dist/commands/trace/document.mjs.map +1 -0
  12. package/dist/commands/trace/line-counts.d.mts +15 -0
  13. package/dist/commands/trace/line-counts.mjs +107 -0
  14. package/dist/commands/trace/line-counts.mjs.map +1 -0
  15. package/dist/commands/trace/model.d.mts +2 -1
  16. package/dist/commands/trace/model.mjs +13 -1
  17. package/dist/commands/trace/model.mjs.map +1 -1
  18. package/dist/commands/trace/progression.mjs +7 -3
  19. package/dist/commands/trace/progression.mjs.map +1 -1
  20. package/dist/commands/trace/task-link.d.mts +3 -0
  21. package/dist/commands/trace/task-link.mjs.map +1 -1
  22. package/dist/commands/trace/trace.mjs +64 -44
  23. package/dist/commands/trace/trace.mjs.map +1 -1
  24. package/dist/lib/python-helper.d.mts +1 -1
  25. package/dist/lib/python-helper.mjs +11 -5
  26. package/dist/lib/python-helper.mjs.map +1 -1
  27. package/dist/lib/types.d.mts +1 -0
  28. package/docs/architecture/storage-model.md +50 -0
  29. package/docs/cli.md +31 -15
  30. package/docs/project-structure-overview.md +6 -1
  31. package/package.json +1 -1
  32. package/runtime/BUILD.json +2 -2
  33. package/runtime/agents/operations/trace-tests-review.json +6 -0
  34. package/runtime/prompts/duties/test-reviewer.json +32 -0
  35. package/runtime/prompts/lead/report-writer.md +13 -1
  36. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  37. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  38. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  39. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  40. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  41. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  42. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  43. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  44. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  45. package/runtime/python/okstra_ctl/consumers.py +6 -1
  46. package/runtime/python/okstra_ctl/design_review.py +6 -26
  47. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  48. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  49. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  50. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  51. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  52. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  53. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  54. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  55. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  56. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  57. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  58. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  59. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  60. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  61. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  62. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  63. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  64. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  65. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  66. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  67. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  68. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  69. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  70. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  71. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  72. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  73. package/runtime/python/okstra_ctl/paths.py +7 -4
  74. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  75. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  76. package/runtime/python/okstra_ctl/render.py +4 -0
  77. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  78. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  79. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  80. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  81. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  82. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  83. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  84. package/runtime/python/okstra_ctl/run.py +16 -0
  85. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  86. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  87. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  88. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  89. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  90. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  91. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  92. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  93. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  94. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  95. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  99. package/runtime/skills/okstra-run/SKILL.md +31 -0
  100. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  101. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  102. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  103. package/runtime/templates/reports/html/i18n/en.json +113 -0
  104. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  105. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  106. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  107. package/runtime/templates/trace/trace.template.md +2 -0
  108. package/runtime/validators/validate-report-views.py +4 -36
@@ -0,0 +1,309 @@
1
+ """Select stored task stages for whole-task comparison assembly and publication."""
2
+ from __future__ import annotations
3
+
4
+ from collections.abc import Iterator
5
+ from dataclasses import asdict, dataclass, field, replace
6
+ import json
7
+ import os
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from ..consumers import carry_head_commit, stage_consumer_state_from_rows
12
+ from ..final_report_paths import final_report_data_path, is_report_record_path
13
+ from ..implementation_outcome import carry_is_pass_grade
14
+ from ..json_boundary import PageBudgetExhausted, ReadBudget, parse_owned_snapshot
15
+ from ..jsonl import parse_jsonl_snapshot
16
+ from ..paths import RunRef, task_manifest_file
17
+ from ..plan_run_root import list_implementation_planning_reports
18
+ from ..qa_procedures import project_artifact_relative_path, safe_qa_path
19
+ from ..stage_ledger import renumbering_divergence
20
+ from ..stage_map import (
21
+ StageMapError, StageMapSnapshot, active_stage_records, parse_stage_map_data,
22
+ parse_stage_map_text, stage_map_records,
23
+ )
24
+ from ..stage_targets import stage_lifecycle_snapshot_from_state
25
+ from .baseline import MAX_BASELINE_BYTES, ComparisonError, ComparisonOwner
26
+ from .inputs import _ChangedInput, _artifact_bytes, run_comparison_scope, task_comparison_owner
27
+ from .model import MAX_COMPARISON_INPUT_BYTES, MAX_COMPARISON_READ_BYTES
28
+ from .source import MAX_PATHS
29
+
30
+
31
+ class _TaskInputReadError(ComparisonError):
32
+ pass
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class SelectedTaskStage:
37
+ stage: int
38
+ report: str
39
+ run_manifest: str
40
+ head: str
41
+ carry: str
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class TaskComparisonSelection:
46
+ owner: ComparisonOwner
47
+ plan_path: str | None
48
+ required_stages: tuple[int, ...]
49
+ selected_stages: tuple[SelectedTaskStage, ...]
50
+ phase_outcome: dict[str, Any] | None
51
+ lifecycle: dict[int, str]
52
+ selection: dict[str, Any]
53
+ fingerprints: dict[str, str | None]
54
+ limitations: tuple[str, ...]
55
+
56
+
57
+ @dataclass
58
+ class _TaskSelectionInputs:
59
+ root: Path
60
+ budget: ReadBudget
61
+ fingerprints: dict[str, str | None]
62
+ paths: set[str] = field(default_factory=set)
63
+ entry_count: int = 0
64
+
65
+ def relative(self, path: Path) -> str:
66
+ path = path if path.is_absolute() else self.root / path
67
+ return project_artifact_relative_path(self.root, path)
68
+
69
+ def read(self, path: Path) -> bytes:
70
+ relative = self.relative(path)
71
+ if relative not in self.paths and len(self.paths) >= MAX_PATHS:
72
+ raise _TaskInputReadError("Task comparison artifact path limit reached")
73
+ self.paths.add(relative)
74
+ try:
75
+ raw = _artifact_bytes(self.root, relative, self.fingerprints, self.budget, limit=MAX_BASELINE_BYTES)
76
+ except _ChangedInput:
77
+ raise
78
+ except (OSError, ComparisonError, PageBudgetExhausted) as exc:
79
+ raise _TaskInputReadError(str(exc)) from exc
80
+ if raw is None:
81
+ raise FileNotFoundError(f"Task comparison input is missing: {relative}")
82
+ return raw
83
+
84
+ def object(self, path: Path) -> dict[str, Any]:
85
+ return parse_owned_snapshot(path, self.read(path), artifact="task comparison input").value
86
+
87
+ def plan(self, path: Path) -> StageMapSnapshot:
88
+ raw = self.read(path)
89
+ relative = self.relative(path)
90
+ if is_report_record_path(path):
91
+ data = parse_owned_snapshot(path, raw, artifact="task comparison plan").value
92
+ planning = data.get("implementationPlanning")
93
+ rows = planning.get("stageMap") if isinstance(planning, dict) else None
94
+ if isinstance(rows, list) and len(rows) > MAX_PATHS:
95
+ raise _TaskInputReadError("Task comparison plan stage limit reached")
96
+ stages = parse_stage_map_data(data, source_plan_path=relative)
97
+ else:
98
+ if raw.count(b"\n") + bool(raw and not raw.endswith(b"\n")) > MAX_PATHS:
99
+ raise _TaskInputReadError("Task comparison plan line limit reached")
100
+ stages = parse_stage_map_text(raw.decode("utf-8"), source_plan_path=relative)
101
+ return StageMapSnapshot("ready", relative, stage_map_records(stages))
102
+
103
+ def entries(self, path: Path) -> Iterator[Path]:
104
+ directory = safe_qa_path(self.root, self.relative(path))
105
+ if not directory.exists():
106
+ return
107
+ with os.scandir(directory) as entries:
108
+ for entry in entries:
109
+ self.entry_count += 1
110
+ if self.entry_count > MAX_PATHS:
111
+ raise ComparisonError("Task comparison directory entry limit reached")
112
+ yield directory / entry.name
113
+
114
+
115
+ def _task_path(inputs: _TaskSelectionInputs, task: Path, value: str) -> Path:
116
+ if not isinstance(value, str) or not value:
117
+ raise ComparisonError("Task comparison reference is missing")
118
+ path = Path(value)
119
+ if not path.parts:
120
+ raise ComparisonError("Task comparison reference has no path components")
121
+ if not path.is_absolute():
122
+ path = inputs.root / path if path.parts[0] == ".okstra" else task / path
123
+ return safe_qa_path(inputs.root, inputs.relative(path))
124
+
125
+
126
+ def _select_stage(
127
+ inputs: _TaskSelectionInputs, task: Path, task_key: str, stage: int,
128
+ done: dict[str, Any], latest: StageMapSnapshot, candidates: list[Path],
129
+ ) -> SelectedTaskStage:
130
+ if done.get("impl_task_key") != task_key:
131
+ raise ComparisonError("Done row belongs to a different task")
132
+ ref = RunRef.from_task_root(task, "implementation", stage=stage)
133
+ carry_path = ref.carry(stage)
134
+ if done.get("carry_path") and _task_path(inputs, task, done["carry_path"]) != carry_path:
135
+ raise ComparisonError("Done row does not name the stage's canonical carry")
136
+ carry = inputs.object(carry_path)
137
+ recorded_stage = carry.get("stage", carry.get("stageNumber", stage))
138
+ if type(recorded_stage) is not int or recorded_stage != stage:
139
+ raise ComparisonError("Carry belongs to a different stage")
140
+ head = carry_head_commit(carry)
141
+ if not head:
142
+ raise ComparisonError("Carry has no head commit")
143
+ if head != done.get("head_commit"):
144
+ raise ComparisonError(f"Carry head {head} differs from the selected done head {done.get('head_commit')}")
145
+ if not carry_is_pass_grade(carry):
146
+ raise ComparisonError("Carry is not pass-grade at the selected done head")
147
+ source_plan = _task_path(inputs, task, carry.get("sourcePlanPath"))
148
+ if source_plan.parent != RunRef.from_task_root(task, "implementation-planning").reports_dir:
149
+ raise ComparisonError("Carry plan does not belong to this task's planning reports")
150
+ if not is_report_record_path(source_plan):
151
+ record = final_report_data_path(source_plan)
152
+ try:
153
+ built_from = inputs.plan(record)
154
+ except FileNotFoundError:
155
+ built_from = inputs.plan(source_plan)
156
+ else:
157
+ built_from = inputs.plan(source_plan)
158
+ divergence = renumbering_divergence(latest, built_from, {stage})
159
+ if divergence or not any(row["stage_number"] == stage for row in built_from.stages):
160
+ raise ComparisonError("; ".join(divergence) or "Carry plan does not declare the completed stage")
161
+ report_path = _task_path(inputs, ref.run_dir, done.get("report_path"))
162
+ if report_path.parent != ref.reports_dir:
163
+ raise ComparisonError("Done report does not belong to the selected stage")
164
+ record_path = final_report_data_path(report_path)
165
+ try:
166
+ report = inputs.object(record_path)
167
+ report_path = record_path
168
+ except FileNotFoundError:
169
+ if is_report_record_path(report_path):
170
+ raise
171
+ inputs.read(report_path).decode("utf-8")
172
+ report = {}
173
+ header = report.get("header")
174
+ if isinstance(header, dict) and (header.get("taskType", "implementation") != "implementation" or header.get("taskKey", task_key) != task_key):
175
+ raise ComparisonError("Selected report belongs to a different task or phase")
176
+ matched = []
177
+ for path in candidates:
178
+ manifest = inputs.object(path)
179
+ _, _, declared_report = run_comparison_scope(inputs.root, path, manifest)
180
+ if final_report_data_path(declared_report) != record_path:
181
+ continue
182
+ if manifest.get("taskKey") != task_key:
183
+ raise ComparisonError("Selected run manifest belongs to a different task")
184
+ if manifest.get("approvedPlanPath"):
185
+ approved = _task_path(inputs, task, manifest["approvedPlanPath"])
186
+ if final_report_data_path(approved) != final_report_data_path(source_plan):
187
+ raise ComparisonError("Selected run manifest and carry name different approved plans")
188
+ matched.append(path)
189
+ if len(matched) != 1:
190
+ raise ComparisonError(f"Completed report requires exactly one matching run manifest; found {len(matched)}")
191
+ return SelectedTaskStage(stage, inputs.relative(report_path), inputs.relative(matched[0]), head, inputs.relative(carry_path))
192
+
193
+
194
+ def _outcome_limitations(
195
+ outcome: dict[str, Any] | None, required: tuple[int, ...],
196
+ selected: list[SelectedTaskStage], inputs: _TaskSelectionInputs, task: Path,
197
+ ) -> list[str]:
198
+ if outcome is None or outcome.get("state") != "completed":
199
+ return []
200
+ if outcome.get("stages") != list(required) or {row.stage for row in selected} != set(required):
201
+ return ["Stored implementation outcome does not match the current required and selected stages"]
202
+ if not selected:
203
+ return ["Stored implementation outcome has no selected completed stages"]
204
+ latest = max(selected, key=lambda row: row.stage)
205
+ try:
206
+ report = _task_path(inputs, task, outcome.get("reportPath"))
207
+ except (OSError, ValueError) as exc:
208
+ return [f"Stored implementation outcome report is unavailable: {exc}"]
209
+ if outcome.get("headCommit") != latest.head or final_report_data_path(report) != final_report_data_path(inputs.root / latest.report):
210
+ return ["Stored implementation outcome does not match the selected final stage head and report"]
211
+ return []
212
+
213
+
214
+ def read_task_comparison_selection(
215
+ project_root: Path, task_root: Path, *, budget: ReadBudget | None = None,
216
+ fingerprints: dict[str, str | None] | None = None,
217
+ ) -> TaskComparisonSelection:
218
+ """Selection completeness describes read coverage, not task completion."""
219
+ root = Path(project_root).resolve(strict=True)
220
+ task = Path(task_root)
221
+ task = task if task.is_absolute() else root / task
222
+ task = safe_qa_path(root, project_artifact_relative_path(root, task))
223
+ inputs = _TaskSelectionInputs(root, ReadBudget(MAX_COMPARISON_READ_BYTES) if budget is None else budget,
224
+ {} if fingerprints is None else fingerprints)
225
+ manifest_path = task_manifest_file(task)
226
+ owner = task_comparison_owner(root, task)
227
+ plan_path = None
228
+ required: tuple[int, ...] = ()
229
+ selected: list[SelectedTaskStage] = []
230
+ outcome = None
231
+ lifecycle: dict[int, str] = {}
232
+ selection: dict[str, Any] = {"complete": False, "plans": [], "manifests": {}}
233
+ limitations: list[str] = []
234
+ try:
235
+ manifest = inputs.object(manifest_path)
236
+ task_key = manifest.get("taskKey")
237
+ if not isinstance(task_key, str) or not task_key:
238
+ raise ComparisonError("Task manifest has no task key")
239
+ owner["taskKey"] = task_key
240
+ phase_outcomes = manifest.get("phaseOutcome")
241
+ outcome = phase_outcomes.get("implementation") if isinstance(phase_outcomes, dict) else None
242
+ if outcome is not None and not isinstance(outcome, dict):
243
+ outcome = None
244
+ raise ComparisonError("Stored implementation outcome must be an object")
245
+ planning = RunRef.from_task_root(task, "implementation-planning")
246
+ plans = list_implementation_planning_reports(planning.reports_dir, directory_entries=inputs.entries)
247
+ selection["plans"] = [inputs.relative(path) for path in plans]
248
+ if not plans:
249
+ raise ComparisonError("Task comparison has no implementation plan")
250
+ plan_path = inputs.relative(plans[0])
251
+ latest = inputs.plan(plans[0])
252
+ active = active_stage_records(latest.stages)
253
+ required = tuple(row["stage_number"] for row in active)
254
+ ledger = planning.run_dir / "consumers.jsonl"
255
+ try:
256
+ raw = inputs.read(ledger)
257
+ except FileNotFoundError:
258
+ raw = b""
259
+ if raw.count(b"\n") + bool(raw and not raw.endswith(b"\n")) > MAX_PATHS:
260
+ raise ComparisonError("Task comparison consumer row limit reached")
261
+ rows, invalid = parse_jsonl_snapshot(raw.decode("utf-8"))
262
+ if invalid:
263
+ raise ComparisonError(f"Task comparison consumer ledger has invalid rows: {invalid[:10]}")
264
+ if any("stage" in row and (type(row["stage"]) is not int or row["stage"] < 1) for row in rows):
265
+ raise ComparisonError("Task comparison consumer ledger has invalid stage identities")
266
+ for row in rows:
267
+ if row.get("status") == "pr" and row.get("stages") is not None and not isinstance(row["stages"], list):
268
+ raise ComparisonError("Task comparison consumer ledger has an invalid PR stages field")
269
+ if row.get("status") == "verified" and row.get("final_verdict") is not None and not isinstance(row["final_verdict"], dict):
270
+ raise ComparisonError("Task comparison consumer ledger has an invalid verified final_verdict field")
271
+ state = stage_consumer_state_from_rows(rows)
272
+ snapshot = stage_lifecycle_snapshot_from_state(latest.stages, state)
273
+ lifecycle = {row.stage: row.status for row in snapshot.lifecycles}
274
+ for stage in required:
275
+ ref = RunRef.from_task_root(task, "implementation", stage=stage)
276
+ candidates = []
277
+ for path in inputs.entries(ref.run_dir / "manifests"):
278
+ sequence = path.stem.removeprefix("run-manifest-implementation-")
279
+ if not sequence.isascii() or not sequence.isdecimal():
280
+ continue
281
+ number = int(sequence)
282
+ if path == replace(ref, seq=number).manifest:
283
+ candidates.append(path)
284
+ candidates.sort()
285
+ selection["manifests"][str(stage)] = [inputs.relative(path) for path in candidates]
286
+ if stage not in snapshot.done_by_stage:
287
+ continue
288
+ try:
289
+ selected.append(_select_stage(inputs, task, task_key, stage, snapshot.done_by_stage[stage], latest, candidates))
290
+ except (_ChangedInput, _TaskInputReadError):
291
+ raise
292
+ except (OSError, ValueError, StageMapError, RecursionError) as exc:
293
+ limitations.append(f"Stage {stage} was not selected: {exc}")
294
+ limitations.extend(_outcome_limitations(outcome, required, selected, inputs, task))
295
+ selection.update(complete=True, plan=plan_path, requiredStages=list(required),
296
+ lifecycle={str(stage): status for stage, status in lifecycle.items()},
297
+ stages=[asdict(row) for row in selected], phaseOutcome=outcome)
298
+ except _ChangedInput:
299
+ raise
300
+ except (OSError, ValueError, StageMapError, RecursionError) as exc:
301
+ selected = []
302
+ selection["complete"] = False
303
+ limitations.append(str(exc))
304
+ if len(json.dumps(selection, ensure_ascii=True, separators=(",", ":")).encode()) > MAX_COMPARISON_INPUT_BYTES:
305
+ selected = []
306
+ selection = {"complete": False}
307
+ limitations.append("Task comparison selection exceeds its byte limit")
308
+ return TaskComparisonSelection(owner, plan_path, required, tuple(selected), outcome, lifecycle,
309
+ selection, inputs.fingerprints, tuple(limitations))
@@ -0,0 +1,134 @@
1
+ """Read the current completed implementation generation and its consumed inputs."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+ from typing import Callable, Iterable, Mapping
7
+
8
+ from .agent.invocation import reserved_invocation_metadata_path, verify_agent_invocation
9
+ from .conformance_evidence import BoundInvocation, RunVerifiers, bound_attempt, evidence_read_errors, load_run_verifiers
10
+ from .execution_identity import Invocation
11
+ from .json_boundary import ArtifactByteReader, PageBudgetExhausted, ReadBudget, read_bounded_bytes
12
+ from .qa_procedures import project_artifact_relative_path, read_fingerprinted_artifact, safe_qa_path
13
+ from .verification_dispatch import implementation_generation_frontier, read_completed_attempt_result, verification_generation_number
14
+ from .verification_evidence import implementation_verifier_roster, roster_verifier_role_execution_ref
15
+ from .verification_generation import VerificationGenerationRecord
16
+ from .verification_invocation import VerificationGenerationReference, read_invocation_generation, verification_generation_required
17
+
18
+ SETTLED_ARTIFACT_BYTES = 16 * 1024 * 1024
19
+ SETTLED_READ_BYTES = 192 * 1024 * 1024
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class SettledImplementationGeneration:
24
+ reference: VerificationGenerationReference | None
25
+ record: VerificationGenerationRecord | None
26
+ limitations: tuple[str, ...]
27
+ attempts: tuple[tuple[str, int], ...]
28
+ fingerprints: Mapping[str, str | None]
29
+
30
+
31
+ def _selected_implementation_attempts(
32
+ run: RunVerifiers, frontier: int,
33
+ ) -> tuple[Invocation, int, list[tuple[BoundInvocation, int]]]:
34
+ execution = run.execution
35
+ if execution is None or execution.legacy:
36
+ raise ValueError("current implementation generation requires execution identity v2")
37
+ executors = [(index, row) for index, row in enumerate(execution.invocations)
38
+ if row.duty_id == "implementation-executor"]
39
+ if not executors:
40
+ raise ValueError("current implementation generation has no executor invocation")
41
+ executor_index, executor = executors[-1]
42
+ if verification_generation_number(executor.dispatch_kind) != frontier:
43
+ raise ValueError("current executor and verifiers name different generations")
44
+ executor_attempt = run.latest_attempt.get(executor.invocation_ref)
45
+ if executor_attempt is None:
46
+ raise ValueError("current implementation executor has no attempt")
47
+ executor_row = next(row for row in execution.attempts
48
+ if (row.invocation_ref, row.attempt) == (executor.invocation_ref, executor_attempt))
49
+ if executor_row.status != "ok" or executor_row.finished_at is None:
50
+ raise ValueError("current implementation executor attempt is incomplete or failed")
51
+ if executor_attempt > 1:
52
+ raise ValueError("generation does not record which executor retry its verifiers observed")
53
+ selected = []
54
+ for worker in implementation_verifier_roster(run.manifest):
55
+ role = roster_verifier_role_execution_ref(run.manifest, worker)
56
+ if role is None:
57
+ raise ValueError(f"{worker} has no bound verifier role execution")
58
+ bindings = run.verifiers.get(role, [])
59
+ current = bound_attempt(run, role, frontier)
60
+ latest = max(bindings, key=lambda binding: binding.index, default=None)
61
+ if current is None or current[0] != latest:
62
+ raise ValueError(f"{worker} has no current bound verifier attempt")
63
+ binding, attempt = current
64
+ if binding.index <= executor_index:
65
+ raise ValueError(f"{worker} verification predates the current executor attempt")
66
+ selected.append(current)
67
+ if len({binding.invocation.role_execution_ref for binding, _ in selected}) != len(selected):
68
+ raise ValueError("current implementation verifier roles are not distinct")
69
+ return executor, executor_attempt, selected
70
+
71
+
72
+ def read_settled_implementation_generation(
73
+ project: Path, manifest_path: Path, *, reader: ArtifactByteReader | None = None,
74
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
75
+ ) -> SettledImplementationGeneration:
76
+ """Read the current completed implementation generation, without approving its verdict."""
77
+ project = project.resolve()
78
+ fingerprints: dict[str, str | None] = {}
79
+ budget = ReadBudget(SETTLED_READ_BYTES)
80
+ attempts: tuple[tuple[str, int], ...] = ()
81
+
82
+ def read_input(path: Path) -> bytes:
83
+ path = safe_qa_path(project, path.relative_to(project).as_posix())
84
+ return reader(path) if reader is not None else read_bounded_bytes(
85
+ path, max_bytes=SETTLED_ARTIFACT_BYTES, artifact="implementation generation input", budget=budget,
86
+ )
87
+
88
+ def observed(path: Path) -> bytes:
89
+ return read_fingerprinted_artifact(project, path, read_input, fingerprints)
90
+
91
+ try:
92
+ with evidence_read_errors():
93
+ manifest_path = project / project_artifact_relative_path(project, manifest_path)
94
+ run = load_run_verifiers(project, manifest_path, reader=observed)
95
+ if run.manifest.get("taskType") != "implementation":
96
+ raise ValueError("settled implementation generation requires an implementation run")
97
+ if not verification_generation_required(run.manifest, "implementation-verifier"):
98
+ raise ValueError("historical run has no verification evidence generation contract")
99
+ if run.execution is None:
100
+ raise ValueError("implementation execution snapshot is unavailable")
101
+ frontier = implementation_generation_frontier(run.execution)
102
+ if frontier is None:
103
+ raise ValueError("implementation has no dispatched generation")
104
+ executor, number, verifiers = _selected_implementation_attempts(run, frontier)
105
+ attempts = ((executor.invocation_ref, number), *((binding.invocation.invocation_ref, attempt)
106
+ for binding, attempt in verifiers))
107
+ record = None
108
+ reference = None
109
+ selected = [(executor, number), *((binding.invocation, attempt) for binding, attempt in verifiers)]
110
+ for invocation, attempt in selected:
111
+ metadata = reserved_invocation_metadata_path(project, run.manifest, invocation.invocation_ref, attempt, reader=observed)
112
+ if metadata is None:
113
+ raise ValueError("current implementation attempt has no reserved metadata")
114
+ errors = verify_agent_invocation(
115
+ metadata, project_root=project, expected_run_manifest_path=manifest_path,
116
+ expected_audience=invocation.duty_id, expected_invocation_ref=invocation.invocation_ref,
117
+ expected_role_execution_ref=invocation.role_execution_ref,
118
+ expected_participant_ref=invocation.participant_ref, reader=observed,
119
+ directory_entries=directory_entries,
120
+ )
121
+ if errors:
122
+ raise ValueError("implementation invocation: " + "; ".join(errors))
123
+ read_completed_attempt_result(project, run.execution, invocation.invocation_ref, attempt, reader=observed)
124
+ for binding, _ in verifiers:
125
+ current = VerificationGenerationReference.from_payload(binding.generation_ref)
126
+ if reference is not None and current != reference:
127
+ raise ValueError("current implementation verifiers bind different generation references")
128
+ reference = current
129
+ record = read_invocation_generation(project, manifest_path, run.manifest, current, "implementation-verifier", reader=observed)
130
+ if record is None or record["generation"] != frontier:
131
+ raise ValueError("current verification generation differs from its dispatch")
132
+ return SettledImplementationGeneration(reference, record, (), attempts, dict(fingerprints))
133
+ except (OSError, ValueError, KeyError, TypeError, PageBudgetExhausted) as exc:
134
+ return SettledImplementationGeneration(None, None, (str(exc),), attempts, dict(fingerprints))
@@ -59,7 +59,7 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
59
59
  carries = [_load_carry(task_root, stage) for stage in sorted(required_stages)]
60
60
  if any(carry is None for carry in carries):
61
61
  return ImplementationOutcome(completed=False, reason="carry sidecar missing")
62
- if any(not _carry_passed(carry) for carry in carries if carry is not None):
62
+ if any(not carry_is_pass_grade(carry) for carry in carries if carry is not None):
63
63
  return ImplementationOutcome(completed=False, reason="carry sidecar is not pass-grade")
64
64
 
65
65
  latest_stage = max(required_stages)
@@ -136,7 +136,7 @@ def _load_carry(task_root: Path, stage: int) -> dict[str, Any] | None:
136
136
  return data or None
137
137
 
138
138
 
139
- def _carry_passed(carry: dict[str, Any]) -> bool:
139
+ def carry_is_pass_grade(carry: dict[str, Any]) -> bool:
140
140
  status = str(carry.get("status") or "").lower()
141
141
  if status in FAILED_CARRY_STATUSES:
142
142
  return False
@@ -829,6 +829,7 @@ def _materialize_report_writer_packet(
829
829
  try:
830
830
  _, markdown_path = materialize_report_synthesis_packet(
831
831
  project_root=context.project_root,
832
+ manifest_path=context.request.run_manifest_path,
832
833
  manifest=context.manifest,
833
834
  active_context=context.active_context,
834
835
  team_state=context.team_state,
@@ -13,6 +13,7 @@ from .final_report_schema import SchemaError, validate as validate_schema
13
13
 
14
14
 
15
15
  OUTSIDE_WORKER_RESULT_LANES = "outside worker result lanes"
16
+ ArtifactByteReader = Callable[[Path], bytes]
16
17
 
17
18
 
18
19
  class JsonBoundaryError(ValueError):
@@ -218,6 +219,7 @@ def load_owned_object(
218
219
  validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
219
220
  max_bytes: int | None = None,
220
221
  budget: ReadBudget | None = None,
222
+ reader: ArtifactByteReader | None = None,
221
223
  ) -> dict[str, Any]:
222
224
  """Load and validate one okstra-owned JSON object."""
223
225
  return load_owned_object_snapshot(
@@ -227,6 +229,7 @@ def load_owned_object(
227
229
  validate_cross_fields=validate_cross_fields,
228
230
  max_bytes=max_bytes,
229
231
  budget=budget,
232
+ reader=reader,
230
233
  ).value
231
234
 
232
235
 
@@ -238,28 +241,45 @@ def load_owned_object_snapshot(
238
241
  validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
239
242
  max_bytes: int | None = None,
240
243
  budget: ReadBudget | None = None,
244
+ reader: ArtifactByteReader | None = None,
241
245
  ) -> OwnedJsonSnapshot:
242
- """한 번 읽은 바이트에서 객체를 파싱·검증해 함께 반환한다."""
246
+ """Read and validate one snapshot; injected readers own I/O limits."""
243
247
  if budget is not None and max_bytes is None:
244
248
  max_bytes = budget.max_bytes
245
249
  try:
246
- raw_bytes = path.read_bytes() if max_bytes is None else read_bounded_bytes(
247
- path, max_bytes=max_bytes, artifact=artifact, budget=budget,
248
- )
250
+ if reader is not None:
251
+ raw_bytes = reader(path)
252
+ elif max_bytes is None:
253
+ raw_bytes = path.read_bytes()
254
+ else:
255
+ raw_bytes = read_bounded_bytes(path, max_bytes=max_bytes, artifact=artifact, budget=budget)
256
+ except FileNotFoundError as exc:
257
+ raise JsonBoundaryError(path, artifact, "missing") from exc
258
+ except OSError as exc:
259
+ raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
260
+ return parse_owned_snapshot(
261
+ path, raw_bytes, artifact=artifact, schema=schema,
262
+ validate_cross_fields=validate_cross_fields,
263
+ )
264
+
265
+
266
+ def parse_owned_snapshot(
267
+ path: Path, raw_bytes: bytes, *, artifact: str,
268
+ schema: Mapping[str, Any] | None = None,
269
+ validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
270
+ ) -> OwnedJsonSnapshot:
271
+ """Validate exactly the bytes supplied by an artifact reader."""
272
+ try:
249
273
  value = json.loads(
250
274
  raw_bytes.decode("utf-8"),
251
275
  parse_constant=_reject_nonstandard_json_constant,
252
276
  )
253
- except FileNotFoundError as exc:
254
- raise JsonBoundaryError(path, artifact, "missing") from exc
255
277
  except UnicodeDecodeError as exc:
256
278
  raise JsonBoundaryError(path, artifact, "invalid JSON encoding") from exc
257
279
  except _NonstandardJsonConstant as exc:
258
280
  raise JsonBoundaryError(path, artifact, str(exc)) from exc
259
281
  except json.JSONDecodeError as exc:
260
282
  raise JsonBoundaryError(path, artifact, "invalid JSON") from exc
261
- except OSError as exc:
262
- raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
263
283
  return OwnedJsonSnapshot(
264
284
  value=_validate_owned(
265
285
  value,
@@ -15,7 +15,7 @@ from __future__ import annotations
15
15
 
16
16
  import os
17
17
  import re
18
- from collections.abc import Callable, Mapping, Sequence
18
+ from collections.abc import Callable, Iterable, Mapping, Sequence
19
19
  from dataclasses import dataclass, replace
20
20
  from pathlib import Path
21
21
  from typing import Any, Optional
@@ -266,20 +266,23 @@ class RunRef:
266
266
 
267
267
  def latest_verification_check_run(
268
268
  self, invocation_ref: str, attempt: int, check_ref: str,
269
+ *, directory_entries: Callable[[Path], Iterable[Path]] | None = None,
269
270
  ) -> int | None:
270
271
  runs = self.verification_check_dir(invocation_ref, attempt, check_ref)
272
+ entries = Path.iterdir if directory_entries is None else directory_entries
271
273
  numbers = [int(match.group(1)) for match in (
272
274
  _CHECK_RUN_RE.fullmatch(path.name)
273
- for path in (runs.iterdir() if runs.is_dir() else ())
275
+ for path in (entries(runs) if runs.is_dir() else ())
274
276
  ) if match]
275
277
  return max(numbers, default=None)
276
278
 
277
- def verification_check_refs(self, invocation_ref: str, attempt: int) -> list[str]:
279
+ def verification_check_refs(self, invocation_ref: str, attempt: int, *, directory_entries: Callable[[Path], Iterable[Path]] | None = None) -> list[str]:
278
280
  """The checks (`kind:id`) one attempt ran, sorted."""
279
281
  attempt_dir = self._verification_attempt_dir(invocation_ref, attempt)
282
+ entries = Path.iterdir if directory_entries is None else directory_entries
280
283
  return sorted(
281
284
  path.name.replace("-", ":", 1)
282
- for path in (attempt_dir.iterdir() if attempt_dir.is_dir() else ())
285
+ for path in (entries(attempt_dir) if attempt_dir.is_dir() else ())
283
286
  if path.is_dir() and "-" in path.name
284
287
  and _EXECUTION_SEGMENT_RE.fullmatch(path.name)
285
288
  )
@@ -13,7 +13,7 @@ from __future__ import annotations
13
13
 
14
14
  import re
15
15
  from pathlib import Path
16
- from typing import NamedTuple
16
+ from typing import Callable, Iterable, NamedTuple
17
17
 
18
18
  from .prepare_error import PrepareError
19
19
 
@@ -36,12 +36,16 @@ def implementation_planning_report_seq(report: Path) -> int:
36
36
  return int(match.group(1))
37
37
 
38
38
 
39
- def list_implementation_planning_reports(reports_dir: Path) -> list[Path]:
39
+ def list_implementation_planning_reports(
40
+ reports_dir: Path, *,
41
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
42
+ ) -> list[Path]:
40
43
  """Return numbered implementation-planning reports in latest-first order."""
41
44
  numbered: list[tuple[int, Path]] = []
42
- for report in reports_dir.glob(
45
+ reports = reports_dir.glob(
43
46
  "final-report-implementation-planning-*.data.json"
44
- ):
47
+ ) if directory_entries is None else directory_entries(reports_dir)
48
+ for report in reports:
45
49
  match = _FINAL_REPORT_RE.fullmatch(report.name)
46
50
  if match:
47
51
  numbered.append((int(match.group(1)), report))
@@ -7,13 +7,13 @@ import os
7
7
  import tempfile
8
8
  from functools import cache
9
9
  from pathlib import Path
10
- from typing import Any, Callable, Literal, Mapping
10
+ from typing import Any, Callable, Literal, Mapping, MutableMapping
11
11
 
12
12
  from okstra_project import project_json_path
13
13
  from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
14
14
 
15
15
  from .analysis_packet import _heading_lines
16
- from .json_boundary import load_owned_object, write_owned_object_atomic
16
+ from .json_boundary import ArtifactByteReader, load_owned_object, write_owned_object_atomic
17
17
  from .qa_commands import (
18
18
  QA_RELATIVE_PATH_DESCRIPTION, qa_relative_path_valid, validate_qa_commands,
19
19
  )
@@ -59,6 +59,37 @@ def safe_qa_path(root: Path, relative: str) -> Path:
59
59
  return path
60
60
 
61
61
 
62
+ def project_artifact_relative_path(root: Path, path: Path) -> str:
63
+ """Resolve a project-root alias without erasing links below that root."""
64
+ root = root.resolve()
65
+ candidate = path.absolute()
66
+ if candidate.is_relative_to(root):
67
+ return candidate.relative_to(root).as_posix()
68
+ for ancestor in reversed(candidate.parents):
69
+ if ancestor.resolve() == root:
70
+ return candidate.relative_to(ancestor).as_posix()
71
+ raise ValueError(f"Artifact path must remain within its project root: {path}")
72
+
73
+
74
+ def read_fingerprinted_artifact(
75
+ root: Path, path: Path, reader: ArtifactByteReader,
76
+ fingerprints: MutableMapping[str, str | None],
77
+ ) -> bytes:
78
+ relative = project_artifact_relative_path(root, path)
79
+ try:
80
+ raw = reader(root.resolve() / relative)
81
+ except (OSError, ValueError) as exc:
82
+ if relative in fingerprints and fingerprints[relative] is not None:
83
+ raise ValueError(f"Evidence input could not be read again: {relative}: {exc}") from exc
84
+ fingerprints[relative] = None
85
+ raise
86
+ digest = content_digest(raw)
87
+ if relative in fingerprints and fingerprints[relative] != digest:
88
+ raise ValueError(f"Evidence input changed while being read: {relative}")
89
+ fingerprints[relative] = digest
90
+ return raw
91
+
92
+
62
93
  def existing_qa_file(root: Path, relative: str) -> Path:
63
94
  path = safe_qa_path(root, relative)
64
95
  if not path.is_file():