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
@@ -6,7 +6,7 @@ from pathlib import Path
6
6
  from .agent.invocation import AgentInvocationError, verify_standalone_completion
7
7
  from .coverage_census import CellVerdicts
8
8
  from .json_boundary import load_owned_object
9
- from .review_verdicts import read_review_census, _head_tree, parse_review_verdicts
9
+ from .review_verdicts import binding_lines, read_review_census, _head_tree, parse_review_verdicts
10
10
 
11
11
 
12
12
  def check_review_coverage(
@@ -20,6 +20,7 @@ def check_review_coverage(
20
20
  if not completions or len(set(completions)) != len(completions):
21
21
  raise ValueError("pass distinct completion paths for one reviewer")
22
22
  bodies: list[str] = []
23
+ skipped = 0
23
24
  assignment: object = None
24
25
  for path in completions:
25
26
  verified = verify_standalone_completion(
@@ -35,9 +36,19 @@ def check_review_coverage(
35
36
  raise AgentInvocationError("coverage cannot mix reviewer model assignments")
36
37
  assignment = current
37
38
  heads = [line.removeprefix("Review head: ")
38
- for line in verified.returned_body.splitlines()
39
+ for line in binding_lines(verified.returned_body)
39
40
  if line.startswith("Review head: ")]
40
41
  if heads and heads != [tree.commit]:
41
- raise ValueError("completion review head differs from --head")
42
+ skipped += 1
43
+ continue
42
44
  bodies.append(verified.returned_body)
43
- return parse_review_verdicts(project_root, census, bodies, tree.commit, base=base)
45
+ if not bodies:
46
+ raise ValueError("completion review head differs from --head")
47
+ result = parse_review_verdicts(project_root, census, bodies, tree.commit, base=base)
48
+ if skipped:
49
+ note = f"; {skipped} completion(s) bound to another review head were left out"
50
+ result = CellVerdicts(result.verdicts,
51
+ {cell: reason + note for cell, reason in result.missing.items()},
52
+ result.unknown)
53
+ return result
54
+
@@ -155,11 +155,18 @@ def gap_fill_requests(
155
155
  continue
156
156
  if row.get("state") != "completed":
157
157
  continue
158
- missing = dict(row["audit"]["missing"])
158
+ after_gap_fill = item["attempt"] > 1 and item.get("kind") == "gap-fill"
159
+ if row["audit"].get("error"):
160
+ if after_gap_fill:
161
+ stopped.append(f"{team}/{axis}")
162
+ continue
163
+ missing = dict.fromkeys(own, f"attempt rejected: {row['audit']['error']}")
164
+ else:
165
+ missing = dict(row["audit"]["missing"])
159
166
  missing.update((cell, "rejected by the lead") for cell in rejects)
160
167
  if not missing:
161
168
  continue
162
- if item["attempt"] > 1 and item.get("kind") == "gap-fill" and len(row["audit"]["missing"]) >= len(own):
169
+ if after_gap_fill and len(row["audit"]["missing"]) >= len(own):
163
170
  stopped.append(f"{team}/{axis}")
164
171
  continue
165
172
  requests.append(AttemptRequest(team, axis, "gap-fill", tuple(sorted(missing)), missing))
@@ -229,6 +236,7 @@ def _prepare_item(
229
236
  from .agent.standalone import StandaloneInvocationRequest, prepare_standalone_invocation
230
237
  from .code_review_invocation import CodeReviewInputs
231
238
  from .registry.provider_registry import default_provider_registry
239
+ from .review_verdicts import read_review_census
232
240
 
233
241
  record, project, root = batch.record, batch.project, batch.root
234
242
  policy = batch.path(record["policy"])
@@ -247,7 +255,11 @@ def _prepare_item(
247
255
  f"- Specialist axis: {axis}\n"
248
256
  f"- Attempt: {attempt} ({kind})\n"
249
257
  f"- Full census (context only): {record['census']}\n"
250
- f"- Assigned census: {_relative(census, project)}\n\n"
258
+ f"- Assigned census: {_relative(census, project)}\n"
259
+ f"- Rules to account for: {', '.join(read_review_census(census).rules[axis])}. Rules of "
260
+ "other groups in the Rules table belong to other specialists: never list them in "
261
+ "Checked, N/A or Findings. Report a suspected issue under another group's rule as an "
262
+ "out-of-scope observation outside the Coverage Verdicts table.\n\n"
251
263
  f"{continuation}"
252
264
  f"## Inspection scope\n\n```text\n{scope}```\n"
253
265
  ))
@@ -11,7 +11,7 @@ from .agent.invocation import verify_standalone_completion
11
11
  from .fixed_text import scalar
12
12
  from .code_review_coverage import check_review_coverage
13
13
  from .review_verdicts import (
14
- ReviewCensus, _HeadTree, _head_tree, _table_fields, read_review_census,
14
+ ReviewCensus, _HeadTree, _head_tree, _table_fields, binding_lines, read_review_census,
15
15
  )
16
16
  from .verification_input_types import FrozenReviewPolicy
17
17
  from .qa_procedures import canonical_json_digest
@@ -92,8 +92,9 @@ def _prior_inputs(
92
92
  body = verify_standalone_completion(
93
93
  completion, project_root=root, expected_purpose="code-review",
94
94
  ).returned_body
95
+ lines = binding_lines(body)
95
96
  for line in baseline.splitlines():
96
- if body.splitlines().count(line) != 1:
97
+ if lines.count(line) != 1:
97
98
  raise ValueError("previous baseline missing or different")
98
99
  for cell, sources in _dependencies(body, census).items():
99
100
  dependencies.setdefault(cell, set()).update(sources)
@@ -93,7 +93,7 @@ _CLI_EPILOG = r"""Usage:
93
93
  okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
94
94
  okstra code-review target --branch <name> --base <ref> [--date <YYYY-MM-DD>] [--project-root <dir>] --json
95
95
  okstra code-review check-coverage --head <ref> [--base <ref>] --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
96
- okstra code-review census --base <ref> --head <ref> --rules <review-rules.json> --out <artifact-path> [--policy <path> ...] [--run-manifest <path>] [--resource <pack-relative-resource> ...]
96
+ okstra code-review census --base <ref> --head <ref> --rules <review-rules.json> --out <artifact-path> [--policy <path> ...] [--run-manifest <path>] [--resource <pack-relative-resource> ...] [--function-inventory <path>]
97
97
  okstra code-review assign --census <review-id>.census.md [--project-root <dir>]
98
98
  okstra code-review prepare --review-id <id> --census <id>.census.md --review-policy <path> --base <commit> --head <commit> --slots <slots.json> --brief <path> --host-runtime <host> [--resource <id> ...]
99
99
  okstra code-review start --batch <id>.batch.json [--max-calls <n>]
@@ -118,7 +118,9 @@ base evidence at `--base`, never the working tree, prints covered cells, missing
118
118
  prints its Review policy path/digest, and selects its shared catalog with the
119
119
  captured architecture. --run-manifest reuses frozen implementation rules;
120
120
  --policy captures additional applied standards. It exits 1 when changed
121
- non-Python code still needs function cells added by hand. `assign` writes one
121
+ non-Python code still needs function cells. --function-inventory supplies
122
+ them: a missing file is written as a template, and a filled one lists
123
+ {"functions": [{"start", "end", "name"}], "rationale"} per file. `assign` writes one
122
124
  <review-id>.<axis>.census.md per axis that has cells beside the census and
123
125
  prints each axis's cell count and path (`-` for an axis without cells); an
124
126
  existing assignment is reused only when identical. `prepare` assigns the census,
@@ -171,6 +173,8 @@ def _build_parser() -> argparse.ArgumentParser:
171
173
  parser.add_argument("--rules", default="",
172
174
  help="census: canonical shared review-rules.json provenance")
173
175
  parser.add_argument("--out", default="", help="census: file to write the census to")
176
+ parser.add_argument("--function-inventory", default="",
177
+ help="census: JSON function spans for files whose boundaries it cannot read")
174
178
  parser.add_argument("--policy", action="append", default=[],
175
179
  help="census: additional policy to freeze; scope: captured policy to fingerprint")
176
180
  parser.add_argument("--review-policy", default="", help="scope: shared frozen review policy")
@@ -430,7 +434,7 @@ def main(argv: list[str] | None = None) -> int:
430
434
 
431
435
 
432
436
  def _census(args: argparse.Namespace, project_root: Path) -> int:
433
- from .code_review_census import build_review_census
437
+ from .code_review_census import build_review_census_with_inventory
434
438
  from .code_review_coverage import read_review_census
435
439
  from .review_policy import render_review_rule_catalog, select_review_policy
436
440
 
@@ -450,9 +454,15 @@ def _census(args: argparse.Namespace, project_root: Path) -> int:
450
454
  policy, tuple(changed), project_paths=paths, manifest_contents=manifests,
451
455
  resources=args.resource,
452
456
  )
453
- result = build_review_census(
454
- project_root, args.base, args.head, Path(args.rules),
455
- changed, frozen_rules=render_review_rule_catalog(selected),
457
+ inventory_path = None
458
+ if args.function_inventory:
459
+ inventory_path = Path(args.function_inventory).absolute()
460
+ # The inventory binds commits, so a later commit cannot reuse spans read
461
+ # from an earlier one under the same ref name.
462
+ result, _ = build_review_census_with_inventory(
463
+ project_root, _resolve_base_commit(project_root, args.base),
464
+ _resolve_base_commit(project_root, args.head), Path(args.rules), changed,
465
+ inventory_path, frozen_rules=render_review_rule_catalog(selected),
456
466
  previous=Path(args.previous_census) if args.previous_census else None,
457
467
  )
458
468
  selection = (f"Review policy digest: {digest}\nReview resources: "
@@ -9,20 +9,20 @@ from __future__ import annotations
9
9
  from contextlib import contextmanager
10
10
  from dataclasses import dataclass, field
11
11
  from pathlib import Path
12
- from typing import Any, Iterable, Iterator, Mapping
12
+ from typing import Any, Callable, Iterable, Iterator, Mapping, cast
13
13
 
14
14
  from .agent.invocation import AgentInvocationError, reserved_generation_reference
15
15
  from .conformance import QaResult, execution_evidence_defect, qa_result_from_execution
16
16
  from .execution_identity import ExecutionManifest, Invocation
17
- from .execution_manifest import read_execution_manifest
18
- from .json_boundary import JsonBoundaryError, load_owned_object
17
+ from .execution_manifest import read_execution_manifest, execution_manifest_view_from_payload
18
+ from .json_boundary import ArtifactByteReader, JsonBoundaryError, load_owned_object
19
19
  from .paths import RunRef
20
20
  from .qa_commands import QA_VERIFIER_AUDIENCE_BY_TASK_TYPE
21
21
  from .verification_conformance import conformance_stage
22
22
  from .verification_dispatch import verification_generation_number
23
23
  from .verification_evidence import (
24
24
  VerificationExecutionRecord, conformance_check_owner_ref,
25
- read_verification_execution_record,
25
+ read_verification_execution_snapshot,
26
26
  )
27
27
  from .verification_generation import (
28
28
  VerificationGenerationRecord, read_verification_generation,
@@ -89,6 +89,7 @@ class RunVerifiers:
89
89
  ref: RunRef
90
90
  verifiers: dict[str, list[BoundInvocation]]
91
91
  latest_attempt: dict[str, int]
92
+ execution: ExecutionManifest | None = None
92
93
 
93
94
 
94
95
  @dataclass(frozen=True)
@@ -101,6 +102,7 @@ class CheckRunRecord:
101
102
  record: VerificationExecutionRecord | None
102
103
  output: bytes | None
103
104
  defect: str | None
105
+ raw_bytes: bytes | None = None
104
106
 
105
107
 
106
108
  @contextmanager
@@ -131,18 +133,21 @@ def _collect(
131
133
  })
132
134
 
133
135
 
134
- def load_run_verifiers(project: Path, manifest_path: Path) -> RunVerifiers:
135
- manifest = load_owned_object(manifest_path, artifact="run manifest")
136
+ def load_run_verifiers(project: Path, manifest_path: Path, *, reader: ArtifactByteReader | None = None) -> RunVerifiers:
137
+ manifest = load_owned_object(manifest_path, artifact="run manifest", reader=reader)
136
138
  ref = RunRef.from_manifest(manifest_path, manifest)
137
139
  audience = QA_VERIFIER_AUDIENCE_BY_TASK_TYPE.get(manifest.get("taskType"))
138
140
  if audience is None:
139
141
  raise ValueError("verification evidence requires a QA-executing run")
140
- execution = read_execution_manifest(manifest_path)
142
+ if reader is None:
143
+ execution = read_execution_manifest(manifest_path)
144
+ else:
145
+ execution, _ = execution_manifest_view_from_payload(manifest)
141
146
  latest_attempt = _latest_attempts(execution)
142
147
  return RunVerifiers(
143
148
  manifest, ref,
144
- _bound_verifiers(project, ref, manifest, execution, audience, latest_attempt),
145
- latest_attempt,
149
+ _bound_verifiers(project, ref, manifest, execution, audience, latest_attempt, reader=reader),
150
+ latest_attempt, execution,
146
151
  )
147
152
 
148
153
 
@@ -171,6 +176,7 @@ def _stage_evidence(
171
176
  def _bound_verifiers(
172
177
  project: Path, ref: RunRef, manifest: Mapping[str, Any],
173
178
  execution: ExecutionManifest, audience: str, latest_attempt: Mapping[str, int],
179
+ *, reader: ArtifactByteReader | None = None,
174
180
  ) -> dict[str, list[BoundInvocation]]:
175
181
  verifiers: dict[str, list[BoundInvocation]] = {}
176
182
  for index, invocation in enumerate(execution.invocations):
@@ -178,6 +184,7 @@ def _bound_verifiers(
178
184
  verifiers.setdefault(invocation.role_execution_ref, []).append(_bind(
179
185
  project, ref, manifest, invocation, index,
180
186
  latest_attempt.get(invocation.invocation_ref, 1),
187
+ reader=reader,
181
188
  ))
182
189
  for bindings in verifiers.values():
183
190
  bindings.sort(key=lambda binding: (binding.generation_number, binding.index),
@@ -203,6 +210,7 @@ def _required_stages(verifiers: Mapping[str, list[BoundInvocation]]) -> frozense
203
210
  def _bind(
204
211
  project: Path, ref: RunRef, manifest: Mapping[str, Any], invocation: Invocation,
205
212
  index: int, attempt: int,
213
+ *, reader: ArtifactByteReader | None = None,
206
214
  ) -> BoundInvocation:
207
215
  """The generation the invocation's metadata binds, which must be the one its
208
216
  dispatch kind seals and still have the bytes the metadata recorded."""
@@ -211,6 +219,7 @@ def _bind(
211
219
  relative = path.relative_to(project).as_posix()
212
220
  reference = reserved_generation_reference(
213
221
  project, manifest, invocation.invocation_ref, attempt,
222
+ **({"reader": reader} if reader is not None else {}),
214
223
  )
215
224
  if reference is None:
216
225
  return BoundInvocation(invocation, number, index, None,
@@ -221,7 +230,7 @@ def _bind(
221
230
  f"not to {relative}, the generation its dispatch seals"
222
231
  )
223
232
  try:
224
- generation = read_verification_generation(path, reference.digest)
233
+ generation = read_verification_generation(path, reference.digest, **({"reader": reader} if reader is not None else {}))
225
234
  except ValueError as exc:
226
235
  raise ValueError(
227
236
  f"generation {relative} of invocation {invocation.invocation_ref}: {exc}"
@@ -263,40 +272,54 @@ def bound_attempt(
263
272
  def read_latest_check_run(
264
273
  ref: RunRef, role_execution_ref: str, binding: BoundInvocation, attempt: int,
265
274
  check_ref: str,
275
+ *, reader: ArtifactByteReader | None = None,
276
+ directory_entries: Callable[[Path], Iterable[Path]] | None = None,
266
277
  ) -> CheckRunRecord | None:
267
278
  """The latest run of one check under an attempt of a bound invocation; None
268
279
  when the attempt never ran the check."""
269
280
  invocation_ref = binding.invocation.invocation_ref
270
- check_run = ref.latest_verification_check_run(invocation_ref, attempt, check_ref)
281
+ check_run = ref.latest_verification_check_run(invocation_ref, attempt, check_ref,
282
+ **({"directory_entries": directory_entries} if directory_entries is not None else {}))
271
283
  if check_run is None:
272
284
  return None
273
285
  run_dir = ref.verification_execution_dir(invocation_ref, attempt, check_ref, check_run)
274
- record, output, defect = _read_bound_record(run_dir, {
286
+ record, output, defect, raw = _read_bound_record(run_dir, {
275
287
  "invocationRef": invocation_ref, "roleExecutionRef": role_execution_ref,
276
288
  "attempt": attempt, "checkRef": check_ref, "checkRun": check_run,
277
289
  "verificationGeneration": binding.generation_ref,
278
- })
279
- return CheckRunRecord(check_run, run_dir / "record.json", record, output, defect)
290
+ }, reader=reader)
291
+ return CheckRunRecord(check_run, run_dir / "record.json", record, output, defect, raw)
280
292
 
281
293
 
282
294
  def _read_bound_record(
283
295
  run_dir: Path, expected: Mapping[str, object],
284
- ) -> tuple[VerificationExecutionRecord | None, bytes | None, str | None]:
296
+ *, reader: ArtifactByteReader | None = None,
297
+ ) -> tuple[VerificationExecutionRecord | None, bytes | None, str | None, bytes | None]:
285
298
  """One check run's record, its saved stdout, and why the run is no usable
286
299
  evidence (None when it is); `expected` are the record fields its location
287
300
  and binding determine."""
301
+ raw: bytes | None = None
302
+
303
+ def consumed_record(path: Path) -> bytes:
304
+ nonlocal raw
305
+ body = path.read_bytes() if reader is None else reader(path)
306
+ raw = body
307
+ return body
308
+
288
309
  try:
289
- record = read_verification_execution_record(run_dir / "record.json")
310
+ stored = read_verification_execution_snapshot(run_dir / "record.json", reader=consumed_record)
311
+ record = cast(VerificationExecutionRecord, stored.value)
290
312
  except (JsonBoundaryError, OSError) as exc:
291
- return None, None, f"record is unreadable ({exc})"
313
+ return None, None, f"record is unreadable ({exc})", raw
292
314
  if any(record[name] != value for name, value in expected.items()):
293
315
  return record, None, ("record identity, attempt, check run or generation "
294
- "differs from its location")
316
+ "differs from its location"), raw
295
317
  try:
296
- output = (run_dir / "stdout.log").read_bytes()
318
+ output_path = run_dir / "stdout.log"
319
+ output = output_path.read_bytes() if reader is None else reader(output_path)
297
320
  except OSError as exc:
298
- return record, None, f"saved stdout is unreadable ({exc})"
299
- return record, output, execution_evidence_defect(record, output)
321
+ return record, None, f"saved stdout is unreadable ({exc})", raw
322
+ return record, output, execution_evidence_defect(record, output), raw
300
323
 
301
324
 
302
325
  def _combine(outcomes: list[_VerifierOutcome]) -> StageEvidence:
@@ -83,8 +83,13 @@ def latest_done_by_stage(rows: List[Dict[str, Any]]) -> Dict[int, Dict[str, Any]
83
83
  `started` 를 다시 기록하는 것은 정상 흐름이고(`_equivalent_row_exists`),
84
84
  그동안 의존 stage 는 종전대로 마지막 done head 에서 base 를 잡는다.
85
85
  철회는 리드의 명시적 판정인 `failed` 하나로만 일어난다.
86
+
87
+ Only a later done row supersedes a failed settlement; started never restores
88
+ completion after that withdrawal.
86
89
  """
87
- last = last_lifecycle_status_by_stage(rows)
90
+ last = last_lifecycle_status_by_stage([
91
+ row for row in rows if row.get("status") in _LEAD_SETTLED_STATUSES
92
+ ])
88
93
  out: Dict[int, Dict[str, Any]] = {}
89
94
  for r in rows:
90
95
  if r.get("status") == "done" and isinstance(r.get("stage"), int):
@@ -7,7 +7,6 @@ from pathlib import Path
7
7
  from collections.abc import Mapping
8
8
  from typing import Any, TYPE_CHECKING, TypedDict
9
9
 
10
- from .json_boundary import load_owned_object, write_owned_object_atomic
11
10
  from .qa_procedures import canonical_json_digest
12
11
  from .verification_input_types import FrozenReviewPolicy
13
12
 
@@ -53,7 +52,7 @@ class DesignReviewResult:
53
52
  def capture_design_review(
54
53
  source: Path, base: str, head: str, policy: FrozenReviewPolicy, inventory_path: Path,
55
54
  ) -> DesignReviewSnapshot:
56
- from .code_review_census import build_review_census
55
+ from .code_review_census import build_review_census_with_inventory
57
56
  from .code_review_target import changed_lines
58
57
  from .review_verdicts import parse_review_census
59
58
  from .review_policy import (
@@ -68,12 +67,8 @@ def capture_design_review(
68
67
  selected = select_review_policy(policy, tuple(changed), project_paths=paths,
69
68
  manifest_contents=manifests)
70
69
  rules = render_review_rule_catalog(selected)
71
- initial = build_review_census(source, base, head, catalog_path, changed, frozen_rules=rules)
72
- inventory: dict[str, Any] = {}
73
- if initial.unresolved:
74
- inventory = _read_function_inventory(inventory_path, base, head, initial.unresolved)
75
- result = build_review_census(source, base, head, catalog_path, changed,
76
- frozen_rules=rules, inventory=inventory)
70
+ result, inventory = build_review_census_with_inventory(
71
+ source, base, head, catalog_path, changed, inventory_path, frozen_rules=rules)
77
72
  if result.unresolved:
78
73
  raise ValueError("design review has unresolved function boundaries")
79
74
  parse_review_census(result.text, allow_empty=True)
@@ -83,22 +78,6 @@ def capture_design_review(
83
78
  "blockingTiming": catalog["blockingTiming"]}
84
79
 
85
80
 
86
- def _read_function_inventory(
87
- path: Path, base: str, head: str, unresolved: tuple[str, ...],
88
- ) -> dict[str, Any]:
89
- if not path.exists():
90
- write_owned_object_atomic(path, {"base": base, "head": head,
91
- "files": {name: None for name in unresolved}},
92
- artifact="function inventory")
93
- raise ValueError(f"complete the function inventory before verifier dispatch: {path}")
94
- payload = load_owned_object(path, artifact="function inventory")
95
- if (set(payload) != {"base", "head", "files"} or payload["base"] != base
96
- or payload["head"] != head or not isinstance(payload["files"], dict)
97
- or set(payload["files"]) != set(unresolved)):
98
- raise ValueError(f"function inventory must match this base, head and unresolved files: {path}")
99
- return payload["files"]
100
-
101
-
102
81
  def review_binding_lines(snapshot: DesignReviewSnapshot) -> tuple[str, ...]:
103
82
  return (f"Review base: {snapshot['base']}", f"Review head: {snapshot['head']}",
104
83
  f"Review rules: {snapshot['policyDigest']}",
@@ -137,10 +116,11 @@ def render_design_review(snapshot: DesignReviewSnapshot) -> str:
137
116
  def parse_design_review(
138
117
  source: Path, snapshot: DesignReviewSnapshot, body: str,
139
118
  ) -> DesignReviewResult:
140
- from .review_verdicts import parse_review_census, parse_review_verdicts
119
+ from .review_verdicts import binding_lines, parse_review_census, parse_review_verdicts
141
120
 
121
+ lines = binding_lines(body)
142
122
  for line in review_binding_lines(snapshot):
143
- if body.splitlines().count(line) != 1:
123
+ if lines.count(line) != 1:
144
124
  raise ValueError("design review baseline missing or different: " + line.partition(":")[0])
145
125
  census = parse_review_census(snapshot["census"], allow_empty=True)
146
126
  coverage = parse_review_verdicts(source, census, [body], snapshot["head"], base=snapshot["base"])
@@ -9,19 +9,18 @@ from typing import Any
9
9
  from .agent.invocation import (
10
10
  reserved_generation_reference, reserved_invocation_metadata_path, verify_agent_invocation,
11
11
  )
12
- from .attempt_evidence import AttemptEvidenceSeal, read_sealed_artifact
13
12
  from .conformance_evidence import BoundInvocation, bound_attempt, evidence_read_errors, load_run_verifiers
14
13
  from .design_review import parse_design_review
15
- from .execution_identity import ExecutionManifest, build_dispatch_id
14
+ from .execution_identity import ExecutionManifest
16
15
  from .execution_manifest import read_execution_manifest
17
16
  from .json_boundary import load_owned_object
18
17
  from .qa_procedures import canonical_json_digest, content_digest, safe_qa_path
19
- from .verification_dispatch import verification_generation_number
18
+ from .verification_dispatch import implementation_generation_frontier, read_completed_attempt_result, verification_generation_number
20
19
  from .verification_input_ref import VerificationInputReference
21
20
  from .verification_inputs import read_verification_inputs
22
21
  from .verification_input_types import DESIGN_REVIEW_INPUT_SCHEMA_VERSION
23
22
  from .verification_invocation import VerificationGenerationReference, read_invocation_generation
24
- from .verification_evidence import roster_verifier_role_execution_ref
23
+ from .verification_evidence import implementation_verifier_roster, roster_verifier_role_execution_ref
25
24
 
26
25
 
27
26
  def design_review_required(project: Path, manifest: Mapping[str, Any]) -> bool:
@@ -39,13 +38,8 @@ def collect_design_reviews(project: Path, manifest_path: Path) -> dict[str, dict
39
38
  return {}
40
39
  run = load_run_verifiers(project, manifest_path)
41
40
  execution = read_execution_manifest(manifest_path)
42
- generation = max((verification_generation_number(row.dispatch_kind)
43
- for row in execution.invocations
44
- if row.duty_id in ("implementation-executor", "implementation-verifier")), default=1)
45
- roster = [row["workerId"] for row in manifest.get("workerAssignments", [])
46
- if row.get("role") == "verifier"]
47
- if not roster or len(set(roster)) != len(roster):
48
- raise ValueError("design review requires a distinct verifier roster")
41
+ generation = implementation_generation_frontier(execution) or 1
42
+ roster = implementation_verifier_roster(manifest)
49
43
  reviews = {}
50
44
  for worker in roster:
51
45
  role = roster_verifier_role_execution_ref(manifest, worker)
@@ -165,21 +159,7 @@ def _read_review(
165
159
  def _read_attempt_result(
166
160
  project: Path, execution: ExecutionManifest, invocation_ref: str, attempt: int,
167
161
  ) -> tuple[Path, bytes]:
168
- row = next((row for row in execution.attempts if (row.invocation_ref, row.attempt)
169
- == (invocation_ref, attempt)), None)
170
- if row is None or row.status != "ok" or row.finished_at is None or not row.result_path:
171
- raise ValueError("design review requires the current completed ok attempt")
172
- attempt_ref = build_dispatch_id(invocation_ref, attempt)
173
- seals = [seal for seal in execution.attempt_evidence_seals
174
- if seal.get("sealRef") == row.evidence_seal_ref and seal.get("attemptRef") == attempt_ref]
175
- if len(seals) != 1:
176
- raise ValueError("design review result requires its attempt evidence seal")
177
- path = Path(row.result_path)
178
- relative = path.relative_to(project).as_posix() if path.is_absolute() else path.as_posix()
179
- if not relative.startswith(".okstra/"):
180
- raise ValueError("design review result must remain in project artifacts")
181
- path = safe_qa_path(project, relative)
182
- return path, read_sealed_artifact(AttemptEvidenceSeal.from_payload(seals[0]), path)
162
+ return read_completed_attempt_result(project, execution, invocation_ref, attempt)
183
163
 
184
164
 
185
165
  def _read_carry(body: str, history: list[dict[str, Any]]) -> list[dict[str, str]]:
@@ -1604,7 +1604,7 @@ def _canonical_write_contract(
1604
1604
  capability = execution.binding.worker_write_capability
1605
1605
  if capability is None:
1606
1606
  raise DispatchError("worker write policy has no runner write capability")
1607
- artifacts = _worker_artifact_paths(plan, job)
1607
+ artifacts = _worker_artifact_paths(plan, job, role=execution.role)
1608
1608
  worktree = Path(job.worktree_path) if job.worktree_path else None
1609
1609
  planned = (
1610
1610
  planned_paths_from_run_manifest(plan.project_root, plan.manifest)
@@ -1631,7 +1631,11 @@ def _canonical_write_contract(
1631
1631
  raise DispatchError(f"worker write policy is invalid: {exc}") from exc
1632
1632
 
1633
1633
 
1634
- def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ...]:
1634
+ def _worker_artifact_paths(
1635
+ plan: DispatchPlan, job: WorkerJob, *, role: str | None = None,
1636
+ ) -> tuple[Path, ...]:
1637
+ from .implementation_comparison.run_integration import run_comparison_notes_paths
1638
+
1635
1639
  active_context = _load_optional_json(
1636
1640
  plan.project_root, plan.manifest.get("activeRunContextPath")
1637
1641
  )
@@ -1646,6 +1650,9 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
1646
1650
  # sibling started — landed inside this worker's window as an
1647
1651
  # unauthorized artifact-root change.
1648
1652
  *prompt_derived_paths(job.prompt_path),
1653
+ *run_comparison_notes_paths(
1654
+ plan.project_root, plan.manifest_path, plan.manifest, role=role if role is not None else job.role,
1655
+ ),
1649
1656
  }
1650
1657
  error_logs = active_context.get("errorLogs")
1651
1658
  if isinstance(error_logs, Mapping):
@@ -832,6 +832,8 @@ def _agent_write_contract(
832
832
  prompt_path: Path,
833
833
  assignment_ref: str,
834
834
  ):
835
+ from .implementation_comparison.run_integration import run_comparison_notes_paths
836
+
835
837
  execution_manifest = read_execution_manifest(manifest_path)
836
838
  execution = next(
837
839
  (
@@ -866,6 +868,9 @@ def _agent_write_contract(
866
868
  if execution.role == "implementer"
867
869
  else ((), True)
868
870
  )
871
+ artifacts = (*artifacts, *run_comparison_notes_paths(
872
+ project_root, manifest_path, authority, role=execution.role,
873
+ ))
869
874
  try:
870
875
  return build_invocation_write_contract(
871
876
  role=execution.role,
@@ -55,6 +55,7 @@ DUTY_ROLE_IDS = {
55
55
  "code-reviewer": "verifier",
56
56
  "schedule-verifier": "verifier",
57
57
  "interface-reviewer": "verifier",
58
+ "test-reviewer": "verifier",
58
59
  "business-flow-investigator": "analyser",
59
60
  "report-writer": "report-writer",
60
61
  }
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
  import json
5
5
  import os
6
6
  import tempfile
7
+ from copy import deepcopy
7
8
  from collections.abc import Mapping, MutableMapping, Sequence
8
9
  from dataclasses import replace
9
10
  from functools import lru_cache
@@ -62,6 +63,13 @@ def read_execution_manifest_view(
62
63
  ) -> tuple[ExecutionManifest, Mapping[str, Any]]:
63
64
  """Read one validated manifest snapshot with its enclosing run authority."""
64
65
  surface = read_identity_surface(path, surface="run-manifest")
66
+ return execution_manifest_view_from_payload(surface.payload)
67
+
68
+
69
+ def execution_manifest_view_from_payload(
70
+ payload: Mapping[str, Any],
71
+ ) -> tuple[ExecutionManifest, Mapping[str, Any]]:
72
+ surface = identity_surface_from_payload(deepcopy(payload), surface="run-manifest")
65
73
  if surface.legacy:
66
74
  return synthesize_v1_execution_view(surface.payload), surface.payload
67
75
  hoist_legacy_attempt_write_contract(surface.payload)
@@ -0,0 +1,12 @@
1
+ """Owner-bound implementation comparison preservation and assembly."""
2
+ from .baseline import ComparisonError, ComparisonOwner, capture_baseline, comparison_directory, read_baseline_status
3
+ from .target import capture_target, capture_trace_target, read_target_status
4
+ from .assembly import Assembly, ComparisonSource, assemble_comparison, comparison_fingerprints
5
+ from .publication import publish_comparison, read_comparison_status
6
+
7
+ __all__ = [
8
+ "ComparisonError", "ComparisonOwner", "capture_baseline", "comparison_directory",
9
+ "read_baseline_status", "capture_target", "capture_trace_target", "read_target_status", "Assembly",
10
+ "ComparisonSource", "assemble_comparison", "comparison_fingerprints",
11
+ "publish_comparison", "read_comparison_status",
12
+ ]