okstra 0.234.1 → 0.236.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 (171) 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/host-registry-client.d.mts +9 -2
  25. package/dist/lib/host-registry-client.mjs +29 -3
  26. package/dist/lib/host-registry-client.mjs.map +1 -1
  27. package/dist/lib/python-helper.d.mts +1 -1
  28. package/dist/lib/python-helper.mjs +11 -5
  29. package/dist/lib/python-helper.mjs.map +1 -1
  30. package/dist/lib/runtime-payload.mjs +1 -0
  31. package/dist/lib/runtime-payload.mjs.map +1 -1
  32. package/dist/lib/types.d.mts +1 -0
  33. package/docs/architecture/storage-model.md +50 -0
  34. package/docs/architecture.md +1 -1
  35. package/docs/cli.md +37 -15
  36. package/docs/project-structure-overview.md +6 -1
  37. package/package.json +1 -1
  38. package/runtime/BUILD.json +2 -2
  39. package/runtime/agents/operations/trace-tests-review.json +6 -0
  40. package/runtime/bin/lib/okstra/usage.sh +8 -8
  41. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  42. package/runtime/prompts/duties/test-reviewer.json +32 -0
  43. package/runtime/prompts/lead/convergence.md +4 -1
  44. package/runtime/prompts/lead/okstra-lead-contract.md +3 -3
  45. package/runtime/prompts/lead/report-writer.md +13 -1
  46. package/runtime/prompts/profiles/_common-contract.md +10 -1
  47. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  48. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  49. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  50. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  51. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  52. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  53. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  54. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  55. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  56. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  57. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  58. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  59. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  60. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  61. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  62. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  63. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  64. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  65. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  66. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  67. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  68. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  69. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  70. package/runtime/python/okstra_ctl/consumers.py +6 -1
  71. package/runtime/python/okstra_ctl/convergence.py +95 -5
  72. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  73. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  74. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  75. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  76. package/runtime/python/okstra_ctl/design_review.py +6 -26
  77. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  78. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  79. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  80. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  81. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  82. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  83. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  84. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  85. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  86. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  87. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  88. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  89. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  90. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  91. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  92. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  93. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  94. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  95. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  96. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  97. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  98. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  99. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  100. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  101. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  102. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  103. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  104. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  105. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  106. package/runtime/python/okstra_ctl/models.py +2 -2
  107. package/runtime/python/okstra_ctl/paths.py +7 -4
  108. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  109. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  110. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  111. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  112. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  113. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  114. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  115. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  116. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  117. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  118. package/runtime/python/okstra_ctl/render.py +4 -0
  119. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  120. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  121. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  122. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  123. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  124. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  125. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  126. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  127. package/runtime/python/okstra_ctl/run.py +17 -1
  128. package/runtime/python/okstra_ctl/run_context.py +18 -3
  129. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  130. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  131. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  132. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  133. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  134. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  135. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  136. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  137. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  138. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  139. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  140. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  141. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  142. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  143. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  144. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  145. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  146. package/runtime/python/okstra_ctl/wizard/state.py +67 -20
  147. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  148. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  149. package/runtime/python/okstra_ctl/worker_audit_ledger.py +44 -8
  150. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  151. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  152. package/runtime/python/okstra_token_usage/claude.py +5 -1
  153. package/runtime/python/okstra_token_usage/collect.py +3 -3
  154. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  155. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  156. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  157. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  158. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  159. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  160. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  161. package/runtime/skills/okstra-run/SKILL.md +33 -2
  162. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  163. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  164. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  165. package/runtime/templates/reports/html/i18n/en.json +113 -0
  166. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  167. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  168. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  169. package/runtime/templates/trace/trace.template.md +2 -0
  170. package/runtime/templates/worker-prompt-preamble.md +12 -2
  171. package/runtime/validators/validate-report-views.py +4 -36
@@ -22,13 +22,18 @@ from .convergence_provenance import id_occurs_wordbounded
22
22
  from .json_boundary import JsonBoundaryError, load_owned_object
23
23
  from .phases.improvement_discovery.lenses import LENSES, validate_priority_lenses
24
24
  from .scope_provenance import brief_end_state_id_sequence
25
+ from .worker_audit_ledger import named_files, recorded_as_opened
25
26
 
26
27
 
27
28
  CENSUS_SCHEMA_VERSION = "1.0"
