okstra 0.230.0 → 0.231.1

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 (75) hide show
  1. package/README.md +3 -3
  2. package/docs/architecture/storage-model.md +67 -6
  3. package/docs/architecture.md +6 -2
  4. package/docs/coding-rules.md +15 -0
  5. package/docs/project-structure-overview.md +2 -1
  6. package/package.json +2 -2
  7. package/runtime/BUILD.json +2 -2
  8. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  9. package/runtime/prompts/coding-preflight/overview.md +1 -0
  10. package/runtime/prompts/launch.template.md +2 -0
  11. package/runtime/prompts/lead/convergence.md +3 -3
  12. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  13. package/runtime/prompts/lead/report-writer.md +1 -1
  14. package/runtime/prompts/lead/team-contract.md +1 -1
  15. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  16. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  17. package/runtime/python/okstra_ctl/agent/invocation.py +48 -4
  18. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  19. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  20. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  21. package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
  22. package/runtime/python/okstra_ctl/convergence.py +112 -20
  23. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  24. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  25. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  26. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  27. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  28. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  29. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  30. package/runtime/python/okstra_ctl/paths.py +19 -4
  31. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +1 -0
  32. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  33. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +1 -0
  34. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  35. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +5 -1
  36. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +3 -1
  37. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +20 -4
  38. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  39. package/runtime/python/okstra_ctl/phases/implementation/spec.md +2 -0
  40. package/runtime/python/okstra_ctl/phases/implementation/validation.py +230 -30
  41. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  42. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  43. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  44. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  45. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  47. package/runtime/python/okstra_ctl/render.py +15 -0
  48. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  49. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  50. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  51. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  52. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  53. package/runtime/python/okstra_ctl/report_synthesis_packet.py +8 -0
  54. package/runtime/python/okstra_ctl/run.py +16 -0
  55. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  56. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  57. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  58. package/runtime/python/okstra_ctl/team.py +3 -1
  59. package/runtime/python/okstra_ctl/verification_dispatch.py +8 -2
  60. package/runtime/python/okstra_ctl/verification_evidence.py +26 -7
  61. package/runtime/python/okstra_ctl/verification_generation.py +12 -4
  62. package/runtime/python/okstra_ctl/verification_inputs.py +10 -0
  63. package/runtime/python/okstra_ctl/verification_invocation.py +2 -1
  64. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  65. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  66. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  67. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  68. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  69. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  70. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  71. package/runtime/skills/okstra-run/SKILL.md +5 -1
  72. package/runtime/templates/reports/html/i18n/en.json +7 -0
  73. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  74. package/runtime/validators/validate-run.py +27 -11
  75. package/runtime/validators/validate-workflow.sh +1 -1
@@ -24,8 +24,13 @@ from ..registry.provider_registry import default_provider_registry
24
24
  from ..worker_request import build_request
25
25
  from ..worker_runner import QUIET, run_worker
26
26
  from ..write_policy import build_write_policy, derive_write_enforcement
27
+ from ..wrapper_status import WrapperStatus, read_log_tail, read_wrapper_status
27
28
  from .contracts import OPERATION, BusinessFlowError, FlowRequest
28
29
 
30
+ # The message lands in the execution record's `error` field, so it carries
31
+ # the CLI's last lines rather than its whole transcript.
32
+ _EXIT_LOG_TAIL_BYTES = 800
33
+
29
34
 
30
35
  @dataclass(frozen=True)
31
36
  class PreparedCall:
@@ -111,14 +116,16 @@ class ProviderFlowExecutor:
111
116
  pool = ModelPool.from_registry(registry)
112
117
  selected = pool.resolve_alias(assignment["provider"], assignment["model"])
113
118
  request = _read_only_worker_request(call, assignment)
119
+ log_path = call.prompt_path.with_suffix(".log")
120
+ status_path = call.prompt_path.with_suffix(".status.json")
114
121
  output, errors = io.StringIO(), io.StringIO()
115
122
  with contextlib.redirect_stdout(output), contextlib.redirect_stderr(errors):
