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,297 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import re
5
+ from pathlib import Path
6
+ from collections.abc import Mapping
7
+ from typing import Any
8
+
9
+ from .agent.invocation import (
10
+ reserved_generation_reference, reserved_invocation_metadata_path, verify_agent_invocation,
11
+ )
12
+ from .attempt_evidence import AttemptEvidenceSeal, read_sealed_artifact
13
+ from .conformance_evidence import BoundInvocation, bound_attempt, evidence_read_errors, load_run_verifiers
14
+ from .design_review import parse_design_review
15
+ from .execution_identity import ExecutionManifest, build_dispatch_id
16
+ from .execution_manifest import read_execution_manifest
17
+ from .json_boundary import load_owned_object
18
+ from .qa_procedures import canonical_json_digest, content_digest, safe_qa_path
19
+ from .verification_dispatch import verification_generation_number
20
+ from .verification_input_ref import VerificationInputReference
21
+ from .verification_inputs import read_verification_inputs
22
+ from .verification_input_types import DESIGN_REVIEW_INPUT_SCHEMA_VERSION
23
+ from .verification_invocation import VerificationGenerationReference, read_invocation_generation
24
+ from .verification_evidence import roster_verifier_role_execution_ref
25
+
26
+
27
+ def design_review_required(project: Path, manifest: Mapping[str, Any]) -> bool:
28
+ reference = VerificationInputReference.from_artifact_fields(manifest)
29
+ if reference is None or manifest.get("taskType") not in ("implementation", "final-verification"):
30
+ return False
31
+ inputs = read_verification_inputs(safe_qa_path(project, reference.relative_path), reference.digest)
32
+ return inputs["schemaVersion"] == DESIGN_REVIEW_INPUT_SCHEMA_VERSION
33
+
34
+
35
+ def collect_design_reviews(project: Path, manifest_path: Path) -> dict[str, dict[str, Any]]:
36
+ with evidence_read_errors():
37
+ manifest = load_owned_object(manifest_path, artifact="run manifest")
38
+ if manifest.get("taskType") != "implementation" or not design_review_required(project, manifest):
39
+ return {}
40
+ run = load_run_verifiers(project, manifest_path)
41
+ execution = read_execution_manifest(manifest_path)
42
+ generation = max((verification_generation_number(row.dispatch_kind)
43
+ for row in execution.invocations
44
+ if row.duty_id in ("implementation-executor", "implementation-verifier")), default=1)
45
+ roster = [row["workerId"] for row in manifest.get("workerAssignments", [])
46
+ if row.get("role") == "verifier"]
47
+ if not roster or len(set(roster)) != len(roster):
48
+ raise ValueError("design review requires a distinct verifier roster")
49
+ reviews = {}
50
+ for worker in roster:
51
+ role = roster_verifier_role_execution_ref(manifest, worker)
52
+ current = bound_attempt(run, role, generation)
53
+ before = (generation, len(execution.invocations), 2**31)
54
+ if current is not None:
55
+ before = (generation, current[0].index, current[1])
56
+ history = _prior_reviews(project, manifest_path, manifest, execution, role, before)
57
+ current_attempt = None if current is None else next((row for row in execution.attempts
58
+ if (row.invocation_ref, row.attempt) == (current[0].invocation.invocation_ref, current[1])), None)
59
+ if current_attempt is None or current_attempt.status != "ok":
60
+ reviews[worker] = {"collection": "incomplete", "reason": "no current bound verifier attempt",
61
+ "generationNumber": generation, "verdict": "not-run", "history": history}
62
+ continue
63
+ record, body = _read_review(project, manifest_path, manifest, execution, *current)
64
+ record["history"] = history
65
+ record["carry"] = _read_carry(body, history)
66
+ if any(row["disposition"] == "open" for row in record["carry"]):
67
+ record["verdict"] = "FAIL"
68
+ reviews[worker] = record
69
+ return reviews
70
+
71
+
72
+ def _prior_reviews(
73
+ project: Path, manifest_path: Path, manifest: Mapping[str, Any], execution: ExecutionManifest,
74
+ role: str, before: tuple[int, int, int],
75
+ ) -> list[dict[str, Any]]:
76
+ history = []
77
+ for index, invocation in enumerate(execution.invocations):
78
+ if invocation.role_execution_ref != role or invocation.duty_id != "implementation-verifier":
79
+ continue
80
+ number = verification_generation_number(invocation.dispatch_kind)
81
+ for attempt in execution.attempts:
82
+ if (attempt.invocation_ref != invocation.invocation_ref or attempt.status != "ok"
83
+ or (number, index, attempt.attempt) >= before):
84
+ continue
85
+ reference = reserved_generation_reference(project, manifest, invocation.invocation_ref, attempt.attempt)
86
+ if reference is None:
87
+ raise ValueError("earlier design-review attempt has no bound generation")
88
+ binding = BoundInvocation(invocation, number, index, None, reference.to_payload())
89
+ record, _ = _read_review(project, manifest_path, manifest, execution, binding, attempt.attempt)
90
+ history.append(record)
91
+ return history
92
+
93
+
94
+ def prior_design_review_prompt(
95
+ project: Path, manifest_path: Path, role: str, generation: int,
96
+ invocation_ref: str = "", attempt: int = 1,
97
+ ) -> str:
98
+ run = load_run_verifiers(project, manifest_path)
99
+ execution = read_execution_manifest(manifest_path)
100
+ index = next((index for index, row in enumerate(execution.invocations)
101
+ if row.invocation_ref == invocation_ref), len(execution.invocations))
102
+ history = _prior_reviews(project, manifest_path, run.manifest,
103
+ execution, role, (generation, index, attempt))
104
+ if not history:
105
+ return ""
106
+ return ("\n## Prior Design Review Findings\n\n"
107
+ "The current census requires fresh inspection of the full stage diff. Earlier findings "
108
+ "are retained below; do not inherit their rule judgments. Return `## Design Carry` "
109
+ "with a JSON array containing {finding, disposition, basis} for each earlier blocking "
110
+ "finding, where finding is `<generationNumber>:<invocationRef>:<attempt>:<id>`, disposition is "
111
+ "open/fixed/accepted-risk/rejected, and basis cites the current code/test or an explicit "
112
+ "accepted-risk decision. Preserve that basis for every disposition.\n\n"
113
+ + json.dumps(history, ensure_ascii=False, indent=2) + "\n")
114
+
115
+
116
+ def _read_review(
117
+ project: Path, manifest_path: Path, manifest: Mapping[str, Any], execution: ExecutionManifest,
118
+ binding: BoundInvocation, attempt: int,
119
+ ) -> tuple[dict[str, Any], str]:
120
+ invocation = binding.invocation
121
+ metadata_path = reserved_invocation_metadata_path(project, manifest, invocation.invocation_ref, attempt)
122
+ if metadata_path is None:
123
+ raise ValueError("design review has no reserved invocation metadata")
124
+ errors = verify_agent_invocation(
125
+ metadata_path, project_root=project, expected_run_manifest_path=manifest_path,
126
+ expected_audience="implementation-verifier", expected_invocation_ref=invocation.invocation_ref,
127
+ expected_role_execution_ref=invocation.role_execution_ref,
128
+ expected_participant_ref=invocation.participant_ref,
129
+ )
130
+ if errors:
131
+ raise ValueError("design review invocation: " + "; ".join(errors))
132
+ generation = read_invocation_generation(project, manifest_path, manifest,
133
+ VerificationGenerationReference.from_payload(binding.generation_ref),
134
+ "implementation-verifier")
135
+ if generation is None or "designReview" not in generation:
136
+ raise ValueError("design review has no sealed census")
137
+ from .paths import RunRef
138
+
139
+ expected_path = RunRef.from_manifest(manifest_path, manifest).verification_generation(binding.generation_number)
140
+ if (generation["generation"] != binding.generation_number
141
+ or binding.generation_ref["path"] != expected_path.relative_to(project).as_posix()):
142
+ raise ValueError("design review generation differs from its dispatch")
143
+ result_path, raw = _read_attempt_result(project, execution, invocation.invocation_ref, attempt)
144
+ body = raw.decode("utf-8")
145
+ source = Path(generation["sourceRoot"])
146
+ review = parse_design_review(source if source.is_dir() else project, generation["designReview"], body)
147
+ verdicts = re.findall(r"^Verifier verdict: (PASS|CONCERNS|FAIL)$", body, re.M)
148
+ if len(verdicts) != 1:
149
+ raise ValueError("design review requires one explicit Verifier verdict line")
150
+ return {"collection": "complete", "generationNumber": generation["generation"],
151
+ "generation": dict(binding.generation_ref), "head": generation["head"],
152
+ "base": generation["designReview"]["base"],
153
+ "policyDigest": generation["designReview"]["policyDigest"],
154
+ "censusDigest": canonical_json_digest(generation["designReview"]),
155
+ "invocationRef": invocation.invocation_ref, "attempt": attempt,
156
+ "resultPath": result_path.relative_to(project).as_posix(), "resultDigest": content_digest(raw),
157
+ "expectedCells": len(review.coverage.verdicts) + len(review.coverage.missing),
158
+ "coveredCells": len(review.coverage.verdicts), "missing": dict(review.coverage.missing),
159
+ "unknown": list(review.coverage.unknown), "findings": list(review.findings),
160
+ "blockingFindings": list(review.blocking_findings),
161
+ "verdict": "FAIL" if review.blocking else verdicts[0],
162
+ "scope": "full stage diff; no prior rule judgments inherited"}, body
163
+
164
+
165
+ def _read_attempt_result(
166
+ project: Path, execution: ExecutionManifest, invocation_ref: str, attempt: int,
167
+ ) -> tuple[Path, bytes]:
168
+ row = next((row for row in execution.attempts if (row.invocation_ref, row.attempt)
169
+ == (invocation_ref, attempt)), None)
170
+ if row is None or row.status != "ok" or row.finished_at is None or not row.result_path:
171
+ raise ValueError("design review requires the current completed ok attempt")
172
+ attempt_ref = build_dispatch_id(invocation_ref, attempt)
173
+ seals = [seal for seal in execution.attempt_evidence_seals
174
+ if seal.get("sealRef") == row.evidence_seal_ref and seal.get("attemptRef") == attempt_ref]
175
+ if len(seals) != 1:
176
+ raise ValueError("design review result requires its attempt evidence seal")
177
+ path = Path(row.result_path)
178
+ relative = path.relative_to(project).as_posix() if path.is_absolute() else path.as_posix()
179
+ if not relative.startswith(".okstra/"):
180
+ raise ValueError("design review result must remain in project artifacts")
181
+ path = safe_qa_path(project, relative)
182
+ return path, read_sealed_artifact(AttemptEvidenceSeal.from_payload(seals[0]), path)
183
+
184
+
185
+ def _read_carry(body: str, history: list[dict[str, Any]]) -> list[dict[str, str]]:
186
+ pending = {f"{record['generationNumber']}:{record['invocationRef']}:{record['attempt']}:{identity}"
187
+ for record in history for identity in record.get("blockingFindings", [])}
188
+ if not pending:
189
+ return []
190
+ matches = re.findall(r"^## Design Carry\s*\n```json\s*\n(.*?)\n```", body, re.M | re.S)
191
+ if len(matches) != 1:
192
+ raise ValueError("design review must disposition every earlier blocking finding in Design Carry")
193
+ rows = json.loads(matches[0])
194
+ if not isinstance(rows, list):
195
+ raise ValueError("Design Carry must be an array")
196
+ seen: set[str] = set()
197
+ for row in rows:
198
+ if (not isinstance(row, dict) or set(row) != {"finding", "disposition", "basis"}
199
+ or any(not isinstance(value, str) or not value.strip() for value in row.values())
200
+ or row["finding"] in seen or row["finding"] not in pending
201
+ or row["disposition"] not in ("open", "fixed", "accepted-risk", "rejected")
202
+ or re.search(r"(?:base:)?[A-Za-z0-9_./-]+:[0-9]+", row["basis"]) is None):
203
+ raise ValueError("invalid or duplicate Design Carry disposition")
204
+ seen.add(row["finding"])
205
+ if seen != pending:
206
+ raise ValueError("Design Carry omits earlier blocking findings")
207
+ return rows
208
+
209
+
210
+ def attach_design_reviews(data: dict[str, Any], reviews: Mapping[str, dict[str, Any]]) -> None:
211
+ if not reviews:
212
+ return
213
+ implementation = data.setdefault("implementation", {})
214
+ existing = {row["verifier"]: row for row in implementation.get("verifierResults", [])}
215
+ if existing.keys() - reviews.keys():
216
+ raise ValueError("report verifier is outside the design-review roster")
217
+ rows = []
218
+ for worker, review in reviews.items():
219
+ row = dict(existing.get(worker, {"verifier": worker, "readOnlyCommandLog": "",
220
+ "independentValidationRerun": ""}))
221
+ row.update(verdict=review["verdict"], designReview=review)
222
+ rows.append(row)
223
+ implementation["verifierResults"] = rows
224
+ require_design_acceptance(data, reviews)
225
+
226
+
227
+ def require_design_acceptance(data: Mapping[str, Any], reviews: Mapping[str, Mapping[str, Any]]) -> None:
228
+ token = (data.get("finalVerdict") or {}).get("verdictToken")
229
+ if token not in ("accepted", "conditional-accept"):
230
+ return
231
+ blocked = [worker for worker, row in reviews.items()
232
+ if row["collection"] != "complete" or row["verdict"] in ("FAIL", "not-run")]
233
+ if blocked:
234
+ raise ValueError("design review prevents acceptance: " + ", ".join(blocked))
235
+
236
+
237
+ def validate_design_review_report(
238
+ data: Mapping[str, Any], project: Path, manifest_path: Path, *, head: str = "", base: str = "",
239
+ ) -> None:
240
+ reviews = collect_design_reviews(project, manifest_path)
241
+ if not reviews:
242
+ return
243
+ rows = (data.get("implementation") or {}).get("verifierResults", [])
244
+ reported = {row.get("verifier"): row for row in rows}
245
+ if set(reported) != set(reviews) or len(rows) != len(reviews):
246
+ raise ValueError("report omits or duplicates a design-review verifier")
247
+ for worker, expected in reviews.items():
248
+ if reported[worker].get("designReview") != expected or reported[worker].get("verdict") != expected["verdict"]:
249
+ raise ValueError("report design review differs from sealed verifier result: " + worker)
250
+ if head and expected.get("head") != head:
251
+ raise ValueError("stage head differs from design-review head")
252
+ if base and expected.get("base") != base:
253
+ raise ValueError("stage base differs from design-review base")
254
+ require_design_acceptance(data, reviews)
255
+
256
+
257
+ def validate_stage_design_report(
258
+ project: Path, report: Path, stage: int, *, head: str = "", base: str = "", task_key: str = "",
259
+ ) -> None:
260
+ from .final_report_paths import final_report_data_path
261
+ from .paths import RunRef
262
+
263
+ report = final_report_data_path(report)
264
+ report = safe_qa_path(project, report.absolute().relative_to(project).as_posix())
265
+ manifest_path = RunRef.from_report_path(report).manifest
266
+ manifest = load_owned_object(manifest_path, artifact="implementation run manifest")
267
+ if not design_review_required(project, manifest):
268
+ return
269
+ from .stage_close import _latest_stage_run_manifest
270
+
271
+ if (manifest.get("taskType") != "implementation" or str(manifest.get("stage")) != str(stage)
272
+ or (task_key and manifest.get("taskKey") != task_key)):
273
+ raise ValueError("design-review report belongs to a different task or stage")
274
+ latest = _latest_stage_run_manifest(RunRef.from_report_path(report).task_root, stage)
275
+ if latest != manifest_path:
276
+ raise ValueError("design-review report is not the latest implementation run for this stage")
277
+ data = load_owned_object(report, artifact="implementation report")
278
+ if (data.get("finalVerdict") or {}).get("verdictToken") not in ("accepted", "conditional-accept"):
279
+ raise ValueError("design review has no accepted implementation report")
280
+ validate_design_review_report(data, project, manifest_path, head=head, base=base)
281
+
282
+
283
+ def validate_design_completion(plan_run_root: Path, task_key: str, stage: int, head: str) -> None:
284
+ from .paths import RunRef
285
+ from .stage_close import _latest_stage_run_manifest
286
+
287
+ plan = RunRef.from_run_dir(plan_run_root)
288
+ latest = _latest_stage_run_manifest(plan.task_root, stage)
289
+ if latest is None or plan.project_root is None:
290
+ return
291
+ manifest = load_owned_object(latest, artifact="implementation run manifest")
292
+ if not design_review_required(plan.project_root, manifest):
293
+ return
294
+ if not head:
295
+ raise ValueError("design-review completion requires the stage head")
296
+ report = RunRef.from_manifest(latest, manifest).report
297
+ validate_stage_design_report(plan.project_root, report, stage, head=head, task_key=task_key)
@@ -9,8 +9,7 @@ from typing import Any, Mapping
9
9
 
