okstra 0.230.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.
- package/docs/architecture/storage-model.md +67 -6
- package/docs/architecture.md +2 -0
- 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/okstra-lead-contract.md +5 -5
- 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/blocking_checks.py +10 -0
- package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
- 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 +2 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +19 -3
- 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 +152 -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/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/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/worktree/git_ops.py +8 -1
- package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
- 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 +24 -5
- package/runtime/validators/validate-workflow.sh +1 -1
|
@@ -6,22 +6,23 @@ verification needs a PASS from every verifier it dispatched.
|
|
|
6
6
|
"""
|
|
7
7
|
from __future__ import annotations
|
|
8
8
|
|
|
9
|
+
from contextlib import contextmanager
|
|
9
10
|
from dataclasses import dataclass, field
|
|
10
11
|
from pathlib import Path
|
|
11
|
-
from typing import Iterable, Mapping
|
|
12
|
+
from typing import Any, Iterable, Iterator, Mapping
|
|
12
13
|
|
|
13
|
-
from .agent.invocation import AgentInvocationError
|
|
14
|
+
from .agent.invocation import AgentInvocationError, reserved_generation_reference
|
|
14
15
|
from .conformance import QaResult, execution_evidence_defect, qa_result_from_execution
|
|
15
16
|
from .execution_identity import ExecutionManifest, Invocation
|
|
16
17
|
from .execution_manifest import read_execution_manifest
|
|
17
18
|
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
18
19
|
from .paths import RunRef
|
|
19
20
|
from .qa_commands import QA_VERIFIER_AUDIENCE_BY_TASK_TYPE
|
|
20
|
-
from .qa_procedures import content_digest
|
|
21
21
|
from .verification_conformance import conformance_stage
|
|
22
22
|
from .verification_dispatch import verification_generation_number
|
|
23
23
|
from .verification_evidence import (
|
|
24
|
-
|
|
24
|
+
VerificationExecutionRecord, conformance_check_owner_ref,
|
|
25
|
+
read_verification_execution_record,
|
|
25
26
|
)
|
|
26
27
|
from .verification_generation import (
|
|
27
28
|
VerificationGenerationRecord, read_verification_generation,
|
|
@@ -37,6 +38,14 @@ class StageEvidence:
|
|
|
37
38
|
records: tuple[Path, ...]
|
|
38
39
|
rejections: Mapping[Path, str] = field(default_factory=dict)
|
|
39
40
|
|
|
41
|
+
def unusable_summary(self) -> str | None:
|
|
42
|
+
"""Why a stage without a result has none, when its latest records were
|
|
43
|
+
rejected; None otherwise."""
|
|
44
|
+
if self.result is not None or not self.rejections:
|
|
45
|
+
return None
|
|
46
|
+
return "no usable execution record: " + "; ".join(
|
|
47
|
+
f"{path} ({reason})" for path, reason in self.rejections.items())
|
|
48
|
+
|
|
40
49
|
|
|
41
50
|
@dataclass(frozen=True)
|
|
42
51
|
class RunConformanceEvidence:
|
|
@@ -57,8 +66,8 @@ _NO_OUTCOME = _VerifierOutcome(None)
|
|
|
57
66
|
|
|
58
67
|
|
|
59
68
|
@dataclass(frozen=True)
|
|
60
|
-
class
|
|
61
|
-
"""One verifier invocation and the generation its
|
|
69
|
+
class BoundInvocation:
|
|
70
|
+
"""One verifier invocation and the generation its metadata binds."""
|
|
62
71
|
|
|
63
72
|
invocation: Invocation
|
|
64
73
|
generation_number: int
|
|
@@ -71,37 +80,74 @@ class _BoundInvocation:
|
|
|
71
80
|
and stage in self.generation.get("conformanceStages", ()))
|
|
72
81
|
|
|
73
82
|
|
|
83
|
+
@dataclass(frozen=True)
|
|
84
|
+
class RunVerifiers:
|
|
85
|
+
"""A QA-executing run's verifier invocations, newest first per role
|
|
86
|
+
execution, and each invocation's latest attempt."""
|
|
87
|
+
|
|
88
|
+
manifest: dict[str, Any]
|
|
89
|
+
ref: RunRef
|
|
90
|
+
verifiers: dict[str, list[BoundInvocation]]
|
|
91
|
+
latest_attempt: dict[str, int]
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@dataclass(frozen=True)
|
|
95
|
+
class CheckRunRecord:
|
|
96
|
+
"""The latest run of one check; `defect` says why it is no usable evidence
|
|
97
|
+
(None when it is)."""
|
|
98
|
+
|
|
99
|
+
check_run: int
|
|
100
|
+
path: Path
|
|
101
|
+
record: VerificationExecutionRecord | None
|
|
102
|
+
output: bytes | None
|
|
103
|
+
defect: str | None
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
@contextmanager
|
|
107
|
+
def evidence_read_errors() -> Iterator[None]:
|
|
108
|
+
"""Raise an unreadable invocation or file as the ValueError evidence
|
|
109
|
+
collection reports."""
|
|
110
|
+
try:
|
|
111
|
+
yield
|
|
112
|
+
except (AgentInvocationError, OSError) as exc:
|
|
113
|
+
raise ValueError(str(exc)) from exc
|
|
114
|
+
|
|
115
|
+
|
|
74
116
|
def collect_conformance_evidence(
|
|
75
117
|
project: Path, manifest_path: Path, stage_keys: Iterable[str],
|
|
76
118
|
) -> RunConformanceEvidence:
|
|
77
|
-
|
|
119
|
+
with evidence_read_errors():
|
|
78
120
|
return _collect(project.resolve(), manifest_path.resolve(), tuple(stage_keys))
|
|
79
|
-
except (AgentInvocationError, OSError) as exc:
|
|
80
|
-
raise ValueError(str(exc)) from exc
|
|
81
121
|
|
|
82
122
|
|
|
83
123
|
def _collect(
|
|
84
124
|
project: Path, manifest_path: Path, stage_keys: tuple[str, ...],
|
|
85
125
|
) -> RunConformanceEvidence:
|
|
126
|
+
run = load_run_verifiers(project, manifest_path)
|
|
127
|
+
owner = conformance_check_owner_ref(run.manifest)
|
|
128
|
+
counted = list(run.verifiers) if owner is None else [owner]
|
|
129
|
+
return RunConformanceEvidence(_required_stages(run.verifiers), {
|
|
130
|
+
key: _stage_evidence(run, counted, key) for key in stage_keys
|
|
131
|
+
})
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def load_run_verifiers(project: Path, manifest_path: Path) -> RunVerifiers:
|
|
86
135
|
manifest = load_owned_object(manifest_path, artifact="run manifest")
|
|
87
136
|
ref = RunRef.from_manifest(manifest_path, manifest)
|
|
88
137
|
audience = QA_VERIFIER_AUDIENCE_BY_TASK_TYPE.get(manifest.get("taskType"))
|
|
89
138
|
if audience is None:
|
|
90
139
|
raise ValueError("verification evidence requires a QA-executing run")
|
|
91
140
|
execution = read_execution_manifest(manifest_path)
|
|
92
|
-
verifiers = _bound_verifiers(project, ref, execution, audience)
|
|
93
|
-
owner = conformance_check_owner_ref(manifest)
|
|
94
|
-
counted = list(verifiers) if owner is None else [owner]
|
|
95
141
|
latest_attempt = _latest_attempts(execution)
|
|
96
|
-
return
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
142
|
+
return RunVerifiers(
|
|
143
|
+
manifest, ref,
|
|
144
|
+
_bound_verifiers(project, ref, manifest, execution, audience, latest_attempt),
|
|
145
|
+
latest_attempt,
|
|
146
|
+
)
|
|
100
147
|
|
|
101
148
|
|
|
102
149
|
def _stage_evidence(
|
|
103
|
-
|
|
104
|
-
counted: list[str], stage_key: str, latest_attempt: Mapping[str, int],
|
|
150
|
+
run: RunVerifiers, counted: list[str], stage_key: str,
|
|
105
151
|
) -> StageEvidence:
|
|
106
152
|
"""A counted verifier with no invocation bound to the newest generation that
|
|
107
153
|
seals the stage leaves it without a result; an older generation's record
|
|
@@ -112,27 +158,27 @@ def _stage_evidence(
|
|
|
112
158
|
# expected-miss: a malformed key names no stage a generation can seal,
|
|
113
159
|
# so no record can exist for it.
|
|
114
160
|
return StageEvidence(None, ())
|
|
115
|
-
newest = max((binding.generation_number for bindings in verifiers.values()
|
|
161
|
+
newest = max((binding.generation_number for bindings in run.verifiers.values()
|
|
116
162
|
for binding in bindings if binding.seals(stage)), default=None)
|
|
117
163
|
if newest is None:
|
|
118
164
|
return StageEvidence(None, ())
|
|
119
165
|
return _combine([
|
|
120
|
-
_verifier_result(
|
|
121
|
-
newest, stage_key, latest_attempt)
|
|
166
|
+
_verifier_result(run, role_execution_ref, newest, stage_key)
|
|
122
167
|
for role_execution_ref in counted
|
|
123
168
|
])
|
|
124
169
|
|
|
125
170
|
|
|
126
171
|
def _bound_verifiers(
|
|
127
|
-
project: Path, ref: RunRef,
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
verifiers: dict[str, list[
|
|
172
|
+
project: Path, ref: RunRef, manifest: Mapping[str, Any],
|
|
173
|
+
execution: ExecutionManifest, audience: str, latest_attempt: Mapping[str, int],
|
|
174
|
+
) -> dict[str, list[BoundInvocation]]:
|
|
175
|
+
verifiers: dict[str, list[BoundInvocation]] = {}
|
|
131
176
|
for index, invocation in enumerate(execution.invocations):
|
|
132
177
|
if invocation.duty_id == audience:
|
|
133
|
-
verifiers.setdefault(invocation.role_execution_ref, []).append(
|
|
134
|
-
|
|
135
|
-
|
|
178
|
+
verifiers.setdefault(invocation.role_execution_ref, []).append(_bind(
|
|
179
|
+
project, ref, manifest, invocation, index,
|
|
180
|
+
latest_attempt.get(invocation.invocation_ref, 1),
|
|
181
|
+
))
|
|
136
182
|
for bindings in verifiers.values():
|
|
137
183
|
bindings.sort(key=lambda binding: (binding.generation_number, binding.index),
|
|
138
184
|
reverse=True)
|
|
@@ -146,7 +192,7 @@ def _latest_attempts(execution: ExecutionManifest) -> dict[str, int]:
|
|
|
146
192
|
return latest
|
|
147
193
|
|
|
148
194
|
|
|
149
|
-
def _required_stages(verifiers: Mapping[str, list[
|
|
195
|
+
def _required_stages(verifiers: Mapping[str, list[BoundInvocation]]) -> frozenset[int]:
|
|
150
196
|
return frozenset(
|
|
151
197
|
stage for bindings in verifiers.values() for binding in bindings
|
|
152
198
|
if binding.generation is not None
|
|
@@ -155,67 +201,102 @@ def _required_stages(verifiers: Mapping[str, list[_BoundInvocation]]) -> frozens
|
|
|
155
201
|
|
|
156
202
|
|
|
157
203
|
def _bind(
|
|
158
|
-
project: Path, ref: RunRef,
|
|
159
|
-
|
|
204
|
+
project: Path, ref: RunRef, manifest: Mapping[str, Any], invocation: Invocation,
|
|
205
|
+
index: int, attempt: int,
|
|
206
|
+
) -> BoundInvocation:
|
|
207
|
+
"""The generation the invocation's metadata binds, which must be the one its
|
|
208
|
+
dispatch kind seals and still have the bytes the metadata recorded."""
|
|
160
209
|
number = verification_generation_number(invocation.dispatch_kind)
|
|
161
210
|
path = ref.verification_generation(number)
|
|
162
211
|
relative = path.relative_to(project).as_posix()
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
212
|
+
reference = reserved_generation_reference(
|
|
213
|
+
project, manifest, invocation.invocation_ref, attempt,
|
|
214
|
+
)
|
|
215
|
+
if reference is None:
|
|
216
|
+
return BoundInvocation(invocation, number, index, None,
|
|
217
|
+
{"path": relative, "digest": ""})
|
|
218
|
+
if reference.path != relative:
|
|
219
|
+
raise ValueError(
|
|
220
|
+
f"invocation {invocation.invocation_ref} is bound to {reference.path}, "
|
|
221
|
+
f"not to {relative}, the generation its dispatch seals"
|
|
222
|
+
)
|
|
223
|
+
try:
|
|
224
|
+
generation = read_verification_generation(path, reference.digest)
|
|
225
|
+
except ValueError as exc:
|
|
226
|
+
raise ValueError(
|
|
227
|
+
f"generation {relative} of invocation {invocation.invocation_ref}: {exc}"
|
|
228
|
+
) from exc
|
|
229
|
+
return BoundInvocation(invocation, number, index, generation, reference.to_payload())
|
|
170
230
|
|
|
171
231
|
|
|
172
232
|
def _verifier_result(
|
|
173
|
-
|
|
174
|
-
|
|
233
|
+
run: RunVerifiers, role_execution_ref: str, generation_number: int,
|
|
234
|
+
stage_key: str,
|
|
175
235
|
) -> _VerifierOutcome:
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
if chosen is None:
|
|
236
|
+
bound = bound_attempt(run, role_execution_ref, generation_number)
|
|
237
|
+
if bound is None:
|
|
179
238
|
return _NO_OUTCOME
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
if
|
|
239
|
+
check = read_latest_check_run(run.ref, role_execution_ref, *bound,
|
|
240
|
+
f"conformance:{stage_key}")
|
|
241
|
+
if check is None:
|
|
183
242
|
return _NO_OUTCOME
|
|
184
|
-
|
|
243
|
+
if check.defect is not None or check.record is None or check.output is None:
|
|
244
|
+
return _VerifierOutcome(None, check.path, check.defect)
|
|
245
|
+
return _VerifierOutcome(qa_result_from_execution(check.record, check.output),
|
|
246
|
+
check.path)
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
def bound_attempt(
|
|
250
|
+
run: RunVerifiers, role_execution_ref: str, generation_number: int,
|
|
251
|
+
) -> tuple[BoundInvocation, int] | None:
|
|
252
|
+
"""The verifier's invocation bound to the generation, with its latest
|
|
253
|
+
attempt; None when it has no such invocation or attempt."""
|
|
254
|
+
chosen = next((binding for binding in run.verifiers.get(role_execution_ref, [])
|
|
255
|
+
if binding.generation is not None
|
|
256
|
+
and binding.generation_number == generation_number), None)
|
|
257
|
+
if chosen is None:
|
|
258
|
+
return None
|
|
259
|
+
attempt = run.latest_attempt.get(chosen.invocation.invocation_ref)
|
|
260
|
+
return None if attempt is None else (chosen, attempt)
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def read_latest_check_run(
|
|
264
|
+
ref: RunRef, role_execution_ref: str, binding: BoundInvocation, attempt: int,
|
|
265
|
+
check_ref: str,
|
|
266
|
+
) -> CheckRunRecord | None:
|
|
267
|
+
"""The latest run of one check under an attempt of a bound invocation; None
|
|
268
|
+
when the attempt never ran the check."""
|
|
269
|
+
invocation_ref = binding.invocation.invocation_ref
|
|
185
270
|
check_run = ref.latest_verification_check_run(invocation_ref, attempt, check_ref)
|
|
186
271
|
if check_run is None:
|
|
187
|
-
return
|
|
188
|
-
run_dir = ref.verification_execution_dir(
|
|
189
|
-
|
|
190
|
-
)
|
|
191
|
-
expected = {
|
|
272
|
+
return None
|
|
273
|
+
run_dir = ref.verification_execution_dir(invocation_ref, attempt, check_ref, check_run)
|
|
274
|
+
record, output, defect = _read_bound_record(run_dir, {
|
|
192
275
|
"invocationRef": invocation_ref, "roleExecutionRef": role_execution_ref,
|
|
193
276
|
"attempt": attempt, "checkRef": check_ref, "checkRun": check_run,
|
|
194
|
-
"verificationGeneration":
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
result, rejection = _recorded_result(run_dir, expected)
|
|
198
|
-
return _VerifierOutcome(result, record_path, rejection)
|
|
277
|
+
"verificationGeneration": binding.generation_ref,
|
|
278
|
+
})
|
|
279
|
+
return CheckRunRecord(check_run, run_dir / "record.json", record, output, defect)
|
|
199
280
|
|
|
200
281
|
|
|
201
|
-
def
|
|
282
|
+
def _read_bound_record(
|
|
202
283
|
run_dir: Path, expected: Mapping[str, object],
|
|
203
|
-
) -> tuple[
|
|
284
|
+
) -> tuple[VerificationExecutionRecord | None, bytes | None, str | None]:
|
|
285
|
+
"""One check run's record, its saved stdout, and why the run is no usable
|
|
286
|
+
evidence (None when it is); `expected` are the record fields its location
|
|
287
|
+
and binding determine."""
|
|
204
288
|
try:
|
|
205
289
|
record = read_verification_execution_record(run_dir / "record.json")
|
|
206
290
|
except (JsonBoundaryError, OSError) as exc:
|
|
207
|
-
return None, f"record is unreadable ({exc})"
|
|
291
|
+
return None, None, f"record is unreadable ({exc})"
|
|
208
292
|
if any(record[name] != value for name, value in expected.items()):
|
|
209
|
-
return None, ("record identity, attempt, check run or generation
|
|
210
|
-
|
|
293
|
+
return record, None, ("record identity, attempt, check run or generation "
|
|
294
|
+
"differs from its location")
|
|
211
295
|
try:
|
|
212
296
|
output = (run_dir / "stdout.log").read_bytes()
|
|
213
297
|
except OSError as exc:
|
|
214
|
-
return None, f"saved stdout is unreadable ({exc})"
|
|
215
|
-
|
|
216
|
-
if defect is not None:
|
|
217
|
-
return None, defect
|
|
218
|
-
return qa_result_from_execution(record, output), None
|
|
298
|
+
return record, None, f"saved stdout is unreadable ({exc})"
|
|
299
|
+
return record, output, execution_evidence_defect(record, output)
|
|
219
300
|
|
|
220
301
|
|
|
221
302
|
def _combine(outcomes: list[_VerifierOutcome]) -> StageEvidence:
|
|
@@ -33,6 +33,9 @@ class VerificationSourceSnapshot:
|
|
|
33
33
|
input_paths: frozenset[str]
|
|
34
34
|
protected_files: Mapping[str, str]
|
|
35
35
|
generated_files: Mapping[str, str]
|
|
36
|
+
# Ignored roots that held output at this capture. Unlike `generated_roots`
|
|
37
|
+
# they may differ between captures, so comparisons never require equality.
|
|
38
|
+
ignored_roots: frozenset[str] = frozenset()
|
|
36
39
|
|
|
37
40
|
|
|
38
41
|
@dataclass(frozen=True)
|
|
@@ -562,9 +565,13 @@ def capture_verification_source(
|
|
|
562
565
|
f"verification source path contains a symlink ancestor: {relative}"
|
|
563
566
|
)
|
|
564
567
|
files[relative] = _path_digest(path)
|
|
568
|
+
# A Git-ignored path is output the repository declares is not source, such
|
|
569
|
+
# as a build directory or a test cache; a verification command may rewrite
|
|
570
|
+
# it. Tracked files and explicit inputs stay protected even when ignored.
|
|
571
|
+
ignored = _ignored_paths(root)
|
|
565
572
|
generated_files = {
|
|
566
573
|
relative: digest for relative, digest in files.items()
|
|
567
|
-
if is_generated_verification_path(relative, generated, protected)
|
|
574
|
+
if is_generated_verification_path(relative, generated | ignored, protected)
|
|
568
575
|
}
|
|
569
576
|
protected_files = {
|
|
570
577
|
relative: digest for relative, digest in files.items()
|
|
@@ -574,6 +581,11 @@ def capture_verification_source(
|
|
|
574
581
|
root=root, tracked_paths=tracked, generated_roots=generated,
|
|
575
582
|
input_paths=inputs, protected_files=MappingProxyType(protected_files),
|
|
576
583
|
generated_files=MappingProxyType(generated_files),
|
|
584
|
+
ignored_roots=frozenset(
|
|
585
|
+
ignored_root for ignored_root in ignored
|
|
586
|
+
if any(_excluded(Path(relative), frozenset({ignored_root}))
|
|
587
|
+
for relative in generated_files)
|
|
588
|
+
),
|
|
577
589
|
)
|
|
578
590
|
|
|
579
591
|
|
|
@@ -17,9 +17,10 @@ from .plan_item_evidence import dependency_scopes, reusable_item_ids
|
|
|
17
17
|
from .plan_items import (
|
|
18
18
|
PlanItemContractError,
|
|
19
19
|
content_hash,
|
|
20
|
-
dispatch_item_ids,
|
|
21
20
|
extract_plan_items,
|
|
22
21
|
planning_stage_ledger,
|
|
22
|
+
queue_candidate_ids,
|
|
23
|
+
verified_content_hashes,
|
|
23
24
|
)
|
|
24
25
|
|
|
25
26
|
|
|
@@ -387,7 +388,8 @@ def _carry_unchanged_checklists(
|
|
|
387
388
|
|
|
388
389
|
def _recompute_dispatch_queue(
|
|
389
390
|
narrative: Mapping[str, Any],
|
|
390
|
-
stage_ledger: Mapping[str, Any] | None
|
|
391
|
+
stage_ledger: Mapping[str, Any] | None,
|
|
392
|
+
rows: list[dict],
|
|
391
393
|
) -> list[str]:
|
|
392
394
|
"""이월 뒤 남은 디스패치 큐.
|
|
393
395
|
|
|
@@ -408,7 +410,8 @@ def _recompute_dispatch_queue(
|
|
|
408
410
|
for stage, status in (stage_ledger or {}).items()
|
|
409
411
|
},
|
|
410
412
|
)
|
|
411
|
-
|
|
413
|
+
candidates = queue_candidate_ids(extracted, ledger, verified_content_hashes(rows))
|
|
414
|
+
return [item["id"] for item in extracted if item["id"] in candidates]
|
|
412
415
|
|
|
413
416
|
|
|
414
417
|
def _writer_stage_rows(data: Mapping[str, Any], *, snapshot: str) -> dict[int, dict]:
|
|
@@ -483,7 +486,7 @@ def merge_v3_plan_state(
|
|
|
483
486
|
state_items[item_id] for item_id in sorted(state_items)
|
|
484
487
|
]
|
|
485
488
|
queue = _recompute_dispatch_queue(
|
|
486
|
-
narrative, pbv.get("stageLedger"),
|
|
489
|
+
narrative, pbv.get("stageLedger"), pbv["planItems"],
|
|
487
490
|
)
|
|
488
491
|
if queue:
|
|
489
492
|
pbv["dispatchQueue"] = queue
|
|
@@ -244,12 +244,17 @@ class RunRef:
|
|
|
244
244
|
) -> Path:
|
|
245
245
|
"""The directory holding every run of `check_ref` (`kind:id`) in one attempt."""
|
|
246
246
|
segment = check_ref.replace(":", "-", 1)
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
247
|
+
if not _EXECUTION_SEGMENT_RE.fullmatch(segment):
|
|
248
|
+
raise ValueError(f"verification execution segment is unsafe: {segment}")
|
|
249
|
+
return self._verification_attempt_dir(invocation_ref, attempt) / segment
|
|
250
|
+
|
|
251
|
+
def _verification_attempt_dir(self, invocation_ref: str, attempt: int) -> Path:
|
|
252
|
+
if not _EXECUTION_SEGMENT_RE.fullmatch(invocation_ref):
|
|
253
|
+
raise ValueError(
|
|
254
|
+
f"verification execution segment is unsafe: {invocation_ref}")
|
|
250
255
|
_positive_int(attempt, "verification execution attempt")
|
|
251
256
|
return (self.verification_dir / f"executions{self._suffix}" / invocation_ref
|
|
252
|
-
/ f"attempt-{attempt}"
|
|
257
|
+
/ f"attempt-{attempt}")
|
|
253
258
|
|
|
254
259
|
def verification_execution_dir(
|
|
255
260
|
self, invocation_ref: str, attempt: int, check_ref: str, check_run: int,
|
|
@@ -269,6 +274,16 @@ class RunRef:
|
|
|
269
274
|
) if match]
|
|
270
275
|
return max(numbers, default=None)
|
|
271
276
|
|
|
277
|
+
def verification_check_refs(self, invocation_ref: str, attempt: int) -> list[str]:
|
|
278
|
+
"""The checks (`kind:id`) one attempt ran, sorted."""
|
|
279
|
+
attempt_dir = self._verification_attempt_dir(invocation_ref, attempt)
|
|
280
|
+
return sorted(
|
|
281
|
+
path.name.replace("-", ":", 1)
|
|
282
|
+
for path in (attempt_dir.iterdir() if attempt_dir.is_dir() else ())
|
|
283
|
+
if path.is_dir() and "-" in path.name
|
|
284
|
+
and _EXECUTION_SEGMENT_RE.fullmatch(path.name)
|
|
285
|
+
)
|
|
286
|
+
|
|
272
287
|
@property
|
|
273
288
|
def convergence_state(self) -> Path:
|
|
274
289
|
"""이 run 의 finding convergence 상태 파일.
|
|
@@ -33,6 +33,7 @@
|
|
|
33
33
|
- **Defect-class sweep:** a confirmed defect is one instance of a class, and finding it does not end the search. Name its mechanism in one sentence (for example "after a recovery the editor keeps a copy of server data taken before the recovery"). Enumerate every location in the verified diff and its direct callers where that mechanism can occur, and the cases that change its outcome (for example same version, version changed, two recoveries overlapping, cancelled request). Judge every location × case cell `defective`, `sound`, `unverified`, or `not-applicable` with evidence, and report every defective cell in this run. Each blocker records the sweep as `defectClass` (`mechanism`, `cells[]`, `recurrence`). Its fix is the whole class: every `defective` cell names the `regressionTest` that must fail before the fix and pass after it. Sweep a Residual Risk's class the same way before writing it; a residual row has no `defectClass` field, so the sweep goes into its `item` text. **Enforced:** `phases/final_verification/validation.py` `_validate_defect_class_sweep` refuses a blocker without `defectClass`, without a `defective` cell, or with a `defective` cell that names no `regressionTest`. Whether the enumeration is complete is a judgement no validator can make.
|
|
34
34
|
- **Prior-run carry-in:** when an earlier final-verification run of the same target exists, the analysis packet carries its blockers under `## Prior Final-Verification Blockers` (`phases/final_verification/prior_blockers.py`). Re-check each carried blocker's whole class on the current head. A blocker whose mechanism matches a carried one is `recurrence: recurring` and cites it in `priorBlockers` as `final-verification-NNN AB-NNN`; a class a single-point fix already failed to close is re-planned, so a report with a `recurring` blocker routes to `error-analysis`, `implementation-option-selection`, or `implementation-planning`, never to `implementation`. **Enforced:** `validation.py` `_validate_defect_class_sweep` refuses a `recurring` blocker with no `priorBlockers`, and `_validate_recurring_class_routing` refuses any other routing target. Marking a matching class `new` is a judgement the validator cannot see.
|
|
35
35
|
- **Tier 1 and Tier 2 read-only validation:** Follow the `**Verification inputs:**` declaration-source rule when that header is present. The legacy lookup supplies only the sources that rule leaves unfrozen: Tier 1 is the originating brief/approved plan `validation` set, and Tier 2 is the `Project QA Commands` section from `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). A missing or unreadable referenced snapshot is missing verification input, not permission to substitute current settings. Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token. Tier 2 is already screened by prepare, so this check catches a Tier 1 command the brief or plan named.
|
|
36
|
+
- **Evidence mode (verification evidence contract):** a prompt that carries `**Verification generation path:**` belongs to a run marked `verificationEvidenceVersion: "1.0"`. Run every frozen Tier 2 `qaCommands` entry with `okstra worktree-lock --project-root <PROJECT_ROOT> --invocation-metadata <Invocation metadata path> --check qa:<id>`, and every in-scope Tier 3 stage the generation seals with `--check conformance:<stageKey>`; every verifier runs Tier 3, and none writes `qa/result-<stageKey>.json`. The command, worktree and locks come from the sealed generation, so pass no `--worktree` or `--command`. Judge each call by its `okstra worktree-lock: evidence <status>: <record path>` stderr line: `completed` is the command's result whatever its exit code, any other status is no evidence (exit 70, or 128+N after a signal), and `evidence refused:` means nothing ran; the plain lock mode is never a substitute. Report assembly writes one `readonlyCommandLog` row per record, so do not author executed Tier 2 or Tier 3 rows. Tier 1 runs as before. **Enforced:** `phases/final_verification/validation.py` `validate_command_log_execution_evidence` (spec FV-5) and the evidence branch of `validators/validate-run.py` `_validate_conformance`.
|
|
36
37
|
- **External QA outcome policy:** continue to attempt every in-scope Tier 3
|
|
37
38
|
command. For an entry requiring `db`, `http`, or `external`, record non-PASS
|
|
38
39
|
as a Tier 3 `advisory` command, add a user-owned Residual Risk and exact
|
|
@@ -47,6 +47,14 @@
|
|
|
47
47
|
{% if final.manualUserTest.applicable %}{% for row in final.manualUserTest.results %}<article class="summary-card tone-{{ row.result }}"><h3>{{ row.target | inline_code }} · {{ row.result }}</h3><p>{{ row.performed | inline_code }}</p><p>{{ row.observed | inline_code }}</p></article>{% endfor %}{% else %}<p>{{ final.manualUserTest.exemptionReaffirm | inline_code }}</p>{% endif %}
|
|
48
48
|
</section>
|
|
49
49
|
|
|
50
|
+
{% if final.get("readonlyCommandLog") %}
|
|
51
|
+
<section data-report-section="read-only-commands" data-report-field="finalVerification.readonlyCommandLog">
|
|
52
|
+
<h2>{{ t('tasks.final-verification.read-only-commands') }}</h2>
|
|
53
|
+
<div class="table-scroll"><table><thead><tr><th>#</th><th>{{ t('tasks.final-verification.tier') }}</th><th>{{ t('tasks.final-verification.command') }}</th><th>{{ t('macros.layout.status') }}</th><th>{{ t('tasks.final-verification.exit-code') }}</th><th>{{ t('tasks.final-verification.execution-record') }}</th></tr></thead>
|
|
54
|
+
<tbody>{% for row in final.readonlyCommandLog %}<tr><td>{{ row.number }}</td><td>{{ row.tier }}</td><td>{{ row.command | inline_code }}</td><td><span class="status status-{{ row.status }}">{{ row.status }}</span>{% if row.get("statusReason") %} {{ row.statusReason | inline_code }}{% endif %}</td><td>{{ row.exitCode if row.exitCode is not none else "" }}</td><td>{% if row.get("executionEvidence") %}<code>{{ row.executionEvidence.checkRef }}</code> run {{ row.executionEvidence.checkRun }} · <code>{{ row.executionEvidence.recordPath }}</code>{% endif %}</td></tr>{% endfor %}</tbody></table></div>
|
|
55
|
+
</section>
|
|
56
|
+
{% endif %}
|
|
57
|
+
|
|
50
58
|
<section data-report-section="verified-source" data-report-field="finalVerification.sourceImplementationReport">
|
|
51
59
|
<h2>{{ t('tasks.final-verification.what-was-verified') }}</h2>
|
|
52
60
|
<table><tbody><tr><th>{{ t('tasks.final-verification.implementation-report') }}</th><td><code>{{ final.sourceImplementationReport.path }}</code></td></tr><tr><th>{{ t('tasks.final-verification.worktree') }}</th><td><code>{{ final.sourceImplementationReport.worktreePath }}</code></td></tr><tr><th>{{ t('tasks.final-verification.base-commit') }}</th><td><code>{{ final.sourceImplementationReport.implementationBaseRef }}</code> → <code>{{ final.sourceImplementationReport.capturedHeadSha }}</code></td></tr><tr><th>{{ t('tasks.final-verification.diff-summary') }}</th><td>{{ final.sourceImplementationReport.diffSummaryQuote | inline_code }}</td></tr><tr><th>{{ t('tasks.final-verification.uncommitted-state') }}</th><td>{{ final.sourceImplementationReport.gitStatusShort | inline_code }}</td></tr></tbody></table>
|
|
@@ -10,6 +10,7 @@ This directory is the canonical home of the final-verification phase. Report fie
|
|
|
10
10
|
| FV-2 | A release-handoff route requires a release-ready verdict | `validators/validate-run.py::_refuse_unsuitable_final_verification_route` |
|
|
11
11
|
| FV-3 | The final-verification destination list matches the report schema | unenforced |
|
|
12
12
|
| FV-4 | The phase profile is not also stored under prompts/profiles | unenforced |
|
|
13
|
+
| FV-5 | In a run marked `verificationEvidenceVersion: "1.0"`, every executed Tier 2 or Tier 3 read-only command row is one current execution record of a verifier, and the row's command, status, exit code and output are the record's | `scripts/okstra_ctl/phases/final_verification/validation.py::validate_command_log_execution_evidence` |
|
|
13
14
|
|
|
14
15
|
## Process
|
|
15
16
|
|
|
@@ -10,6 +10,10 @@ import re
|
|
|
10
10
|
from collections.abc import Mapping
|
|
11
11
|
from pathlib import Path
|
|
12
12
|
|
|
13
|
+
from okstra_ctl.report_execution_evidence import (
|
|
14
|
+
EXECUTION_EVIDENCE_BLOCKING, RECORD_DERIVED_TIERS, collect_report_evidence,
|
|
15
|
+
command_row, execution_evidence_contract, omitted_records, reference_errors,
|
|
16
|
+
)
|
|
13
17
|
from okstra_ctl.verification_target import TARGET_FIELD_RES, read_verification_target
|
|
14
18
|
|
|
15
19
|
_ADDED_SURFACE_NO_CALLER_RE = re.compile(r"^\s*none\b", re.IGNORECASE)
|
|
@@ -280,3 +284,52 @@ def validate_verification_target_match(
|
|
|
280
284
|
f"(`{relative}`). A verdict must not be rendered for a stage set "
|
|
281
285
|
"nobody prepared evidence for."
|
|
282
286
|
)
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def validate_command_log_execution_evidence(
|
|
291
|
+
data: dict, project_root: Path, manifest_path: Path, run_manifest: Mapping,
|
|
292
|
+
failures: list[str],
|
|
293
|
+
) -> None:
|
|
294
|
+
"""Every read-only command row of an evidence-contract run that executed a
|
|
295
|
+
Tier 2 or Tier 3 check is one current execution record of a verifier.
|
|
296
|
+
|
|
297
|
+
A row's reference must be the latest run of a check under a verifier's
|
|
298
|
+
latest attempt of the invocation bound to the run's newest generation, and
|
|
299
|
+
the row's command, status, exit code and output must be the record's.
|
|
300
|
+
"""
|
|
301
|
+
if not execution_evidence_contract(run_manifest, failures):
|
|
302
|
+
return
|
|
303
|
+
try:
|
|
304
|
+
verifiers = list(collect_report_evidence(project_root, manifest_path).values())
|
|
305
|
+
except ValueError as exc:
|
|
306
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} verification execution "
|
|
307
|
+
f"evidence could not be collected: {exc}")
|
|
308
|
+
return
|
|
309
|
+
final = data.get("finalVerification")
|
|
310
|
+
rows = final.get("readonlyCommandLog") if isinstance(final, Mapping) else None
|
|
311
|
+
matched: set[str] = set()
|
|
312
|
+
for index, row in enumerate(rows if isinstance(rows, list) else []):
|
|
313
|
+
if not isinstance(row, Mapping):
|
|
314
|
+
continue
|
|
315
|
+
where = f"finalVerification.readonlyCommandLog[{index}]"
|
|
316
|
+
if "executionEvidence" not in row:
|
|
317
|
+
if row.get("status") == "executed" and row.get("tier") in RECORD_DERIVED_TIERS:
|
|
318
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} {where} records an "
|
|
319
|
+
f"executed Tier {row.get('tier')} check without its "
|
|
320
|
+
"execution record")
|
|
321
|
+
continue
|
|
322
|
+
errors, paths = reference_errors(
|
|
323
|
+
f"{where}.executionEvidence", row["executionEvidence"], verifiers,
|
|
324
|
+
)
|
|
325
|
+
failures.extend(f"{EXECUTION_EVIDENCE_BLOCKING} {error}" for error in errors)
|
|
326
|
+
if paths and not errors:
|
|
327
|
+
derived = command_row(row.get("number"), row["executionEvidence"])
|
|
328
|
+
if dict(row) != derived:
|
|
329
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} {where} differs from "
|
|
330
|
+
f"its execution record {sorted(paths)[0]}")
|
|
331
|
+
matched |= paths
|
|
332
|
+
omitted = omitted_records(verifiers, matched)
|
|
333
|
+
if omitted:
|
|
334
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} finalVerification."
|
|
335
|
+
f"readonlyCommandLog omits execution records {omitted}")
|
|
@@ -51,6 +51,10 @@ If `render-bundle` fails with a `PrepareError` containing `Recorded stage SHAs n
|
|
|
51
51
|
|
|
52
52
|
If the anchor (`implementation_base_commit`) is reported unresolvable, run the same command's `--reset-anchor <ref>` after user confirmation. Correcting a confirm item without the picker is forbidden — the runtime also rejects a confirm correction without `--use-ref`.
|
|
53
53
|
|
|
54
|
+
### Predecessor merge conflict (merge-base gate)
|
|
55
|
+
|
|
56
|
+
A stage that depends on two or more stages starts from a merge-base branch that okstra builds from the implementation anchor by merging each predecessor's completion commit with `--no-ff`, in stage order. If two predecessors conflict, `render-bundle` fails with a `PrepareError` containing `merge conflict while merging stage <N>`. okstra never resolves the conflict itself. When it was creating the branch, it deletes the half-built branch and the steps start from the anchor. When it was advancing an existing branch to a newer predecessor commit, the branch stays at its previous tip and the steps check it out and merge only the commits it lacks. Do not edit the registry or consumers, and do not merge a predecessor into a stage branch. Stop and show the user the conflicting paths and the steps from the error verbatim: the branch name, the `git worktree add` command, and one `git merge --no-ff --no-edit <commit>` per predecessor in the listed order. Those commands disable repository hooks the way okstra's own merges do. The user, or you on the user's instruction, runs those steps, resolves the conflict, runs the project's checks, commits the merge and removes that worktree. Then retry the failed `render-bundle` with the same arguments. It reuses the branch only when the branch contains the anchor and every predecessor commit and carries no other non-merge commit; otherwise it fails and names the problem.
|
|
57
|
+
|
|
54
58
|
### Next stage not yet ready — normal termination (not an exception gate)
|
|
55
59
|
Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
|
|
56
60
|
|
|
@@ -58,4 +62,4 @@ Because of the dependency closure, the chain queue **may include a stage that an
|
|
|
58
62
|
A verifier FAIL that a passing lead minor fix answered does not make the verdict `FAIL` (`_implementation-deliverable.md` "Lead minor fix"); that stage settles `done` and the queue continues. When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
|
|
59
63
|
|
|
60
64
|
### Exception gate during chaining
|
|
61
|
-
If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch)
|
|
65
|
+
If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch), git stale-SHA reconciliation (git-reconcile branch) or a predecessor merge conflict (merge-base gate), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these branches do not discard the queue; they wait for user resolution.)
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md
CHANGED
|
@@ -45,6 +45,8 @@ are collected and convergence finished. Phase 1-5 do not need it.
|
|
|
45
45
|
|
|
46
46
|
## Lead minor fix (decided after convergence, before the report-writer dispatch)
|
|
47
47
|
|
|
48
|
+
**Not in an evidence-contract run.** When the run manifest carries `verificationEvidenceVersion`, there is no lead minor fix: every fix, however small, goes through a correction round below, so the executor commits it and a new generation is sealed before the verifiers check it again. **Enforced:** `scripts/okstra_ctl/phases/implementation/validation.py` `_validate_lead_fixes` blocks any `implementation.leadFixes` entry in such a run, and `validate_settled_round_was_reverified` blocks a stage settled after correction round N without each verifier's records of generation N + 1. Runs without the field keep the rules below.
|
|
49
|
+
|
|
48
50
|
When the synthesised verdict would be `FAIL` only because of verifier findings that are small and local, the lead fixes them itself in this run instead of ending it and opening a fix run. Decide after Phase 5.5 convergence, before building the report-writer dispatch prompt and before "Lead post-stage persistence" below. No worker dispatch is open then, so the edit falls inside no read-only worker's mutation audit window. Never edit while a verifier, convergence, or report-writer dispatch is running: its audit reports `readonly source changed` and discards that worker's result.
|
|
49
51
|
|
|
50
52
|
**Eligibility.** Every rule holds for every blocking finding of the round, or the lead fixes none of them and §"Correction round" decides whether the executor fixes them in this run:
|