okstra 0.231.0 → 0.232.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 (143) hide show
  1. package/README.md +15 -3
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +129 -2
  20. package/docs/architecture.md +11 -2
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/lead/convergence.md +3 -3
  43. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  44. package/runtime/prompts/lead/report-writer.md +1 -1
  45. package/runtime/prompts/lead/team-contract.md +1 -1
  46. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  47. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  48. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  49. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  50. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  51. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  52. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  53. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  54. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  55. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  56. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  57. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  58. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  59. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  60. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  61. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  62. package/runtime/python/okstra_ctl/consumers.py +12 -9
  63. package/runtime/python/okstra_ctl/convergence.py +112 -20
  64. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  65. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  66. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  67. package/runtime/python/okstra_ctl/design_review.py +207 -0
  68. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  69. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  70. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  71. package/runtime/python/okstra_ctl/doctor.py +8 -25
  72. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  73. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  74. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  75. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  76. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  77. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  78. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  79. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  80. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  81. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  82. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  83. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  84. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  85. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  86. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  87. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  88. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  89. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  90. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  91. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  92. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  93. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  94. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  95. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  96. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  97. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  98. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
  99. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  100. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  101. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
  102. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  103. package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
  104. package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
  105. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  106. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  107. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  108. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  109. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  110. package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
  111. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  112. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  113. package/runtime/python/okstra_ctl/run.py +24 -1
  114. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  115. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  116. package/runtime/python/okstra_ctl/team.py +3 -1
  117. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  118. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  119. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  120. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  121. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  122. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  123. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  124. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  125. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  126. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  127. package/runtime/python/okstra_project/__init__.py +2 -0
  128. package/runtime/python/okstra_project/dirs.py +18 -0
  129. package/runtime/python/okstra_project/state.py +25 -20
  130. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  131. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  132. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  133. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  134. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  135. package/runtime/schemas/record-secret-patterns.json +41 -0
  136. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  137. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  138. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  139. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  140. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  141. package/runtime/templates/implementation-worker-preamble.md +4 -9
  142. package/runtime/templates/worker-prompt-preamble.md +4 -12
  143. package/runtime/validators/validate-run.py +17 -8
@@ -14,6 +14,7 @@ from okstra_project.slug import slugify
14
14
  from okstra_project.state import StateError, parse_task_key
15
15
 
