okstra 0.229.0 → 0.231.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 (150) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +168 -18
  9. package/docs/architecture.md +15 -14
  10. package/docs/coding-rules.md +15 -0
  11. package/docs/contributor-change-matrix.md +5 -5
  12. package/docs/project-structure-overview.md +13 -19
  13. package/package.json +2 -3
  14. package/runtime/BUILD.json +2 -2
  15. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  16. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  17. package/runtime/prompts/coding-preflight/overview.md +1 -0
  18. package/runtime/prompts/launch.template.md +7 -5
  19. package/runtime/prompts/lead/convergence.md +4 -4
  20. package/runtime/prompts/lead/okstra-lead-contract.md +19 -18
  21. package/runtime/prompts/lead/phase-routing.md +1 -1
  22. package/runtime/prompts/lead/report-writer.md +3 -3
  23. package/runtime/prompts/lead/team-contract.md +3 -3
  24. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  25. package/runtime/python/okstra_ctl/agent/invocation.py +190 -9
  26. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  27. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  28. package/runtime/python/okstra_ctl/cmux.py +4 -2
  29. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  30. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  31. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  32. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  33. package/runtime/python/okstra_ctl/conformance.py +30 -0
  34. package/runtime/python/okstra_ctl/conformance_evidence.py +316 -0
  35. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  36. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  37. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  38. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  39. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  40. package/runtime/python/okstra_ctl/ids.py +1 -41
  41. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  42. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  43. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  44. package/runtime/python/okstra_ctl/locks.py +28 -1
  45. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  46. package/runtime/python/okstra_ctl/paths.py +90 -33
  47. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  48. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  50. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  51. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  53. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +5 -4
  55. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  57. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +5 -4
  58. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  59. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +6 -2
  60. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +4 -2
  61. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +23 -7
  63. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  65. package/runtime/python/okstra_ctl/phases/implementation/spec.md +6 -4
  66. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  67. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  68. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  69. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -12
  70. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  71. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  72. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  73. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  74. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  75. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  76. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  77. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  78. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  79. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  80. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  81. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  82. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  83. package/runtime/python/okstra_ctl/process_group.py +26 -3
  84. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  85. package/runtime/python/okstra_ctl/recap.py +1 -2
  86. package/runtime/python/okstra_ctl/render.py +25 -2
  87. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  88. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  89. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  90. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  91. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  92. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  93. package/runtime/python/okstra_ctl/run.py +40 -20
  94. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  95. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  96. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  97. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  98. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  99. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  100. package/runtime/python/okstra_ctl/verification_dispatch.py +136 -0
  101. package/runtime/python/okstra_ctl/verification_evidence.py +671 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +34 -16
  103. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  104. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  105. package/runtime/python/okstra_ctl/verification_inputs.py +83 -2
  106. package/runtime/python/okstra_ctl/verification_invocation.py +140 -0
  107. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  108. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  109. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  110. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  111. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  112. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  113. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  114. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  115. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  116. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  117. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  118. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  119. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  120. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  121. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  122. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  123. package/runtime/skills/okstra-run/SKILL.md +11 -7
  124. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  125. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  126. package/runtime/templates/reports/html/i18n/en.json +7 -0
  127. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  128. package/runtime/validators/validate-run.py +130 -20
  129. package/runtime/validators/validate-workflow.sh +1 -1
  130. package/docs/cli.md +0 -1060
  131. package/docs/container.md +0 -100
  132. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  133. package/docs/performance-improvement-plan-v2.md +0 -369
  134. package/runtime/python/okstra_ctl/container.py +0 -702
  135. package/runtime/python/okstra_ctl/rollup.py +0 -241
  136. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  137. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  138. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  139. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  140. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  141. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  142. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  143. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  144. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  145. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  146. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  147. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  148. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  149. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  150. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -0,0 +1,220 @@
1
+ """Report rows derived from the verification execution records of a run.
2
+
3
+ A verifier's evidence is the latest run of each check under the latest attempt
4
+ of its invocation bound to the run's newest sealed generation. That is the
5
+ invocation `conformance_evidence` takes a stage result from only for a stage the
6
+ newest generation seals: an earlier stage it does not seal is gated by an older
7
+ generation's record, which the report does not show. Report assembly writes
8
+ these rows and the phase validators derive them again to compare.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import signal
13
+ from dataclasses import dataclass
14
+ from pathlib import Path
15
+ from typing import Any, Literal, Mapping, TypedDict
16
+
17
+ from .conformance_evidence import (
18
+ BoundInvocation, bound_attempt, evidence_read_errors, load_run_verifiers,
19
+ read_latest_check_run,
20
+ )
21
+ from .paths import RunRef
22
+ from .qa_procedures import content_digest
23
+ from .report_inputs import uses_execution_evidence
24
+ from .verification_evidence import shell_exit_code
25
+
26
+ EXECUTION_EVIDENCE_BLOCKING = "execution-evidence BLOCKING:"
27
+ OUTPUT_TAIL_LINES = 20
28
+ OUTPUT_TAIL_CHARACTERS = 2000
29
+ # Evidence mode runs the Tier 2 QA checks and the Tier 3 conformance scripts, so
30
+ # rows of these tiers come from execution records, never from the narrative.
31
+ _QA_CHECK_TIER = 2
32
+ _CONFORMANCE_TIER = 3
33
+ RECORD_DERIVED_TIERS = frozenset({_QA_CHECK_TIER, _CONFORMANCE_TIER})
34
+
35
+
36
+ def execution_evidence_contract(
37
+ manifest: Mapping[str, Any], failures: list[str],
38
+ ) -> bool | None:
39
+ """Whether the run is under the verification evidence contract; None, with
40
+ a failure, for an unsupported contract version.
41
+
42
+ A caller that settles lead fixes counts None as the contract, as
43
+ `stage_fix_carry` does, so such a run's lead fixes resolve nothing; its
44
+ execution records are not read.
45
+ """
46
+ try:
47
+ return uses_execution_evidence(manifest)
48
+ except ValueError as exc:
49
+ failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} {exc} "
50
+ f"{manifest.get('verificationEvidenceVersion')!r}; the run's "
51
+ "execution records cannot be read")
52
+ return None
53
+
54
+
55
+ class ExecutionEvidenceReference(TypedDict):
56
+ """`ExecutionEvidenceRef` of `schemas/final-report-v3.0.schema.json`."""
57
+
58
+ recordPath: str
59
+ recordDigest: str | None
60
+ invocationRef: str
61
+ attempt: int
62
+ checkRef: str
63
+ checkRun: int
64
+ generation: dict[str, str]
65
+ collection: Literal["complete", "incomplete"]
66
+ defect: str | None
67
+ command: str | None
68
+ exitCode: int | None
69
+ signal: str | None
70
+ outputTail: str
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class VerifierEvidence:
75
+ """One verifier's references, in check order; empty when its bound attempt
76
+ ran no check."""
77
+
78
+ role_execution_ref: str
79
+ invocation_ref: str
80
+ attempt: int
81
+ generation_ref: Mapping[str, str]
82
+ references: tuple[ExecutionEvidenceReference, ...]
83
+
84
+
85
+ def collect_report_evidence(
86
+ project: Path, manifest_path: Path,
87
+ ) -> dict[str, VerifierEvidence]:
88
+ """Each verifier with an attempt bound to the newest generation, by role
89
+ execution."""
90
+ with evidence_read_errors():
91
+ return _collect(project.resolve(), manifest_path.resolve())
92
+
93
+
94
+ def _collect(project: Path, manifest_path: Path) -> dict[str, VerifierEvidence]:
95
+ run = load_run_verifiers(project, manifest_path)
96
+ newest = max((binding.generation_number for bindings in run.verifiers.values()
97
+ for binding in bindings if binding.generation is not None),
98
+ default=None)
99
+ evidence = {}
100
+ for role_execution_ref in run.verifiers:
101
+ bound = None if newest is None else bound_attempt(run, role_execution_ref, newest)
102
+ if bound is not None:
103
+ evidence[role_execution_ref] = _verifier_evidence(
104
+ project, run.ref, role_execution_ref, *bound,
105
+ )
106
+ return evidence
107
+
108
+
109
+ def _verifier_evidence(
110
+ project: Path, ref: RunRef, role_execution_ref: str, binding: BoundInvocation,
111
+ attempt: int,
112
+ ) -> VerifierEvidence:
113
+ invocation_ref = binding.invocation.invocation_ref
114
+ return VerifierEvidence(
115
+ role_execution_ref, invocation_ref, attempt, binding.generation_ref,
116
+ tuple(
117
+ _reference(project, ref, role_execution_ref, binding, attempt, check_ref)
118
+ for check_ref in ref.verification_check_refs(invocation_ref, attempt)
119
+ ),
120
+ )
121
+
122
+
123
+ def _reference(
124
+ project: Path, ref: RunRef, role_execution_ref: str, binding: BoundInvocation,
125
+ attempt: int, check_ref: str,
126
+ ) -> ExecutionEvidenceReference:
127
+ invocation_ref = binding.invocation.invocation_ref
128
+ check = read_latest_check_run(ref, role_execution_ref, binding, attempt, check_ref)
129
+ if check is None:
130
+ raise ValueError(f"{check_ref} of {invocation_ref} has no check run directory")
131
+ record, path = check.record, check.path
132
+ return {
133
+ "recordPath": path.relative_to(project).as_posix(),
134
+ "recordDigest": content_digest(path.read_bytes()) if path.is_file() else None,
135
+ "invocationRef": invocation_ref, "attempt": attempt, "checkRef": check_ref,
136
+ "checkRun": check.check_run, "generation": dict(binding.generation_ref),
137
+ "collection": "complete" if check.defect is None else "incomplete",
138
+ "defect": check.defect,
139
+ "command": None if record is None else record["command"],
140
+ "exitCode": None if record is None else record["exitCode"],
141
+ "signal": None if record is None else record["signal"],
142
+ "outputTail": "" if check.output is None else output_tail(check.output),
143
+ }
144
+
145
+
146
+ def output_tail(output: bytes) -> str:
147
+ text = output.decode("utf-8", errors="replace")
148
+ return "\n".join(text.splitlines()[-OUTPUT_TAIL_LINES:])[-OUTPUT_TAIL_CHARACTERS:]
149
+
150
+
151
+ def command_row(number: int, reference: ExecutionEvidenceReference) -> dict[str, Any]:
152
+ """The final-verification read-only command row of one record."""
153
+ row: dict[str, Any] = {
154
+ "number": number,
155
+ "tier": (_CONFORMANCE_TIER if str(reference["checkRef"]).startswith("conformance:")
156
+ else _QA_CHECK_TIER),
157
+ "command": reference["command"] or reference["checkRef"],
158
+ "outputTail": reference["outputTail"],
159
+ "executionEvidence": dict(reference),
160
+ }
161
+ if reference["collection"] != "complete":
162
+ return {**row, "status": "evidence-incomplete", "exitCode": None,
163
+ "statusReason": reference["defect"]}
164
+ return {**row, "status": "executed", "exitCode": _exit_code(reference)}
165
+
166
+
167
+ def _exit_code(reference: ExecutionEvidenceReference) -> int:
168
+ if reference["exitCode"] is not None:
169
+ return int(reference["exitCode"])
170
+ return shell_exit_code(-signal.Signals[str(reference["signal"])].value)
171
+
172
+
173
+ def reference_errors(
174
+ where: str, reported: object, verifiers: list[VerifierEvidence],
175
+ ) -> tuple[list[str], set[str]]:
176
+ """Why a reported reference is not the record a verifier's current evidence
177
+ holds, or differs from it; and the record paths it matched."""
178
+ if not isinstance(reported, dict):
179
+ return [f"{where}: execution evidence must be an object"], set()
180
+ expected = {reference["recordPath"]: reference
181
+ for verifier in verifiers for reference in verifier.references}
182
+ match = expected.get(str(reported.get("recordPath")))
183
+ if match is None:
184
+ return [f"{where}: {_foreign_reason(reported, verifiers)}"], set()
185
+ if reported.get("recordDigest") != match["recordDigest"]:
186
+ return [f"{where}: record {match['recordPath']} has digest "
187
+ f"{match['recordDigest']}, not {reported.get('recordDigest')}"], set()
188
+ differing = sorted(key for key, value in match.items() if reported.get(key) != value)
189
+ if differing or set(reported) != set(match):
190
+ return [f"{where}: {differing or sorted(set(reported) ^ set(match))} differ "
191
+ f"from record {match['recordPath']}"], {match["recordPath"]}
192
+ return [], {match["recordPath"]}
193
+
194
+
195
+ def _foreign_reason(reported: Mapping[str, Any], verifiers: list[VerifierEvidence]) -> str:
196
+ named = (f"{reported.get('recordPath')} (invocation {reported.get('invocationRef')}, "
197
+ f"attempt {reported.get('attempt')}, check {reported.get('checkRef')}, "
198
+ f"check run {reported.get('checkRun')})")
199
+ owner = next((verifier for verifier in verifiers
200
+ if verifier.invocation_ref == reported.get("invocationRef")), None)
201
+ if owner is None:
202
+ bound = ", ".join(f"{verifier.invocation_ref} attempt {verifier.attempt}"
203
+ for verifier in verifiers) or "none"
204
+ return (f"names {named}, which belongs to no invocation bound to the run's "
205
+ f"newest verification generation (bound: {bound})")
206
+ if reported.get("attempt") != owner.attempt:
207
+ return f"names {named}, but the invocation's latest attempt is {owner.attempt}"
208
+ latest = next((reference for reference in owner.references
209
+ if reference["checkRef"] == reported.get("checkRef")), None)
210
+ if latest is None:
211
+ return f"names {named}, a check the invocation's attempt did not run"
212
+ return f"names {named}, but the record of that check's latest run is {latest['recordPath']}"
213
+
214
+
215
+ def omitted_records(
216
+ verifiers: list[VerifierEvidence], matched: set[str],
217
+ ) -> list[str]:
218
+ return sorted(reference["recordPath"] for verifier in verifiers
219
+ for reference in verifier.references
220
+ if reference["recordPath"] not in matched)
@@ -1325,7 +1325,7 @@ def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
1325
1325
  }
1326
1326
  pointer = result.get("nextRecommendedPhase")
1327
1327
  if not isinstance(pointer, Mapping):
1328
- return {"command": "/okstra-inspect status", "note": "no pointer recorded"}
1328
+ return {"command": "okstra task-show <task-key>", "note": "no pointer recorded; replace <task-key> with the full task key"}
1329
1329
  status = str(pointer.get("status") or "").strip()
1330
1330
  phase = str(pointer.get("phase") or "").strip()
1331
1331
  rationale = str(pointer.get("rationale") or "").strip()
@@ -1345,14 +1345,14 @@ def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
1345
1345
  "command": "",
1346
1346
  "note": "the lifecycle ends here — say the task is finished, name any "
1347
1347
  "follow-up tasks this run registered, and do not send the user "
1348
- "to /okstra-inspect",
1348
+ "to a separate status workflow",
1349
1349
  }
1350
1350
  if status in (STATUS_BLOCKED, STATUS_PENDING) and rationale:
1351
1351
  return {
1352
1352
  "command": "",
1353
1353
  "note": "quote the rationale above and issue the command it names",
1354
1354
  }
1355
- return {"command": "/okstra-inspect status", "note": ""}
1355
+ return {"command": "okstra task-show <task-key>", "note": "replace <task-key> with the full task key"}
1356
1356
 
1357
1357
 
1358
1358
  def _next_phase_summary_lines(result: Mapping[str, Any]) -> list[str]:
@@ -5,6 +5,9 @@ from dataclasses import dataclass
5
5
  from pathlib import Path
6
6
  from typing import Any, Mapping
7
7
 
8
+ from .qa_commands import QA_VERIFIER_AUDIENCE_BY_TASK_TYPE
9
+ from .verification_invocation import verification_generation_required
10
+
8
11
 
9
12
  REPORT_CONTRACT_V3 = "3.0"
10
13
 
@@ -32,6 +35,11 @@ _INPUT_FIELDS = (
32
35
  # 없을 때 조립이 report-writer 를 지목하면 띄울 수 없는 워커를 찾게 된다.
33
36
  _LEAD_AUTHORED_NARRATIVE_TASK_TYPES = frozenset({"release-handoff"})
34
37
 
38
+ # The evidence-mode runner observed these processes; neither the report writer
39
+ # nor a verifier authors them.
40
+ EXECUTION_EVIDENCE_INPUT = "execution-evidence"
41
+ EXECUTION_EVIDENCE_OWNER = "verification-execution"
42
+
35
43
  _PLANNING_INPUT_FIELDS = (
36
44
  ("design-preparation", "design-surface-detector", "designPreparationPath"),
37
45
  ("plan-body-verification", "convergence", "planBodyVerificationPath"),
@@ -76,6 +84,26 @@ def report_input_paths(
76
84
  )
77
85
  for key, owner, field in fields
78
86
  )
87
+ rows += _execution_evidence_rows(project_root, manifest)
79
88
  if len({row.key for row in rows}) != len(rows):
80
89
  raise ReportInputError("report input keys must be unique")
81
90
  return rows
91
+
92
+
93
+ def uses_execution_evidence(manifest: Mapping[str, Any]) -> bool:
94
+ """A QA-executing run under the verification evidence contract."""
95
+ audience = QA_VERIFIER_AUDIENCE_BY_TASK_TYPE.get(str(manifest.get("taskType")))
96
+ return audience is not None and verification_generation_required(manifest, audience)
97
+
98
+
99
+ def _execution_evidence_rows(
100
+ project_root: Path, manifest: Mapping[str, Any],
101
+ ) -> tuple[ReportInputPath, ...]:
102
+ """The run's verification directory, which holds its execution records."""
103
+ if not uses_execution_evidence(manifest):
104
+ return ()
105
+ inputs = _project_path(
106
+ project_root, manifest.get("verificationInputsPath"), "verificationInputsPath",
107
+ )
108
+ return (ReportInputPath(EXECUTION_EVIDENCE_INPUT, EXECUTION_EVIDENCE_OWNER,
109
+ inputs.parent),)
@@ -21,6 +21,9 @@ _NESTED_FORBIDDEN = frozenset(
21
21
  {
22
22
  "implementationPlanning.designPreparation",
23
23
  "implementationPlanning.planBodyVerification",
24
+ # Report assembly derives these from the verification execution records.
25
+ "implementation.verifierResults.executionEvidence",
26
+ "finalVerification.readonlyCommandLog.executionEvidence",
24
27
  }
25
28
  )
