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.
Files changed (57) hide show
  1. package/docs/architecture/storage-model.md +67 -6
  2. package/docs/architecture.md +2 -0
  3. package/docs/coding-rules.md +15 -0
  4. package/docs/project-structure-overview.md +2 -1
  5. package/package.json +2 -2
  6. package/runtime/BUILD.json +2 -2
  7. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  8. package/runtime/prompts/coding-preflight/overview.md +1 -0
  9. package/runtime/prompts/launch.template.md +2 -0
  10. package/runtime/prompts/lead/okstra-lead-contract.md +5 -5
  11. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  12. package/runtime/python/okstra_ctl/agent/invocation.py +48 -4
  13. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  14. package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
  15. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  16. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  17. package/runtime/python/okstra_ctl/paths.py +19 -4
  18. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +1 -0
  19. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  20. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +1 -0
  21. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  22. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +5 -1
  23. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -0
  24. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +19 -3
  25. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  26. package/runtime/python/okstra_ctl/phases/implementation/spec.md +2 -0
  27. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  28. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  29. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  30. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  31. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  32. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  33. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  34. package/runtime/python/okstra_ctl/render.py +15 -0
  35. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  36. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  37. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  38. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  39. package/runtime/python/okstra_ctl/run.py +16 -0
  40. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  41. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  42. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  43. package/runtime/python/okstra_ctl/verification_dispatch.py +8 -2
  44. package/runtime/python/okstra_ctl/verification_evidence.py +26 -7
  45. package/runtime/python/okstra_ctl/verification_generation.py +12 -4
  46. package/runtime/python/okstra_ctl/verification_inputs.py +10 -0
  47. package/runtime/python/okstra_ctl/verification_invocation.py +2 -1
  48. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  49. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  50. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  51. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  52. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  53. package/runtime/skills/okstra-run/SKILL.md +5 -1
  54. package/runtime/templates/reports/html/i18n/en.json +7 -0
  55. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  56. package/runtime/validators/validate-run.py +24 -5
  57. 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
- conformance_check_owner_ref, read_verification_execution_record,
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 _BoundInvocation:
61
- """One verifier invocation and the generation its dispatch kind seals."""
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
- try:
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 RunConformanceEvidence(_required_stages(verifiers), {
97
- key: _stage_evidence(ref, verifiers, counted, key, latest_attempt)
98
- for key in stage_keys
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
- ref: RunRef, verifiers: Mapping[str, list[_BoundInvocation]],
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(ref, role_execution_ref, verifiers.get(role_execution_ref, []),
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, execution: ExecutionManifest, audience: str,
128
- ) -> dict[str, list[_BoundInvocation]]:
129
- """Each verifier's invocations, newest first."""
130
- verifiers: dict[str, list[_BoundInvocation]] = {}
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
- _bind(project, ref, invocation, index),
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[_BoundInvocation]]) -> frozenset[int]:
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, invocation: Invocation, index: int,
159
- ) -> _BoundInvocation:
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
- if not path.is_file():
164
- return _BoundInvocation(invocation, number, index, None,
165
- {"path": relative, "digest": ""})
166
- digest = content_digest(path.read_bytes())
167
- return _BoundInvocation(invocation, number, index,
168
- read_verification_generation(path, digest),
169
- {"path": relative, "digest": digest})
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
- ref: RunRef, role_execution_ref: str, bindings: list[_BoundInvocation],
174
- generation_number: int, stage_key: str, latest_attempt: Mapping[str, int],
233
+ run: RunVerifiers, role_execution_ref: str, generation_number: int,
234
+ stage_key: str,
175
235
  ) -> _VerifierOutcome:
176
- chosen = next((binding for binding in bindings if binding.generation is not None
177
- and binding.generation_number == generation_number), None)
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
- invocation_ref = chosen.invocation.invocation_ref
181
- attempt = latest_attempt.get(invocation_ref)
182
- if attempt is None:
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
- check_ref = f"conformance:{stage_key}"
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 _NO_OUTCOME
188
- run_dir = ref.verification_execution_dir(
189
- invocation_ref, attempt, check_ref, check_run,
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": chosen.generation_ref,
195
- }
196
- record_path = run_dir / "record.json"
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 _recorded_result(
282
+ def _read_bound_record(
202
283
  run_dir: Path, expected: Mapping[str, object],
203
- ) -> tuple[QaResult | None, str | None]:
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 differs "
210
- "from its location")
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
- defect = execution_evidence_defect(record, output)
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 = 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
- return dispatch_item_ids(extracted, ledger)
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
- for value in (invocation_ref, segment):
248
- if not _EXECUTION_SEGMENT_RE.fullmatch(value):
249
- raise ValueError(f"verification execution segment is unsafe: {value}")
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}" / segment)
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) or git stale-SHA reconciliation (git-reconcile branch), **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 two branches do not discard the queue; they wait for user resolution.)
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.)
@@ -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: