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.
- package/README.md +3 -3
- package/docs/architecture/storage-model.md +67 -6
- package/docs/architecture.md +6 -2
- package/docs/coding-rules.md +15 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +2 -2
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/coding-preflight/clean-code.md +8 -0
- package/runtime/prompts/coding-preflight/overview.md +1 -0
- package/runtime/prompts/launch.template.md +2 -0
- package/runtime/prompts/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
- package/runtime/python/okstra_ctl/agent/invocation.py +48 -4
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
- package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
- package/runtime/python/okstra_ctl/paths.py +19 -4
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +1 -0
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +1 -0
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +5 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +20 -4
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +2 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +230 -30
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
- package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +28 -0
- package/runtime/python/okstra_ctl/render.py +15 -0
- package/runtime/python/okstra_ctl/report_assembly.py +102 -1
- package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
- package/runtime/python/okstra_ctl/report_inputs.py +28 -0
- package/runtime/python/okstra_ctl/report_narrative.py +12 -3
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +8 -0
- package/runtime/python/okstra_ctl/run.py +16 -0
- package/runtime/python/okstra_ctl/stage_close.py +52 -6
- package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
- package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
- package/runtime/python/okstra_ctl/team.py +3 -1
- package/runtime/python/okstra_ctl/verification_dispatch.py +8 -2
- package/runtime/python/okstra_ctl/verification_evidence.py +26 -7
- package/runtime/python/okstra_ctl/verification_generation.py +12 -4
- package/runtime/python/okstra_ctl/verification_inputs.py +10 -0
- package/runtime/python/okstra_ctl/verification_invocation.py +2 -1
- package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
- package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
- package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
- package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- package/runtime/schemas/final-report-v3.0.schema.json +184 -1
- package/runtime/skills/okstra-run/SKILL.md +5 -1
- package/runtime/templates/reports/html/i18n/en.json +7 -0
- package/runtime/templates/reports/html/i18n/ko.json +7 -0
- package/runtime/validators/validate-run.py +27 -11
- 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
|
|
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 =
|
|
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
|
|
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
|
|
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.
|
|
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():
|