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
@@ -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):
@@ -1592,6 +1592,61 @@ def _recorded_results(
1592
1592
  return result_args
1593
1593
 
1594
1594
 
1595
+ # Verdicts that accept the cited evidence. `_grounded_vote` also checks a
1596
+ # burden-not-met refusal, which re-inspected it; counter-evidence stands on what
1597
+ # the verifier found instead.
1598
+ _GROUNDED_VERDICTS = ("agree", "supplement")
1599
+
1600
+
1601
+ def _origin_evidence_paths(plan_path: Path) -> dict[str, frozenset[str]]:
1602
+ """Each queued finding's cited files, from the working state beside the round plan.
1603
+
1604
+ ``plan-round`` writes `convergence-round-<N>-plan-<suffix>.json` next to the
1605
+ `convergence-work-<suffix>.json` it planned from. A plan named otherwise has
1606
+ no working state to read, and its votes are collected as given.
1607
+ """
1608
+ match = re.fullmatch(r"convergence-round-\d+-plan-(?P<suffix>.+)\.json", Path(plan_path).name)
1609
+ path = Path(plan_path).with_name(f"convergence-work-{match['suffix']}.json") if match else None
1610
+ if path is None or not path.is_file():
1611
+ return {}
1612
+ from .worker_audit_ledger import named_files
1613
+
1614
+ findings = load_owned_json_object(path).get("findings") or []
1615
+ return {
1616
+ str(row["findingId"]): frozenset(named_files(str(row.get("originEvidence") or "")))
1617
+ for row in findings if isinstance(row, Mapping) and row.get("findingId")
1618
+ }
1619
+
1620
+
1621
+ def _grounded_vote(vote: FindingVote, origin: frozenset[str] | None) -> dict[str, Any]:
1622
+ """The vote as collected; one that opened none of the cited files counts as unverifiable.
1623
+
1624
+ Evidence that names no file (a query result, prose) leaves nothing to compare,
1625
+ so such a vote is collected as given.
1626
+ """
1627
+ from .worker_audit_ledger import recorded_as_opened
1628
+
1629
+ row = {
1630
+ "verdict": vote.verdict,
1631
+ "disagreeBasis": vote.disagree_basis,
1632
+ "explanation": vote.explanation,
1633
+ }
1634
+ leans_on_origin = vote.verdict in _GROUNDED_VERDICTS or vote.disagree_basis == "burden-not-met"
1635
+ if not origin or not leans_on_origin:
1636
+ return row
1637
+ if any(recorded_as_opened(cited, frozenset(vote.opened)) for cited in origin):
1638
+ return row
1639
+ return {
1640
+ "verdict": "unverifiable",
1641
+ "disagreeBasis": None,
1642
+ "explanation": (
1643
+ "Collected as unverifiable: the Opened line names none of the cited files ("
1644
+ + ", ".join(sorted(origin)) + "). " + vote.explanation
1645
+ ),
1646
+ }
1647
+
1648
+
1649
+
1595
1650
  def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
1596
1651
  plan = load_owned_json_object(args.plan)
1597
1652
  planned = _planned_finding_ids(plan)
@@ -1624,14 +1679,13 @@ def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
1624
1679
  "close their attempt as ok — a discarded or failed attempt's file is not "
1625
1680
  "a vote"
1626
1681
  )
1682
+ origins = _origin_evidence_paths(args.plan)
1627
1683
  by_finding: dict[str, dict[str, Any]] = {}
1628
1684
  for worker, parsed in votes.items():
1629
1685
  for finding_id, vote in parsed.items():