26
29
 
@@ -215,7 +218,7 @@ def writer_owned_path_defect(path: str) -> str | None:
215
218
  있어야 하고, `_NESTED_FORBIDDEN` 아래는 기계 소유다. 교정 원장이 그 자리를
216
219
  고치라고 하면 조립이 나중에 거절할 것이므로 여기서 먼저 거절한다.
217
220
  """
218
- dotted = re.sub(r"\[\d+\]", "", path)
221
+ dotted = _field_path(path)
219
222
  top = dotted.split(".", 1)[0]
220
223
  if top not in _allowed_top_level():
221
224
  owned = ", ".join(f"`{humanise(key)}`" for key in sorted(_allowed_top_level()))
@@ -228,6 +231,11 @@ def writer_owned_path_defect(path: str) -> str | None:
228
231
  return None
229
232
 
230
233
 
234
+ def _field_path(path: str) -> str:
235
+ """`a.b[1].c` as the `a.b.c` that names the field in every array item."""
236
+ return re.sub(r"\[\d+\]", "", path)
237
+
238
+
231
239
  def writer_owned_data(data: Mapping[str, Any]) -> dict[str, Any]:
232
240
  """완성 리포트에서 보고서 작성자 소유 필드만 복사한다."""
233
241
  owned = {
@@ -444,7 +452,8 @@ def _allowed_labels(node: Any, index: SchemaIndex, path: str) -> list[str]:
444
452
  if not path:
445
453
  keys = [key for key in keys if key in _allowed_top_level()]
446
454
  # 파서가 뒤에서 거부할 필드를 여기서 권하면 안내가 다음 거부를 만든다.
447
- keys = [key for key in keys if f"{path}.{key}".lstrip(".") not in _NESTED_FORBIDDEN]
455
+ keys = [key for key in keys
456
+ if _field_path(f"{path}.{key}".lstrip(".")) not in _NESTED_FORBIDDEN]
448
457
  return sorted(humanise(key) for key in keys)
449
458
 
450
459
 
@@ -578,7 +587,7 @@ def _parse_object(
578
587
  if key is None:
579
588
  continue
580
589
  child_path = f"{path}.{key}" if path else key
581
- if child_path in _NESTED_FORBIDDEN:
590
+ if _field_path(child_path) in _NESTED_FORBIDDEN:
582
591
  defects.add(
583
592
  child_path, f"owner=report-writer cannot author `{path}.{child.label}`"
584
593
  )
@@ -15,6 +15,7 @@ from okstra_token_usage.blocks import accounting_workers
15
15
 
16
16
  from .analysis_packet import reference_source_extracts
17
17
  from .correction_round import correction_convergence_states
18
+ from .dispatch_state import UNSUCCESSFUL_WORKER_STATUSES
18
19
  from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
19
20
  from .phases.implementation_option_selection.authoring import (
20
21
  requirement_instructions as selection_requirement_instructions,
@@ -849,6 +850,10 @@ def _source_specs(
849
850
  for worker in workers:
850
851
  if not isinstance(worker, Mapping) or worker.get("workerId") == "report-writer":
851
852
  continue
853
+ # Such a worker settled no result, whatever file it left; a run closed with
854
+ # no verifier result still owes the writer a report.
855
+ if worker.get("status") in UNSUCCESSFUL_WORKER_STATUSES:
856
+ continue
852
857
  path = _string(worker.get("resultPath"))
853
858
  if path:
854
859
  worker_id = _string(worker.get("workerId")) or "unknown"
@@ -47,7 +47,7 @@ from typing import Mapping, Sequence
47
47
 
48
48
  from okstra_project import project_json_path, upsert_project_json
49
49
  from okstra_project.slug import slugify
50
- from .phases.catalog import host_rules
50
+ from .phases.catalog import INPUT_DOCUMENT_TASK_TYPES, host_rules
51
51
  from .phases.implementation_planning.entry import (
52
52
  _resolve_planning_input_path,
53
53
  _validate_planning_entry_inputs,
@@ -97,6 +97,7 @@ from .implementation_direction import (
97
97
  )
98
98
  from .qa_commands import (
99
99
  QA_COMMAND_EXECUTING_TASK_TYPES,
100
+ QA_VERIFIER_AUDIENCE_BY_TASK_TYPE,
100
101
  format_errors as _format_qa_errors,
101
102
  validate_qa_commands,
102
103
  )
@@ -106,6 +107,8 @@ from .verification_input_ref import (
106
107
  VerificationInputReference, retain_recorded_reference,
107
108
  )
108
109
  from .ports.verification_inputs import VerificationInputStore
110
+ from .verification_inputs import evidence_contract_applies
111
+ from .verification_invocation import VERIFICATION_EVIDENCE_VERSION
109
112
  from .registry.verification_inputs_store import default_verification_input_store
110
113
  from .material import (
111
114
  build_analysis_material,
@@ -442,9 +445,13 @@ def _validate_approved_plan_conformance(path: Path) -> None:
442
445
  data_path, data = loaded
443
446
  from .implementation_direction import stage_validation_executability_errors
444
447
 
445
- command_errors = stage_validation_executability_errors(
446
- data.get("implementationPlanning") or {}
447
- )
448
+ from .stage_command_commits import stage_command_commit_errors_from_task_state
449
+
450
+ planning = data.get("implementationPlanning") or {}
451
+ command_errors = [
452
+ *stage_validation_executability_errors(planning),
453
+ *stage_command_commit_errors_from_task_state(data_path, data),
454
+ ]
448
455
  if command_errors:
449
456
  raise PrepareError(
450
457
  f"approved plan command preflight failed: {data_path}\n"
@@ -453,10 +460,9 @@ def _validate_approved_plan_conformance(path: Path) -> None:
453
460
  bad = malformed_conformance_stages(data)
454
461
  if not bad:
455
462
  return
456
- planning = data.get("implementationPlanning") if isinstance(data, dict) else None
457
463
  declared_by_stage = {
458
464
  stage.get("stage"): stage.get("conformanceTests")
459
- for stage in (planning or {}).get("stages") or []
465
+ for stage in planning.get("stages") or []
460
466
  if isinstance(stage, dict)
461
467
  }
462
468
  # 한 stage 씩 고치고 다시 막히는 왕복을 피하려면 전부 나열해야 한다 —
@@ -820,7 +826,10 @@ def _published_run_seqs(run_dir: Path, task_type_segment: str) -> dict[str, str]
820
826
  매니페스트의 `runSequencesByCategory` 가 같은 런의 나머지 카테고리 seq 를
821
827
  묶는 유일한 기록이다. 재실행이 카테고리별로 다른 속도로 올라가므로
822
828
  (`paths.next_run_seq` 가 디렉터리마다 따로 스캔한다) 이 대응 없이는 "리포트
823
- 017 의 worker-results 는 몇 번인가" 에 답할 방법이 없다.
829
+ 017 의 worker-results 는 몇 번인가" 에 답할 방법이 없다. The divergence
830
+ above describes runs prepared before `compute_run_paths` gave every
831
+ category one seq; newer runs share one seq across categories, and this
832
+ mapping still resolves the older ones.
824
833
  """