29
+ RECORDS_EVIDENCE = "records"
28
30
  CENSUS_ASPECTS_LINE = "- Census aspects:"
29
31
  SCOPES = ("requirement", "task", "file", "lens")
32
+ # `[records]` marks an aspect that okstra's own records (brief, plan, other task
33
+ # records) may settle, so a `clean` citing only them is accepted.
30
34
  _ASPECT_RE = re.compile(
31
- r"^ - (?P<scope>[a-z]+) (?P<slug>[a-z0-9]+(?:-[a-z0-9]+)*):\s*(?P<question>\S.*)$"
35
+ r"^ - (?P<scope>[a-z]+) (?P<slug>[a-z0-9]+(?:-[a-z0-9]+)*)(?P<records> \[records\])?:"
36
+ r"\s*(?P<question>\S.*)$"
32
37
  )
33
38
 
34
39
 
@@ -41,6 +46,7 @@ class Aspect:
41
46
  scope: str
42
47
  slug: str
43
48
  question: str
49
+ records: bool = False
44
50
 
45
51
 
46
52
  def parse_census_aspects(profile_text: str) -> tuple[Aspect, ...]:
@@ -72,7 +78,10 @@ def parse_census_aspects(profile_text: str) -> tuple[Aspect, ...]:
72
78
  raise CensusError(
73
79
  f"census aspect scope {scope!r} is not one of {', '.join(SCOPES)}"
74
80
  )
75
- aspects.append(Aspect(scope, match.group("slug"), match.group("question").strip()))
81
+ aspects.append(Aspect(
82
+ scope, match.group("slug"), match.group("question").strip(),
83
+ records=match.group("records") is not None,
84
+ ))
76
85
  keys = [(aspect.scope, aspect.slug) for aspect in aspects]
77
86
  if len(keys) != len(set(keys)):
78
87
  raise CensusError("census aspects repeat a scope and slug pair")
@@ -101,6 +110,7 @@ def build_census(
101
110
  "aspect": aspect.slug,
102
111
  "subject": subject,
103
112
  "question": aspect.question,
113
+ **({"evidence": RECORDS_EVIDENCE} if aspect.records else {}),
104
114
  })
105
115
 
106
116
  by_scope = {
@@ -200,9 +210,13 @@ def render_census_section(census: Mapping[str, Any], census_rel_path: str) -> st
200
210
  "|---|---|---|---|",
201
211
  ]
202
212
  for cell in cells:
213
+ settled_by_records = (
214
+ " The brief or okstra records may settle it."
215
+ if cell.get("evidence") == RECORDS_EVIDENCE else ""
216
+ )
203
217
  rows.append(
204
218
  f"| `{cell['id']}` | {cell['scope']} | `{_cell_text(str(cell['subject']))}` "
205
- f"| {_cell_text(str(cell['question']))} |"
219
+ f"| {_cell_text(str(cell['question']) + settled_by_records)} |"
206
220
  )
207
221
  return "\n".join(rows)
208
222
 
@@ -265,12 +279,41 @@ def split_coverage_verdict_section(text: str) -> tuple[list[str], str]:
265
279
  return lines[start + 1:end], "\n".join(lines[:start] + lines[end:])
266
280
 
267
281
 
268
- def _judge(kind: str, rest: str, body_texts: Sequence[str]) -> tuple[str, str] | str:
269
- """``(kind, detail)`` for a usable verdict, otherwise why it is unusable."""
282
+ # Stage worktrees live under `~/.okstra/worktrees/`, so source cited by its
283
+ # absolute worktree path is not an okstra input.
284
+ _OKSTRA_INPUT_RE = re.compile(r"(?:^|/)\.okstra/(?!worktrees/)")
285
+
286
+
287
+ def _okstra_input(path: str) -> bool:
288
+ """One of okstra's own inputs: they pose the cell's question, they cannot clear it."""
289
+ return _OKSTRA_INPUT_RE.search(path) is not None
290
+
291
+
292
+ def _judge(
293
+ kind: str, rest: str, body_texts: Sequence[str], opened: frozenset[str] | None = None,
294
+ accepts_records: bool = False,
295
+ ) -> tuple[str, str] | str:
296
+ """``(kind, detail)`` for a usable verdict, otherwise why it is unusable.
297
+
298
+ ``opened`` holds the worker's recorded Evidence read paths; ``None`` means
299
+ the worker kept no ledger, so a clean is not checked against one.
300
+ """
270
301
  detail = rest.strip().lstrip(_SEPARATORS).strip()