116
123
  code = run_worker(
117
124
  provider.exec_strategy,
118
125
  request,
119
126
  presentation=QUIET,
120
- log_path=call.prompt_path.with_suffix(".log"),
121
- status_path=call.prompt_path.with_suffix(".status.json"),
127
+ log_path=log_path,
128
+ status_path=status_path,
122
129
  status_extra={
123
130
  "writePolicy": request.policy.write_policy.to_payload(),
124
131
  "writeEnforcement": request.policy.write_enforcement.to_payload(),
@@ -130,11 +137,36 @@ class ProviderFlowExecutor:
130
137
  )
131
138
  if code:
132
139
  raise BusinessFlowError(
133
- f"business investigator exited {code}: {errors.getvalue().strip()}"
140
+ f"business investigator exited {code}: "
141
+ + _exit_cause(errors.getvalue(), status_path, log_path)
134
142
  )
135
143
  return output.getvalue().encode("utf-8")
136
144
 
137
145
 
146
+ def _exit_cause(stderr: str, status_path: Path, log_path: Path) -> str:
147
+ """run_worker writes the CLI's own output to the log, not to this
148
+ process's stderr, so the cause is read back from the status sidecar and
149
+ the log tail, with the log path for the rest."""
150
+ status = read_wrapper_status(status_path)
151
+ parts = (
152
+ stderr.strip(),
153
+ _sidecar_cause(status) if status is not None else "",
154
+ read_log_tail(log_path, _EXIT_LOG_TAIL_BYTES) or "",
155
+ f"log: {log_path}",
156
+ )
157
+ return "; ".join(part for part in parts if part)
158
+
159
+
160
+ def _sidecar_cause(status: WrapperStatus) -> str:
161
+ """An idle-watchdog kill records `timeout` and `idle_seconds` but no
162
+ `failure` (worker_runner.run_worker), so it is named separately."""
163
+ if not status.timeout:
164
+ return status.failure
165
+ idle = status.raw.get("idle_seconds")
166
+ timeout = f"idle timeout after {idle}s" if isinstance(idle, int) else "idle timeout"
167
+ return "; ".join(part for part in (status.failure, timeout) if part)
168
+
169
+
138
170
  def _read_only_worker_request(
139
171
  call: PreparedCall, assignment: dict[str, str]
140
172
  ) -> WorkerExecRequest:
@@ -6,22 +6,23 @@ verification needs a PASS from every verifier it dispatched.
6
6
  """
7
7
  from __future__ import annotations
8
8
 
9
+ from contextlib import contextmanager
9
10
  from dataclasses import dataclass, field
10
11
  from pathlib import Path
11
- from typing import Iterable, Mapping
12
+ from typing import Any, Iterable, Iterator, Mapping
12
13
 
13
- from .agent.invocation import AgentInvocationError
14
+ from .agent.invocation import AgentInvocationError, reserved_generation_reference
14
15
  from .conformance import QaResult, execution_evidence_defect, qa_result_from_execution
15
16
  from .execution_identity import ExecutionManifest, Invocation
16
17
  from .execution_manifest import read_execution_manifest
17
18
  from .json_boundary import JsonBoundaryError, load_owned_object
18
19
  from .paths import RunRef
19
20
  from .qa_commands import QA_VERIFIER_AUDIENCE_BY_TASK_TYPE
20
- from .qa_procedures import content_digest
21
21
  from .verification_conformance import conformance_stage
22
22
  from .verification_dispatch import verification_generation_number
23
23
  from .verification_evidence import (
24
- conformance_check_owner_ref, read_verification_execution_record,
24
+ VerificationExecutionRecord, conformance_check_owner_ref,
25
+ read_verification_execution_record,
25
26
  )
26
27
  from .verification_generation import (
27
28
  VerificationGenerationRecord, read_verification_generation,
@@ -37,6 +38,14 @@ class StageEvidence:
37
38
  records: tuple[Path, ...]
38
39
  rejections: Mapping[Path, str] = field(default_factory=dict)
39
40
 
41
+ def unusable_summary(self) -> str | None:
42
+ """Why a stage without a result has none, when its latest records were
43
+ rejected; None otherwise."""
44
+ if self.result is not None or not self.rejections:
45
+ return None
46
+ return "no usable execution record: " + "; ".join(
47
+ f"{path} ({reason})" for path, reason in self.rejections.items())
48
+
40
49
 
41
50
  @dataclass(frozen=True)
42
51
  class RunConformanceEvidence:
@@ -57,8 +66,8 @@ _NO_OUTCOME = _VerifierOutcome(None)
57
66
 
58
67
 
59
68
  @dataclass(frozen=True)
60
- class _BoundInvocation:
61
- """One verifier invocation and the generation its dispatch kind seals."""
69
+ class BoundInvocation:
70
+ """One verifier invocation and the generation its metadata binds."""
62
71
 
63
72
  invocation: Invocation
64
73
  generation_number: int
@@ -71,37 +80,74 @@ class _BoundInvocation:
71
80
  and stage in self.generation.get("conformanceStages", ()))
72
81
 
73
82
 
83
+ @dataclass(frozen=True)
84
+ class RunVerifiers:
85
+ """A QA-executing run's verifier invocations, newest first per role
86
+ execution, and each invocation's latest attempt."""
87
+
88
+ manifest: dict[str, Any]
89
+ ref: RunRef
90
+ verifiers: dict[str, list[BoundInvocation]]
91
+ latest_attempt: dict[str, int]
92
+
93
+
94
+ @dataclass(frozen=True)
95
+ class CheckRunRecord:
96
+ """The latest run of one check; `defect` says why it is no usable evidence
97
+ (None when it is)."""
98
+
99
+ check_run: int
100
+ path: Path
101
+ record: VerificationExecutionRecord | None
102
+ output: bytes | None
103
+ defect: str | None
104
+
105
+
106
+ @contextmanager
107
+ def evidence_read_errors() -> Iterator[None]:
108
+ """Raise an unreadable invocation or file as the ValueError evidence
109
+ collection reports."""
110
+ try:
111
+ yield
112
+ except (AgentInvocationError, OSError) as exc:
113
+ raise ValueError(str(exc)) from exc
114
+
115
+
74
116
  def collect_conformance_evidence(
75
117
  project: Path, manifest_path: Path, stage_keys: Iterable[str],
76
118
  ) -> RunConformanceEvidence:
77
- try:
119
+ with evidence_read_errors():
78
120
  return _collect(project.resolve(), manifest_path.resolve(), tuple(stage_keys))
79
- except (AgentInvocationError, OSError) as exc:
80
- raise ValueError(str(exc)) from exc
81
121
 
82
122
 
83
123
  def _collect(
84
124
  project: Path, manifest_path: Path, stage_keys: tuple[str, ...],
85
125
  ) -> RunConformanceEvidence:
126
+ run = load_run_verifiers(project, manifest_path)
127
+ owner = conformance_check_owner_ref(run.manifest)
128
+ counted = list(run.verifiers) if owner is None else [owner]
129
+ return RunConformanceEvidence(_required_stages(run.verifiers), {
130
+ key: _stage_evidence(run, counted, key) for key in stage_keys
131
+ })
132
+
133
+
134
+ def load_run_verifiers(project: Path, manifest_path: Path) -> RunVerifiers:
86
135
  manifest = load_owned_object(manifest_path, artifact="run manifest")
87
136
  ref = RunRef.from_manifest(manifest_path, manifest)
88
137
  audience = QA_VERIFIER_AUDIENCE_BY_TASK_TYPE.get(manifest.get("taskType"))
89
138
  if audience is None:
90
139
  raise ValueError("verification evidence requires a QA-executing run")
91
140
  execution = read_execution_manifest(manifest_path)
92
- verifiers = _bound_verifiers(project, ref, execution, audience)
93
- owner = conformance_check_owner_ref(manifest)
94
- counted = list(verifiers) if owner is None else [owner]
95
141
  latest_attempt = _latest_attempts(execution)
96
- return RunConformanceEvidence(_required_stages(verifiers), {
97
- key: _stage_evidence(ref, verifiers, counted, key, latest_attempt)
98
- for key in stage_keys
99
- })
142
+ return RunVerifiers(
143
+ manifest, ref,
144
+ _bound_verifiers(project, ref, manifest, execution, audience, latest_attempt),
145
+ latest_attempt,
146
+ )
100
147
 
101
148
 
102
149
  def _stage_evidence(
103
- ref: RunRef, verifiers: Mapping[str, list[_BoundInvocation]],
104
- counted: list[str], stage_key: str, latest_attempt: Mapping[str, int],
150
+ run: RunVerifiers, counted: list[str], stage_key: str,
105
151
  ) -> StageEvidence:
106
152
  """A counted verifier with no invocation bound to the newest generation that
107
153
  seals the stage leaves it without a result; an older generation's record
@@ -112,27 +158,27 @@ def _stage_evidence(
112
158
  # expected-miss: a malformed key names no stage a generation can seal,
113
159
  # so no record can exist for it.
114
160
  return StageEvidence(None, ())
115
- newest = max((binding.generation_number for bindings in verifiers.values()
161
+ newest = max((binding.generation_number for bindings in run.verifiers.values()
116
162
  for binding in bindings if binding.seals(stage)), default=None)
117
163
  if newest is None:
118
164
  return StageEvidence(None, ())
119
165
  return _combine([
120
- _verifier_result(ref, role_execution_ref, verifiers.get(role_execution_ref, []),
121
- newest, stage_key, latest_attempt)
166
+ _verifier_result(run, role_execution_ref, newest, stage_key)
122
167
  for role_execution_ref in counted
123
168
  ])
124
169
 
125
170
 
126
171
  def _bound_verifiers(
127
- project: Path, ref: RunRef, execution: ExecutionManifest, audience: str,
128
- ) -> dict[str, list[_BoundInvocation]]:
129
- """Each verifier's invocations, newest first."""
130
- verifiers: dict[str, list[_BoundInvocation]] = {}
172
+ project: Path, ref: RunRef, manifest: Mapping[str, Any],
173
+ execution: ExecutionManifest, audience: str, latest_attempt: Mapping[str, int],
174
+ ) -> dict[str, list[BoundInvocation]]:
175
+ verifiers: dict[str, list[BoundInvocation]] = {}
131
176
  for index, invocation in enumerate(execution.invocations):
