okstra 0.232.0 → 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 (183) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +8 -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/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +36 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +279 -2
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +31 -41
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  77. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  78. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  79. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  80. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  81. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  82. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  83. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  84. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  85. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  86. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  87. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  88. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  89. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  90. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  91. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  92. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  93. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  94. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  95. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  96. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  97. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  98. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  99. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  100. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  101. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  102. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  103. package/runtime/python/okstra_ctl/material.py +2 -0
  104. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  105. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  106. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  107. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  108. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  109. package/runtime/python/okstra_ctl/paths.py +6 -1
  110. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  111. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  112. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  113. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  114. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  115. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  116. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  117. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  118. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  119. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  120. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  121. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  122. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  123. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  124. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  125. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  126. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  127. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  128. package/runtime/python/okstra_ctl/render.py +28 -2
  129. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  130. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  131. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  132. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  133. package/runtime/python/okstra_ctl/report_language.py +4 -1
  134. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  135. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  136. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  137. package/runtime/python/okstra_ctl/run.py +43 -35
  138. package/runtime/python/okstra_ctl/run_context.py +10 -1
  139. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  140. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  141. package/runtime/python/okstra_ctl/task_query.py +239 -0
  142. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  143. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  144. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  145. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  146. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  147. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  148. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  149. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  150. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  151. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  152. package/runtime/python/okstra_project/state.py +20 -0
  153. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  154. package/runtime/python/okstra_token_usage/cli.py +23 -10
  155. package/runtime/python/okstra_token_usage/collect.py +25 -22
  156. package/runtime/python/okstra_token_usage/policy.py +193 -0
  157. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  158. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  159. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  160. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  161. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  162. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  163. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  164. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  165. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  166. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  167. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  168. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  169. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  170. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  171. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  172. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  173. package/runtime/skills/okstra-run/SKILL.md +55 -183
  174. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  175. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  176. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  177. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  178. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  179. package/runtime/templates/manager/view.template.html +4 -0
  180. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  181. package/runtime/templates/trace/trace.template.md +42 -0
  182. package/runtime/validators/checks/fixtures-02.py +25 -33
  183. package/runtime/validators/validate-run.py +93 -36
@@ -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
@@ -100,6 +100,19 @@ def _prior_inputs(
100
100
  return dependencies
101
101
 
102
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
+
103
116
  def review_scope(
104
117
  root: Path, census_path: Path, base: str, head: str, policies: list[Path], *,
105
118
  previous_head: str = "", previous_census: Path | None = None,
@@ -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:]))
@@ -94,6 +94,11 @@ _CLI_EPILOG = r"""Usage:
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
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> ...]
97
+ okstra code-review assign --census <review-id>.census.md [--project-root <dir>]
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
+ okstra code-review start --batch <id>.batch.json [--max-calls <n>]
100
+ okstra code-review await --batch <id>.batch.json --timeout-seconds <s>
101
+ okstra code-review gap-fill --batch <id>.batch.json [--reject <team>:<cell-id> ...]
97
102
  okstra code-review scope --base <ref> --head <ref> --census <path> --review-policy <shared-policy-path> [--policy <captured-path> ...] [--previous-head <ref> --previous-census <path> --completion <path> ...]
98
103
  okstra code-review check-lines --base <ref> --head <ref> --cite <path:line> [--cite ...] [--project-root <dir>]
99
104
 
@@ -113,7 +118,19 @@ base evidence at `--base`, never the working tree, prints covered cells, missing
113
118
  prints its Review policy path/digest, and selects its shared catalog with the
114
119
  captured architecture. --run-manifest reuses frozen implementation rules;
115
120
  --policy captures additional applied standards. It exits 1 when changed
116
- non-Python code still needs function cells added by hand. Scope reads frozen
121
+ non-Python code still needs function cells added by hand. `assign` writes one
122
+ <review-id>.<axis>.census.md per axis that has cells beside the census and
123
+ prints each axis's cell count and path (`-` for an axis without cells); an
124
+ existing assignment is reused only when identical. `prepare` assigns the census,
125
+ then scopes, materializes (cli-wrapper runner) and verifies one prompt per model
126
+ team and axis, and writes <review-id>.batch.json. `start` launches each
127
+ prepared wrapper in its own session under a supervisor that records the exit;
128
+ `await` finalizes, verifies and audits finished items, prints ALL_DONE (exit 0
129
+ complete, 1 incomplete) or POLL_TIMEOUT (exit 75), and can be called again;
130
+ it retries a wrapper that exited nonzero without a body once and repairs a
131
+ format-only rejection once. `gap-fill` prepares the next attempt for open or
132
+ rejected cells (run `start` next) and prints NO_PROGRESS for a team/axis whose
133
+ last gap-fill closed nothing. Scope reads frozen
117
134
  policy bodies; legacy scope without --review-policy requires --policy files.
118
135
  """
119
136
 
