okstra 0.230.0 → 0.231.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +3 -3
  2. package/docs/architecture/storage-model.md +67 -6
  3. package/docs/architecture.md +6 -2
  4. package/docs/coding-rules.md +15 -0
  5. package/docs/project-structure-overview.md +2 -1
  6. package/package.json +2 -2
  7. package/runtime/BUILD.json +2 -2
  8. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  9. package/runtime/prompts/coding-preflight/overview.md +1 -0
  10. package/runtime/prompts/launch.template.md +2 -0
  11. package/runtime/prompts/lead/convergence.md +3 -3
  12. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  13. package/runtime/prompts/lead/report-writer.md +1 -1
  14. package/runtime/prompts/lead/team-contract.md +1 -1
  15. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  16. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  17. package/runtime/python/okstra_ctl/agent/invocation.py +48 -4
  18. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  19. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  20. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  21. package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
  22. package/runtime/python/okstra_ctl/convergence.py +112 -20
  23. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  24. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  25. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  26. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  27. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  28. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  29. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  30. package/runtime/python/okstra_ctl/paths.py +19 -4
  31. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +1 -0
  32. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  33. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +1 -0
  34. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  35. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +5 -1
  36. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +3 -1
  37. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +20 -4
  38. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  39. package/runtime/python/okstra_ctl/phases/implementation/spec.md +2 -0
  40. package/runtime/python/okstra_ctl/phases/implementation/validation.py +230 -30
  41. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  42. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  43. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  44. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  45. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  47. package/runtime/python/okstra_ctl/render.py +15 -0
  48. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  49. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  50. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  51. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  52. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  53. package/runtime/python/okstra_ctl/report_synthesis_packet.py +8 -0
  54. package/runtime/python/okstra_ctl/run.py +16 -0
  55. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  56. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  57. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  58. package/runtime/python/okstra_ctl/team.py +3 -1
  59. package/runtime/python/okstra_ctl/verification_dispatch.py +8 -2
  60. package/runtime/python/okstra_ctl/verification_evidence.py +26 -7
  61. package/runtime/python/okstra_ctl/verification_generation.py +12 -4
  62. package/runtime/python/okstra_ctl/verification_inputs.py +10 -0
  63. package/runtime/python/okstra_ctl/verification_invocation.py +2 -1
  64. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  65. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  66. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  67. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  68. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  69. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  70. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  71. package/runtime/skills/okstra-run/SKILL.md +5 -1
  72. package/runtime/templates/reports/html/i18n/en.json +7 -0
  73. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  74. package/runtime/validators/validate-run.py +27 -11
  75. package/runtime/validators/validate-workflow.sh +1 -1
@@ -17,10 +17,20 @@ from .clarification_items import (
17
17
  row_blocks_progress,
18
18
  )
19
19
  from .final_report_schema import load_schema_version, validate
20
- from .report_inputs import ReportInputPath, report_input_paths, uses_report_contract_v3
20
+ from .report_inputs import (
21
+ EXECUTION_EVIDENCE_INPUT,
22
+ EXECUTION_EVIDENCE_OWNER,
23
+ ReportInputPath,
24
+ report_input_paths,
25
+ uses_report_contract_v3,
26
+ )
21
27
  from .correction_round import correction_convergence_states, correction_round
22
28
  from .json_boundary import JsonBoundaryError, load_owned_object, serialize_owned_object
23
29
  from .report_narrative import parse_narrative, task_narrative_errors