132
177
  if invocation.duty_id == audience:
133
- verifiers.setdefault(invocation.role_execution_ref, []).append(
134
- _bind(project, ref, invocation, index),
135
- )
178
+ verifiers.setdefault(invocation.role_execution_ref, []).append(_bind(
179
+ project, ref, manifest, invocation, index,
180
+ latest_attempt.get(invocation.invocation_ref, 1),
181
+ ))
136
182
  for bindings in verifiers.values():
137
183
  bindings.sort(key=lambda binding: (binding.generation_number, binding.index),
138
184
  reverse=True)
@@ -146,7 +192,7 @@ def _latest_attempts(execution: ExecutionManifest) -> dict[str, int]:
146
192
  return latest
147
193
 
148
194
 
149
- def _required_stages(verifiers: Mapping[str, list[_BoundInvocation]]) -> frozenset[int]:
195
+ def _required_stages(verifiers: Mapping[str, list[BoundInvocation]]) -> frozenset[int]:
150
196
  return frozenset(
151
197
  stage for bindings in verifiers.values() for binding in bindings
152
198
  if binding.generation is not None
@@ -155,67 +201,102 @@ def _required_stages(verifiers: Mapping[str, list[_BoundInvocation]]) -> frozens
155
201
 
156
202
 
157
203
  def _bind(
158
- project: Path, ref: RunRef, invocation: Invocation, index: int,
159
- ) -> _BoundInvocation:
204
+ project: Path, ref: RunRef, manifest: Mapping[str, Any], invocation: Invocation,
205
+ index: int, attempt: int,
206
+ ) -> BoundInvocation:
207
+ """The generation the invocation's metadata binds, which must be the one its
208
+ dispatch kind seals and still have the bytes the metadata recorded."""
160
209
  number = verification_generation_number(invocation.dispatch_kind)