16
16
  from .convergence_engine import (
17
+ ANALYSIS_SOURCE_ROLES,
17
18
  ConvergenceContractError,
18
19
  apply_acceptance_critic_results,
19
20
  apply_critic_gap_results,
@@ -54,9 +55,11 @@ from .convergence_migration import (
54
55
  )
55
56
  from .convergence_provenance import (
56
57
  GROUPS_BASENAME_RE,
58
+ accepted_role_execution_refs,
57
59
  discarded_worker_errors,
58
60
  missing_scope_results,
59
61
  provenance_errors,
62
+ resolve_recorded_result_path,
60
63
  worker_result_suffix,
61
64
  )
62
65
  from .correction_round import (
@@ -454,7 +457,9 @@ def _parser() -> argparse.ArgumentParser:
454
457
  collect.add_argument("--plan", type=Path, required=True)
455
458
  collect.add_argument("--result", action="append", default=[],
456
459
  metavar="<worker>=<path>",
457
- help="one worker's reverify result file (repeatable)")
460
+ help="one worker's reverify result file (repeatable); "
461
+ "a worker without one is read from the result "
462
+ "path its ok attempt recorded")
458
463
  collect.add_argument("--run-manifest", type=Path, required=True,
459
464
  help="the current run manifest; each planned worker's "
460
465
  "terminal outcome and duration are read from its "
@@ -1418,7 +1423,7 @@ def _dispatch_rows_from_manifest(
1418
1423
  manifest: Any,
1419
1424
  run_manifest_path: Path,
1420
1425
  scope: str | None = None,
1421
- ) -> list[dict[str, Any]]:
1426
+ ) -> tuple[list[dict[str, Any]], dict[str, str]]:
1422
1427
  """`dispatches[]` 를 execution manifest 의 attempt 원장에서 도출한다.
1423
1428
 
1424
1429
  종전에는 리드가 `--dispatch <worker>=<status>:<durationMs>` 로 상태와
@@ -1432,6 +1437,11 @@ def _dispatch_rows_from_manifest(
1432
1437
  상태 대응: `ok` → completed, 그 밖의 terminal 은 error (wrapper 가 timeout
1433
1438
  으로 닫은 attempt 는 `changeSummary.timeout` 이 참이면 timeout). 이 라운드의
1434
1439
  invocation 이 없는 워커는 not-run.
1440
+
1441
+ The second value maps each worker to the `resultPath` its deciding attempt
1442
+ closed with. A batch dispatch records the worker-result file there, so the
1443
+ lead does not have to repeat it as `--result`: collect-results reads it for
1444
+ each completed worker given no `--result`, and refuses when it is absent.
1435
1445
  """
1436
1446
  round_number = plan.get("round")
1437
1447
  if not isinstance(round_number, int) or round_number < 1:
@@ -1441,12 +1451,9 @@ def _dispatch_rows_from_manifest(
1441
1451
  role.role_execution_ref: role.source_role_execution_ref or role.role_execution_ref
1442
1452
  for role in getattr(manifest, "role_executions", ())
1443
1453
  }
1444
- latest: dict[str, Any] = {}
1445
- for attempt in getattr(manifest, "attempts", ()):
1446
- current = latest.get(attempt.invocation_ref)
1447
- if current is None or attempt.attempt > current.attempt:
1448
- latest[attempt.invocation_ref] = attempt
1454
+ latest = _latest_attempts(manifest)
1449
1455
  rows: list[dict[str, Any]] = []
1456
+ recorded_result_paths: dict[str, str] = {}
1450
1457
  for row in plan.get("dispatches") or []:
1451
1458
  if not isinstance(row, Mapping):
1452
1459
  continue
@@ -1475,15 +1482,30 @@ def _dispatch_rows_from_manifest(
1475
1482
  "round result written over an open attempt is a status the ledger "
1476
1483
  "never recorded"
1477
1484
  )
1478
- status = _ATTEMPT_DISPATCH_STATUS.get(attempt.status, "error")
1479
- if status == "error" and bool((attempt.change_summary or {}).get("timeout")):
1480
- status = "timeout"
1481
1485
  rows.append({
1482
1486
  "worker": worker,
1483
- "status": status,
1487
+ "status": _attempt_dispatch_status(attempt),
1484
1488
  "durationMs": _duration_ms(attempt.started_at, attempt.finished_at),
1485
1489
  })
1486
- return rows
1490
+ if attempt.result_path:
1491
+ recorded_result_paths[worker] = attempt.result_path
1492
+ return rows, recorded_result_paths
1493
+
1494
+
1495
+ def _latest_attempts(manifest: Any) -> dict[str, Any]:
1496
+ latest: dict[str, Any] = {}
1497
+ for attempt in getattr(manifest, "attempts", ()):
1498
+ current = latest.get(attempt.invocation_ref)
1499
+ if current is None or attempt.attempt > current.attempt:
1500
+ latest[attempt.invocation_ref] = attempt
1501
+ return latest
1502
+
1503
+
1504
+ def _attempt_dispatch_status(attempt: Any) -> str:
1505
+ status = _ATTEMPT_DISPATCH_STATUS.get(attempt.status, "error")
1506
+ if status == "error" and bool((attempt.change_summary or {}).get("timeout")):
1507
+ return "timeout"
1508
+ return status
1487
1509
 
1488
1510
 
1489
1511
  def _duration_ms(started_at: str, finished_at: str) -> int:
@@ -1541,10 +1563,39 @@ def _worker_votes(
1541
1563
  return votes
1542
1564
 
1543
1565
 
1566
+ def _recorded_results(
1567
+ dispatches: list[dict[str, Any]],
1568
+ recorded_result_paths: Mapping[str, str],
1569
+ supplied_results: list[str],
1570
+ authority: Mapping[str, Any],
1571
+ ) -> list[str]:
1572
+ explicit_workers = {_split_pair(raw, "--result")[0] for raw in supplied_results}
1573
+ result_args: list[str] = []
1574
+ for row in dispatches:
1575
+ worker = row["worker"]
1576
+ if row["status"] != "completed" or worker in explicit_workers:
1577
+ continue
1578
+ value = recorded_result_paths.get(worker)
1579
+ if not value:
1580
+ raise ConvergenceContractError(
1581
+ f"`{worker}` closed its attempt ok but the ledger recorded no result "
1582
+ f"path and no `--result {worker}=<path>` was given — a completed "
1583
+ "worker without a vote fails apply-round"
1584
+ )
1585
+ path = resolve_recorded_result_path(value, authority)
1586
+ if not path.is_file():
1587
+ raise ConvergenceContractError(
1588
+ f"`{worker}` closed its attempt ok with result `{path}`, which does "
1589
+ f"not exist; pass `--result {worker}=<path>` for the file it wrote"
1590
+ )
1591
+ result_args.append(f"{worker}={path}")
1592
+ return result_args
1593
+
1594
+
1544
1595
  def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
1545
1596
  plan = load_owned_json_object(args.plan)
1546
1597
  planned = _planned_finding_ids(plan)
1547
- manifest, _authority = read_execution_manifest_view(args.run_manifest)
1598
+ manifest, authority = read_execution_manifest_view(args.run_manifest)
1548
1599
  if getattr(manifest, "legacy", False):
1549
1600
  raise ConvergenceContractError(
1550
1601
  "collect-results reads dispatch outcomes from a v2 execution manifest; "
@@ -1554,8 +1605,14 @@ def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
1554
1605
  scope = convergence_scope(args.correction_round)
1555
1606
  except CorrectionRoundError as exc:
1556
1607
  raise ConvergenceContractError(str(exc)) from exc
1557
- dispatches = _dispatch_rows_from_manifest(plan, manifest, args.run_manifest, scope)
1558
- votes = _worker_votes(args.result, planned)
1608
+ dispatches, recorded_result_paths = _dispatch_rows_from_manifest(
1609
+ plan, manifest, args.run_manifest, scope
1610
+ )
1611
+ raw_results = [
1612
+ *args.result,
1613
+ *_recorded_results(dispatches, recorded_result_paths, args.result, authority),
1614
+ ]
1615
+ votes = _worker_votes(raw_results, planned)
1559
1616
  returned_without_completion = sorted(
1560
1617
  worker for worker in votes
1561
1618
  if next((row["status"] for row in dispatches if row["worker"] == worker), None)
@@ -1750,6 +1807,42 @@ def _group_worker(manifest: Mapping[str, Any], worker_id: str) -> dict[str, str]
1750
1807
  "sourceRoleExecutionRef": str(execution["roleExecutionRef"])}
1751
1808
 
1752
1809
 
1810
+ def _group_workers(
1811
+ manifest: Mapping[str, Any],
1812
+ execution_manifest: ExecutionManifest | None,
1813
+ cited: list[str],
1814
+ scope: str | None,
1815
+ ) -> list[dict[str, str]]:
1816
+ """Grouping roster: analysis workers with an accepted result, the other cited workers, the critic.
1817
+
1818
+ Analysis workers are listed in `workerAssignments` order whether or not a group cites them, so
1819
+ the auto-disable rule counts analysers that returned a result. A legacy or missing execution
1820
+ manifest has no attempt ledger, so its roster is the cited workers.
1821
+ """
1822
+ if execution_manifest is None or execution_manifest.legacy:
1823
+ workers = [_group_worker(manifest, worker) for worker in cited]
1824
+ else:
1825
+ accepted = accepted_role_execution_refs(execution_manifest, scope)
1826
+ # Groups may cite `codex-verifier-worker` for the `codex-verifier` row; the roster keeps the
1827
+ # cited spelling because the engine matches group sources to roster rows by that string.
1828
+ spelling = {worker.removesuffix("-worker"): worker for worker in cited}
1829
+ assignments = manifest.get("workerAssignments")
1830
+ workers = []
1831
+ for row in assignments if isinstance(assignments, list) else []:
1832
+ if not isinstance(row, Mapping) or row.get("role") not in ANALYSIS_SOURCE_ROLES:
1833
+ continue
1834
+ bare_id = str(row.get("workerId") or "").removesuffix("-worker")
1835
+ if not bare_id:
1836
+ continue
1837
+ worker = _group_worker(manifest, spelling.get(bare_id, bare_id))
1838
+ if worker["sourceRoleExecutionRef"] in accepted:
1839
+ workers.append(worker)
1840
+ listed = {worker["workerId"] for worker in workers}
1841
+ workers.extend(_group_worker(manifest, worker) for worker in cited if worker not in listed)
1842
+ workers.extend(_critic_tie_breaker(manifest))
1843
+ return workers
1844
+
1845
+
1753
1846
  def _critic_tie_breaker(manifest: Mapping[str, Any]) -> list[dict[str, str]]:
1754
1847
  """로스터에 크리틱이 있으면 동률 finding 을 판정할 `critic` 워커 행 하나."""
1755
1848
  executions = manifest.get("roleExecutions") if isinstance(manifest.get("roleExecutions"), list) else []
@@ -1838,16 +1931,15 @@ def _prepare_groups(args: argparse.Namespace) -> tuple[str, Path]:
1838
1931
  authority = validated_run_authority(args.run_manifest)
1839
1932
  manifest = authority.payload
1840
1933
  groups = _parse_grouping_markdown(args.input)
1841
- worker_ids = list(dict.fromkeys(
1934
+ cited_worker_ids = list(dict.fromkeys(
1842
1935
  source["worker"] for group in groups for source in group["sourceItems"]
1843
1936
  ))
1937
+ scope = _correction_scope(args, authority)
1844
1938
  output = authority.run_dir / "state" / _canonical_run_artifact_name(
1845
- "convergence-groups", authority.task_type, authority.state_sequence,
1846
- _correction_scope(args, authority),
1939
+ "convergence-groups", authority.task_type, authority.state_sequence, scope,
1847
1940
  )
1848
1941
  config = _convergence_config(authority)
1849
- workers = [_group_worker(manifest, worker) for worker in worker_ids]
1850
- workers.extend(_critic_tie_breaker(manifest))
1942
+ workers = _group_workers(manifest, authority.execution_manifest, cited_worker_ids, scope)
1851
1943
  source_refs = [worker["sourceRoleExecutionRef"] for worker in workers]
1852
1944
  if len(source_refs) != len(set(source_refs)):
1853
1945
  raise ConvergenceContractError("duplicate sourceRoleExecutionRef")
@@ -26,6 +26,7 @@ _AUDIENCE_SOURCE_ROLES = {
26
26
  "report-writer": frozenset({"report-writer"}),
27
27
  "critic": frozenset({"critic"}),
28
28
  }
29
+ ANALYSIS_SOURCE_ROLES = _AUDIENCE_SOURCE_ROLES["analysis"]
29
30
  _VERIFICATION_MODES = {"lightweight", "full-reanalysis"}
30
31
  # `unverified` 가 없던 시절의 산출물. `reuse-final` 이 그대로 읽으므로 그
31
32
  # 어휘로 검증한다 — 없던 키를 요구하면 이미 디스크에 있는 리포트가 무효가 된다.
@@ -133,6 +133,28 @@ def discovery_attempts(
133
133
  return by_role
134
134
 
135
135
 
136
+ def accepted_role_execution_refs(
137
+ manifest: ExecutionManifest, scope: str | None = None,
138
+ ) -> set[str]:
139
+ """Role executions whose latest attempt of some discovery invocation in the scope is ``ok``."""
140
+ return {
141
+ ref for ref, attempts in discovery_attempts(manifest, scope).items()
142
+ if any(attempt.status == "ok" for attempt in attempts)
143
+ }
144
+
145
+
146
+ def resolve_recorded_result_path(result_path: str, authority: Mapping) -> Path:
147
+ # A batch dispatch records the absolute worker-result path; a native agent
148
+ # dispatch records it relative to the project root.
149
+ candidate = Path(result_path)
150
+ if candidate.is_absolute():
151
+ return candidate
152
+ project_root = authority.get("projectRoot")
153
+ if not _nonempty_string(project_root):
154
+ raise ValueError("relative accepted resultPath requires projectRoot")
155
+ return Path(project_root) / candidate
156
+
157
+
136
158
  def worker_result_paths(
137
159
  run_dir: Path, document: Mapping, suffix: str, scope: str | None = None,
138
160
  ) -> dict[str, Path]:
@@ -162,12 +184,7 @@ def worker_result_paths(
162
184
  ]
163
185
  if not accepted:
164
186
  continue
165
- candidate = Path(accepted[-1].result_path)
166
- if not candidate.is_absolute():
167
- project_root = authority.get("projectRoot")
168
- if not _nonempty_string(project_root):
169
- raise ValueError("relative accepted resultPath requires projectRoot")
170
- candidate = Path(project_root) / candidate
187
+ candidate = resolve_recorded_result_path(accepted[-1].result_path, authority)
171
188
  if candidate.resolve().parent != results_dir.resolve():
172
189
  raise ValueError(f"accepted resultPath is outside worker-results: {candidate}")
173
190
  if not candidate.is_file():
@@ -357,6 +374,7 @@ def discarded_workers(
357
374
  if execution_manifest is None or getattr(execution_manifest, "legacy", False):
358
375
  return {}
359
376
  attempts = discovery_attempts(execution_manifest, scope)
377
+ accepted = accepted_role_execution_refs(execution_manifest, scope)
360
378
  result: dict[str, str] = {}
361
379
  for row in document["workers"]:
362
380
  if not isinstance(row, dict):
@@ -366,7 +384,7 @@ def discarded_workers(
366
384
  if not _nonempty_string(worker) or not _nonempty_string(role_ref):
367
385
  continue
368
386
  rows = attempts.get(role_ref, [])
369
- if not rows or any(item.status == "ok" for item in rows):
387
+ if not rows or role_ref in accepted:
370
388
  continue
371
389
  discarded = [item for item in rows if item.status in DISCARDED_ATTEMPT_STATUSES]
372
390
  if discarded:
@@ -424,14 +442,12 @@ def missing_scope_results(
424
442
  return []
425
443
  if not isinstance(document, dict):
426
444
  return []
427
- attempts = discovery_attempts(execution_manifest, scope)
445
+ accepted = accepted_role_execution_refs(execution_manifest, scope)
428
446
  missing = sorted({
429
447
  str(row.get("workerId"))
430
448
  for row in document.get("workers") or []
431
449
  if isinstance(row, dict) and row.get("audience") == "analysis"
432
- and not any(
433
- item.status == "ok" for item in attempts.get(row.get("sourceRoleExecutionRef"), [])
434
- )
450
+ and row.get("sourceRoleExecutionRef") not in accepted
435
451
  })
436
452
  return [
437
453
  f"`{worker}` has no accepted `{scope}` result; await that round's verifiers "
@@ -61,6 +61,11 @@ def correction_convergence_states(initial_final: Path) -> list[tuple[str, Path]]
61
61
  return rows
62
62
 
63
63
 
64
+ def invocation_in_correction_namespace(invocation_ref: str) -> bool:
65
+ """Whether an invocation id contains `-correction-r`, as every correction-round id does."""
66
+ return f"-{CORRECTION_DISPATCH_KIND_PREFIX}" in invocation_ref
67
+
68
+
64
69
  def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_number: int) -> bool:
65
70
  """Whether a `reverify-r<N>` invocation belongs to this convergence namespace.
66
71
 
@@ -68,7 +73,7 @@ def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_n
68
73
  correction re-convergence names it `…-correction-r<M>-reverify-r<N>-<worker>`.
69
74
  """
70
75
  if scope is None:
71
- return f"-{CORRECTION_DISPATCH_KIND_PREFIX}" not in invocation_ref
76
+ return not invocation_in_correction_namespace(invocation_ref)
72
77
  return f"-{scope}-reverify-r{round_number}-" in invocation_ref
73
78
 
74
79
 
@@ -0,0 +1,207 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import re
5
+ from dataclasses import dataclass
6
+ from pathlib import Path
7
+ from collections.abc import Mapping
8
+ from typing import Any, TYPE_CHECKING, TypedDict
9
+
10
+ from .json_boundary import load_owned_object, write_owned_object_atomic
11
+ from .qa_procedures import canonical_json_digest
12
+ from .verification_input_types import FrozenReviewPolicy
13
+
14
+ if TYPE_CHECKING:
15
+ from .coverage_census import CellVerdicts
16
+ from .review_verdicts import ReviewCensus
17
+
18
+
19
+ class DesignReviewSnapshot(TypedDict):
20
+ base: str
21
+ head: str
22
+ policyDigest: str
23
+ census: str
24
+ manualInventory: dict[str, Any]
25
+ blockingSeverities: list[str]
26
+ blockingTiming: str
27
+
28
+
29
+ DESIGN_REVIEW_SCHEMA = {
30
+ "type": "object", "additionalProperties": False,
31
+ "required": list(DesignReviewSnapshot.__required_keys__),
32
+ "properties": {
33
+ "base": {"type": "string"}, "head": {"type": "string"},
34
+ "policyDigest": {"type": "string"}, "census": {"type": "string"},
35
+ "manualInventory": {"type": "object"},
36
+ "blockingSeverities": {"type": "array", "items": {"type": "string"}},
37
+ "blockingTiming": {"type": "string"},
38
+ },
39
+ }
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class DesignReviewResult:
44
+ coverage: CellVerdicts
45
+ findings: tuple[dict[str, str], ...]
46
+ blocking_findings: tuple[str, ...]
47
+
48
+ @property
49
+ def blocking(self) -> bool:
50
+ return bool(self.coverage.missing or self.coverage.unknown or self.blocking_findings)
51
+
52
+
53
+ def capture_design_review(
54
+ source: Path, base: str, head: str, policy: FrozenReviewPolicy, inventory_path: Path,
55
+ ) -> DesignReviewSnapshot:
56
+ from .code_review_census import build_review_census
57
+ from .code_review_target import changed_lines
58
+ from .review_verdicts import parse_review_census
59
+ from .review_policy import (
60
+ review_policy_catalog_path, review_policy_context, select_review_policy,
61
+ render_review_rule_catalog,
62
+ )
63
+
64
+ catalog_path = review_policy_catalog_path(policy)
65
+ catalog = json.loads(policy["sources"][str(catalog_path)]["body"])
66
+ changed = changed_lines(source, base, head)
67
+ paths, manifests = review_policy_context(source, head, tuple(changed), base=base)
68
+ selected = select_review_policy(policy, tuple(changed), project_paths=paths,
69
+ manifest_contents=manifests)
70
+ 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)
77
+ if result.unresolved:
78
+ raise ValueError("design review has unresolved function boundaries")
79
+ parse_review_census(result.text, allow_empty=True)
80
+ return {"base": base, "head": head, "policyDigest": canonical_json_digest(policy),
81
+ "census": result.text, "manualInventory": inventory,
82
+ "blockingSeverities": catalog["blockingSeverities"],
83
+ "blockingTiming": catalog["blockingTiming"]}
84
+
85
+
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
+ def review_binding_lines(snapshot: DesignReviewSnapshot) -> tuple[str, ...]:
103
+ return (f"Review base: {snapshot['base']}", f"Review head: {snapshot['head']}",
104
+ f"Review rules: {snapshot['policyDigest']}",
105
+ f"Review census: {canonical_json_digest(snapshot)}")
106
+
107
+
108
+ def render_design_review(snapshot: DesignReviewSnapshot) -> str:
109
+ return ("\n## Frozen Design Review\n\n" + "\n".join(review_binding_lines(snapshot))
110
+ + "\n\n" + snapshot["census"]
111
+ + "\nIndependently inspect every cell and rule. Return the four binding lines verbatim, "
112
+ "one Coverage Verdicts row per cell (Cell | Checked | N/A | Findings | Evidence), "
113
+ "using only the rules assigned to that cell's Group in the Rules table. Account for "
114
+ "each assigned rule exactly once across Checked (comma-separated IDs), N/A "
115
+ "(RULE=reason) and Findings (RULE=finding-ID). Separate assignments with semicolons "
116
+ "and multiple finding IDs for one rule with commas. Use `-` for an empty field; "
117
+ "do not add rules from other groups even as N/A. Evidence starts with that cell's "
118
+ "literal target path:line, optionally backtick-quoted, followed by an optional "
119
+ "observation with a space or ` — ` separator. Do not use line ranges or replace "
120
+ "the target anchor with another file. Return the table under `## Coverage Verdicts` "
121
+ "and one `## Design Findings` section with a JSON array, including `[]` when empty. "
122
+ "Each finding has string fields id, cell, rule, kind (execution-error/design-violation), "
123
+ "severity (must-fix/should-fix/nit), timing (now/park), source (path:line), consequence, "
124
+ "fix, disposition (open/fixed/accepted-risk/rejected), basis. Give a reachable failing "
125
+ "input for an execution error or a rule violation and design impact for a design finding. "
126
+ "Every coverage finding ID must match its cell/rule in that array. Checked G2/G3/G5 "
127
+ "include `RULE=path:line observation` assignments after ` :: ` in Evidence, "
128
+ "separated with semicolons. Include observations only for checked rules; "
129
+ "N/A and Findings already explain their rules. Follow the coding-preflight "
130
+ "grading rubric; current open blocking findings force FAIL. Missing cells or rules "
131
+ "are incomplete, never clean. Other workers' results and executor self-check do not "
132
+ "satisfy your coverage. Also return exactly one `Verifier verdict: PASS|CONCERNS|FAIL` "
133
+ "line with the overall result, including command failures. Manual inventory completeness "
134
+ "remains lead judgment.\n")
135
+
136
+
137
+ def parse_design_review(
138
+ source: Path, snapshot: DesignReviewSnapshot, body: str,
139
+ ) -> DesignReviewResult:
140
+ from .review_verdicts import parse_review_census, parse_review_verdicts
141
+
142
+ for line in review_binding_lines(snapshot):
143
+ if body.splitlines().count(line) != 1:
144
+ raise ValueError("design review baseline missing or different: " + line.partition(":")[0])
145
+ census = parse_review_census(snapshot["census"], allow_empty=True)
146
+ coverage = parse_review_verdicts(source, census, [body], snapshot["head"], base=snapshot["base"])
147
+ matches = re.findall(r"^## Design Findings\s*\n```json\s*\n(.*?)\n```", body, re.M | re.S)
148
+ if len(matches) != 1:
149
+ raise ValueError("design review needs one Design Findings JSON array, including []")
150
+ findings = json.loads(matches[0])
151
+ if not isinstance(findings, list):
152
+ raise ValueError("design findings must be an array")
153
+ indexed: dict[str, dict[str, str]] = {}
154
+ for finding in findings:
155
+ _validate_finding(source, snapshot, census, finding)
156
+ if finding["id"] in indexed:
157
+ raise ValueError("duplicate design finding ID")
158
+ indexed[finding["id"]] = finding
159
+ _match_finding_rows(body, indexed)
160
+ blocking = tuple(row["id"] for row in indexed.values()
161
+ if row["severity"] in snapshot["blockingSeverities"]
162
+ and row["timing"] == snapshot["blockingTiming"]
163
+ and row["disposition"] == "open")
164
+ return DesignReviewResult(coverage, tuple(indexed.values()), blocking)
165
+
166
+
167
+ def _validate_finding(source: Path, snapshot: DesignReviewSnapshot, census: ReviewCensus,
168
+ finding: object) -> None:
169
+ from .review_verdicts import _head_tree, _source_evidence
170
+
171
+ fields = {"id", "cell", "rule", "kind", "severity", "timing", "source",
172
+ "consequence", "fix", "disposition", "basis"}
173
+ if (not isinstance(finding, dict) or set(finding) != fields
174
+ or any(not isinstance(value, str) or not value.strip() for value in finding.values())):
175
+ raise ValueError("design finding requires non-blank typed evidence and disposition fields")
176
+ cell = census.cells.get(finding["cell"])
177
+ if cell is None or finding["rule"] not in census.rules[cell.group]:
178
+ raise ValueError("design finding names an unknown cell or rule")
179
+ if (finding["kind"] not in ("execution-error", "design-violation")
180
+ or finding["severity"] not in ("must-fix", "should-fix", "nit")
181
+ or finding["timing"] not in ("now", "park")
182
+ or finding["disposition"] not in ("open", "fixed", "accepted-risk", "rejected")):
183
+ raise ValueError("design finding has an invalid grade or disposition")
184
+ tree = _head_tree(source, snapshot["head"])
185
+ tree.base = _head_tree(source, snapshot["base"])
186
+ _source_evidence(tree, cell, finding["source"])
187
+
188
+
189
+ def _match_finding_rows(body: str, findings: Mapping[str, Mapping[str, str]]) -> None:
190
+ from .review_verdicts import _keyed_values, _table_fields
191
+
192
+ section = body.partition("## Coverage Verdicts")[2].split("\n## ", 1)[0]
193
+ mentioned: set[str] = set()
194
+ for line in section.splitlines():
195
+ if not line.strip().startswith("|"):
196
+ continue
197
+ fields = _table_fields(line)
198
+ if not fields[0].startswith("C-CR-") or len(fields) != 5:
199
+ continue
200
+ for rule, ids in _keyed_values(fields[3]).items():
201
+ for identity in (value.strip() for value in ids.split(",")):
202
+ finding = findings.get(identity)
203
+ if finding is None or finding["cell"] != fields[0] or finding["rule"] != rule:
204
+ raise ValueError("coverage finding differs from Design Findings")
205
+ mentioned.add(identity)
206
+ if mentioned != findings.keys():
207
+ raise ValueError("Design Findings contains findings absent from coverage")