1630
- by_finding.setdefault(finding_id, {})[worker] = {
1631
- "verdict": vote.verdict,
1632
- "disagreeBasis": vote.disagree_basis,
1633
- "explanation": vote.explanation,
1634
- }
1686
+ by_finding.setdefault(finding_id, {})[worker] = _grounded_vote(
1687
+ vote, origins.get(finding_id),
1688
+ )
1635
1689
  write_json_atomic(args.output, {
1636
1690
  "schemaVersion": "1.0",
1637
1691
  "round": plan.get("round"),
@@ -2123,6 +2177,36 @@ def _read_if_present(path: Path) -> str | None:
2123
2177
  return path.read_text(encoding="utf-8") if path.is_file() else None
2124
2178
 
2125
2179
 
2180
+ def _evidence_ledger(result_path: Path) -> frozenset[str] | None:
2181
+ """The Evidence read paths of a result's audit sidecar.
2182
+
2183
+ ``None`` when the result's prompt asked for no ledger — the rule
2184
+ validate-run applies — so a result of such a prompt is not checked. A prompt
2185
+ that asked for one and a sidecar without rows give an empty ledger.
2186
+ """
2187
+ from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
2188
+ from .worker_audit_ledger import audit_evidence_read_paths, ledger_required
2189
+
2190
+ prefix, separator, rest = result_path.name.partition("-worker-")
2191
+ prompt = result_path.parent.parent / "prompts" / f"{prefix}-worker-prompt-{rest}"
2192
+ if not separator or not ledger_required(prompt):
2193
+ return None
2194
+ try:
2195
+ sidecar = result_path.with_name(audit_sidecar_rel(result_path.name))
2196
+ except WorkerArtifactPathError:
2197
+ return None
2198
+ return frozenset(audit_evidence_read_paths(_read_if_present(sidecar) or ""))
2199
+
2200
+
2201
+ def _joined_ledger(
2202
+ first: frozenset[str] | None, gapfill: frozenset[str] | None,
2203
+ ) -> frozenset[str] | None:
2204
+ """A gap-fill without its own ledger is not checked: it may cite files it opened anew."""
2205
+ if gapfill is None:
2206
+ return None
2207
+ return gapfill | (first or frozenset())
2208
+
2209
+
2126
2210
  def _census_audit(args: argparse.Namespace) -> dict[str, Any]:
2127
2211
  """Audit the census verdicts. Unjudged cells are data, never an error."""
2128
2212
  authority = validated_run_authority(args.run_manifest)
@@ -2141,10 +2225,16 @@ def _census_audit(args: argparse.Namespace) -> dict[str, Any]:
2141
2225
  raise ConvergenceContractError(
2142
2226
  f"--gapfill names {unrostered}, which no --result names"
2143
2227
  )
2228
+ first_ledgers = {worker: _evidence_ledger(path) for worker, path in result_paths.items()}
2144
2229
  audit = audit_census(
2145
2230
  census,
2146
2231
  {worker: _read_if_present(path) for worker, path in result_paths.items()},
2147
2232
  {worker: _read_if_present(path) for worker, path in gapfill_paths.items()},
2233
+ opened=first_ledgers,
2234
+ gapfill_opened={
2235
+ worker: _joined_ledger(first_ledgers.get(worker), _evidence_ledger(path))
2236
+ for worker, path in gapfill_paths.items()
2237
+ },
2148
2238
  )
2149
2239
  for row in audit["workers"]:
2150
2240
  row["resultPath"] = relative_to_project_root(
@@ -9,7 +9,7 @@
9
9
 
10
10
  이 모듈이 그 지시문을 만든다. 입력은 리드가 `apply-critic-gaps` 에 줄 것과 같은
11
11
  coverage 배치(투표 전, `gaps[]` 만 채운 상태)와 Round 0 그룹(분석 로스터)이다.
12
- 배정은 엔진과 같은 규칙(`critic_gap_assignees`, 로스터 순서 round-robin)이라
12
+ 배정은 엔진과 같은 규칙(`critic_gap_assignees`: all analysers up to two, otherwise round-robin)이라
13
13
  `apply-critic-gaps` 의 커버리지 검사와 어긋나지 않는다. gap 마다 critic 결과
14
14
  파일의 `### [<gapId>]` 절과 critic 감사 사이드카를 실어, 검증자가 리드의 전사가
15
15
  아니라 critic 이 실제로 인용한 것을 판단하게 한다. 응답 형식은 번호 라운드와
@@ -131,10 +131,11 @@ def critic_verify_gaps(
131
131
  ) -> list[CriticGap]:
132
132
  """이 워커에게 배정된 gap 을 배치 순서대로.
133
133
 
134
- 배정은 `critic_gap_assignees` 와 같다: 선언된 중복을 뺀 gap *i* 가
135
- `roster[i % len(roster)]` 에게 간다. 로스터는 Round 0 그룹의 분석 audience
136
- 워커 순서다 — `apply-critic-gaps` 가 `analyserRoster` 로 적는 것과 같은
137
- 순서다.
134
+ The assignment is `critic_gap_assignees`: every analyser verifies every gap
135
+ on a roster of `FULL_GAP_VERIFICATION_ROSTER` or fewer, otherwise gap *i*
136
+ goes to `roster[i % len(roster)]`. The roster is the Round 0 groups'
137
+ analysis workers in order, the order `apply-critic-gaps` records as
138
+ `analyserRoster`.
138
139
  """
139
140
  gaps_value = batch.get("gaps")
140
141
  if not isinstance(gaps_value, list) or not gaps_value:
@@ -153,17 +154,17 @@ def critic_verify_gaps(
153
154
  gap for gap in gaps_value
154
155
  if isinstance(gap, Mapping) and not gap.get("duplicateOf")
155
156
  ]
156
- assignees = critic_gap_assignees(roster, verifiable)
157
+ verifiers_by_gap = critic_gap_assignees(roster, verifiable)
157
158
  assigned: list[CriticGap] = []
158
159
  seen: set[str] = set()
159
- for gap, assignee in zip(verifiable, assignees):
160
+ for gap, verifiers in zip(verifiable, verifiers_by_gap):
160
161
  gap_id = _nonempty_string(gap.get("gapId"))
161
162
  if not gap_id:
162
163
  raise CriticVerifyPromptError("coverage batch gap has no gapId")
163
164
  if gap_id in seen:
164
165
  raise CriticVerifyPromptError(f"duplicate critic gapId: {gap_id}")
165
166
  seen.add(gap_id)
166
- if assignee != worker_id:
167
+ if worker_id not in verifiers:
167
168
  continue
168
169
  ticket_ids = gap.get("ticketIds")
169
170
  assigned.append(CriticGap(
@@ -177,8 +178,8 @@ def critic_verify_gaps(
177
178
  ))
178
179
  if not assigned:
179
180
  raise CriticVerifyPromptError(
180
- f"round-robin assigns no gap to `{worker_id}`; assignees in batch "
181
- f"order: {', '.join(assignees) or 'none'}"
181
+ f"no gap is assigned to `{worker_id}`; verifiers in batch order: "
182
+ + (", ".join("+".join(verifiers) for verifiers in verifiers_by_gap) or "none")
182
183
  )
183
184
  return assigned
184
185
 
@@ -1136,26 +1136,34 @@ def _parse_critic_dispatches(
1136
1136
  return dispatches, completed
1137
1137
 
1138
1138
 
1139
+ # With this many analysers or fewer, every gap goes to all of them: one
1140
+ # verifier per gap lets a single shallow pass decide what merges into the report.
1141
+ FULL_GAP_VERIFICATION_ROSTER = 2
1142
+
1143
+
1139
1144
  def critic_gap_assignees(
1140
1145
  roster_order: list[str],
1141
1146
  gaps: list[Mapping[str, Any]],
1142
- ) -> list[str]:
1143
- """gap 하나당 검증자 한 명. 로스터 순서 위의 round-robin 이다.
1147
+ ) -> list[tuple[str, ...]]:
1148
+ """The verifiers of each gap, in batch order.
1144
1149
 
1145
- 종전 계약은 gap 배치를 분석자 전원에게 부치라고 요구했다. 거부도 승인과 같은
1146
- 값을 치르는데, 그 라운드는 `rounds: []` 로 기록조차 남지 않는 직렬 구간이다.
1147
- gap 마다 검증자 하나면 gap 이 로스터보다 적을 때 디스패치 수가 그만큼 줄고,
1148
- 많을 때는 각 분석자가 전체가 아니라 자기 몫만 읽는다.
1150
+ A roster of `FULL_GAP_VERIFICATION_ROSTER` or fewer verifies every gap in
1151
+ full. A larger roster is walked round-robin, one verifier per gap: a
1152
+ rejection costs the same as an acceptance in a stretch recorded as
1153
+ `rounds: []`, so each analyser reads only its share.
1149
1154
 
1150
- 선언한 중복(`duplicateOf`)은 배정에서 빠진다 — 검증하지 않기로 한 gap 이다.
1155
+ Declared duplicates (`duplicateOf`) are not assigned; they are not verified.
1151
1156
  """
1152
1157
  verifiable = [gap for gap in gaps if not gap.get("duplicateOf")]
1153
1158
  if not roster_order:
1154
1159
  return []
1155
- return [
1156
- roster_order[index % len(roster_order)]
1157
- for index in range(len(verifiable))
1158
- ]
1160
+ if len(roster_order) <= FULL_GAP_VERIFICATION_ROSTER:
1161
+ return [tuple(roster_order) for _ in verifiable]
1162
+ return [(worker,) for worker in _round_robin_assignees(roster_order, len(verifiable))]
1163
+
1164
+
1165
+ def _round_robin_assignees(roster_order: list[str], count: int) -> list[str]:
1166
+ return [roster_order[index % len(roster_order)] for index in range(count)]
1159
1167
 
1160
1168
 
1161
1169
  def _critic_gap_coverage_errors(
@@ -1174,13 +1182,20 @@ def _critic_gap_coverage_errors(
1174
1182
  계약 위반이 아니라 더 본 것이고, 그 사이 방치된 gap 은 표가 없어
1175
1183
  `unverifiedGaps` 로 스스로 드러난다.
1176
1184
  """
1177
- assignees = set(critic_gap_assignees(roster_order, gaps))
1178
- if dispatched == set(roster_order) or dispatched == assignees:
1185
+ assignees = {
1186
+ worker for verifiers in critic_gap_assignees(roster_order, gaps) for worker in verifiers
1187
+ }
1188
+ # A run finished under the earlier one-verifier rule dispatched the round-robin set.
1189
+ earlier = set(_round_robin_assignees(
1190
+ roster_order, len([gap for gap in gaps if not gap.get("duplicateOf")]),
1191
+ )) if roster_order else set()
1192
+ if dispatched in (set(roster_order), assignees, earlier):
1179
1193
  return []
1180
1194
  missing = sorted(assignees - dispatched)
1181
1195
  return [
1182
- "critic dispatches must cover every gap exactly once (round-robin over "
1183
- "the analyser roster) or account for every non-critic analyser exactly "
1196
+ "critic dispatches must cover every gap's assigned verifiers (all analysers "
1197
+ f"up to {FULL_GAP_VERIFICATION_ROSTER}, otherwise round-robin) or account "
1198
+ "for every non-critic analyser exactly "
1184
1199
  f"once; missing: {', '.join(missing) or 'none'}"
1185
1200
  ]
1186
1201
 
@@ -94,7 +94,14 @@ ADVERSARIAL_RESPONSE = """### <finding-id>
94
94
  **Basis** (only if REFUTED): counter-evidence | burden-not-met
95
95
  **Explanation** (required for every verdict, SURVIVES included): <2-3 sentences; for
96
96
  SURVIVES say what you attacked and why the attack failed; for counter-evidence include
97
- the file:line you found>"""
97
+ the file:line you found>
98
+ **Opened**: <every file you opened for this finding, as path:line, comma-separated>"""
99
+
100
+ # `okstra convergence collect-results` enforces this for round votes
101
+ # (`convergence._grounded_vote`); critic and acceptance votes are not collected there.
102
+ OPENED_RULE = """A SURVIVES, SURVIVES-WITH-CAVEAT or burden-not-met verdict whose `**Opened**` line
103
+ names none of the files the finding cites is collected as UNVERIFIABLE: a verdict
104
+ on evidence you did not open is not a vote."""
98
105
 
99
106
  def _nonempty_string(value: Any) -> str:
100
107
  return value if isinstance(value, str) and value.strip() else ""
@@ -222,7 +229,7 @@ def reverify_prompt_body(
222
229
  "collector also reads `**Verdict:** …` and `- Verdict: …` as the same field.\n\n"
223
230
  )
224
231
  rows.append(ADVERSARIAL_RESPONSE.replace("<finding-id>", findings[0].finding_id))
225
- rows.append("\n")
232
+ rows.append("\n\n" + OPENED_RULE + "\n")
226
233
  if len(findings) > 1:
227
234
  rows.append(f"\n### {findings[1].finding_id}\n**Verdict**: ...\n")
228
235
  return "".join(rows)