825
834
  reports = run_dir / "reports"
826
835
  manifests = run_dir / "manifests"
@@ -1428,7 +1437,7 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
1428
1437
  f"got {inp.task_type}"
1429
1438
  )
1430
1439
  validate_discussion_start(project_root, inp)
1431
- if inp.task_type in ("release-handoff", "discussion"):
1440
+ if inp.task_type in INPUT_DOCUMENT_TASK_TYPES:
1432
1441
  # brief 는 entry phase 의 입력물 — release-handoff 는 검증 보고서를
1433
1442
  # 인용하는 input 문서를 prepare 가 직접 생성해 brief 자리에 채운다
1434
1443
  # (materialize_handoff_input, 이 검증 직후 실행). discussion 은 시작
@@ -1567,11 +1576,6 @@ def _validate_selected_implementation_plan(
1567
1576
  expected_task_root,
1568
1577
  "selected direction snapshot",
1569
1578
  )
1570
- brief_path = validate_task_artifact_path(
1571
- expected_task_root / "instruction-set" / "task-brief.md",
1572
- expected_task_root,
1573
- "selected direction task brief",
1574
- )
1575
1579
  except DirectionSelectionError as exc:
1576
1580
  raise PrepareError(f"selected-direction plan input is invalid: {exc}") from exc