@@ -127,7 +144,7 @@ def _build_parser() -> argparse.ArgumentParser:
127
144
  )
128
145
  parser.add_argument(
129
146
  "command",
130
- choices=("target", "check-lines", "check-coverage", "scope", "census"),
147
+ choices=("target", "check-lines", "check-coverage", "scope", "census", "assign", "prepare", "start", "await", "gap-fill"),
131
148
  )
132
149
  parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
133
150
  parser.add_argument("--stage", type=int, default=0, help="stage number to review")
@@ -159,7 +176,20 @@ def _build_parser() -> argparse.ArgumentParser:
159
176
  parser.add_argument("--review-policy", default="", help="scope: shared frozen review policy")
160
177
  parser.add_argument("--run-manifest", default="", help="census: reuse this run's frozen review policy")
161
178
  parser.add_argument("--resource", action="append", default=[],
162
- help="census: additional captured pack-relative rule resource")
179
+ help="census, prepare: additional captured pack-relative rule resource")
180
+ parser.add_argument("--review-id", default="", help="prepare: slug naming this review round")
181
+ parser.add_argument("--slots", default="", help="prepare: resolve-operation --json output")
182
+ parser.add_argument("--brief", default="", help="prepare: shared specialist brief")
183
+ parser.add_argument("--host-runtime", default="", help="prepare: registered host id")
184
+ parser.add_argument("--batch", default="", help="start, await, gap-fill: <review-id>.batch.json")
185
+ parser.add_argument("--previous-batch", default="",
186
+ help="prepare: previous round's batch whose completions become carry candidates")
187
+ parser.add_argument("--reject", action="append", default=[],
188
+ help="gap-fill: <team>:<cell-id> whose verdict the lead rejected")
189
+ parser.add_argument("--max-calls", type=int, default=None,
190
+ help="start: refuse to exceed this many started calls for the review")
191
+ parser.add_argument("--timeout-seconds", type=float, default=None,
192
+ help="await: stop waiting after this many seconds and print POLL_TIMEOUT")
163
193
  parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
164
194
  parser.add_argument("--project-root", default="", help="explicit project root")
165
195
  parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
@@ -362,6 +392,14 @@ def main(argv: list[str] | None = None) -> int:
362
392
  return _scope(args, Path(project_root))
363
393
  if args.command == "census":
364
394
  return _census(args, Path(project_root))
395
+ if args.command == "assign":
396
+ return _assign(args, Path(project_root))
397
+ if args.command == "prepare":
398
+ return _prepare(args, Path(project_root))
399
+ if args.command in ("start", "await"):
400
+ return _run(args, Path(project_root))
401
+ if args.command == "gap-fill":
402
+ return _gap_fill(args, Path(project_root))
365
403
  if args.command == "check-coverage":
366
404
  return _check_coverage(args, Path(project_root))
367
405
  if args.command == "check-lines":
@@ -431,6 +469,102 @@ def _census(args: argparse.Namespace, project_root: Path) -> int:
431
469
  return 1 if result.unresolved else 0
432
470
 
433
471
 