271
302
  if kind == "clean":
272
303
  if not _CITATION_RE.search(detail):
273
304
  return "clean without a path:line citation"
305
+ sources = [path for path in named_files(detail) if not _okstra_input(path)]
306
+ if not sources and not accepts_records:
307
+ return "clean cites only .okstra/ artifacts, not the source it judges"
308
+ unopened = [
309
+ path for path in sources
310
+ if opened is not None and not recorded_as_opened(path, opened)
311
+ ]
312
+ if unopened:
313
+ return (
314
+ f"clean rests on `{unopened[0]}`, which the audit sidecar does not "
315
+ "record as opened"
316
+ )
274
317
  return kind, detail
275
318
  if kind == "n/a":
276
319
  if not detail:
@@ -290,12 +333,16 @@ def parse_cell_verdicts(
290
333
  cell_ids: Sequence[str],
291
334
  *,
292
335
  reference_texts: Sequence[str] = (),
336
+ opened: frozenset[str] | None = None,
337
+ record_cells: frozenset[str] = frozenset(),
293
338
  ) -> CellVerdicts:
294
339
  """Read a result's `Coverage Verdicts` section against ``cell_ids``.
295
340
 
296
341
  ``reference_texts`` are other results a `finding` may point into: a
297
342
  gap-fill result can cite an item its worker's first result already raised.
298
- The first usable line for a cell wins.
343
+ ``opened`` is the worker's Evidence read ledger, which a `clean` citation
344
+ must appear in. ``record_cells`` are cells whose `clean` may cite okstra
345
+ records alone. The first usable line for a cell wins.
299
346
  """
300
347
  section, body = split_coverage_verdict_section(result_text)
301
348
  wanted = list(dict.fromkeys(cell_ids))