161
210
  path = ref.verification_generation(number)
162
211
  relative = path.relative_to(project).as_posix()
163
- if not path.is_file():
164
- return _BoundInvocation(invocation, number, index, None,
165
- {"path": relative, "digest": ""})
166
- digest = content_digest(path.read_bytes())
167
- return _BoundInvocation(invocation, number, index,
168
- read_verification_generation(path, digest),
169
- {"path": relative, "digest": digest})
212
+ reference = reserved_generation_reference(
213
+ project, manifest, invocation.invocation_ref, attempt,
214
+ )
215
+ if reference is None:
216
+ return BoundInvocation(invocation, number, index, None,
217
+ {"path": relative, "digest": ""})
218
+ if reference.path != relative:
219
+ raise ValueError(
220
+ f"invocation {invocation.invocation_ref} is bound to {reference.path}, "
221
+ f"not to {relative}, the generation its dispatch seals"
222
+ )
223
+ try:
224
+ generation = read_verification_generation(path, reference.digest)
225
+ except ValueError as exc:
226
+ raise ValueError(
227
+ f"generation {relative} of invocation {invocation.invocation_ref}: {exc}"
228
+ ) from exc
229
+ return BoundInvocation(invocation, number, index, generation, reference.to_payload())
170
230
 
171
231
 
172
232
  def _verifier_result(
173
- ref: RunRef, role_execution_ref: str, bindings: list[_BoundInvocation],
174
- generation_number: int, stage_key: str, latest_attempt: Mapping[str, int],
233
+ run: RunVerifiers, role_execution_ref: str, generation_number: int,
234
+ stage_key: str,
175
235
  ) -> _VerifierOutcome:
176
- chosen = next((binding for binding in bindings if binding.generation is not None
177
- and binding.generation_number == generation_number), None)
178
- if chosen is None:
236
+ bound = bound_attempt(run, role_execution_ref, generation_number)
237
+ if bound is None:
179
238
  return _NO_OUTCOME