10
10
  from .convergence_store import write_json_atomic
11
11
  from .design_surfaces import DesignSurfaceError, detect_design_surfaces
12
- from .final_report_schema import load_schema_version
13
- from .report_narrative import NarrativeContractError, parse_narrative
12
+ from .report_narrative import NarrativeContractError, load_writer_input
14
13
 
15
14
 
16
15
  def _evidence(trigger: Any) -> list[dict[str, Any]]:
@@ -102,10 +101,15 @@ def build_design_snapshot(planning: Mapping[str, Any]) -> dict[str, Any]:
102
101
  }
103
102
 
104
103
 
105
- def write_snapshot(narrative_path: Path, output_path: Path) -> dict[str, Any]:
106
- narrative = parse_narrative(
107
- narrative_path.read_text(encoding="utf-8"), load_schema_version("3.0")
108
- )
104
+ def write_snapshot(
105
+ narrative_path: Path, output_path: Path, *, run_manifest: Path | None = None,
106
+ ) -> dict[str, Any]:
107
+ try:
108
+ narrative = load_writer_input(narrative_path, run_manifest=run_manifest)
109
+ except NarrativeContractError as exc:
110
+ if run_manifest is None:
111
+ raise
112
+ raise DesignSurfaceError(str(exc)) from exc
109
113
  planning = narrative.get("implementationPlanning")