@@ -315,7 +362,8 @@ def parse_cell_verdicts(
315
362
  if cell in verdicts:
316
363
  continue
317
364
  judged = _judge(
318
- match.group("kind").lower(), match.group("rest"), (body, *reference_texts)
365
+ match.group("kind").lower(), match.group("rest"), (body, *reference_texts), opened,
366
+ cell in record_cells,
319
367
  )
320
368
  if isinstance(judged, tuple):
321
369
  verdicts[cell] = judged
@@ -342,21 +390,33 @@ def audit_census(
342
390
  census: Mapping[str, Any],
343
391
  results: Mapping[str, str | None],
344
392
  gapfills: Mapping[str, str | None] | None = None,
393
+ opened: Mapping[str, frozenset[str] | None] | None = None,
394
+ gapfill_opened: Mapping[str, frozenset[str] | None] | None = None,
345
395
  ) -> dict[str, Any]:
346
396
  """Per-worker coverage of ``census``, the cell x worker matrix, and the
347
397
  cells two workers judged in opposite directions.
348
398
 
349
399
  ``results`` maps each analysis worker to its result text (``None``: the
350
400
  file is missing). ``gapfills`` does the same for the one gap-fill dispatch;
351
- a worker absent from it was not sent one. Whatever stays unjudged after
352
- both is ``unverdicted`` — recorded, never raised.
401
+ a worker absent from it was not sent one. ``opened`` and ``gapfill_opened``
402
+ map a worker to the Evidence read ledger of that result (``None`` or absent:
403
+ no ledger, no check). Whatever stays unjudged after both is ``unverdicted``
404
+ — recorded, never raised.
353
405
  """
354
406
  gapfills = gapfills or {}
407
+ opened = opened or {}
408
+ gapfill_opened = gapfill_opened or {}
355
409
  cell_ids = [str(cell["id"]) for cell in census.get("cells") or []]
410
+ record_cells = frozenset(
411
+ str(cell["id"]) for cell in census.get("cells") or []
412
+ if cell.get("evidence") == RECORDS_EVIDENCE
413
+ )
356
414
  workers: list[dict[str, Any]] = []
357
415
  judged: dict[str, dict[str, tuple[str, str]]] = {}
358
416
  for worker, text in results.items():
359
- first = parse_cell_verdicts(text or "", cell_ids)
417
+ first = parse_cell_verdicts(
418
+ text or "", cell_ids, opened=opened.get(worker), record_cells=record_cells,
419
+ )
360
420
  verdicts = dict(first.verdicts)
361
421
  missing = dict(first.missing)
362
422
  if text is None:
@@ -367,7 +427,8 @@ def audit_census(
367
427
  gapfill_status = "missing" if gapfill_text is None else "read"
368
428
  if gapfill_text is not None and missing:
369
429
  second = parse_cell_verdicts(
370
- gapfill_text, list(missing), reference_texts=(text or "",)
430
+ gapfill_text, list(missing), reference_texts=(text or "",),
431
+ opened=gapfill_opened.get(worker), record_cells=record_cells,
371
432
  )
372
433
  verdicts.update(second.verdicts)
373
434
  missing = {
@@ -446,7 +507,9 @@ requires, and only these two sections:
446
507
  evidence. Write `- none` when there is none. A `finding` may also cite an
447
508
  item ID from your first result.
448
509
  - `## 6. Coverage Verdicts` — one line per cell listed below, in the
449
- preamble's form: `clean — <path:line>`, `finding <ID>`, or `n/a — <reason>`.
510
+ preamble's form: `clean — <path:line>` citing project source (the brief or
511
+ okstra records only where the cell says they may settle it), `finding <ID>`,
512
+ or `n/a — <reason>`.
450
513
 
451
514
  Do not judge cells that are not listed, and do not repeat your first result.
452
515
  """.strip()
@@ -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
  }
@@ -233,7 +233,7 @@ def _probe_paths(project_root: str, home_dir: str):
233
233
 
234
234
  def _unclaimed_host_message(registry: HostAdapterRegistry, command: str) -> str:
235
235
  runtime_flag = "--runtime" if command in {
236
- "install", "ensure-installed", "doctor"
236
+ "install", "ensure-installed", "doctor", "preflight"
237
237
  } else "--lead-runtime"
238
238
  allowed = "|".join(registry.ids())
239
239
  return (
@@ -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
+ ]
@@ -0,0 +1,129 @@
1
+ """Bounded JSON bridge for preserved implementation comparisons."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import json
6
+ from pathlib import Path
7
+ import re
8
+ import sys
9
+ from typing import Any
10
+
11
+ from ..json_boundary import PageBudgetExhausted, ReadBudget
12
+ from .model import MAX_COMPARISON_INPUT_BYTES, MAX_COMPARISON_READ_BYTES
13
+ from .baseline import (
14
+ MAX_BASELINE_RESPONSE_BYTES, MAX_OWNER_BYTES, ComparisonError,
15
+ _owner_and_directory, capture_baseline, read_baseline_status,
16
+ )
17
+ from .inputs import _validate_source, resolve_run_comparison, resolve_task_comparison
18
+ from .target import capture_target, capture_trace_target, read_target_status
19
+
20
+
21
+ def _read_source() -> dict[str, Any]:
22
+ raw = sys.stdin.buffer.read(MAX_COMPARISON_INPUT_BYTES + 1)
23
+ if len(raw) > MAX_COMPARISON_INPUT_BYTES:
24
+ raise ComparisonError("Comparison source stdin exceeds its byte limit")
25
+ source = json.loads(raw)
26
+ if not isinstance(source, dict):
27
+ raise ComparisonError("Comparison source stdin must be a JSON object")
28
+ return source
29
+
30
+
31
+ def _comparison_status(root: Path, directory: Path | None, owner: dict[str, Any]) -> dict[str, Any]:
32
+ from .publication import read_comparison_status
33
+
34
+ result = read_baseline_status(root, directory, owner)
35
+ try:
36
+ result["target"] = read_target_status(root, directory, owner)
37
+ except (OSError, ValueError) as exc:
38
+ result["target"] = {"status": "unavailable", "targetRef": None, "generation": None, "limitations": [str(exc)]}
39
+ try:
40
+ result["report"] = read_comparison_status(root, directory, owner)
41
+ except (OSError, ValueError) as exc:
42
+ result["report"] = {"status": "failed", "reportStatus": None, "dataPath": None, "htmlPath": None, "warnings": [str(exc)]}
43
+ return result
44
+
45
+
46
+ def _write_response(result: dict[str, Any]) -> None:
47
+ summaries = [result, *(result[key] for key in ("target", "report") if isinstance(result.get(key), dict))]
48
+ while len(json.dumps(result, ensure_ascii=True).encode()) + 1 > MAX_BASELINE_RESPONSE_BYTES:
49
+ for value in summaries:
50
+ field = next((key for key in ("limitations", "warnings") if value.get(key)), None)
51
+ if field:
52
+ value[field].pop()
53
+ value[field + "Omitted"] = True
54
+ break
55
+ else:
56
+ raise ComparisonError("Comparison response metadata exceeds its byte limit")
57
+ print(json.dumps(result, ensure_ascii=True))
58
+
59
+
60
+ def main(argv: list[str] | None = None) -> int:
61
+ parser = argparse.ArgumentParser()
62
+ parser.add_argument("action", choices=("capture", "capture-target", "status", "render"))
63
+ parser.add_argument("--project-root", type=Path)
64
+ parser.add_argument("--source-root", type=Path)
65
+ parser.add_argument("--comparison-dir", type=Path)
66
+ original = parser.add_mutually_exclusive_group(required=True)
67
+ original.add_argument("--owner-json")
68
+ original.add_argument("--run-manifest", type=Path)
69
+ parser.add_argument("--baseline-ref", default="")
70
+ parser.add_argument("--generation")
71
+ parser.add_argument("--scope", choices=("task",))
72
+ args = parser.parse_args(argv)
73
+ try:
74
+ if args.scope and (args.run_manifest is None or args.action not in {"render", "status"}):
75
+ raise ComparisonError("--scope task requires a stored --run-manifest render/status")
76
+ if args.run_manifest is not None:
77
+ if args.action not in {"render", "status"} or args.comparison_dir is not None:
78
+ raise ComparisonError("--run-manifest supports only stored render/status without --comparison-dir")
79
+ if args.project_root is None:
80
+ from okstra_project.resolver import ResolverError, resolve_project_root
81
+
82
+ try:
83
+ args.project_root = resolve_project_root(cwd=str(args.run_manifest.absolute().parent))
84
+ except ResolverError as exc:
85
+ raise ComparisonError(str(exc)) from exc
86
+ resolve_scope = resolve_task_comparison if args.scope == "task" else resolve_run_comparison
87
+ owner, args.comparison_dir = resolve_scope(args.project_root, args.run_manifest)
88
+ else:
89
+ if args.project_root is None:
90
+ raise ComparisonError("Comparison requires --project-root")
91
+ if len(args.owner_json.encode()) > MAX_OWNER_BYTES:
92
+ raise ComparisonError("Comparison owner exceeds its byte limit")
93
+ owner = json.loads(args.owner_json)
94
+ root, directory, owner = _owner_and_directory(args.project_root, args.comparison_dir, owner)
95
+ if args.action == "capture":
96
+ if args.source_root is None:
97
+ raise ComparisonError("Capture requires --source-root")
98
+ result = capture_baseline(root, args.source_root, directory,
99
+ owner, baseline_ref=args.baseline_ref)
100
+ elif args.action == "capture-target":
101
+ if args.source_root is None or not args.generation or re.fullmatch(r"[a-f0-9]{64}", args.generation) is None:
102
+ raise ComparisonError("Target capture requires --source-root and a 64-hex --generation")
103
+ source = _read_source()
104
+ if owner["kind"] == "trace":
105
+ capture_trace_target(root, args.source_root, directory, owner, source, generation=args.generation)
106
+ else:
107
+ if not _validate_source(root, owner, source, {}, ReadBudget(MAX_COMPARISON_READ_BYTES)):
108
+ raise ComparisonError("Comparison source no longer matches its saved original")
109
+ capture_target(root, args.source_root, directory, owner, generation=args.generation)
110
+ result = _comparison_status(root, directory, owner)
111
+ elif args.action == "render":
112
+ from .publication import publish_comparison
113
+
114
+ source = None if owner["kind"] in {"run", "task"} else _read_source()
115
+ try:
116
+ result = publish_comparison(root, directory, owner, source)
117
+ except (OSError, ValueError, PageBudgetExhausted) as exc:
118
+ result = {"status": "failed", "reportStatus": None, "dataPath": None, "htmlPath": None, "warnings": [str(exc)]}
119
+ else:
120
+ result = _comparison_status(root, directory, owner)
121
+ _write_response(result)
122
+ return 0
123
+ except (OSError, ValueError, PageBudgetExhausted) as exc:
124
+ print(str(exc), file=sys.stderr)
125
+ return 1
126
+
127
+
128
+ if __name__ == "__main__":
129
+ raise SystemExit(main())