okstra 0.231.1 → 0.233.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 (265) hide show
  1. package/README.md +19 -271
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/memory/memory.mjs +9 -55
  10. package/dist/commands/memory/memory.mjs.map +1 -1
  11. package/dist/commands/trace/capacity.d.mts +12 -0
  12. package/dist/commands/trace/capacity.mjs +21 -0
  13. package/dist/commands/trace/capacity.mjs.map +1 -0
  14. package/dist/commands/trace/model.d.mts +89 -0
  15. package/dist/commands/trace/model.mjs +251 -0
  16. package/dist/commands/trace/model.mjs.map +1 -0
  17. package/dist/commands/trace/progression.d.mts +11 -0
  18. package/dist/commands/trace/progression.mjs +194 -0
  19. package/dist/commands/trace/progression.mjs.map +1 -0
  20. package/dist/commands/trace/review.d.mts +7 -0
  21. package/dist/commands/trace/review.mjs +51 -0
  22. package/dist/commands/trace/review.mjs.map +1 -0
  23. package/dist/commands/trace/task-link.d.mts +18 -0
  24. package/dist/commands/trace/task-link.mjs +72 -0
  25. package/dist/commands/trace/task-link.mjs.map +1 -0
  26. package/dist/commands/trace/trace.d.mts +1 -0
  27. package/dist/commands/trace/trace.mjs +293 -0
  28. package/dist/commands/trace/trace.mjs.map +1 -0
  29. package/dist/lib/bounded-file.d.mts +1 -0
  30. package/dist/lib/bounded-file.mjs +36 -0
  31. package/dist/lib/bounded-file.mjs.map +1 -0
  32. package/dist/lib/config-store.d.mts +34 -0
  33. package/dist/lib/config-store.mjs +70 -0
  34. package/dist/lib/config-store.mjs.map +1 -0
  35. package/dist/lib/file-lock.mjs +4 -5
  36. package/dist/lib/file-lock.mjs.map +1 -1
  37. package/dist/lib/input-limit.d.mts +4 -0
  38. package/dist/lib/input-limit.mjs +8 -0
  39. package/dist/lib/input-limit.mjs.map +1 -0
  40. package/dist/lib/memory-auto-register.d.mts +1 -0
  41. package/dist/lib/memory-auto-register.mjs +98 -0
  42. package/dist/lib/memory-auto-register.mjs.map +1 -0
  43. package/dist/lib/memory-entry-contract.d.mts +12 -0
  44. package/dist/lib/memory-entry-contract.mjs +46 -0
  45. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  46. package/dist/lib/python-helper.d.mts +1 -1
  47. package/dist/lib/python-helper.mjs +3 -2
  48. package/dist/lib/python-helper.mjs.map +1 -1
  49. package/dist/lib/record-secrets.d.mts +1 -0
  50. package/dist/lib/record-secrets.mjs +28 -0
  51. package/dist/lib/record-secrets.mjs.map +1 -0
  52. package/dist/lib/report-language-tag.d.mts +1 -0
  53. package/dist/lib/report-language-tag.mjs +4 -0
  54. package/dist/lib/report-language-tag.mjs.map +1 -0
  55. package/dist/lib/report-language.d.mts +1 -0
  56. package/dist/lib/report-language.mjs +50 -0
  57. package/dist/lib/report-language.mjs.map +1 -0
  58. package/dist/lib/skill-catalog.mjs +3 -0
  59. package/dist/lib/skill-catalog.mjs.map +1 -1
  60. package/dist/lib/types.d.mts +2 -1
  61. package/docs/architecture/storage-model.md +163 -5
  62. package/docs/architecture.md +17 -4
  63. package/docs/cli.md +511 -0
  64. package/docs/contributor-change-matrix.md +1 -2
  65. package/docs/project-structure-overview.md +33 -42
  66. package/package.json +1 -1
  67. package/runtime/BUILD.json +2 -2
  68. package/runtime/agents/common.json +8 -8
  69. package/runtime/agents/operations/trace-interface-review.json +6 -0
  70. package/runtime/agents/operations/trace-scope-review.json +6 -0
  71. package/runtime/agents/roles/verifier.json +2 -4
  72. package/runtime/bin/okstra-provider-exec.py +10 -4
  73. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  74. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  75. package/runtime/prompts/coding-preflight/clean-code.md +88 -286
  76. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  77. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  78. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  79. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  80. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  81. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  82. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  83. package/runtime/prompts/coding-preflight/overview.md +25 -38
  84. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  85. package/runtime/prompts/duties/code-reviewer.json +15 -18
  86. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  87. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  88. package/runtime/prompts/host-orchestration/README.md +18 -9
  89. package/runtime/prompts/launch.template.md +3 -2
  90. package/runtime/prompts/lead/context-loader.md +2 -0
  91. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  92. package/runtime/prompts/lead/report-writer.md +6 -6
  93. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  94. package/runtime/prompts/profiles/_common-contract.md +1 -1
  95. package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
  96. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
  97. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  98. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
  99. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  100. package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
  101. package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
  102. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  103. package/runtime/python/okstra_ctl/code_review_census.py +162 -7
  104. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  105. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  106. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  107. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  108. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  109. package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
  110. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  111. package/runtime/python/okstra_ctl/code_review_target.py +212 -13
  112. package/runtime/python/okstra_ctl/consumers.py +12 -9
  113. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  114. package/runtime/python/okstra_ctl/design_review.py +207 -0
  115. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  116. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  117. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  118. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  119. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  120. package/runtime/python/okstra_ctl/doctor.py +8 -25
  121. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  122. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  123. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  124. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  125. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  126. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  127. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  128. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  129. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  130. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  131. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  132. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  133. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
  134. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  135. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  136. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  137. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  138. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  139. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  140. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  141. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  142. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  143. package/runtime/python/okstra_ctl/json_boundary.py +51 -5
  144. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  145. package/runtime/python/okstra_ctl/manager_cli.py +148 -1
  146. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  147. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  148. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  149. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  150. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  151. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  152. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  153. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  154. package/runtime/python/okstra_ctl/manager_sync.py +45 -25
  155. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  156. package/runtime/python/okstra_ctl/material.py +2 -0
  157. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  158. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  159. package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
  160. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  161. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  162. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  163. package/runtime/python/okstra_ctl/paths.py +6 -1
  164. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  165. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  166. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  167. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  168. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
  169. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
  170. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  171. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  172. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  173. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  174. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  175. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  176. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
  177. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  178. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  179. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
  180. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  181. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  182. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  183. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  184. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  185. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  186. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  187. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  188. package/runtime/python/okstra_ctl/render.py +28 -2
  189. package/runtime/python/okstra_ctl/report_assembly.py +53 -11
  190. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  191. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  192. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  193. package/runtime/python/okstra_ctl/report_language.py +4 -1
  194. package/runtime/python/okstra_ctl/report_narrative.py +182 -7
  195. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  196. package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
  197. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  198. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  199. package/runtime/python/okstra_ctl/run.py +67 -36
  200. package/runtime/python/okstra_ctl/run_context.py +10 -1
  201. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  202. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  203. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  204. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  205. package/runtime/python/okstra_ctl/task_query.py +239 -0
  206. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  207. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  208. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  209. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  210. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  211. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  212. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  213. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  214. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  215. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  216. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  217. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  218. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  219. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  220. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  221. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  222. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  223. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  224. package/runtime/python/okstra_project/__init__.py +2 -0
  225. package/runtime/python/okstra_project/dirs.py +18 -0
  226. package/runtime/python/okstra_project/state.py +45 -20
  227. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  228. package/runtime/python/okstra_token_usage/cli.py +23 -10
  229. package/runtime/python/okstra_token_usage/collect.py +25 -22
  230. package/runtime/python/okstra_token_usage/policy.py +193 -0
  231. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  232. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  233. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  234. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  235. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  236. package/runtime/schemas/record-secret-patterns.json +41 -0
  237. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  238. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  239. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  240. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  241. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  242. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  243. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  244. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  245. package/runtime/skills/okstra-code-review/SKILL.md +92 -136
  246. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  247. package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
  248. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  249. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  250. package/runtime/skills/okstra-manager/SKILL.md +31 -0
  251. package/runtime/skills/okstra-memory/SKILL.md +8 -1
  252. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  253. package/runtime/skills/okstra-run/SKILL.md +55 -183
  254. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  255. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  256. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  257. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  258. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  259. package/runtime/templates/implementation-worker-preamble.md +4 -9
  260. package/runtime/templates/manager/view.template.html +4 -0
  261. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  262. package/runtime/templates/trace/trace.template.md +42 -0
  263. package/runtime/templates/worker-prompt-preamble.md +4 -12
  264. package/runtime/validators/checks/fixtures-02.py +25 -33
  265. package/runtime/validators/validate-run.py +107 -38