180
- invocation_ref = chosen.invocation.invocation_ref
181
- attempt = latest_attempt.get(invocation_ref)
182
- if attempt is None:
239
+ check = read_latest_check_run(run.ref, role_execution_ref, *bound,
240
+ f"conformance:{stage_key}")
241
+ if check is None:
183
242
  return _NO_OUTCOME
184
- check_ref = f"conformance:{stage_key}"
243
+ if check.defect is not None or check.record is None or check.output is None:
244
+ return _VerifierOutcome(None, check.path, check.defect)
245
+ return _VerifierOutcome(qa_result_from_execution(check.record, check.output),
246
+ check.path)
247
+
248
+
249
+ def bound_attempt(
250
+ run: RunVerifiers, role_execution_ref: str, generation_number: int,
251
+ ) -> tuple[BoundInvocation, int] | None:
252
+ """The verifier's invocation bound to the generation, with its latest
253
+ attempt; None when it has no such invocation or attempt."""
254
+ chosen = next((binding for binding in run.verifiers.get(role_execution_ref, [])
255
+ if binding.generation is not None
256
+ and binding.generation_number == generation_number), None)
257
+ if chosen is None:
258
+ return None
259
+ attempt = run.latest_attempt.get(chosen.invocation.invocation_ref)
260
+ return None if attempt is None else (chosen, attempt)
261
+
262
+
263
+ def read_latest_check_run(
264
+ ref: RunRef, role_execution_ref: str, binding: BoundInvocation, attempt: int,
265
+ check_ref: str,
266
+ ) -> CheckRunRecord | None:
267
+ """The latest run of one check under an attempt of a bound invocation; None
268
+ when the attempt never ran the check."""
269
+ invocation_ref = binding.invocation.invocation_ref
185
270
  check_run = ref.latest_verification_check_run(invocation_ref, attempt, check_ref)
186
271
  if check_run is None:
187
- return _NO_OUTCOME
188
- run_dir = ref.verification_execution_dir(
189
- invocation_ref, attempt, check_ref, check_run,
190
- )
191
- expected = {
272
+ return None
273
+ run_dir = ref.verification_execution_dir(invocation_ref, attempt, check_ref, check_run)
274
+ record, output, defect = _read_bound_record(run_dir, {
192
275
  "invocationRef": invocation_ref, "roleExecutionRef": role_execution_ref,
193
276
  "attempt": attempt, "checkRef": check_ref, "checkRun": check_run,
194
- "verificationGeneration": chosen.generation_ref,
195
- }
196
- record_path = run_dir / "record.json"
197
- result, rejection = _recorded_result(run_dir, expected)
198
- return _VerifierOutcome(result, record_path, rejection)
277
+ "verificationGeneration": binding.generation_ref,
278
+ })
279
+ return CheckRunRecord(check_run, run_dir / "record.json", record, output, defect)
199
280
 
200
281
 
201
- def _recorded_result(
282
+ def _read_bound_record(
202
283
  run_dir: Path, expected: Mapping[str, object],
203
- ) -> tuple[QaResult | None, str | None]:
284
+ ) -> tuple[VerificationExecutionRecord | None, bytes | None, str | None]:
285
+ """One check run's record, its saved stdout, and why the run is no usable
286
+ evidence (None when it is); `expected` are the record fields its location
287
+ and binding determine."""
204
288
  try:
205
289
  record = read_verification_execution_record(run_dir / "record.json")
206
290
  except (JsonBoundaryError, OSError) as exc:
207
- return None, f"record is unreadable ({exc})"
291
+ return None, None, f"record is unreadable ({exc})"
208
292
  if any(record[name] != value for name, value in expected.items()):
209
- return None, ("record identity, attempt, check run or generation differs "
210
- "from its location")
293
+ return record, None, ("record identity, attempt, check run or generation "
294
+ "differs from its location")
211
295
  try:
212
296
  output = (run_dir / "stdout.log").read_bytes()
213
297
  except OSError as exc:
214
- return None, f"saved stdout is unreadable ({exc})"
215
- defect = execution_evidence_defect(record, output)
216
- if defect is not None:
217
- return None, defect
218
- return qa_result_from_execution(record, output), None
298
+ return record, None, f"saved stdout is unreadable ({exc})"
299
+ return record, output, execution_evidence_defect(record, output)
219
300
 
220
301
 
221
302
  def _combine(outcomes: list[_VerifierOutcome]) -> StageEvidence:
@@ -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
  # 어휘로 검증한다 — 없던 키를 요구하면 이미 디스크에 있는 리포트가 무효가 된다.