110
114
  if not isinstance(planning, Mapping):
111
115
  raise DesignSurfaceError("implementationPlanning is missing from narrative")
@@ -115,7 +119,7 @@ def write_snapshot(narrative_path: Path, output_path: Path) -> dict[str, Any]:
115
119
 
116
120
 
117
121
  _CLI_EPILOG = r"""Usage:
118
- okstra design-snapshot --narrative <report-narrative.md> --output <design-preparation.json>
122
+ okstra design-snapshot --run-manifest <path> --narrative <path> --output <design-preparation.json>
119
123
  """
120
124
  _CLI_DESCRIPTION = "Write the detector-owned planning snapshot."
121
125
 
@@ -127,11 +131,14 @@ def main(argv: list[str] | None = None) -> int:
127
131
  formatter_class=argparse.RawDescriptionHelpFormatter,
128
132
  prog="okstra design-snapshot")
129
133
  parser.add_argument("--narrative", type=Path, required=True)
134
+ parser.add_argument("--run-manifest", type=Path)
130
135
  parser.add_argument("--output", type=Path, required=True)
131
136
  args = parser.parse_args(argv)
132
137
  try:
133
- snapshot = write_snapshot(args.narrative, args.output)
134
- except (OSError, UnicodeError, DesignSurfaceError, NarrativeContractError) as exc:
138
+ snapshot = write_snapshot(
139
+ args.narrative, args.output, run_manifest=args.run_manifest,
140
+ )
141
+ except (OSError, UnicodeError, ValueError) as exc:
135
142
  print(f"design-snapshot: {exc}", file=sys.stderr)