1577
1581
 
@@ -1582,7 +1586,9 @@ def _validate_selected_implementation_plan(
1582
1586
  "selected-direction plan header.taskKey must match the implementation "
1583
1587
  f"task: expected {expected_task_key!r}, got {actual_task_key!r}"
1584
1588
  )
1585
- failures = validate_selected_direction_plan(data, brief_path, snapshot_path)
1589
+ # instruction-set/task-brief.md holds whatever brief the task's last run used
1590
+ # (a release-handoff run leaves its input there), so read this run's brief.
1591
+ failures = validate_selected_direction_plan(data, Path(inp.brief_path), snapshot_path)
1586
1592
  if failures:
1587
1593
  raise PrepareError(
1588
1594
  "selected-direction plan failed implementation entry validation:\n - "
@@ -3479,6 +3485,7 @@ def _prepare_verification_input_reference(
3479
3485
  reference = store.freeze(
3480
3486
  project_root, source, run_ref, approved_plan=approved_plan,
3481
3487
  )
3488
+ _mark_evidence_contract(ctx, store, project_root, reference)
3482
3489
  else:
3483
3490
  _validate_recorded_verification_inputs(
3484
3491
  project_root, source, run_ref, reference, store, approved_plan,
@@ -3488,6 +3495,19 @@ def _prepare_verification_input_reference(
3488
3495
  raise PrepareError(f"verification inputs preparation failed: {exc}") from exc
3489
3496
 
3490
3497
 
3498
+ def _mark_evidence_contract(
3499
+ ctx: dict, store: VerificationInputStore, project_root: Path,
3500
+ reference: VerificationInputReference,
3501
+ ) -> None:
3502
+ """Put a run whose inputs were just frozen under the verification evidence
3503
+ contract when those inputs can satisfy it."""
3504
+ frozen_inputs = store.read(
3505
+ safe_qa_path(project_root, reference.relative_path), reference.digest,
3506
+ )
3507
+ if evidence_contract_applies(frozen_inputs):
3508
+ ctx["VERIFICATION_EVIDENCE_VERSION"] = VERIFICATION_EVIDENCE_VERSION
3509
+
3510
+
3491
3511
  def _persist_pre_dispatch_run_manifest(ctx: dict) -> None:
3492
3512
  """Publish and re-read the complete invocation authority before prompts."""
3493
3513
  render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
@@ -3809,10 +3829,10 @@ def _allowed_agent_audiences(
3809
3829
  audiences.add("reverification-worker")
3810
3830
  if any(item.worker_id == "report-writer" for item in models.worker_assignments):
3811
3831
  audiences.add("report-writer")
3812
- if inp.task_type == "implementation":
3813
- audiences.update({"implementation-executor", "implementation-verifier"})
3814
- elif inp.task_type == "final-verification":
3815
- audiences.add("acceptance-verifier")
3832
+ if inp.task_type in QA_VERIFIER_AUDIENCE_BY_TASK_TYPE:
3833
+ audiences.add(QA_VERIFIER_AUDIENCE_BY_TASK_TYPE[inp.task_type])
3834
+ if inp.task_type == "implementation":
3835
+ audiences.add("implementation-executor")
3816
3836
  else:
3817
3837
  # Same map the prompt policy resolves the duty from. Allowing a
3818
3838
  # different audience here than the one the policy will ask for makes
@@ -4210,7 +4230,7 @@ def _prepare_user_authorization(inp: PrepareInputs) -> dict:
4210
4230
  "user authorization scope does not match --preselected-direction; confirm the changed scope"
4211
4231
  )
4212
4232
  for key, path in (
4213
- ("task-brief", "" if inp.task_type in ("release-handoff", "discussion") else inp.brief_path),
4233
+ ("task-brief", "" if inp.task_type in INPUT_DOCUMENT_TASK_TYPES else inp.brief_path),
4214
4234
  ("approved-plan", inp.approved_plan_path),
4215
4235
  ("clarification-response", inp.clarification_response_path),
4216
4236
  ("selected-direction", inp.selected_direction_path),
@@ -4277,7 +4297,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
4277
4297
  task_index_template = assets.task_index_template
4278
4298
  final_report_template = assets.final_report_template
4279
4299
  ctx_stage_map = _validate_prepare_inputs(project_root, inp)
4280
- if inp.task_type not in ("release-handoff", "discussion"):
4300
+ if inp.task_type not in INPUT_DOCUMENT_TASK_TYPES:
4281
4301
  _validate_task_brief_preflight(
4282
4302
  project_root,
4283
4303
  inp.brief_path,
@@ -38,9 +38,11 @@ from .conformance import (
38
38
  decide_conformance_gate,
39
39
  qa_result_from_dict,
40
40
  )
41
+ from .conformance_evidence import collect_conformance_evidence
41
42
  from .consumers import append_consumer, last_lifecycle_status_by_stage, read_consumers
42
43
  from .json_boundary import JsonBoundaryError, load_owned_object
43
- from .paths import RunRef, task_conformance_manifest_file, task_qa_dir
44
+ from .paths import RunRef, next_run_seq, task_conformance_manifest_file, task_qa_dir
45
+ from .report_inputs import uses_execution_evidence
44
46
  from .stage_map import StageMapError, load_latest_plan_stage_map
45
47
 
46
48
  def _git_commit_exists(repo_root: Path, commit: str) -> bool:
@@ -80,17 +82,42 @@ def _manifest_entry(task_root: Path, stage: int) -> dict | None:
80
82
  )
81
83
 
82
84
 
83
- def _conformance_state(task_root: Path, stage: int) -> tuple[bool, str]:
85
+ def _latest_stage_run_manifest(task_root: Path, stage: int) -> Path | None:
86
+ staged = RunRef.from_task_root(task_root, "implementation", stage=stage)
87
+ seq = next_run_seq(staged.run_dir / "manifests", staged.task_type) - 1
88
+ if seq == 0:
89
+ return None
90
+ return RunRef.from_task_root(task_root, "implementation", seq=seq, stage=stage).manifest
91
+
92
+
93
+ def _conformance_state(project_root: Path, task_root: Path, stage: int) -> tuple[bool, str]:
84
94
  """(닫아도 되는가, 사람이 읽는 근거).
85
95
 
86
- 선언 자체가 없으면 게이트할 것이 없다. 있으면 그 stage 의 결과 사이드카로
96
+ 선언 자체가 없으면 게이트할 것이 없다. 있으면 그 stage 의 결과로
87
97
  `decide_conformance_gate` 를 그대로 돌린다 — 검증기가 쓰는 것과 같은 판정
88
- 함수라, 여기서 통과한 stage 는 검증기에서도 통과한다.
98
+ 함수라, 여기서 통과한 stage 는 검증기에서도 통과한다. A stage whose latest
99
+ implementation run is marked `verificationEvidenceVersion` reads its result
100
+ only from that run's execution records; otherwise from the verifier-written
101
+ sidecar.
89
102
  """
90
103
  entry = _manifest_entry(task_root, stage)
91
104
  if entry is None:
92
105
  return True, "no conformance entry declared for this stage"
93
106
  key = str(entry.get("stageKey"))
107
+ run_manifest = _latest_stage_run_manifest(task_root, stage)
108
+ if run_manifest is None:
109
+ return _sidecar_conformance_state(task_root, entry, key)
110
+ try:
111
+ marked = uses_execution_evidence(
112
+ load_owned_object(run_manifest, artifact="run manifest"))
113
+ except (JsonBoundaryError, ValueError) as exc:
114
+ return False, f"BLOCKING: run manifest {run_manifest}: {exc}"
115
+ if marked:
116
+ return _recorded_conformance_state(project_root, run_manifest, entry, key)
117
+ return _sidecar_conformance_state(task_root, entry, key)
118
+
119
+
120
+ def _sidecar_conformance_state(task_root: Path, entry: dict, key: str) -> tuple[bool, str]:
94
121
  sidecar = conformance_result_file(task_qa_dir(task_root), key)
95
122
  result = None
96
123
  if sidecar.is_file():
@@ -106,6 +133,22 @@ def _conformance_state(task_root: Path, stage: int) -> tuple[bool, str]:
106
133
  return verdict.ok, f"{verdict.status}: {verdict.message}"
107
134
 
108
135
 
136
+ def _recorded_conformance_state(
137
+ project_root: Path, run_manifest: Path, entry: dict, key: str,
138
+ ) -> tuple[bool, str]:
139
+ try:
140
+ run_evidence = collect_conformance_evidence(project_root, run_manifest, [key])
141
+ except ValueError as exc:
142
+ return False, (f"BLOCKING: execution records of {run_manifest} could not "
143
+ f"be collected ({exc})")
144
+ stage_evidence = run_evidence.results[key]
145
+ verdict = decide_conformance_gate(entry, stage_evidence.result)
146
+ # As in validate-run: an exemption, waiver or advisory entry passes without
147
+ # a usable record, and rejected records only explain a blocking verdict.
148
+ message = (stage_evidence.unusable_summary() if not verdict.ok else None) or verdict.message
149
+ return verdict.ok, f"{verdict.status}: {message} (from {run_manifest})"
150
+
151
+
109
152
  def close_stage(
110
153
  project_root: Path, task_key: str, stage: int, head_commit: str,
111
154
  *, supersede_failed: str = "",
@@ -173,7 +216,7 @@ def close_stage(
173
216
  stage="git",
174
217
  )
175
218
 
176
- ok, conformance = _conformance_state(task_root, stage)
219
+ ok, conformance = _conformance_state(project_root, task_root, stage)
177
220
  if not ok:
178
221
  raise StateError(
179
222
  f"stage {stage} conformance does not permit closing it "
@@ -223,7 +266,10 @@ whose work is already committed but which never registered as done (the run
223
266
  ended before writing its carry sidecar). Refuses unless the Stage Map has that
224
267
  stage and does not mark it cancelled, no `done`/`failed` row exists for it,
225
268
  `--from-commit` resolves to a commit in the project repo, and the stage's
226
- conformance gate permits progress. `--supersede-failed` accepts a stage whose
269
+ conformance gate permits progress. When the stage's latest implementation run
270
+ is marked `verificationEvidenceVersion`, the conformance result comes from that
271
+ run's execution records instead of `qa/result-<stageKey>.json`.
272
+ `--supersede-failed` accepts a stage whose
227
273
  last row is `failed` under the same checks and records the reason, the latest
228
274
  plan path and the conformance verdict on the `done` row.
229
275