472
+ def _assign(args: argparse.Namespace, project_root: Path) -> int:
473
+ from .code_review_census import ASSIGNMENT_AXES, write_review_assignments
474
+ from .review_verdicts import read_review_census
475
+
476
+ if not args.census:
477
+ print("assign: pass --census <review-id>.census.md", file=sys.stderr)
478
+ return 2
479
+ try:
480
+ outputs = write_review_assignments(project_root, Path(args.census).absolute())
481
+ counts = {axis: len(read_review_census(path).cells) for axis, path in outputs.items()}
482
+ except (OSError, ValueError) as exc:
483
+ print(f"assign: {exc}", file=sys.stderr)
484
+ return 2
485
+ for axis in ASSIGNMENT_AXES:
486
+ print(f"Axis: {axis}")
487
+ print(f"Cells: {counts.get(axis, 0)}")
488
+ print(f"Census: {outputs.get(axis, '-')}")
489
+ return 0
490
+
491
+
492
+ def _prepare(args: argparse.Namespace, project_root: Path) -> int:
493
+ from .code_review_prepare import prepare_review_batch, render_batch_summary
494
+
495
+ required = (args.review_id, args.census, args.review_policy, args.base, args.head,
496
+ args.slots, args.brief, args.host_runtime)
497
+ if not all(required):
498
+ print("prepare: pass --review-id, --census, --review-policy, --base, --head, "
499
+ "--slots, --brief and --host-runtime", file=sys.stderr)
500
+ return 2
501
+ try:
502
+ batch = prepare_review_batch(
503
+ project_root=project_root, review_id=args.review_id, census=Path(args.census),
504
+ policy=Path(args.review_policy).absolute(), base=args.base, head=args.head,
505
+ slots_path=Path(args.slots), brief=Path(args.brief),
506
+ host_runtime=args.host_runtime, resources=args.resource,
507
+ previous_batch=Path(args.previous_batch) if args.previous_batch else None,
508
+ )
509
+ except (OSError, ValueError) as exc:
510
+ print(f"prepare: {exc}", file=sys.stderr)
511
+ return 2
512
+ print(render_batch_summary(batch), end="")
513
+ return 0
514
+
515
+
516
+ def _run(args: argparse.Namespace, project_root: Path) -> int:
517
+ from .code_review_run import await_review_batch, render_state, start_review_batch
518
+
519
+ if not args.batch or (args.command == "await" and args.timeout_seconds is None):
520
+ print(f"{args.command}: pass --batch" + (" and --timeout-seconds" if args.command == "await" else ""),
521
+ file=sys.stderr)
522
+ return 2
523
+ batch = Path(args.batch)
524
+ try:
525
+ if args.command == "start":
526
+ print(render_state(batch, start_review_batch(project_root, batch, max_calls=args.max_calls)),
527
+ end="")
528
+ return 0
529
+ result = await_review_batch(project_root, batch, timeout_seconds=args.timeout_seconds)
530
+ except (OSError, ValueError) as exc:
531
+ print(f"{args.command}: {exc}", file=sys.stderr)
532
+ return 2
533
+ print(render_state(batch, result), end="")
534
+ if not result.done:
535
+ return 75
536
+ return 0 if result.complete else 1
537
+
538
+
539
+ def _gap_fill(args: argparse.Namespace, project_root: Path) -> int:
540
+ from .code_review_prepare import add_review_attempts, gap_fill_requests
541
+ from .code_review_run import _load_batch, _locked_state
542
+
543
+ if not args.batch:
544
+ print("gap-fill: pass --batch", file=sys.stderr)
545
+ return 2
546
+ try:
547
+ rejected: dict[int, list[str]] = {}
548
+ for value in args.reject:
549
+ team, sep, cell = value.partition(":")
550
+ if not sep or not team.isdigit() or not cell:
551
+ raise ValueError(f"--reject takes <team>:<cell-id>, got {value!r}")
552
+ rejected.setdefault(int(team), []).append(cell)
553
+ project, batch = _load_batch(project_root, Path(args.batch))
554
+ with _locked_state(project, batch) as state:
555
+ requests, stopped = gap_fill_requests(batch, state, rejected)
556
+ added = add_review_attempts(project, Path(args.batch), state, requests)
557
+ except (OSError, ValueError) as exc:
558
+ print(f"gap-fill: {exc}", file=sys.stderr)
559
+ return 2
560
+ for item in added:
561
+ print(f"Item: {item['invocationId']} | team {item['team']} | {item['axis']} | {item['census']}")
562
+ for pair in stopped:
563
+ print(f"NO_PROGRESS: {pair}")
564
+ print(f"Added: {len(added)}")
565
+ return 1 if stopped else 0
566
+
567
+
434
568
  def _census_review_policy(
435
569
  args: argparse.Namespace, project: Path, out: Path,
436
570
  ) -> tuple[Path, dict, str]:
@@ -471,29 +605,20 @@ def _census_review_policy(
471
605
 
472
606
  def _scope(args: argparse.Namespace, project_root: Path) -> int:
473
607
  from .agent.invocation import AgentInvocationError
474
- from .code_review_scope import review_scope
608
+ from .code_review_scope import review_scope, shared_review_policy
475
609
 
476
610
  if not (args.base and args.head and args.census and (args.policy or args.review_policy)):
477
611
  print("scope: pass --base, --head, --census and --review-policy or --policy", file=sys.stderr)
478
612
  return 2
479
613
  try:
480
- from .review_policy import read_review_policy
481
- from .qa_procedures import content_digest
482
-
483
- policy_path = Path(args.review_policy) if args.review_policy else None
484
- if policy_path is not None:
485
- digests = [row.removeprefix("Review policy digest: ")
486
- for row in Path(args.census).read_text(encoding="utf-8").splitlines()
487
- if row.startswith("Review policy digest: ")]
488
- if digests != [content_digest(policy_path.read_bytes())]:
489
- raise ValueError("census review policy digest is missing or differs from the shared policy")
490
614
  result = review_scope(
491
615
  project_root, Path(args.census), args.base, args.head,
492
616
  [Path(path).expanduser() for path in args.policy],
493
617
  previous_head=args.previous_head,
494
618
  previous_census=Path(args.previous_census) if args.previous_census else None,
495
619
  completions=[Path(path) for path in args.completion],
496
- policy=read_review_policy(policy_path) if policy_path is not None else None,
620
+ policy=shared_review_policy(Path(args.census), Path(args.review_policy))
621
+ if args.review_policy else None,
497
622
  )
498
623
  except (OSError, ValueError, AgentInvocationError) as exc:
499
624
  print(f"scope: {exc}", file=sys.stderr)