136
143
  return 2
137
144
  print(json.dumps({"ok": True, "surfaces": sum(
@@ -6,8 +6,8 @@ import json
6
6
  from datetime import date
7
7
  from pathlib import Path
8
8
 
9
- from okstra_project import project_json_path, tasks_root
10
- from okstra_project.dirs import TASK_CATALOG_RELATIVE
9
+ from okstra_project import parse_task_key, project_json_path, resolve_task_root_read_only, tasks_root
10
+ from okstra_project.dirs import TASK_CATALOG_RELATIVE, contained_relative_path
11
11
 
12
12
  from . import group_context
13
13
  from .brief_frontmatter import read_brief_frontmatter
@@ -17,6 +17,41 @@ from .paths import task_dir, task_manifest_file
17
17
  from .render import render_task_catalog_discovery
18
18
  from .run_context import dir_flock
19
19
 
20
+ TASK_MANIFEST_MAX_BYTES = 2 * 1024 * 1024
21
+
22
+
23
+ def load_direct_task(project_root: Path, entry: dict, *, allow_create: bool) -> tuple[Path, dict]:
24
+ project_root = project_root.resolve()
25
+ project_id, group, task_id = parse_task_key(entry["taskKey"])
26
+ project = load_owned_object(project_json_path(project_root), artifact="project config", max_bytes=TASK_MANIFEST_MAX_BYTES)
27
+ if project.get("projectId") != project_id or not slugify_task_segment(group) or not slugify_task_segment(task_id):
28
+ raise ValueError("Task identity does not belong to this project")
29
+ existing = resolve_task_root_read_only(project_root, entry["taskKey"])
30
+ canonical = task_manifest_file(existing or task_dir(project_root, group, task_id))
31
+ path = Path(entry.get("taskManifestPath") or canonical)
32
+ path = path if path.is_absolute() else project_root / path
33
+ if (contained_relative_path(str(path), project_root) is None
34
+ or contained_relative_path(str(path), tasks_root(project_root).resolve()) is None):
35
+ raise ValueError("Task manifest is outside project tasks")
36
+ if path.exists():
37
+ manifest = load_owned_object(path, artifact="task manifest", max_bytes=TASK_MANIFEST_MAX_BYTES)
38
+ if manifest.get("taskKey") != entry["taskKey"]:
39
+ raise ValueError("Task manifest identity does not match the requested task")
40
+ for field, value in (("projectId", project_id), ("taskGroup", group), ("taskId", task_id)):
41
+ if field in manifest and manifest[field] != value:
42
+ raise ValueError("Task manifest owner is inconsistent")
43
+ return path, manifest
44
+ if not allow_create or (path.parent / "runs").exists() or entry.get("latestRunPath"):
45
+ raise ValueError("Task manifest is missing for a task with existing history")
46
+ return path, {
47
+ "schemaVersion": "1.0", "projectId": project_id, "projectRoot": str(project_root),
48
+ "taskKey": entry["taskKey"], "taskGroup": group, "taskId": task_id,
49
+ "taskGroupPathSegment": slugify_task_segment(group), "taskIdPathSegment": slugify_task_segment(task_id),
50
+ "taskRootPath": path.parent.relative_to(project_root).as_posix(),
51
+ "taskManifestPath": path.relative_to(project_root).as_posix(),
52
+ "taskBriefPath": entry.get("taskBriefPath", ""), "registrationSource": "direct",
53
+ }
54
+
20
55
 
21
56
  def find_brief_tasks(project_root: Path, token: str, task_group: str) -> list[dict]:
22
57
  project = load_owned_object(project_json_path(project_root), artifact="project config")
@@ -63,13 +98,20 @@ def record_direct_work(project_root: Path, manifest_path: Path, manifest: dict)
63
98
  load_owned_object(project_root / previous_path, artifact="direct work record")
64
99
  if previous_path else {}
65
100
  )
66
- if previous.get("summary") == summary and previous.get("statusUpdatedAt") == manifest["workStatusUpdatedAt"]:
101
+ trace_fields = {
102
+ "implementationTracePath": manifest["implementationTracePath"],
103
+ "traceDigest": manifest["traceDigest"],
104
+ "changedFiles": manifest["traceMetadata"].get("changedFiles", []),
105
+ } if manifest.get("traceDigest") else {}
106
+ if (previous.get("summary") == summary and previous.get("statusUpdatedAt") == manifest["workStatusUpdatedAt"]
107
+ and all(previous.get(key) == value for key, value in trace_fields.items())):
67
108
  return
68
109
  record = {
69
110
  "schemaVersion": "1.0", "taskKey": manifest["taskKey"], "source": "direct",
70
111
  "summary": summary, "crossVerification": "not-performed",
71
112
  "statusUpdatedAt": manifest["workStatusUpdatedAt"],
72
113
  "previousRecordPath": previous_path,
114
+ **trace_fields,
73
115
  }
74
116
  identity = {key: value for key, value in record.items() if key != "statusUpdatedAt"}
75
117
  digest = hashlib.sha256(json.dumps(identity, sort_keys=True).encode()).hexdigest()
@@ -766,7 +766,7 @@ def _dispatch_cli_wrapper_batch(
766
766
  returncode = port.wait(runtime)
767
767
  completed = subprocess.CompletedProcess(handle.job.command, returncode)
768
768
  settled = replace(handle, completed_process=completed)
769
- outcomes.append((settled, attempt, _outcome_from_completed(settled)))
769
+ outcomes.append((settled, attempt, _outcome_from_completed(settled, manifest=plan.manifest)))
770
770
 
771
771
  next_round: list[tuple[WorkerJob, int]] = []
772
772
  for handle, attempt, outcome in outcomes:
@@ -885,7 +885,7 @@ def _abort_cli_batch_start(
885
885
  continue
886
886
  outcome = WorkerOutcome(
887
887
  returncode=1,
888
- missing_completion_paths=_missing_completion_paths(job),
888
+ missing_completion_paths=_missing_completion_paths(job, manifest=plan.manifest),
889
889
  pane_id="",
890
890
  status_sidecar_path=status_path_for_prompt(job.prompt_path),
891
891
  timeout=False,
@@ -1326,7 +1326,7 @@ def _spawn_job(
1326
1326
  _record_dispatch(plan.team_state_path, handle, attempt, "running", "")
1327
1327
  _append_event(plan, "worker-dispatched", _attempt_details(job, attempt, handle))
1328
1328
  if handle.completed_process is not None:
1329
- outcome = _outcome_from_completed(handle)
1329
+ outcome = _outcome_from_completed(handle, manifest=plan.manifest)
1330
1330
  retry_allowed = _finish_attempt(
1331
1331
  plan,
1332
1332
  job,
@@ -1720,7 +1720,7 @@ def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:
1720
1720
  handle = _spawn_job(plan, job, attempt)
1721
1721
  if handle.completed_process is None:
1722
1722
  return await_dispatches(plan, timeout_seconds=None)
1723
- outcome = _outcome_from_completed(handle)
1723
+ outcome = _outcome_from_completed(handle, manifest=plan.manifest)
1724
1724
  if _job_terminal_status(plan, job, attempt) == "completed":
1725
1725
  return 0
1726
1726
  if _should_retry(outcome, attempt) and handle.mutation_retry_allowed:
@@ -1835,25 +1835,30 @@ def _opened_cmux_surfaces(team_state_path: Path) -> tuple[str, ...]:
1835
1835
  return tuple(opened)
1836
1836
 
1837
1837
 
1838
- def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
1838
+ def _outcome_from_completed(
1839
+ handle: WorkerHandle, *, manifest: Mapping[str, Any],
1840
+ ) -> WorkerOutcome:
1839
1841
  completed = handle.completed_process
1840
1842
  if completed is None:
1841
1843
  raise DispatchError("completed process missing")
1842
1844
  return WorkerOutcome(
1843
1845
  returncode=completed.returncode,
1844
- missing_completion_paths=_missing_completion_paths(handle.job),
1846
+ missing_completion_paths=_missing_completion_paths(handle.job, manifest=manifest),
1845
1847
  pane_id=handle.pane_id,
1846
1848
  status_sidecar_path=handle.status_sidecar_path,
1847
1849
  timeout=False,
1848
1850
  terminal_stage="exited",
1849
1851
  degraded_from=handle.degraded_from,
1850
- artifact_defects=_artifact_defects(handle.job),
1852
+ artifact_defects=_artifact_defects(handle.job, manifest=manifest),
1851
1853
  )
1852
1854
 
1853
1855
 
1854
- def _artifact_defects(job: WorkerJob) -> tuple[str, ...]:
1856
+ def _artifact_defects(
1857
+ job: WorkerJob, *, manifest: Mapping[str, Any],
1858
+ ) -> tuple[str, ...]:
1855
1859
  defect = unusable_result_defect(
1856
1860
  job.worker_id, job.result_path, job.dispatch_kind,
1861
+ project_root=job.project_root, manifest=manifest,
1857
1862
  )
1858
1863
  return (defect,) if defect else ()
1859
1864
 
@@ -1881,7 +1886,7 @@ def _correct_teardown_marked_dispatches(plan: DispatchPlan) -> None:
1881
1886
  status = read_wrapper_status(status_path) if status_path else None
1882
1887
  if status is None or not status.is_terminal:
1883
1888
  continue
1884
- outcome = _outcome_from_status(record, status)
1889
+ outcome = _outcome_from_status(record, status, project_root=plan.project_root, manifest=plan.manifest)
1885
1890
  if outcome.returncode != 0 or outcome.missing_completion_paths or outcome.timeout:
1886
1891
  continue
1887
1892
  _finish_record(plan, record, outcome)
@@ -1895,7 +1900,7 @@ def _advance_running_dispatches(plan: DispatchPlan, records: Sequence[Mapping[st
1895
1900
  if status is not None and _wrapper_process_is_gone(status):
1896
1901
  _settle_dead_dispatch(plan, record, status)
1897
1902
  continue
1898
- outcome = _outcome_from_status(record, status)
1903
+ outcome = _outcome_from_status(record, status, project_root=plan.project_root, manifest=plan.manifest)
1899
1904
  retry_allowed = _finish_record(plan, record, outcome)
1900
1905
  if (
1901
1906
  _should_retry(outcome, int(record.get("attempt", 1)))
@@ -2991,16 +2996,19 @@ def _retry_details(job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> dict
2991
2996
  }
2992
2997
 
2993
2998
 
2994
- def _outcome_from_status(record: Mapping[str, Any], status) -> WorkerOutcome:
2999
+ def _outcome_from_status(
3000
+ record: Mapping[str, Any], status, *, project_root: Path,
3001
+ manifest: Mapping[str, Any],
3002
+ ) -> WorkerOutcome:
2995
3003
  return WorkerOutcome(
2996
3004
  returncode=status.exit_code if status.exit_code is not None else 1,
2997
- missing_completion_paths=_record_missing_completion_paths(record),
3005
+ missing_completion_paths=_record_missing_completion_paths(record, project_root=project_root, manifest=manifest),
2998
3006
  pane_id=_string_value(record.get("paneId")),
2999
3007
  status_sidecar_path=status.path,
3000
3008
  timeout=status.timeout,
3001
3009
  terminal_stage=status.stage,
3002
3010
  degraded_from=_string_value(record.get("degradedFrom")),
3003
- artifact_defects=_record_artifact_defects(record),
3011
+ artifact_defects=_record_artifact_defects(record, project_root=project_root, manifest=manifest),
3004
3012
  )
3005
3013
 
3006
3014
 
@@ -3063,7 +3071,10 @@ def _record_completion_paths(record: Mapping[str, Any]) -> list[Path]:
3063
3071
  return [Path(path) for path in _string_list(record.get("completionPaths"))]
3064
3072
 
3065
3073
 
3066
- def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, ...]:
3074
+ def _record_missing_completion_paths(
3075
+ record: Mapping[str, Any], *, project_root: Path,
3076
+ manifest: Mapping[str, Any],
3077
+ ) -> tuple[Path, ...]:
3067
3078
  aliases = {Path(path) for path in _string_list(record.get("resultAliases"))}
3068
3079
  result_path = Path(_string_value(record.get("resultPath")))
3069
3080
  worker_result = Path(_string_value(record.get("workerResultPath")))
@@ -3074,6 +3085,7 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
3074
3085
  if path.is_file():
3075
3086
  if path == result_path and unusable_result_defect(
3076
3087
  worker_id, path, dispatch_kind,
3088
+ project_root=project_root, manifest=manifest,
3077
3089
  ):
3078
3090
  missing.append(path)
3079
3091
  continue
@@ -3083,11 +3095,15 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
3083
3095
  return tuple(missing)
3084
3096
 
3085
3097
 
3086
- def _record_artifact_defects(record: Mapping[str, Any]) -> tuple[str, ...]:
3098
+ def _record_artifact_defects(
3099
+ record: Mapping[str, Any], *, project_root: Path,
3100
+ manifest: Mapping[str, Any],
3101
+ ) -> tuple[str, ...]:
3087
3102
  defect = unusable_result_defect(
3088
3103
  dispatch_worker_key(record),
3089
3104
  Path(_string_value(record.get("resultPath"))),
3090
3105
  _string_value(record.get("dispatchKind")),
3106
+ project_root=project_root, manifest=manifest,
3091
3107
  )
3092
3108
  return (defect,) if defect else ()
3093
3109
 
@@ -53,7 +53,7 @@ from .execution_manifest import (
53
53
  from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
54
54
  from .final_report_paths import final_report_data_path
55
55
  from .report_inputs import report_narrative_path, uses_report_contract_v3
56
- from .report_narrative import narrative_structure_defect
56
+ from .report_narrative import narrative_structure_defect, report_narrative_structure_defect
57
57
  from .verdict_blocks import finding_vote_defect
58
58
  from .worker_prompt_body import REPORT_WRITER_WORKER_ID
59
59
  from .worker_prompt_contract import (
@@ -1656,6 +1656,7 @@ def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
1656
1656
 
1657
1657
  def unusable_result_defect(
1658
1658
  worker_id: str, result_path: Path, dispatch_kind: str = "",
1659
+ *, project_root: Path, manifest: Mapping[str, Any],
1659
1660
  ) -> str | None:
1660
1661
  """산출물이 있어도 소비자가 읽을 수 없으면 없는 것이다 — 서사와 재검증 표.
1661
1662
 
@@ -1688,6 +1689,9 @@ def unusable_result_defect(
1688
1689
  return f"reverify result does not parse: {defect}"
1689
1690
  if worker_id != REPORT_WRITER_WORKER_ID:
1690
1691
  return None
1692
+ if uses_report_contract_v3(manifest):
1693
+ defect = report_narrative_structure_defect(project_root, manifest, path=result_path)
1694
+ return f"narrative does not parse: {defect}" if defect else None
1691
1695
  try:
1692
1696
  text = result_path.read_text(encoding="utf-8")
1693
1697
  except (OSError, UnicodeDecodeError) as exc:
@@ -1698,12 +1702,15 @@ def unusable_result_defect(
1698
1702
  return f"narrative does not parse: {defect}"
1699
1703
 
1700
1704
 
1701
- def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
1705
+ def missing_completion_paths(
1706
+ job: WorkerJob, *, manifest: Mapping[str, Any],
1707
+ ) -> tuple[Path, ...]:
1702
1708
  missing: list[Path] = []
1703
1709
  for path in job.completion_paths:
1704
1710
  if path.is_file():
1705
1711
  if path == job.result_path and unusable_result_defect(
1706
1712
  job.worker_id, path, job.dispatch_kind,
1713
+ project_root=job.project_root, manifest=manifest,
1707
1714
  ):
1708
1715
  missing.append(path)
1709
1716
  continue