30
+ from .report_execution_evidence import (
31
+ RECORD_DERIVED_TIERS, collect_report_evidence, command_row,
32
+ )
33
+ from .verification_evidence import roster_verifier_role_execution_ref
24
34
  from .report_synthesis_packet import (
25
35
  report_synthesis_packet_paths,
26
36
  verify_report_synthesis_packet_sources,
@@ -146,6 +156,12 @@ def _input_preflight_issues(
146
156
  ) -> tuple[AssemblyIssue, ...]:
147
157
  issues: list[AssemblyIssue] = []
148
158
  for row in inputs.values():
159
+ if row.key == EXECUTION_EVIDENCE_INPUT:
160
+ if not row.path.is_dir():
161
+ issues.append(AssemblyIssue(
162
+ row.owner, str(row.path), "$", "required input is missing",
163
+ ))
164
+ continue
149
165
  if not row.path.is_file():
150
166
  issues.append(
151
167
  AssemblyIssue(
@@ -543,6 +559,7 @@ def _compose(
543
559
  if scope:
544
560
  data["verificationScope"] = scope
545
561
  data["agentActivity"] = activities
562
+ _attach_execution_evidence(data, project_root, manifest_path, manifest, inputs)
546
563
  data["evidence"] = {"primary": _promoted_evidence([
547
564
  *(("convergence", item) for item in convergence_data["promotedEvidence"]),
548
565
  *round_evidence,
@@ -561,6 +578,88 @@ def _compose(
561
578
  return data
562
579
 
563
580
 
581
+ def _attach_execution_evidence(
582
+ data: dict[str, Any], project_root: Path, manifest_path: Path,
583
+ manifest: Mapping[str, Any], inputs: Mapping[str, ReportInputPath],
584
+ ) -> None:
585
+ """Copy what the verification execution records observed into the report.
586
+
587
+ The narrative keeps each verifier's judgment and observations; the records
588
+ are the only source of a check's command, outcome and output.
589
+ """
590
+ row = inputs.get(EXECUTION_EVIDENCE_INPUT)
591
+ if row is None:
592
+ return
593
+ try:
594
+ evidence = collect_report_evidence(project_root, manifest_path)
595
+ except ValueError as exc:
596
+ _fail(row.owner, row.path, "$", exc)
597
+ narrative = inputs["narrative"]
598
+ if manifest.get("taskType") == "implementation":
599
+ issues = _attach_verifier_evidence(data, manifest, evidence, narrative)
600
+ else:
601
+ issues = _attach_command_log_evidence(data, evidence, narrative)
602
+ if issues:
603
+ raise ReportAssemblyError(tuple(issues))
604
+
605
+
606
+ def _attach_verifier_evidence(
607
+ data: dict[str, Any], manifest: Mapping[str, Any],
608
+ evidence: Mapping[str, Any], narrative: ReportInputPath,
609
+ ) -> list[AssemblyIssue]:
610
+ implementation = data.get("implementation")
611
+ rows = implementation.get("verifierResults") if isinstance(implementation, dict) else None
612
+ issues = []
613
+ for index, row in enumerate(rows if isinstance(rows, list) else []):
614
+ if not isinstance(row, dict) or row.get("verdict") == "not-run":
615
+ continue
616
+ role_execution_ref = roster_verifier_role_execution_ref(manifest, row.get("verifier"))
617
+ if role_execution_ref is None:
618
+ issues.append(AssemblyIssue(
619
+ narrative.owner, str(narrative.path),
620
+ f"implementation.verifierResults[{index}].verifier",
621
+ "an evidence-contract run attaches execution records by roster "
622
+ f"verifier worker id; `{row.get('verifier')}` names none",
623
+ ))
624
+ continue
625
+ verifier = evidence.get(role_execution_ref)
626
+ if verifier is not None and verifier.references:
627
+ row["executionEvidence"] = [dict(item) for item in verifier.references]
628
+ return issues
629
+
630
+
631
+ def _attach_command_log_evidence(
632
+ data: dict[str, Any], evidence: Mapping[str, Any], narrative: ReportInputPath,
633
+ ) -> list[AssemblyIssue]:
634
+ final = data.get("finalVerification")
635
+ if not isinstance(final, dict):
636
+ return []
637
+ log = final.get("readonlyCommandLog")
638
+ rows = log if isinstance(log, list) else []
639
+ issues = [
640
+ AssemblyIssue(
641
+ narrative.owner, str(narrative.path),
642
+ f"finalVerification.readonlyCommandLog[{index}]",
643
+ f"an evidence-contract run takes executed Tier {row.get('tier')} rows "
644
+ "from its verification execution records",
645
+ )
646
+ for index, row in enumerate(rows)
647
+ if isinstance(row, dict) and row.get("status") == "executed"
648
+ and row.get("tier") in RECORD_DERIVED_TIERS
649
+ ]
650
+ number = max((row["number"] for row in rows if isinstance(row, dict)
651
+ and isinstance(row.get("number"), int)), default=0)
652
+ derived = [
653
+ command_row(number + offset, reference)
654
+ for offset, reference in enumerate(
655
+ (reference for verifier in evidence.values()
656
+ for reference in verifier.references), start=1)
657
+ ]
658
+ if derived:
659
+ final["readonlyCommandLog"] = [*rows, *derived]
660
+ return issues
661
+
662
+
564
663
  def _attach_discussion(data: dict[str, Any], project_root: Path, manifest: Mapping[str, Any]) -> None:
565
664
  """확정본은 토론 기록이 정본이다 — 보고서에는 조립이 그 id 와 digest 만 옮긴다."""
566
665
  if manifest.get("taskType") != "discussion":
@@ -838,6 +937,8 @@ def _schema_owner(error: str, narrative_owner: str) -> str:
838
937
  return "design-surface-detector"
839
938
  if "planBodyVerification" in error:
840
939
  return "convergence"
940
+ if "executionEvidence" in error:
941
+ return EXECUTION_EVIDENCE_OWNER
841
942
  if "selectedDirectionRef" in error:
842
943
  return narrative_owner
843
944
  return owners.get(field.split(".", 1)[0], narrative_owner)
@@ -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)
@@ -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
  )
@@ -151,3 +151,10 @@ PROSE_KEYS = frozenset({
151
151
  "whyItMatters",
152
152
  "workingAssumption",
153
153
  })
154
+
155
+
156
+ # A stringified null is not prose. Lowercase `none` is a token the clarification
157
+ # option contract uses on purpose ("reverses nothing"), so only the capitalised
158
+ # and language-native spellings count — 2026-09-05 audit: `"None"` in 16
159
+ # trade-off cells and 2 option fields across the shipped reports.
160
+ NULL_LITERALS = frozenset({"None", "null", "undefined", "NaN"})
@@ -263,6 +263,14 @@ class ReportSynthesisPacket:
263
263
  "state` is the initial round's. Describe the stage's open findings from the "
264
264
  "last round's re-convergence, not the initial one; report what each round "
265
265
  "fixed through `implementation.correctionRounds`.",
266
+ "`implementation.verifierResults[]` holds each verifier's last-round "
267
+ "verdict. Its `implementation.verifierResults[].discrepancy` records only "
268
+ "a divergence between that verifier's last-round rerun and the executor's "
269
+ "reported result: leave it empty when that rerun matched. A verdict that "
270
+ "changed between rounds (an initial `FAIL`, then `PASS`) is not a "
271
+ "discrepancy; `implementation.correctionRounds[].verifierVerdicts` records "
272
+ "it. `validate-run` reads any text in `discrepancy` beside a `PASS` "
273
+ "verdict as an unresolved divergence.",
266
274
  ]
267
275
  if self.task_type != "implementation-option-selection":
268
276
  return []
@@ -107,6 +107,8 @@ from .verification_input_ref import (
107
107
  VerificationInputReference, retain_recorded_reference,
108
108
  )
109
109
  from .ports.verification_inputs import VerificationInputStore
110
+ from .verification_inputs import evidence_contract_applies
111
+ from .verification_invocation import VERIFICATION_EVIDENCE_VERSION
110
112
  from .registry.verification_inputs_store import default_verification_input_store
111
113
  from .material import (
112
114
  build_analysis_material,
@@ -3483,6 +3485,7 @@ def _prepare_verification_input_reference(
3483
3485
  reference = store.freeze(
3484
3486
  project_root, source, run_ref, approved_plan=approved_plan,
3485
3487
  )
3488
+ _mark_evidence_contract(ctx, store, project_root, reference)
3486
3489
  else:
3487
3490
  _validate_recorded_verification_inputs(
3488
3491
  project_root, source, run_ref, reference, store, approved_plan,
@@ -3492,6 +3495,19 @@ def _prepare_verification_input_reference(
3492
3495
  raise PrepareError(f"verification inputs preparation failed: {exc}") from exc
3493
3496
 
3494
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
+
3495
3511
  def _persist_pre_dispatch_run_manifest(ctx: dict) -> None:
3496
3512
  """Publish and re-read the complete invocation authority before prompts."""
3497
3513
  render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
@@ -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
 
@@ -17,7 +17,9 @@ from pathlib import Path
17
17
 
18
18
  from .consumers import read_consumers
19
19
  from .json_boundary import JsonBoundaryError, load_owned_object
20
+ from .paths import RunRef
20
21
  from .phases.implementation.validation import lead_fixed_verifiers
22
+ from .report_inputs import uses_execution_evidence
21
23
 
22
24
  _REPORT_RE = re.compile(r"final-report-implementation-(\d+)\.data\.json$")
23
25
  _SEQ_RE = re.compile(r"-(\d+)\.data\.json$")
@@ -113,7 +115,7 @@ def derive_stage_fix_carry(
113
115
  if not isinstance(impl, dict):
114
116
  return None
115
117
  # 통과한 리드 수정이 답한 FAIL 은 그 run 안에서 해소됐다 — 다시 fix run 으로 넘기지 않는다.
116
- fixed = lead_fixed_verifiers(impl)
118
+ fixed = lead_fixed_verifiers(impl, evidence_contract=_evidence_contract(report))
117
119
  failed = [
118
120
  row for row in impl.get("verifierResults") or []
119
121
  if isinstance(row, dict) and row.get("verdict") == "FAIL"
@@ -231,6 +233,24 @@ def _routing_line(value: object) -> str:
231
233
  return target or rationale
232
234
 
233
235
 
236
+ def _evidence_contract(report: Path) -> bool:
237
+ """Whether the report's run is under the verification evidence contract. An
238
+ unsupported contract version counts as one, so its lead fixes resolve
239
+ nothing."""
240
+ try:
241
+ manifest = load_owned_object(
242
+ RunRef.from_report_path(report).manifest, artifact="run manifest",
243
+ )
244
+ except (OSError, JsonBoundaryError, ValueError):
245
+ # expected-miss: a report from before run manifests sat beside it is
246
+ # from before the contract existed.
247
+ return False
248
+ try:
249
+ return uses_execution_evidence(manifest)
250
+ except ValueError:
251
+ return True
252
+
253
+
234
254
  def _latest_report(stage_run_dir: Path) -> Path | None:
235
255
  reports_dir = stage_run_dir / "reports"
236
256
  if not reports_dir.is_dir():