@@ -0,0 +1,384 @@
1
+ """Start prepared code-review invocations and await, finalize and audit them.
2
+
3
+ The batch record written by `code-review prepare` stays immutable. Progress
4
+ lives in `<review-id>.state.json`, updated only under its lock, so concurrent
5
+ `start` and `await` calls cannot lose each other's updates.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import os
11
+ import re
12
+ import subprocess
13
+ import sys
14
+ import time
15
+ from collections.abc import Iterator, Mapping
16
+ from contextlib import contextmanager
17
+ from dataclasses import dataclass
18
+ from pathlib import Path
19
+
20
+ PURPOSE = "code-review"
21
+ STATE_SCHEMA_VERSION = 1
22
+ TERMINAL = ("completed", "failed", "stalled")
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class AwaitResult:
27
+ done: bool
28
+ complete: bool
29
+ state: dict
30
+
31
+
32
+ def start_review_batch(project_root: Path, batch_path: Path, *, max_calls: int | None = None) -> dict:
33
+ """Launch every item that has not started yet; return the updated state."""
34
+ project, batch = _load_batch(project_root, batch_path)
35
+ with _locked_state(project, batch) as state:
36
+ if max_calls is not None:
37
+ state["maxCalls"] = max_calls
38
+ pending = [item for item in batch["items"]
39
+ if state["items"].get(item["invocationId"], {}).get("state", "pending") == "pending"]
40
+ _launch(project, pending, state)
41
+ return state
42
+
43
+
44
+ def await_review_batch(
45
+ project_root: Path, batch_path: Path, *, timeout_seconds: float, poll_seconds: float = 2.0,
46
+ ) -> AwaitResult:
47
+ """Advance items until all are terminal or the timeout passes, then audit."""
48
+ project, batch = _load_batch(project_root, batch_path)
49
+ deadline = time.monotonic() + timeout_seconds
50
+ while True:
51
+ with _locked_state(project, batch) as state:
52
+ _, batch = _load_batch(project_root, batch_path)
53
+ pending = [item["invocationId"] for item in batch["items"]
54
+ if state["items"].get(item["invocationId"], {}).get("state", "pending") == "pending"]
55
+ if pending:
56
+ raise ValueError("items not started; run code-review start: " + ", ".join(pending))
57
+ for item in batch["items"]:
58
+ _advance(project, batch, item, state["items"][item["invocationId"]])
59
+ repairs = automatic_repairs(project, batch, state)
60
+ if repairs:
61
+ from .code_review_prepare import add_review_attempts
62
+
63
+ _launch(project, add_review_attempts(project, batch_path, state, repairs), state)
64
+ continue
65
+ if all(state["items"][item["invocationId"]]["state"] in TERMINAL for item in batch["items"]):
66
+ _audit(project, batch, state)
67
+ complete = all(not audit["missing"] and not audit["unknown"] and not audit["error"]
68
+ for audit in (*state["axes"].values(), *state["teams"].values()))
69
+ return AwaitResult(True, complete, state)
70
+ if time.monotonic() >= deadline:
71
+ return AwaitResult(False, False, state)
72
+ time.sleep(poll_seconds)
73
+
74
+
75
+ # Parser rejections about how a row is written, not about what it claims.
76
+ # A missing row counts only when the response produced no verdict at all:
77
+ # with some verdicts present, a missing row is an omission for the lead.
78
+ _FORMAT_REASONS = frozenset({
79
+ "expected Cell, Checked, N/A, Findings, Evidence columns",
80
+ "duplicate cell row",
81
+ "duplicate or conflicting rule verdicts",
82
+ "n/a needs an inline applicability reason, not an alias",
83
+ "invalid finding ID",
84
+ "clean check evidence names an unchecked rule",
85
+ "clean check evidence needs source path:line and an observation",
86
+ "clean check evidence needs an observation, not a verdict label",
87
+ })
88
+ _FORMAT_REASON_PATTERNS = (
89
+ re.compile(r"finding \S+ has no finding body"),
90
+ re.compile(r"empty or duplicate rule assignment: .*"),
91
+ re.compile(r"missing clean check evidence: .*"),
92
+ )
93
+ _MISSING_ROW = "no grouped verdict row"
94
+
95
+
96
+ def format_only_cells(audit: Mapping) -> dict[str, str]:
97
+ """The rejected cells of one attempt when every rejection is about format; else empty."""
98
+ missing = audit.get("missing") or {}
99
+ if not missing or audit.get("unknown"):
100
+ return {}
101
+ for reason in missing.values():
102
+ if reason == _MISSING_ROW:
103
+ if audit.get("covered"):
104
+ return {}
105
+ elif reason not in _FORMAT_REASONS and not any(
106
+ pattern.fullmatch(reason) for pattern in _FORMAT_REASON_PATTERNS
107
+ ):
108
+ return {}
109
+ return dict(missing)
110
+
111
+
112
+ def automatic_repairs(project: Path, batch: Mapping, state: Mapping) -> list:
113
+ """The two repairs the review workflow pre-authorizes, once per team and axis.
114
+
115
+ A wrapper that exits nonzero without a returned body gets one retry; an
116
+ attempt whose rejected cells were all rejected for format gets one format
117
+ repair for those cells. Every other open cell waits for the lead's gap-fill.
118
+ """
119
+ from .code_review_prepare import AttemptRequest, latest_items
120
+ from .review_verdicts import read_review_census
121
+
122
+ requests = []
123
+ for (team, axis), item in sorted(latest_items(batch).items()):
124
+ row = state["items"].get(item["invocationId"], {})
125
+ kinds = {other.get("kind") for other in batch["items"] if (other["team"], other["axis"]) == (team, axis)}
126
+ cells = tuple(read_review_census(project / item["census"]).cells)
127
+ if (row.get("state") == "failed" and row.get("noBody") and "retry" not in kinds):
128
+ requests.append(AttemptRequest(team, axis, "retry", cells))
129
+ elif row.get("state") == "completed" and "format" not in kinds:
130
+ rejected = format_only_cells(row["audit"])
131
+ if rejected:
132
+ requests.append(AttemptRequest(team, axis, "format", tuple(sorted(rejected)), rejected))
133
+ limit = state.get("maxCalls")
134
+ if requests and limit is not None and state["calls"] + len(requests) > limit:
135
+ return []
136
+ return requests
137
+
138
+
139
+ def render_state(batch_path: Path, result: AwaitResult | dict) -> str:
140
+ state = result.state if isinstance(result, AwaitResult) else result
141
+ rows = [f"Batch: {batch_path}\n", f"Calls started: {state['calls']}\n"]
142
+ for identity, row in state["items"].items():
143
+ audit = row.get("audit") or {}
144
+ rows.append(
145
+ f"Item: {identity} | {row['state']} | exit {row.get('exitCode', '-')} | "
146
+ f"missing {len(audit.get('missing', []))} | unknown {len(audit.get('unknown', []))} | "
147
+ f"{row.get('completion') or row.get('reason') or '-'}\n"
148
+ )
149
+ for axis, audit in sorted(state.get("axes", {}).items()):
150
+ rows.append(
151
+ f"Axis: {axis} | covered {audit.get('covered', 0)} | missing {len(audit.get('missing', []))} | "
152
+ f"unknown {len(audit.get('unknown', []))} | {audit.get('error') or '-'}\n"
153
+ )
154
+ for team, audit in sorted(state.get("teams", {}).items()):
155
+ rows.append(
156
+ f"Team: {team} | covered {audit.get('covered', 0)} | missing {len(audit.get('missing', []))} | "
157
+ f"unknown {len(audit.get('unknown', []))} | {audit.get('error') or '-'}\n"
158
+ )
159
+ if isinstance(result, AwaitResult):
160
+ rows.append(("ALL_DONE" if result.done else "POLL_TIMEOUT") + "\n")
161
+ return "".join(rows)
162
+
163
+
164
+ def _launch(project: Path, items: list, state: dict) -> None:
165
+ limit = state.get("maxCalls")
166
+ if limit is not None and state["calls"] + len(items) > limit:
167
+ raise ValueError(f"starting {len(items)} calls would exceed --max-calls {limit}; "
168
+ f"{state['calls']} already started")
169
+ (_root(project) / ".tmp").mkdir(exist_ok=True)
170
+ for item in items:
171
+ identity = item["invocationId"]
172
+ paths = _item_paths(project, identity)
173
+ if any(path.exists() for path in paths.values()):
174
+ raise ValueError(f"{identity} already has run output; prepare a new attempt instead")
175
+ command = [
176
+ sys.executable, "-P", "-m", "okstra_ctl.code_review_supervisor",
177
+ str(paths["exit"]), str(paths["returned"]), str(paths["stderr"]), "--",
178
+ str(_wrapper(item)), str(project), item["modelExecutionValue"],
179
+ str(project / item["prompt"]), "", item["role"],
180
+ "--invocation-metadata", str(project / item["metadata"]),
181
+ ]
182
+ process = subprocess.Popen(
183
+ command, cwd=project, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
184
+ stderr=subprocess.DEVNULL, start_new_session=True, env=_child_env(),
185
+ )
186
+ state["items"][identity] = {"state": "started", "pid": process.pid, "startedAt": time.time()}
187
+ state["calls"] += 1
188
+
189
+
190
+ def _advance(project: Path, batch: Mapping, item: Mapping, row: dict) -> None:
191
+ identity = item["invocationId"]
192
+ paths = _item_paths(project, identity)
193
+ if row["state"] == "started":
194
+ if paths["exit"].exists():
195
+ record = json.loads(paths["exit"].read_text(encoding="utf-8"))
196
+ row.update(state="exited", exitCode=record["exitCode"])
197
+ elif not _alive(row["pid"]):
198
+ row.update(state="stalled", reason="supervisor ended without an exit record")
199
+ return
200
+ else:
201
+ return
202
+ if row["state"] == "exited":
203
+ reason = _failure(project, item, row["exitCode"], paths)
204
+ if reason:
205
+ no_body = not paths["returned"].exists() or not paths["returned"].read_bytes().strip()
206
+ row.update(state="failed", reason=reason,
207
+ noBody=no_body and not reason.startswith("write audit violation"))
208
+ return
209
+ row["state"] = "result"
210
+ if row["state"] == "result":
211
+ try:
212
+ row["completion"] = _finalize(project, item, paths)
213
+ except (OSError, ValueError) as exc:
214
+ row.update(state="failed", reason=f"finalization failed: {exc}")
215
+ return
216
+ row["state"] = "completed"
217
+ if row["state"] == "completed" and "audit" not in row:
218
+ row["audit"] = _coverage(project, batch, project / item["census"],
219
+ [project / row["completion"]])
220
+
221
+
222
+ def _failure(project: Path, item: Mapping, code: int, paths: Mapping[str, Path]) -> str:
223
+ status_path = project / f"{item['prompt']}.status.json"
224
+ status = json.loads(status_path.read_text(encoding="utf-8")) if status_path.exists() else {}
225
+ audit = status.get("writeAudit") or {}
226
+ if isinstance(audit, dict) and audit.get("violations"):
227
+ return "write audit violation: " + "; ".join(map(str, audit["violations"]))
228
+ if code != 0:
229
+ detail = status.get("failure") or _last_line(paths["stderr"]) or "no diagnostic"
230
+ return f"exit {code}: {detail}"
231
+ if not paths["returned"].exists() or not paths["returned"].read_bytes().strip():
232
+ return "exit 0 without a returned body"
233
+ return ""
234
+
235
+
236
+ def _finalize(project: Path, item: Mapping, paths: Mapping[str, Path]) -> str:
237
+ from datetime import datetime, timezone
238
+
239
+ from .agent.invocation import (
240
+ AgentInvocationError, materialize_standalone_result, publish_standalone_completion,
241
+ verify_standalone_completion,
242
+ )
243
+ from .agent.standalone import standalone_returned_body
244
+
245
+ metadata = project / item["metadata"]
246
+ prompt = project / item["prompt"]
247
+ result = _root(project) / f"{item['invocationId']}.result.json"
248
+ completion = prompt.with_name(prompt.name + ".completion.json")
249
+ try:
250
+ if not result.exists():
251
+ materialize_standalone_result(
252
+ project_root=project, purpose=PURPOSE, metadata_path=metadata,
253
+ returned_body=standalone_returned_body(project, PURPOSE, paths["returned"]),
254
+ )
255
+ if not completion.exists():
256
+ completion = publish_standalone_completion(
257
+ project_root=project, purpose=PURPOSE, metadata_path=metadata,
258
+ completed_at=datetime.now(timezone.utc),
259
+ )
260
+ verify_standalone_completion(completion, project_root=project, expected_purpose=PURPOSE)
261
+ except AgentInvocationError as exc:
262
+ raise ValueError(str(exc)) from exc
263
+ return completion.resolve().relative_to(project).as_posix()
264
+
265
+
266
+ def _audit(project: Path, batch: Mapping, state: dict) -> None:
267
+ """Audit every team-axis over its attempts, then every team over the full census."""
268
+ from .code_review_prepare import _first_attempt
269
+
270
+ completed: dict[tuple[int, str], list[tuple[int, Path]]] = {}
271
+ for item in batch["items"]:
272
+ row = state["items"][item["invocationId"]]
273
+ if row["state"] == "completed":
274
+ completed.setdefault((item["team"], item["axis"]), []).append(
275
+ (item["attempt"], project / row["completion"]))
276
+ state["axes"], state["teams"] = {}, {}
277
+ for team, axis in sorted({(item["team"], item["axis"]) for item in batch["items"]}):
278
+ census = project / _first_attempt(batch, team, axis)["census"]
279
+ state["axes"][f"{team}/{axis}"] = _coverage_of(project, batch, census, completed.get((team, axis), []))
280
+ for team in sorted({item["team"] for item in batch["items"]}):
281
+ entries = [entry for (owner, _), rows in completed.items() if owner == team for entry in rows]
282
+ state["teams"][str(team)] = _coverage_of(project, batch, project / batch["census"], entries)
283
+
284
+
285
+ def _coverage_of(project: Path, batch: Mapping, census: Path, entries: list) -> dict:
286
+ if not entries:
287
+ return {"covered": 0, "missing": {}, "unknown": [], "verdicts": {},
288
+ "error": "no completed specialist"}
289
+ return _coverage(project, batch, census, completion_order(entries))
290
+
291
+
292
+ def completion_order(completions: list[tuple[int, Path]]) -> list[Path]:
293
+ """Latest attempt first, so the coverage parser's first usable row is the newest."""
294
+ return [path for _, path in sorted(completions, key=lambda entry: -entry[0])]
295
+
296
+
297
+ def _coverage(project: Path, batch: Mapping, census: Path, completions: list[Path]) -> dict:
298
+ from .agent.invocation import AgentInvocationError
299
+ from .code_review_coverage import check_review_coverage
300
+
301
+ try:
302
+ result = check_review_coverage(project, census, completions, batch["head"], base=batch["base"])
303
+ except (OSError, ValueError, AgentInvocationError) as exc:
304
+ return {"covered": 0, "missing": {}, "unknown": [], "verdicts": {}, "error": str(exc)}
305
+ return {"covered": len(result.verdicts), "missing": dict(sorted(result.missing.items())),
306
+ "unknown": list(result.unknown),
307
+ "verdicts": {cell: list(verdict) for cell, verdict in sorted(result.verdicts.items())},
308
+ "error": ""}
309
+
310
+
311
+ def _load_batch(project_root: Path, batch_path: Path) -> tuple[Path, dict]:
312
+ project = project_root.resolve()
313
+ batch_path = batch_path.resolve(strict=True)
314
+ if batch_path.parent != _root(project).resolve() or not batch_path.name.endswith(".batch.json"):
315
+ raise ValueError("batch must be <review-id>.batch.json in the code-review artifact directory")
316
+ batch = json.loads(batch_path.read_text(encoding="utf-8"))
317
+ if batch.get("schemaVersion") != 1 or batch.get("projectRoot") != str(project):
318
+ raise ValueError("batch belongs to another project root or schema")
319
+ return project, batch
320
+
321
+
322
+ @contextmanager
323
+ def _locked_state(project: Path, batch: Mapping) -> Iterator[dict]:
324
+ from .agent.invocation import _exclusive_lock
325
+
326
+ root = _root(project)
327
+ path = root / f"{batch['reviewId']}.state.json"
328
+ with _exclusive_lock(root / f".{batch['reviewId']}.state.lock"):
329
+ if path.exists():
330
+ state = json.loads(path.read_text(encoding="utf-8"))
331
+ else:
332
+ state = {"schemaVersion": STATE_SCHEMA_VERSION, "reviewId": batch["reviewId"],
333
+ "calls": 0, "items": {}, "axes": {}, "teams": {}}
334
+ yield state
335
+ temporary = path.with_name(path.name + ".partial")
336
+ temporary.write_text(json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
337
+ os.replace(temporary, path)
338
+
339
+
340
+ def _item_paths(project: Path, identity: str) -> dict[str, Path]:
341
+ tmp = _root(project) / ".tmp"
342
+ return {"returned": tmp / f"{identity}.returned.txt", "stderr": tmp / f"{identity}.stderr.txt",
343
+ "exit": tmp / f"{identity}.exit.json"}
344
+
345
+
346
+ def _wrapper(item: Mapping) -> Path:
347
+ from .paths import okstra_home
348
+
349
+ wrapper = Path(str(item["wrapper"]))
350
+ return wrapper if wrapper.is_absolute() else okstra_home() / "bin" / wrapper
351
+
352
+
353
+ def _child_env() -> dict[str, str]:
354
+ package_root = str(Path(__file__).resolve().parents[1])
355
+ env = dict(os.environ)
356
+ env["PYTHONPATH"] = os.pathsep.join(filter(None, (package_root, env.get("PYTHONPATH"))))
357
+ return env
358
+
359
+
360
+ def _alive(pid: int) -> bool:
361
+ try:
362
+ reaped, _ = os.waitpid(pid, os.WNOHANG)
363
+ if reaped:
364
+ return False
365
+ except ChildProcessError:
366
+ pass
367
+ try:
368
+ os.kill(pid, 0)
369
+ except ProcessLookupError:
370
+ return False
371
+ except PermissionError:
372
+ return True
373
+ return True
374
+
375
+
376
+ def _last_line(path: Path) -> str:
377
+ if not path.exists():
378
+ return ""
379
+ lines = [line for line in path.read_text(encoding="utf-8", errors="replace").splitlines() if line.strip()]
380
+ return lines[-1] if lines else ""
381
+
382
+
383
+ def _root(project: Path) -> Path:
384
+ return project / ".okstra" / "agent-invocations" / PURPOSE
@@ -5,13 +5,17 @@ import hashlib
5
5
  import re
6
6
  from dataclasses import dataclass
7
7
  from pathlib import Path, PurePosixPath
8
+ from collections.abc import Sequence
8
9
 
9
10
  from .agent.invocation import verify_standalone_completion
10
11
  from .fixed_text import scalar
11
- from .code_review_coverage import (
12
- ReviewCensus, _HeadTree, _head_tree, _table_fields, check_review_coverage,
13
- read_review_census,
12
+ from .code_review_coverage import check_review_coverage
13
+ from .review_verdicts import (
14
+ ReviewCensus, _HeadTree, _head_tree, _table_fields, read_review_census,
14
15
  )
16
+ from .verification_input_types import FrozenReviewPolicy
17
+ from .qa_procedures import canonical_json_digest
18
+ from .review_policy import select_review_policy
15
19
 
16
20
 
17
21
  @dataclass(frozen=True)
@@ -30,21 +34,35 @@ class ReviewScope:
30
34
  )
31
35
 
32
36
 
33
- def _rule_digest(census: ReviewCensus, policies: list[Path]) -> str:
37
+ def _rule_digest(
38
+ census: ReviewCensus, policies: list[Path], policy: FrozenReviewPolicy | None = None,
39
+ resources: Sequence[str] = (),
40
+ ) -> str:
34
41
  digest = hashlib.sha256()
35
42
  values = [repr(census.rules), repr(census.references)]
43
+ if resources:
44
+ values.append(repr(tuple(resources)))
45
+ if policy is not None:
46
+ values.append(canonical_json_digest(policy))
36
47
  for reference in census.references.values():
37
48
  for location in reference.split(";"):
38
49
  name = re.sub(r":\d+(?:-\d+)?$", "", location.strip().partition("#")[0])
39
- values.append(
40
- hashlib.sha256(Path(name).expanduser().read_bytes()).hexdigest()
41
- )
42
- values.extend(hashlib.sha256(path.read_bytes()).hexdigest() for path in policies)
50
+ values.append(_policy_source_digest(Path(name).expanduser(), policy))
51
+ values.extend(_policy_source_digest(path, policy) for path in policies)
43
52
  for value in values:
44
53
  digest.update(value.encode() + b"\0")
45
54
  return digest.hexdigest()
46
55
 
47
56
 
57
+ def _policy_source_digest(path: Path, policy: FrozenReviewPolicy | None) -> str:
58
+ if policy is None:
59
+ return hashlib.sha256(path.read_bytes()).hexdigest()
60
+ source = policy["sources"].get(str(path.absolute()))
61
+ if source is None:
62
+ raise ValueError(f"review reference was not captured in the frozen policy: {path}")
63
+ return source["digest"]
64
+
65
+
48
66
  def _dependencies(body: str, census: ReviewCensus) -> dict[str, set[str]]:
49
67
  dependencies: dict[str, set[str]] = {}
50
68
  section = ""
@@ -82,17 +100,39 @@ def _prior_inputs(
82
100
  return dependencies
83
101
 
84
102
 
103
+ def shared_review_policy(census_path: Path, policy_path: Path) -> FrozenReviewPolicy:
104
+ """Read the shared frozen policy a census names by digest."""
105
+ from .qa_procedures import content_digest
106
+ from .review_policy import read_review_policy
107
+
108
+ digests = [row.removeprefix("Review policy digest: ")
109
+ for row in census_path.read_text(encoding="utf-8").splitlines()
110
+ if row.startswith("Review policy digest: ")]
111
+ if digests != [content_digest(policy_path.read_bytes())]:
112
+ raise ValueError("census review policy digest is missing or differs from the shared policy")
113
+ return read_review_policy(policy_path)
114
+
115
+
85
116
  def review_scope(
86
117
  root: Path, census_path: Path, base: str, head: str, policies: list[Path], *,
87
118
  previous_head: str = "", previous_census: Path | None = None,
88
119
  completions: list[Path] | None = None,
120
+ policy: FrozenReviewPolicy | None = None,
89
121
  ) -> ReviewScope:
90
122
  census = read_review_census(census_path)
123
+ selections = [line.removeprefix("Review resources: ")
124
+ for line in census_path.read_text(encoding="utf-8").splitlines()
125
+ if line.startswith("Review resources: ")]
126
+ if len(selections) > 1:
127
+ raise ValueError("review census repeats its resource selection")
128
+ resources = tuple(part.strip() for part in selections[0].split(";")) if selections and selections[0] != "-" else ()
129
+ if policy is not None:
130
+ select_review_policy(policy, resources=resources)
91
131
  current = _head_tree(root, head)
92
132
  base_commit = _head_tree(root, base).commit
93
133
  if current._git("merge-base", "--is-ancestor", base_commit, current.commit).returncode:
94
134
  raise ValueError("review base is not an ancestor of head")
95
- rules = _rule_digest(census, policies)
135
+ rules = _rule_digest(census, policies, policy, resources)
96
136
  baseline = (
97
137
  f"Review base: {base_commit}\nReview head: {current.commit}\n"
98
138
  f"Review rules: {rules}\n"
@@ -0,0 +1,41 @@
1
+ """Run one provider wrapper and record its exit, even when the wrapper never starts.
2
+
3
+ `code-review start` launches this module in a new session and returns, so the
4
+ wrapper keeps running after the lead's command ends. The wrapper writes its own
5
+ status file only once it has passed preflight; the exit record written here is
6
+ what tells `code-review await` that a preflight failure already ended the item.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import os
12
+ import subprocess
13
+ import sys
14
+ import time
15
+ from pathlib import Path
16
+
17
+
18
+ def main(argv: list[str]) -> int:
19
+ if len(argv) < 5 or argv[3] != "--":
20
+ print("usage: code_review_supervisor <exit.json> <stdout> <stderr> -- <command...>",
21
+ file=sys.stderr)
22
+ return 64
23
+ exit_path, stdout_path, stderr_path = (Path(value) for value in argv[:3])
24
+ command = argv[4:]
25
+ started = time.time()
26
+ try:
27
+ with stdout_path.open("wb") as stdout, stderr_path.open("wb") as stderr:
28
+ code = subprocess.run(command, stdin=subprocess.DEVNULL, stdout=stdout,
29
+ stderr=stderr, check=False).returncode
30
+ except OSError as exc:
31
+ stderr_path.write_text(f"supervisor could not start the wrapper: {exc}\n", encoding="utf-8")
32
+ code = 127
33
+ record = {"exitCode": code, "startedAt": started, "endedAt": time.time(), "pid": os.getpid()}
34
+ temporary = exit_path.with_name(exit_path.name + ".partial")
35
+ temporary.write_text(json.dumps(record) + "\n", encoding="utf-8")
36
+ os.replace(temporary, exit_path)
37
+ return 0
38
+
39
+
40
+ if __name__ == "__main__":
41
+ raise SystemExit(main(sys.argv[1:]))