okstra 0.234.0 → 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 (109) 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 +12 -7
  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 +66 -46
  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-brief-gen/SKILL.md +52 -6
  97. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  98. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  99. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +31 -0
  101. package/runtime/skills/okstra-tdd/SKILL.md +75 -11
  102. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  103. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  104. package/runtime/templates/reports/html/i18n/en.json +113 -0
  105. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  106. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  107. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  108. package/runtime/templates/trace/trace.template.md +2 -0
  109. package/runtime/validators/validate-report-views.py +4 -36
@@ -0,0 +1,348 @@
1
+ """Resolve stored run originals without collecting implementation state."""
2
+ from __future__ import annotations
3
+
4
+ from collections.abc import Mapping
5
+ import json
6
+ import re
7
+ from pathlib import Path, PurePosixPath
8
+ from typing import Any
9
+
10
+ from ..final_report_schema import load_schema_for_data
11
+ from ..json_boundary import ReadBudget, load_owned_object_snapshot, parse_owned_snapshot
12
+ from ..paths import RunRef, task_manifest_file
13
+ from ..qa_procedures import safe_qa_path
14
+ from ..report_validation_identity import _report_run_seq
15
+ from ..trace_tasks import parse_trace_source
16
+ from .baseline import MAX_BASELINE_BYTES, ComparisonError, ComparisonOwner, _owner_and_directory
17
+ from .model import ComparisonSource, MAX_COMPARISON_INPUT_BYTES, MAX_COMPARISON_READ_BYTES, MAX_RECORDS
18
+ from .source import SOURCE_CHANGED_DURING_READ, digest_bytes, read_source_bytes
19
+
20
+ MAX_NORMALIZED_SUMMARY_CHARS = 64 * 1024
21
+ NORMALIZATION_DIAGNOSTIC_RESERVE_BYTES = 8192
22
+
23
+
24
+ class _ChangedInput(ComparisonError):
25
+ pass
26
+
27
+
28
+ def _artifact_bytes(root: Path, relative: str, fingerprints: dict[str, str | None], budget: ReadBudget, *, limit: int = MAX_BASELINE_BYTES) -> bytes | None:
29
+ if not isinstance(relative, str):
30
+ raise ComparisonError("Comparison input path must be a string")
31
+ path = PurePosixPath(relative)
32
+ if relative != path.as_posix() or path.is_absolute() or ".." in path.parts or not path.parts or path.parts[0] != ".okstra":
33
+ raise ComparisonError("Comparison input path must remain under .okstra")
34
+ try:
35
+ body, _, problem = read_source_bytes(root, relative, budget, file_limit=limit, shared_budget=budget)
36
+ except FileNotFoundError:
37
+ if fingerprints.get(relative) is not None:
38
+ raise _ChangedInput("Comparison input disappeared during assembly")
39
+ fingerprints[relative] = None
40
+ return None
41
+ if problem == SOURCE_CHANGED_DURING_READ:
42
+ raise _ChangedInput(f"Comparison input changed during assembly: {relative}")
43
+ if problem or body is None:
44
+ raise ComparisonError(f"Comparison input could not be read: {relative}: {problem}")
45
+ digest = digest_bytes(body)
46
+ if relative in fingerprints and fingerprints[relative] != digest:
47
+ raise _ChangedInput("Comparison input changed during assembly")
48
+ fingerprints[relative] = digest
49
+ return body
50
+
51
+
52
+ def _validate_source(root: Path, owner: dict[str, Any], source: Mapping[str, Any], fingerprints: dict[str, str | None], budget: ReadBudget) -> bool:
53
+ if len(json.dumps(source, ensure_ascii=True, separators=(",", ":")).encode()) > MAX_COMPARISON_INPUT_BYTES:
54
+ raise ComparisonError("Normalized comparison source exceeds its byte limit")
55
+ allowed = set(ComparisonSource.__required_keys__) | set(ComparisonSource.__optional_keys__)
56
+ if set(source) - allowed:
57
+ raise ComparisonError("Normalized comparison source has unsupported fields")
58
+ if source.get("owner") != owner or source.get("kind") != owner["kind"] or owner["kind"] not in {"trace", "run", "task"}:
59
+ raise ComparisonError("Comparison source owner is invalid")
60
+ for key in ("path", "digest", "language", "title", "status"):
61
+ if not isinstance(source.get(key), str):
62
+ raise ComparisonError(f"Comparison source requires {key}")
63
+ path = source["path"]
64
+ if owner["kind"] in {"trace", "task"}:
65
+ if path != owner["path"]:
66
+ raise ComparisonError("Comparison source does not belong to its owner")
67
+ elif not (root / path).is_relative_to((root / owner["path"]).parent.parent):
68
+ raise ComparisonError("Run report does not belong to its owner")
69
+ body = _artifact_bytes(root, path, fingerprints, budget)
70
+ if body is None or digest_bytes(body) != source["digest"]:
71
+ return False
72
+ if owner["kind"] == "trace":
73
+ trace = parse_trace_source(body)
74
+ if trace.frontmatter.get("createdAt") != owner.get("createdAt"):
75
+ raise ComparisonError("Trace creation identity does not match its owner")
76
+ elif owner["kind"] == "task":
77
+ manifest = parse_owned_snapshot(root / path, body, artifact="comparison task manifest").value
78
+ if task_manifest_file((root / path).parent) != root / path or manifest.get("taskKey") != owner.get("taskKey"):
79
+ raise ComparisonError("Comparison source does not identify its canonical task")
80
+ else:
81
+ raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
82
+ manifest = parse_owned_snapshot(root / owner["path"], raw, artifact="comparison run manifest").value if raw is not None else {}
83
+ expected_owner, _, report_path = run_comparison_scope(root, root / owner["path"], manifest)
84
+ if expected_owner != owner:
85
+ raise ComparisonError("Run manifest identity does not match its owner")
86
+ if report_path.relative_to(root).as_posix() != path:
87
+ raise ComparisonError("Run report does not match the manifest's declared report")
88
+ for key in ("requirements", "useCases"):
89
+ values = source.get(key, [])
90
+ if not isinstance(values, list) or len(values) > MAX_RECORDS or any(not isinstance(value, (str, dict)) for value in values):
91
+ raise ComparisonError(f"Comparison source {key} is invalid")
92
+ if "summary" in source and not isinstance(source["summary"], str):
93
+ raise ComparisonError("Comparison source summary is invalid")
94
+ limitations = source.get("limitations", [])
95
+ if not isinstance(limitations, list) or len(limitations) > MAX_RECORDS or any(not isinstance(value, str) for value in limitations):
96
+ raise ComparisonError("Comparison source limitations are invalid")
97
+ records = source.get("evidence", [])
98
+ if not isinstance(records, list) or len(records) > MAX_RECORDS or any(not isinstance(row, dict) for row in records):
99
+ raise ComparisonError("Comparison source evidence is invalid")
100
+ if not isinstance(source.get("stages", []), list) or any(not isinstance(stage, (str, int)) or isinstance(stage, bool) for stage in source.get("stages", [])):
101
+ raise ComparisonError("Comparison source stages are invalid")
102
+ return True
103
+
104
+
105
+ def _project_artifact(project_root: Path, value: str | Path) -> Path:
106
+ requested = Path(project_root).absolute()
107
+ root = requested.resolve(strict=True)
108
+ path = Path(value)
109
+ if path.is_absolute():
110
+ anchor = requested if path.is_relative_to(requested) else root
111
+ if not path.is_relative_to(anchor):
112
+ anchor = next((parent for parent in path.parents if parent.resolve() == root), root)
113
+ path = path.relative_to(anchor)
114
+ return safe_qa_path(root, path.as_posix())
115
+
116
+
117
+ def run_comparison_scope(
118
+ project_root: Path, manifest_path: Path, manifest: Mapping[str, Any],
119
+ ) -> tuple[ComparisonOwner, Path, Path]:
120
+ root = Path(project_root).resolve(strict=True)
121
+ path = _project_artifact(project_root, manifest_path)
122
+ if manifest.get("taskType") != "implementation":
123
+ raise ComparisonError("Comparison run must be an implementation run")
124
+ categories = manifest.get("runSequencesByCategory")
125
+ seq = categories.get("manifests") if isinstance(categories, Mapping) else _report_run_seq(path)
126
+ if not isinstance(seq, str) or not seq.isascii() or not seq.isdigit():
127
+ raise ComparisonError("Comparison run manifest has no valid manifest sequence")
128
+ ref = RunRef.from_run_dir(path.parent.parent, seq=int(seq))
129
+ if ref.task_type != "implementation" or ref.manifest != path:
130
+ raise ComparisonError("Comparison run manifest is not at its canonical run path")
131
+ owner: ComparisonOwner = {"kind": "run", "path": path.relative_to(root).as_posix(), "runSeq": seq}
132
+ if "taskKey" in manifest:
133
+ owner["taskKey"] = manifest["taskKey"]
134
+ if ref.stage is not None:
135
+ owner["stage"] = str(ref.stage)
136
+ declaration = manifest.get("implementationComparison")
137
+ directory = None
138
+ if declaration is not None:
139
+ if not isinstance(declaration, dict) or declaration.get("schemaVersion") != "1.0" or declaration.get("owner") != owner:
140
+ raise ComparisonError("Run comparison declaration does not match its run")
141
+ directory = declaration.get("comparisonDirectory")
142
+ if not isinstance(directory, str) or not directory:
143
+ raise ComparisonError("Run comparison declaration requires its directory")
144
+ directory = _project_artifact(project_root, directory)
145
+ _, directory, _ = _owner_and_directory(root, directory, owner)
146
+ original = manifest.get("expectedReportRecordPath") or manifest.get("expectedReportPath")
147
+ if not isinstance(original, str) or not original:
148
+ raise ComparisonError("Run manifest does not declare its report original")
149
+ report = _project_artifact(project_root, original)
150
+ if report.parent != ref.reports_dir:
151
+ raise ComparisonError("Run report does not belong to its run")
152
+ return owner, directory, report
153
+
154
+
155
+ def resolve_run_comparison(project_root: Path, manifest_path: Path) -> tuple[ComparisonOwner, Path]:
156
+ path = _project_artifact(project_root, manifest_path)
157
+ manifest = load_owned_object_snapshot(path, artifact="comparison run manifest", max_bytes=MAX_BASELINE_BYTES).value
158
+ owner, directory, _ = run_comparison_scope(project_root, path, manifest)
159
+ return owner, directory
160
+
161
+
162
+ def _bounded_source(source: ComparisonSource, limitations: list[str]) -> ComparisonSource:
163
+ for key, maximum in (("summary", MAX_NORMALIZED_SUMMARY_CHARS), ("title", 4096)):
164
+ value = source.get(key, "")
165
+ if not isinstance(value, str):
166
+ raise ComparisonError(f"Run comparison {key} must be text")
167
+ if len(value) > maximum:
168
+ source[key] = value[:maximum]
169
+ limitations.append(f"Recorded {key} was truncated for the normalized source")
170
+ rows = {key: source[key] for key in ("requirements", "useCases", "evidence")}
171
+ source.update(requirements=[], useCases=[], evidence=[], limitations=limitations)
172
+ if any(not isinstance(source[key], str) or len(source[key]) > 128 for key in ("language", "status")):
173
+ raise ComparisonError("Run comparison language and status must be bounded text")
174
+ remaining = MAX_COMPARISON_INPUT_BYTES - len(json.dumps(source, ensure_ascii=True, separators=(",", ":")).encode()) - NORMALIZATION_DIAGNOSTIC_RESERVE_BYTES
175
+ for key, values in rows.items():
176
+ if not isinstance(values, list):
177
+ raise ComparisonError(f"Run comparison {key} must be an array")
178
+ for index, value in enumerate(values):
179
+ size = len(json.dumps(value, ensure_ascii=True, separators=(",", ":")).encode()) + 1
180
+ if index >= MAX_RECORDS or size > remaining:
181
+ limitations.append(f"Recorded {key} omitted {len(values) - index} rows at the normalized input limit")
182
+ break
183
+ source[key].append(value)
184
+ remaining -= size
185
+ return source
186
+
187
+
188
+ def read_run_comparison_source(
189
+ project_root: Path, owner: ComparisonOwner, *, budget: ReadBudget | None = None,
190
+ fingerprints: dict[str, str | None] | None = None,
191
+ ) -> ComparisonSource:
192
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES) if budget is None else budget
193
+ fingerprints = {} if fingerprints is None else fingerprints
194
+ path = _project_artifact(project_root, owner["path"])
195
+ root = Path(project_root).resolve(strict=True)
196
+ manifest_raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
197
+ manifest = parse_owned_snapshot(path, manifest_raw, artifact="comparison run manifest").value if manifest_raw is not None else {}
198
+ actual, _, report = run_comparison_scope(project_root, path, manifest)
199
+ if owner != actual:
200
+ raise ComparisonError("Comparison source belongs to a different run")
201
+ raw = _artifact_bytes(root, report.relative_to(root).as_posix(), fingerprints, budget)
202
+ if raw is None:
203
+ raise ComparisonError("Run comparison report original is missing")
204
+ limitations = []
205
+ source: ComparisonSource = {
206
+ "kind": "run", "owner": actual, "path": report.relative_to(root).as_posix(),
207
+ "digest": digest_bytes(raw), "language": "en", "title": report.stem,
208
+ "status": "unknown", "requirements": [], "evidence": [], "useCases": [],
209
+ "stages": [actual["stage"]] if actual.get("stage") else [],
210
+ }
211
+ if "implementationComparison" not in manifest:
212
+ limitations.append("This historical run has no original comparison capture declaration")
213
+ if report.suffix == ".md":
214
+ source["summary"] = raw.decode("utf-8")
215
+ limitations.append("Historical Markdown is retained as recorded narrative; structured evidence was not inferred")
216
+ else:
217
+ data = json.loads(raw)
218
+ if not isinstance(data, dict):
219
+ raise ComparisonError("Run report original must be a JSON object")
220
+ try:
221
+ load_schema_for_data(data)
222
+ except ValueError as exc:
223
+ limitations.append(str(exc)[:1024])
224
+ header, meta = data.get("header", {}), data.get("meta", {})
225
+ frontmatter, human = data.get("frontmatter", {}), data.get("humanSummary", {})
226
+ if any(not isinstance(value, dict) for value in (header, meta, frontmatter, human)):
227
+ raise ComparisonError("Run report metadata must be JSON objects")
228
+ if header.get("taskType", "implementation") != "implementation" or (actual.get("taskKey") and header.get("taskKey", actual["taskKey"]) != actual["taskKey"]):
229
+ raise ComparisonError("Report original belongs to a different run task")
230
+ source["language"] = meta.get("reportLanguage", "en")
231
+ source["title"] = human.get("headline") or frontmatter.get("title") or report.stem
232
+ summary = data.get("summary", [])
233
+ source["summary"] = human.get("outcome") or ("\n".join(row["summary"] for row in summary if isinstance(row, dict) and isinstance(row.get("summary"), str)) if isinstance(summary, list) else str(summary))
234
+ implementation = data.get("implementation", {})
235
+ if not isinstance(implementation, dict):
236
+ raise ComparisonError("Run implementation record must be a JSON object")
237
+ source["status"] = frontmatter.get("status", "unknown")
238
+ source["requirements"] = implementation.get("requirementCoverage", [])
239
+ source["useCases"] = implementation.get("useCases", [])
240
+ validation = implementation.get("validationEvidence", [])
241
+ if not isinstance(validation, list):
242
+ raise ComparisonError("Run validation evidence must be a JSON array")
243
+ if len(validation) > MAX_RECORDS:
244
+ limitations.append(f"Recorded validation evidence omitted {len(validation) - MAX_RECORDS} rows before normalization")
245
+ source["evidence"] = [{"id": f"validation-{index}", **{key: row[key] for key in ("command", "exitCode") if key in row},
246
+ "summary": row.get("outputTail", "")}
247
+ for index, row in enumerate(validation[:MAX_RECORDS], 1) if isinstance(row, dict)]
248
+ return _bounded_source(source, limitations)
249
+
250
+
251
+ def task_comparison_owner(project_root: Path, task_root: Path, task_key: str | None = None) -> ComparisonOwner:
252
+ root = Path(project_root).resolve(strict=True)
253
+ path = _project_artifact(project_root, task_manifest_file(task_root))
254
+ owner: ComparisonOwner = {"kind": "task", "path": path.relative_to(root).as_posix()}
255
+ if task_key is not None:
256
+ owner["taskKey"] = task_key
257
+ return owner
258
+
259
+
260
+ def resolve_task_comparison(project_root: Path, manifest_path: Path) -> tuple[ComparisonOwner, Path]:
261
+ root = Path(project_root).resolve(strict=True)
262
+ run_owner, _ = resolve_run_comparison(root, manifest_path)
263
+ ref = RunRef.from_run_dir((root / run_owner["path"]).parent.parent, seq=int(run_owner["runSeq"]))
264
+ path = task_manifest_file(ref.task_root)
265
+ manifest = load_owned_object_snapshot(safe_qa_path(root, path.relative_to(root).as_posix()),
266
+ artifact="comparison task manifest", max_bytes=MAX_BASELINE_BYTES).value
267
+ key = manifest.get("taskKey")
268
+ if not isinstance(key, str) or not key or (run_owner.get("taskKey") and run_owner["taskKey"] != key):
269
+ raise ComparisonError("Selected implementation run does not identify its task")
270
+ owner = task_comparison_owner(root, ref.task_root, key)
271
+ _, directory, _ = _owner_and_directory(root, None, owner)
272
+ return owner, directory
273
+
274
+
275
+ def read_task_comparison_source(
276
+ project_root: Path, owner: ComparisonOwner, *, budget: ReadBudget | None = None,
277
+ fingerprints: dict[str, str | None] | None = None, plan_path: str | None = None,
278
+ ) -> ComparisonSource:
279
+ root = Path(project_root).resolve(strict=True)
280
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES) if budget is None else budget
281
+ fingerprints = {} if fingerprints is None else fingerprints
282
+ raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
283
+ path = root / owner["path"]
284
+ manifest = parse_owned_snapshot(path, raw, artifact="comparison task manifest").value if raw is not None else {}
285
+ if owner.get("kind") != "task" or task_manifest_file(path.parent) != path or manifest.get("taskKey") != owner.get("taskKey"):
286
+ raise ComparisonError("Comparison source does not identify its canonical task")
287
+ outcomes = manifest.get("phaseOutcome", {})
288
+ outcome = outcomes.get("implementation", {}) if isinstance(outcomes, dict) else {}
289
+ language = manifest.get("reportLanguage", "en")
290
+ limitations = []
291
+ if plan_path is not None and "reportLanguage" not in manifest:
292
+ plan = safe_qa_path(root, plan_path)
293
+ if plan.parent != RunRef.from_task_root(path.parent, "implementation-planning").reports_dir:
294
+ raise ComparisonError("Task comparison plan belongs to another task")
295
+ plan_raw = _artifact_bytes(root, plan_path, fingerprints, budget)
296
+ try:
297
+ payload = parse_owned_snapshot(plan, plan_raw, artifact="comparison task plan").value if plan_raw is not None else {}
298
+ meta = payload.get("meta", {})
299
+ language = meta.get("reportLanguage", "en") if isinstance(meta, dict) else "en"
300
+ except ValueError as exc:
301
+ limitations.append(f"Task report language was not recovered from the invalid latest plan: {exc}")
302
+ source: ComparisonSource = {
303
+ "kind": "task", "owner": owner, "path": owner["path"], "digest": digest_bytes(raw),
304
+ "language": language, "title": str(manifest.get("title") or owner["taskKey"]),
305
+ "status": str(outcome.get("state", "unknown")) if isinstance(outcome, dict) else "unknown",
306
+ "requirements": [], "evidence": [], "useCases": [],
307
+ }
308
+ return _bounded_source(source, limitations)
309
+
310
+
311
+ def read_comparison_before_commit(
312
+ root: Path, owner: ComparisonOwner, *, budget: ReadBudget,
313
+ fingerprints: dict[str, str | None],
314
+ ) -> str | None:
315
+ raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
316
+ if raw is None:
317
+ return None
318
+ if owner["kind"] == "trace":
319
+ trace = parse_trace_source(raw)
320
+ if trace.frontmatter.get("createdAt") != owner.get("createdAt"):
321
+ raise ComparisonError("Trace creation identity does not match its owner")
322
+ value = trace.frontmatter.get("baseCommit")
323
+ elif owner["kind"] == "run":
324
+ from ..verification_input_ref import VerificationInputReference
325
+ from ..verification_inputs import DESIGN_REVIEW_INPUT_SCHEMA_VERSION, read_verification_inputs
326
+
327
+ manifest = parse_owned_snapshot(root / owner["path"], raw, artifact="comparison run manifest").value
328
+ actual, _, _ = run_comparison_scope(root, root / owner["path"], manifest)
329
+ if actual != owner:
330
+ raise ComparisonError("Historical comparison run identity changed")
331
+ reference = VerificationInputReference.from_artifact_fields(manifest)
332
+ if reference is None:
333
+ return None
334
+ ref = RunRef.from_manifest(root / owner["path"], manifest)
335
+ if reference.relative_path != ref.verification_inputs.relative_to(root).as_posix():
336
+ raise ComparisonError("Historical verification inputs belong to another run")
337
+
338
+ def reader(path: Path) -> bytes:
339
+ body = _artifact_bytes(root, path.relative_to(root).as_posix(), fingerprints, budget)
340
+ if body is None:
341
+ raise FileNotFoundError(path)
342
+ return body
343
+
344
+ inputs = read_verification_inputs(safe_qa_path(root, reference.relative_path), reference.digest, reader=reader)
345
+ value = inputs.get("reviewBase") if inputs["schemaVersion"] == DESIGN_REVIEW_INPUT_SCHEMA_VERSION else None
346
+ else:
347
+ return None
348
+ return value if isinstance(value, str) and re.fullmatch(r"[0-9a-f]{40}(?:[0-9a-f]{24})?", value) else None
@@ -0,0 +1,47 @@
1
+ """Shared input contract for preserved implementation comparisons."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Any, Literal, NotRequired, TypedDict
5
+
6
+ from .baseline import MAX_BASELINE_BYTES, ComparisonOwner
7
+ from .source import MAX_TOTAL_READ_BYTES
8
+
9
+ MAX_COMPARISON_INPUT_BYTES = 1024 * 1024
10
+ MAX_COMPARISON_READ_BYTES = 2 * MAX_TOTAL_READ_BYTES + 4 * MAX_BASELINE_BYTES
11
+ MAX_RECORDS = 1000
12
+
13
+
14
+ class RunCheckSelection(TypedDict):
15
+ roleExecutionRef: str
16
+ invocationRef: str
17
+ attempt: int
18
+ checkRuns: list[list[str | int]]
19
+
20
+
21
+ class RunEvidenceSelection(TypedDict):
22
+ generation: dict[str, str] | None
23
+ generationNumber: int | None
24
+ attempts: list[list[str | int]]
25
+ checks: list[RunCheckSelection]
26
+
27
+
28
+ class TaskEvidenceSelection(TypedDict):
29
+ task: dict[str, Any]
30
+ stages: dict[str, RunEvidenceSelection | None]
31
+ integrated: dict[str, Any]
32
+
33
+
34
+ class ComparisonSource(TypedDict):
35
+ kind: Literal["run", "trace", "task"]
36
+ owner: ComparisonOwner
37
+ path: str
38
+ digest: str
39
+ language: str
40
+ title: str
41
+ status: str
42
+ requirements: list[str | dict[str, Any]]
43
+ evidence: list[dict[str, Any]]
44
+ summary: NotRequired[str]
45
+ limitations: NotRequired[list[str]]
46
+ useCases: NotRequired[list[str | dict[str, Any]]]
47
+ stages: NotRequired[list[str | int]]
@@ -0,0 +1,195 @@
1
+ """Declare and preserve implementation baselines before lead dispatch."""
2
+ from __future__ import annotations
3
+
4
+ from contextlib import ExitStack
5
+ import json
6
+ from pathlib import Path
7
+ import subprocess
8
+ import sys
9
+ from typing import Any, Literal
10
+
11
+ from ..json_boundary import JsonBoundaryError, load_owned_object
12
+ from ..qa_procedures import safe_qa_path
13
+ from ..render import render_run_manifest
14
+ from ..run_context import dir_flock
15
+ from . import comparison_directory
16
+
17
+
18
+ def _read_manifest(path: Path) -> dict[str, Any]:
19
+ try:
20
+ return load_owned_object(path, artifact="run manifest")
21
+ except (OSError, JsonBoundaryError):
22
+ return {}
23
+
24
+
25
+ def _comparison_scope(project: Path, owner: dict[str, str], source: Path) -> dict[str, Any]:
26
+ project = project.resolve()
27
+ directory = comparison_directory(project, owner)
28
+ return {
29
+ "comparisonDirectory": directory.relative_to(project).as_posix(),
30
+ "owner": owner, "sourceRoot": str(source),
31
+ "baseline": {
32
+ "status": "unavailable", "baselineRef": None,
33
+ "notesPath": (directory / "notes.json").relative_to(project).as_posix(),
34
+ "limitations": ["Initial baseline capture did not complete"],
35
+ },
36
+ }
37
+
38
+
39
+ def _valid_scope(value: object, expected: dict[str, Any]) -> bool:
40
+ if not isinstance(value, dict) or value.get("owner") != expected["owner"]:
41
+ return False
42
+ baseline = value.get("baseline")
43
+ return (
44
+ value.get("comparisonDirectory") == expected["comparisonDirectory"]
45
+ and isinstance(value.get("sourceRoot"), str)
46
+ and isinstance(baseline, dict)
47
+ and {"status", "baselineRef", "notesPath", "limitations"} <= baseline.keys()
48
+ and isinstance(baseline["limitations"], list)
49
+ and all(isinstance(item, str) for item in baseline["limitations"])
50
+ )
51
+
52
+
53
+ def _save_comparison(ctx: dict[str, Any], comparison: dict[str, Any]) -> None:
54
+ ctx["IMPLEMENTATION_COMPARISON_JSON"] = json.dumps(comparison, ensure_ascii=False)
55
+ render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
56
+
57
+
58
+ def declare_implementation_comparison(
59
+ ctx: dict[str, Any], task_source: Path, stage: int, *, new_run: bool,
60
+ ) -> None:
61
+ recorded = _read_manifest(Path(ctx["RUN_MANIFEST_PATH"]))
62
+ if not new_run and "implementationComparison" not in recorded:
63
+ ctx.pop("IMPLEMENTATION_COMPARISON_JSON", None)
64
+ return
65
+ project = Path(ctx["PROJECT_ROOT"])
66
+ initial = {
67
+ "schemaVersion": "1.0",
68
+ **_comparison_scope(project, {
69
+ "kind": "run", "path": ctx["RUN_MANIFEST_RELATIVE_PATH"],
70
+ "taskKey": ctx["TASK_KEY"], "runSeq": ctx["RUN_MANIFESTS_SEQ"], "stage": str(stage),
71
+ }, Path(ctx.get("EXECUTOR_WORKTREE_PATH") or project)),
72
+ "taskBaseline": {
73
+ **_comparison_scope(project, {
74
+ "kind": "task", "path": ctx["TASK_MANIFEST_RELATIVE_PATH"], "taskKey": ctx["TASK_KEY"],
75
+ }, task_source),
76
+ "captureState": "pending",
77
+ },
78
+ }
79
+ comparison = initial if new_run else recorded.get("implementationComparison")
80
+ if not new_run and not (
81
+ _valid_scope(comparison, initial)
82
+ and _valid_scope(comparison.get("taskBaseline"), initial["taskBaseline"])
83
+ ):
84
+ comparison = initial
85
+ comparison["taskBaseline"]["captureState"] = "attempted"
86
+ for scope in (comparison, comparison["taskBaseline"]):
87
+ scope["baseline"]["limitations"] = ["Recorded comparison metadata is invalid; baseline was not recollected"]
88
+ ctx["IMPLEMENTATION_COMPARISON_JSON"] = json.dumps(comparison, ensure_ascii=False)
89
+
90
+
91
+ def _baseline_result(
92
+ project: Path, scope: dict[str, Any], action: Literal["capture", "status"], baseline_ref: str = "",
93
+ ) -> dict[str, Any]:
94
+ from . import capture_baseline, read_baseline_status
95
+
96
+ directory = project / scope["comparisonDirectory"]
97
+ try:
98
+ if action == "capture":
99
+ return capture_baseline(project, Path(scope["sourceRoot"]), directory, scope["owner"], baseline_ref=baseline_ref)
100
+ return read_baseline_status(project, directory, scope["owner"])
101
+ except (OSError, ValueError, subprocess.SubprocessError) as exc:
102
+ return {
103
+ **scope["baseline"], "status": "unavailable", "baselineRef": None,
104
+ "limitations": [f"Baseline collection failed: {exc}"],
105
+ }
106
+
107
+
108
+ def _task_capture_blocker(ctx: dict[str, Any], scope: dict[str, Any]) -> dict[str, Any] | None:
109
+ manifest_path = Path(ctx["RUN_MANIFEST_PATH"])
110
+ for path in (Path(ctx["TASK_ROOT"]) / "runs/implementation").rglob("run-manifest-*.json"):
111
+ if path == manifest_path:
112
+ continue
113
+ recorded = _read_manifest(path)
114
+ comparison = recorded.get("implementationComparison")
115
+ prior = comparison.get("taskBaseline") if isinstance(comparison, dict) else None
116
+ resources = recorded.get("resources")
117
+ prompt = resources.get("leadExecutionPromptPath") if isinstance(resources, dict) else None
118
+ try:
119
+ unpublished = isinstance(prompt, str) and bool(prompt) and not safe_qa_path(Path(ctx["PROJECT_ROOT"]), prompt).exists()
120
+ except (OSError, ValueError):
121
+ unpublished = False
122
+ if (
123
+ isinstance(comparison, dict) and comparison.get("schemaVersion") == "1.0"
124
+ and _valid_scope(prior, scope)
125
+ and prior.get("sourceRoot") == scope["sourceRoot"]
126
+ and prior.get("captureState") == "pending"
127
+ and prior["baseline"]["baselineRef"] is None
128
+ and unpublished
129
+ ):
130
+ continue
131
+ if _valid_scope(prior, scope) and prior["baseline"]["baselineRef"] is None:
132
+ return prior["baseline"]
133
+ return {
134
+ **scope["baseline"],
135
+ "limitations": ["Task baseline was not captured before an earlier implementation run"],
136
+ }
137
+ return None
138
+
139
+
140
+ def _capture_task_baseline(
141
+ ctx: dict[str, Any], comparison: dict[str, Any], task_base: str, *, new_run: bool,
142
+ ) -> dict[str, Any]:
143
+ project = Path(ctx["PROJECT_ROOT"])
144
+ scope = comparison["taskBaseline"]
145
+ if not new_run:
146
+ return _baseline_result(project, scope, "status")
147
+ with ExitStack() as locks:
148
+ try:
149
+ locks.enter_context(dir_flock(Path(ctx["TASK_ROOT"]), ".implementation-comparison.lock"))
150
+ except OSError as exc:
151
+ scope["captureState"] = "attempted"
152
+ return {
153
+ **scope["baseline"], "status": "unavailable", "baselineRef": None,
154
+ "limitations": [f"Task baseline lock failed: {exc}"],
155
+ }
156
+ path = project / scope["comparisonDirectory"] / "baseline.json"
157
+ if path.exists() or path.is_symlink() or scope.get("captureState") != "pending":
158
+ return _baseline_result(project, scope, "status")
159
+ blocked = _task_capture_blocker(ctx, scope)
160
+ if blocked is not None:
161
+ return blocked
162
+ scope["captureState"] = "attempted"
163
+ _save_comparison(ctx, comparison)
164
+ scope["baseline"] = _baseline_result(project, scope, "capture", task_base)
165
+ _save_comparison(ctx, comparison)
166
+ return scope["baseline"]
167
+
168
+
169
+ def capture_implementation_comparison(
170
+ ctx: dict[str, Any], *, stage_base: str, task_base: str, new_run: bool,
171
+ ) -> None:
172
+ encoded = ctx.get("IMPLEMENTATION_COMPARISON_JSON")
173
+ if encoded is None:
174
+ return
175
+ comparison = json.loads(encoded)
176
+ previous_run = comparison["baseline"]
177
+ run_result = _baseline_result(Path(ctx["PROJECT_ROOT"]), comparison, "capture" if new_run else "status", stage_base)
178
+ comparison["baseline"] = (
179
+ previous_run if not new_run and run_result["baselineRef"] is None and previous_run["baselineRef"] is None
180
+ else run_result
181
+ )
182
+ previous_task = comparison["taskBaseline"]["baseline"]
183
+ task_result = _capture_task_baseline(ctx, comparison, task_base, new_run=new_run)
184
+ comparison["taskBaseline"]["baseline"] = (
185
+ previous_task if not new_run and task_result["baselineRef"] is None and previous_task["baselineRef"] is None
186
+ else task_result
187
+ )
188
+ for scope in (comparison, comparison["taskBaseline"]):
189
+ result = scope["baseline"]
190
+ if result["status"] != "complete":
191
+ print(
192
+ f"implementation-comparison: {scope['owner']['kind']} baseline {result['status']}: "
193
+ + "; ".join(result["limitations"]), file=sys.stderr,
194
+ )
195
+ _save_comparison(ctx, comparison)