okstra 0.230.0 → 0.231.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +3 -3
  2. package/docs/architecture/storage-model.md +67 -6
  3. package/docs/architecture.md +6 -2
  4. package/docs/coding-rules.md +15 -0
  5. package/docs/project-structure-overview.md +2 -1
  6. package/package.json +2 -2
  7. package/runtime/BUILD.json +2 -2
  8. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  9. package/runtime/prompts/coding-preflight/overview.md +1 -0
  10. package/runtime/prompts/launch.template.md +2 -0
  11. package/runtime/prompts/lead/convergence.md +3 -3
  12. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  13. package/runtime/prompts/lead/report-writer.md +1 -1
  14. package/runtime/prompts/lead/team-contract.md +1 -1
  15. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  16. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  17. package/runtime/python/okstra_ctl/agent/invocation.py +48 -4
  18. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  19. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  20. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  21. package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
  22. package/runtime/python/okstra_ctl/convergence.py +112 -20
  23. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  24. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  25. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  26. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  27. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  28. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  29. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  30. package/runtime/python/okstra_ctl/paths.py +19 -4
  31. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +1 -0
  32. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  33. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +1 -0
  34. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  35. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +5 -1
  36. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +3 -1
  37. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +20 -4
  38. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  39. package/runtime/python/okstra_ctl/phases/implementation/spec.md +2 -0
  40. package/runtime/python/okstra_ctl/phases/implementation/validation.py +230 -30
  41. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  42. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  43. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  44. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  45. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  47. package/runtime/python/okstra_ctl/render.py +15 -0
  48. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  49. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  50. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  51. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  52. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  53. package/runtime/python/okstra_ctl/report_synthesis_packet.py +8 -0
  54. package/runtime/python/okstra_ctl/run.py +16 -0
  55. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  56. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  57. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  58. package/runtime/python/okstra_ctl/team.py +3 -1
  59. package/runtime/python/okstra_ctl/verification_dispatch.py +8 -2
  60. package/runtime/python/okstra_ctl/verification_evidence.py +26 -7
  61. package/runtime/python/okstra_ctl/verification_generation.py +12 -4
  62. package/runtime/python/okstra_ctl/verification_inputs.py +10 -0
  63. package/runtime/python/okstra_ctl/verification_invocation.py +2 -1
  64. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  65. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  66. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  67. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  68. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  69. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  70. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  71. package/runtime/skills/okstra-run/SKILL.md +5 -1
  72. package/runtime/templates/reports/html/i18n/en.json +7 -0
  73. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  74. package/runtime/validators/validate-run.py +27 -11
  75. package/runtime/validators/validate-workflow.sh +1 -1
@@ -133,6 +133,28 @@ def discovery_attempts(
133
133
  return by_role
134
134
 
135
135
 
136
+ def accepted_role_execution_refs(
137
+ manifest: ExecutionManifest, scope: str | None = None,
138
+ ) -> set[str]:
139
+ """Role executions whose latest attempt of some discovery invocation in the scope is ``ok``."""
140
+ return {
141
+ ref for ref, attempts in discovery_attempts(manifest, scope).items()
142
+ if any(attempt.status == "ok" for attempt in attempts)
143
+ }
144
+
145
+
146
+ def resolve_recorded_result_path(result_path: str, authority: Mapping) -> Path:
147
+ # A batch dispatch records the absolute worker-result path; a native agent
148
+ # dispatch records it relative to the project root.
149
+ candidate = Path(result_path)
150
+ if candidate.is_absolute():
151
+ return candidate
152
+ project_root = authority.get("projectRoot")
153
+ if not _nonempty_string(project_root):
154
+ raise ValueError("relative accepted resultPath requires projectRoot")
155
+ return Path(project_root) / candidate
156
+
157
+
136
158
  def worker_result_paths(
137
159
  run_dir: Path, document: Mapping, suffix: str, scope: str | None = None,
138
160
  ) -> dict[str, Path]:
@@ -162,12 +184,7 @@ def worker_result_paths(
162
184
  ]
163
185
  if not accepted:
164
186
  continue
165
- candidate = Path(accepted[-1].result_path)
166
- if not candidate.is_absolute():
167
- project_root = authority.get("projectRoot")
168
- if not _nonempty_string(project_root):
169
- raise ValueError("relative accepted resultPath requires projectRoot")
170
- candidate = Path(project_root) / candidate
187
+ candidate = resolve_recorded_result_path(accepted[-1].result_path, authority)
171
188
  if candidate.resolve().parent != results_dir.resolve():
172
189
  raise ValueError(f"accepted resultPath is outside worker-results: {candidate}")
173
190
  if not candidate.is_file():
@@ -357,6 +374,7 @@ def discarded_workers(
357
374
  if execution_manifest is None or getattr(execution_manifest, "legacy", False):
358
375
  return {}
359
376
  attempts = discovery_attempts(execution_manifest, scope)
377
+ accepted = accepted_role_execution_refs(execution_manifest, scope)
360
378
  result: dict[str, str] = {}
361
379
  for row in document["workers"]:
362
380
  if not isinstance(row, dict):
@@ -366,7 +384,7 @@ def discarded_workers(
366
384
  if not _nonempty_string(worker) or not _nonempty_string(role_ref):
367
385
  continue
368
386
  rows = attempts.get(role_ref, [])
369
- if not rows or any(item.status == "ok" for item in rows):
387
+ if not rows or role_ref in accepted:
370
388
  continue
371
389
  discarded = [item for item in rows if item.status in DISCARDED_ATTEMPT_STATUSES]
372
390
  if discarded:
@@ -424,14 +442,12 @@ def missing_scope_results(
424
442
  return []
425
443
  if not isinstance(document, dict):
426
444
  return []
427
- attempts = discovery_attempts(execution_manifest, scope)
445
+ accepted = accepted_role_execution_refs(execution_manifest, scope)
428
446
  missing = sorted({
429
447
  str(row.get("workerId"))
430
448
  for row in document.get("workers") or []
431
449
  if isinstance(row, dict) and row.get("audience") == "analysis"
432
- and not any(
433
- item.status == "ok" for item in attempts.get(row.get("sourceRoleExecutionRef"), [])
434
- )
450
+ and row.get("sourceRoleExecutionRef") not in accepted
435
451
  })
436
452
  return [
437
453
  f"`{worker}` has no accepted `{scope}` result; await that round's verifiers "
@@ -61,6 +61,11 @@ def correction_convergence_states(initial_final: Path) -> list[tuple[str, Path]]
61
61
  return rows
62
62
 
63
63
 
64
+ def invocation_in_correction_namespace(invocation_ref: str) -> bool:
65
+ """Whether an invocation id contains `-correction-r`, as every correction-round id does."""
66
+ return f"-{CORRECTION_DISPATCH_KIND_PREFIX}" in invocation_ref
67
+
68
+
64
69
  def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_number: int) -> bool:
65
70
  """Whether a `reverify-r<N>` invocation belongs to this convergence namespace.
66
71
 
@@ -68,7 +73,7 @@ def reverify_invocation_in_scope(invocation_ref: str, scope: str | None, round_n
68
73
  correction re-convergence names it `…-correction-r<M>-reverify-r<N>-<worker>`.
69
74
  """
70
75
  if scope is None:
71
- return f"-{CORRECTION_DISPATCH_KIND_PREFIX}" not in invocation_ref
76
+ return not invocation_in_correction_namespace(invocation_ref)
72
77
  return f"-{scope}-reverify-r{round_number}-" in invocation_ref
73
78
 
74
79
 
@@ -6,9 +6,14 @@ dispatch 를 정하고 결과를 확정하는 곳은 `team dispatch` / `team awa
6
6
  명령들이 갖고 있다. 리드가 같은 사실을 `okstra lead-progress append` 로 다시
7
7
  적으면 체크포인트마다 전체 컨텍스트를 한 턴씩 쓰는데, 여기서 기록하면 턴이 들지 않는다.
8
8
 
9
- 워커별 체크포인트는 `initial` dispatch 만 센다. reverify·critic·plan-verify 는
10
- 리드가 따로 알리는 이후 라운드이고, 여기서 기록하면 activity-contract run 이
11
- 존재하지 않는 `worker-dispatched` / `worker-completed` 행을 요구받게 된다.
9
+ The per-worker `phase-4-dispatch` line is recorded for `initial` jobs and for the jobs of an
10
+ implementation correction round: its `correction-r<N>` executor and verifier dispatches and
11
+ the reverify rounds that re-converge it (`…-correction-r<N>-reverify-r<k>-…`). The lead
12
+ emits the lines this command prints instead of appending `phase-4-dispatch` itself, so a
13
+ correction round left out here showed the user no dispatch at all. The initial-namespace
14
+ reverify, critic and plan-verify rounds stay out; the lead reports them through
15
+ `phase-5.5-convergence`, `phase-5.6-critic` and `phase-5.5.9-plan-verify`.
16
+ `phase-5-collect` still counts `initial` dispatches only.
12
17
 
13
18
  activity-contract v1 run 에서는 검증기가 워커별 `phase-4-dispatch` /
14
19
  `phase-5-collect` 마다 같은 워커의 `worker-dispatched` / `worker-completed`
@@ -26,8 +31,10 @@ from .agent.activity import (
26
31
  conversation_activity_line,
27
32
  record_activity,
28
33
  )
34
+ from .correction_round import correction_round, invocation_in_correction_namespace
29
35
  from .dispatch_state import (
30
36
  TERMINAL_WORKER_STATUSES,
37
+ WorkerJob,
31
38
  dispatch_worker_key,
32
39
  has_recorded_team_create,
33
40
  worker_dispatch_records,
@@ -35,6 +42,7 @@ from .dispatch_state import (
35
42
  from .json_boundary import JsonBoundaryError, load_owned_object
36
43
  from .lead_progress import record_checkpoint
37
44
  from .worker_prompt_body import REPORT_WRITER_WORKER_ID
45
+ from .worker_prompt_policy import is_reverify_dispatch_kind
38
46
 
39
47
  _INITIAL = "initial"
40
48
 
@@ -63,7 +71,7 @@ def record_dispatch_checkpoints(
63
71
  project_root, run_manifest, "phase-3-team-create", source=source,
64
72
  ))
65
73
  for job in jobs:
66
- if job.dispatch_kind == _INITIAL:
74
+ if _announces_worker_dispatch(job):
67
75
  lines.append(record_checkpoint(
68
76
  project_root, run_manifest, "phase-4-dispatch", source=source,
69
77
  worker=job.worker_id,
@@ -73,7 +81,7 @@ def record_dispatch_checkpoints(
73
81
  lines.append(_record_worker_activity(
74
82
  project_root, run_manifest, source=source,
75
83
  kind="worker-dispatched", agent=job.worker_id,
76
- summary=f"Dispatched {job.worker_id} as an initial worker",
84
+ summary=_dispatch_summary(job),
77
85
  result_path=_project_relative(project_root, str(job.worker_result_path)),
78
86
  outcome="pending",
79
87
  ))
@@ -88,6 +96,21 @@ def record_dispatch_checkpoints(
88
96
  return [line for line in lines if line]
89
97
 
90
98
 
99
+ def _announces_worker_dispatch(job: WorkerJob) -> bool:
100
+ kind = job.dispatch_kind
101
+ if kind == _INITIAL or correction_round(kind) is not None:
102
+ return True
103
+ return is_reverify_dispatch_kind(kind) and invocation_in_correction_namespace(
104
+ job.invocation_id or job.invocation_ref
105
+ )
106
+
107
+
108
+ def _dispatch_summary(job: WorkerJob) -> str:
109
+ if job.dispatch_kind == _INITIAL:
110
+ return f"Dispatched {job.worker_id} as an initial worker"
111
+ return f"Dispatched {job.worker_id} for {job.dispatch_kind}"
112
+
113
+
91
114
  def settled_initial_dispatches(
92
115
  team_state: Mapping[str, Any],
93
116
  ) -> dict[str, Mapping[str, Any]]:
@@ -133,6 +133,7 @@ from .wrapper_status import (
133
133
  log_path_for_prompt,
134
134
  mutation_snapshot_path_for_prompt,
135
135
  prompt_derived_paths,
136
+ read_log_tail,
136
137
  read_wrapper_status,
137
138
  status_path_for_prompt,
138
139
  )
@@ -2015,8 +2016,7 @@ def _wrapper_failure_text(outcome: WorkerOutcome | None) -> str:
2015
2016
  status = read_wrapper_status(outcome.status_sidecar_path)
2016
2017
  if status is None:
2017
2018
  return ""
2018
- failure = _string_value(status.raw.get("failure"))
2019
- return failure[:_MUTATION_REASON_FAILURE_LIMIT]
2019
+ return status.failure[:_MUTATION_REASON_FAILURE_LIMIT]
2020
2020
 
2021
2021
 
2022
2022
  def _mutation_failure_reason(mutation, outcome: WorkerOutcome | None = None) -> str:
@@ -2604,15 +2604,7 @@ def _wrapper_log_tail(job: WorkerJob) -> str | None:
2604
2604
  some process exited 1. Capped well under the writer's own excerpt limit
2605
2605
  because a whole record must stay inside one atomic `PIPE_BUF` append.
2606
2606
  """
2607
- log_path = log_path_for_prompt(job.prompt_path)
2608
- try:
2609
- with log_path.open("rb") as handle:
2610
- handle.seek(0, 2)
2611
- handle.seek(max(0, handle.tell() - _WRAPPER_LOG_TAIL_BYTES))
2612
- tail = handle.read()
2613
- except OSError:
2614
- return None
2615
- return tail.decode("utf-8", errors="replace").strip() or None
2607
+ return read_log_tail(log_path_for_prompt(job.prompt_path), _WRAPPER_LOG_TAIL_BYTES)
2616
2608
 
2617
2609
 
2618
2610
  def _transition_job_status(
@@ -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.)
@@ -13,7 +13,7 @@ are collected and convergence finished. Phase 1-5 do not need it.
13
13
  - **Plan link & approval evidence**: path to the approved `final-report.md`, the exact quoted approval marker, AND the executed stage number / title quoted from the Stage Map row. For a selected-direction plan, also quote `selectedDirectionRef.optionId`, `snapshotPath`, and the validated snapshot digest; for a legacy plan, quote the effective `implementation-option` or the Recommended Option fallback.
14
14
  - **Commit list**: each commit's SHA (or short SHA), message, and the plan step(s) / TDD cycle it satisfies. A lead minor fix commit is listed too, with `planStep` `Lead minor fix (<finding ids>)`.
15
15
  - **Lead minor fixes**: when the lead fixed verifier findings in this run, pass each `implementation.leadFixes[]` entry to the report writer as recorded (§"Lead minor fix"). Omit the field when there was none.
16
- - **Correction rounds**: when this run ran correction rounds, pass one `implementation.correctionRounds[]` entry per round to the report writer — `round`, `findingIds`, `baseCommit`, `commit`, each verifier's re-verification `verifierVerdicts`, and `result` (§"Correction round"). `verifierResults` then carries the last round's verdicts. Omit the field when there was none.
16
+ - **Correction rounds**: when this run ran correction rounds, pass one `implementation.correctionRounds[]` entry per round to the report writer — `round`, `findingIds`, `baseCommit`, `commit`, each verifier's re-verification `verifierVerdicts`, and `result` (§"Correction round"). `verifierResults` then carries the last round's verdicts, and each row's `discrepancy` carries only a divergence in that verifier's last-round rerun: it stays empty when the last rerun matched. The change from an initial `FAIL` to a last-round `PASS` is recorded in `correctionRounds[].verifierVerdicts`, never in `discrepancy` — `_validate_verifier_discrepancy_is_not_passed` reads text there beside `PASS` as an unresolved divergence. The report-writer packet states this rule for every correction-round run (`report_synthesis_packet.ReportSynthesisPacket._task_instructions`). Omit the field when there was none.
17
17
  - **Diff summary**: capture `git diff --stat <base>..<captured-head>` and `git diff --numstat <base>..<captured-head>` for the full implementation stage, including after a fix run. Supply both outputs to the report writer; put each file's added/deleted counts alone in `diffSummary.files[].lines` (`+150/-0`) and one sentence on what the change in that file does in `diffSummary.files[].summary` — the report renders `summary` as the file's "what it does" column and `lines` as a separate number column. Do not substitute a fix-run aggregate or carry forward older statistics. If the captured commits are unavailable, identify the missing reference in the evidence instead of inventing counts.
18
18
  - **Change narrative scope**: `userNarrative.changeExplanation` describes the same scope as `diffSummary` — the whole stage from its base, every file the table lists. On a fix run, state what the fix run itself changed (its commits and files) as a separate sentence; never present the fix-run delta as the stage's change.
19
19
  - **Out-of-plan edits block**: every file edited that was not in the approved plan's file list, with rationale (empty block is acceptable and preferred)
@@ -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 the records of generation N + 1 of each verifier that generation gives a check it may run. 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:
@@ -60,13 +60,29 @@ okstra worktree-lock --worktree <target.cwd> --command '<target.command>'
60
60
 
61
61
  The verifiers of a stage share one worktree and run at the same time, and each re-runs every Tier 1 command. A Tier 1 command that starts servers on fixed ports (a dev server on 3000 plus a fixture API on 8899 behind one `playwright test` line, fontsninja-v3-site dev-11126 stage 1) collides with the same command from another verifier: each kills or attaches to the other's servers, and the exit codes stop describing the code. The lock is keyed by the worktree, so each verifier still runs the command itself, only one at a time. The wrapper is the launcher, not the command: record the declared `target.command` as the command line, and the wrapper's exit code and stdout/stderr tail as that command's — the wrapper passes both through unchanged and adds only stderr lines prefixed `okstra worktree-lock:`. A `waiting` notice means another verifier held the lock; a `running unlocked` warning means the lock file could not be created, so record that warning beside the result. This is a guideline: nothing checks the command log for the launcher. The lock behaviour (no overlap on one worktree, no blocking across worktrees, output and exit-code pass-through, lock file outside the worktree) is covered by the former Python suite; that regression check is now retired.
62
62
 
63
+ ### Evidence mode (verification evidence contract)
64
+
65
+ A prompt that carries `**Verification generation path:**` and `**Verification generation digest:**` lines belongs to a run marked `verificationEvidenceVersion: "1.0"`. In such a run the Tier 2 and Tier 3 results come only from the execution records `okstra worktree-lock` writes in evidence mode; a result you type into the worker result or a sidecar is not read.
66
+
67
+ - **Tier 2.** Run every frozen `qaCommands` entry by its `id`, one call per entry:
68
+ ```bash
69
+ okstra worktree-lock --project-root <PROJECT_ROOT> --invocation-metadata <Invocation metadata path> --check qa:<id>
70
+ ```
71
+ The command, worktree and resource locks come from the sealed generation, so pass no `--worktree` or `--command`, and do not wrap the call in `okstra verification-target`: evidence mode re-checks the sealed target under the lock and records `target-changed` itself. The language skip rule above still applies; record a skipped entry as before.
72
+ - **Tier 3 (stage QA owner only).** Run each stage the generation seals with `--check conformance:<stageKey>` instead of the manifest `runCommand`, and write no `qa/result-<stageKey>.json`. A non-owner's call is refused (exit 2), and the conformance gate takes the owner's record.
73
+ - **Outcome.** Read the `okstra worktree-lock: evidence <status>: <record path>` line on stderr, not the exit code alone. `evidence completed: <path>` is a complete record whatever the exit code, so a command that exits 2, 70 or 137 is that command's result (a FAIL when non-zero). Any other status (`output-save-failed`, `drain-incomplete`, `cleanup-unconfirmed`, `target-changed`, `lock-unavailable`, `cancelled`, `interrupted`, `evidence-error`) is no evidence; the exit code is then 70, or 128+N when a signal arrived. `evidence refused: <reason>` means nothing ran and no record exists (exit 2). Record the exit code, the status and the record path. Never re-run the same check through the plain lock mode as a substitute; running the same `--check` again writes the next `run-<k>`, and the latest run of each check is the one that counts.
74
+ - **Worker result.** Keep each call in the Read-only command log with its exit code. Name yourself in the report's `verifierResults[].verifier` with the roster worker id from your `**Model:** <id> worker` line: assembly attaches your records by that id, and a name that is not a roster verifier is refused.
75
+ - **Unchanged.** Tier 1 plan commands, the self-mock detector and the static review run as described elsewhere in this sidecar.
76
+
77
+ **Enforced:** `validate_verifier_execution_evidence` in `scripts/okstra_ctl/phases/implementation/validation.py` (spec I-4) and the evidence branch of `_validate_conformance` in `validators/validate-run.py`.
78
+
63
79
  ### Stage QA owner
64
80
 
65
81
  Every verifier of this stage runs in the same worktree at the same time. Two checks change that worktree while they run: a Tier 3 conformance script may build into it (`.next/`, `dist/`) or bind fixed ports, and the self-mock detector's mutation probe rewrites production sources in place (cosmic-ray) or replaces a report file inside the worktree (Stryker). Run concurrently, they corrupt each other's result and the other verifiers' test runs (observed 2026-09-26, fontsninja-v3-site dev-11054 stage 1: `next build` + `next start -p 3000` + a proxy on 8889 from three verifiers at once).
66
82
 
67
83
  Your prompt carries a `**Stage QA owner:**` anchor naming one worker id. If that id is yours (the `<id>` in your `**Model:** <id> worker` line), you run Tier 3 and the self-mock detector as the two sections below describe. Otherwise you run neither and write neither sidecar; each section says what to record instead. A prompt with no such anchor predates this rule: run both yourself.
68
84
 
69
- **Enforced:** the anchor is generated (`scripts/okstra_ctl/worker_prompt_policy.py` `stage_qa_owner`, the first verifier in roster order). If the owner is never dispatched, no sidecar is written and the existing gates report it: a missing conformance result is BLOCKING for an `io`-only entry and ADVISORY for an external one (`scripts/okstra_ctl/conformance.py` `decide_conformance_gate`), and a missing self-mock sidecar blocks when the diff changed a test file (`validators/validate-run.py` `_validate_selfmock`). Nothing checks which verifier's log holds the commands.
85
+ **Enforced:** the anchor is generated (`scripts/okstra_ctl/worker_prompt_policy.py` `stage_qa_owner`, the first verifier in roster order). If the owner is never dispatched, no sidecar is written and the existing gates report it: a missing conformance result is BLOCKING for an `io`-only entry and ADVISORY for an external one (`scripts/okstra_ctl/conformance.py` `decide_conformance_gate`), and a missing self-mock sidecar blocks when the diff changed a test file (`validators/validate-run.py` `_validate_selfmock`). In an evidence-contract run evidence mode refuses a `conformance:` check from anyone but the owner, and the gate reads only the owner's record; otherwise nothing checks which verifier's log holds the commands.
70
86
 
71
87
  ### Tier 3 — stage conformance scripts
72
88
 
@@ -95,10 +111,10 @@ also remain contract violations.
95
111
 
96
112
  - **Owner only.** This section is the stage QA owner's (§ Stage QA owner above). A verifier that is not the owner runs no `runCommand`, writes no `result-*.json`, logs `conformance: owned by <worker-id> — not run`, and judges Tier 3 only from the diff and the manifest entry (declaration, `requires` coverage).
97
113
  - **Source.** The conformance manifest is `<task_root>/qa/conformance-manifest.json` (the directory is the `TASK_QA_PATH` token). This run's stage conformance entry is the manifest `entries[]` item whose `stageKey` equals this run's stageKey — `<task-id>-stage-<N>`, where `<N>` is the injected Stage number. Find that one entry. Also run every other entry whose `script` appears in this stage's `plannedPaths`: this stage rewrote that script, so the result its own stage recorded is stale, and you write that entry's result sidecar exactly as below. Ignore the rest (other stages are run by their own implementation runs or by final-verification).
98
- - **Exemption / waiver → do NOT run.** If the entry carries an `exemption` (or a user `waiver`), the verifier does NOT execute the script. It records the fact and the reason (`exemption.reason` / `waiver.reason` + `waiver.acknowledgedBy`) in the Read-only command log AND writes the result sidecar reflecting the skip. An `exemption` passes outright. An external-advisory waiver is reported as `ADVISORY` with `conditional=false`; only an `io`-only blocking waiver is conditional. An empty `requires` list cannot be waived; it is declaration/contract trouble and remains BLOCKING. No script runs in either permitted waiver case.
114
+ - **Exemption / waiver → do NOT run.** If the entry carries an `exemption` (or a user `waiver`), the verifier does NOT execute the script. It records the fact and the reason (`exemption.reason` / `waiver.reason` + `waiver.acknowledgedBy`) in the Read-only command log AND, outside an evidence-contract run, writes the result sidecar reflecting the skip (the gate reads the exemption or waiver from the manifest entry, so a marked run needs no sidecar). An `exemption` passes outright. An external-advisory waiver is reported as `ADVISORY` with `conditional=false`; only an `io`-only blocking waiver is conditional. An empty `requires` list cannot be waived; it is declaration/contract trouble and remains BLOCKING. No script runs in either permitted waiver case.
99
115
  - **Otherwise run `runCommand` in the worktree cwd.** Execute the entry's `runCommand` verbatim from the worktree cwd. Inject env from `<PROJECT_ROOT>/.okstra/project.json`'s `qaEnv` (replica DB DSN / app base URL / env file — declared in Phase 4e). This is a **replica / test environment only** path — never run it against shared / staging / prod, identical to the DB real-execution gate principle above.
100
116
  - **Interpret the standard interface.** Parse the process exit code together with stdout: the `QA-RESULT: PASS|FAIL` marker line (if several appear, the last one wins) and the per-requirement `REQ <id>: PASS|FAIL: <reason>` lines. If no `QA-RESULT` marker is emitted, the overall result is `MISSING`; classify it according to the entry's blocking or external-advisory capability policy above.
101
- - **Write the result sidecar (BLOCKING deliverable).** Write `<task_root>/qa/result-<stageKey>.json` as:
117
+ - **Write the result sidecar (BLOCKING deliverable; not in an evidence-contract run, see Evidence mode above).** Write `<task_root>/qa/result-<stageKey>.json` as:
102
118
  ```json
103
119
  {
104
120
  "stageKey": "<task-id>-stage-<N>",
@@ -219,7 +235,7 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
219
235
  - **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:501 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 500 lines, or a file the diff took from 500 or fewer past 500. A file already over 500 at the stage base that the diff grows is not blocking; the command prints it as an advisory line. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target: a new file over 300, a file the diff took past 300, or a file already over 300 the diff grew, including one already over 500) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
220
236
  - **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
221
237
  - **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within 500), function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, weak-but-not-misleading names, priority-between-inputs policy inlined in a service condition instead of a named domain function, an error message asserting a cause the code never observed, a memory / concurrency / batching change with no test pinning the bound it claims, or (hexagonal overlay only) a service dependency this diff adds or modifies that injects a concrete adapter instead of a port — record it with the port sketch; advisory only while the project has not declared `architecture.style = hexagonal`, since that declaration — and only that one — promotes exactly this item to blocking per the declared-style bullet above, while a declared `layered` binds dependency direction instead and leaves this item advisory; an existing convention of concrete injections does not convert this one to `clean`, it is the debt the rule pays down. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
222
- - **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
238
+ - **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. Each item, advisory items included, carries an item id as `prompts/profiles/_common-contract.md` "Cross-worker traceability" defines it for worker output. The lead cites a finding by that id, and `okstra convergence seed` refuses a cited id that does not occur in the result, so an unnumbered item cannot enter convergence and drops out of the report. This is a guideline: nothing parses a verifier result for missing ids. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
223
239
 
224
240
  ### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
225
241
 
@@ -23,7 +23,7 @@
23
23
  <h2>{{ t('tasks.implementation.verification-result') }}</h2>
24
24
  {{ render_narrative(narrative.validationExplanation, "implementation.userNarrative.validationExplanation") }}
25
25
  <div class="summary-grid">{% for row in validationCards %}<article class="summary-card tone-{{ row.tone }}"><h3>{% if row.checkId %}{{ row.checkId }} · {% endif %}{{ row.phase }} · {{ t('tasks.implementation.exit-code') }} {{ row.exitCode }}{% if row.get("advisory") %} · {{ t('tasks.implementation.advisory') }}{% endif %}</h3><p><code title="{{ row.command }}">{{ row.commandPreview }}</code></p><p>{{ row.outputTail | inline_code }}</p></article>{% endfor %}</div>
26
- {% for row in implementation.verifierResults %}<article class="summary-card tone-{{ row.verdict | lower }}"><p class="eyebrow">{{ row.verifier | inline_code }} · <span class="status status-{{ row.verdict | lower }}">{{ row.verdict }}</span></p>{% for label, text in ((t('tasks.implementation.independent-rerun'), row.get("independentValidationRerun")), (t('tasks.implementation.command-log'), row.get("readOnlyCommandLog"))) if text %}<details><summary><strong>{{ label }}</strong> {{ t('tasks.implementation.entry-count') | replace('{count}', text.strip().splitlines() | select | list | length | string) }}</summary><pre>{{ text }}</pre></details>{% endfor %}{% if row.get("discrepancy") %}<p class="evidence-refs">{{ t('tasks.implementation.discrepancy') }} {{ row.discrepancy | inline_code }}</p>{% endif %}{% if row.get("declinedFixRecommendations") %}<p>{{ row.declinedFixRecommendations | inline_code }}</p>{% endif %}</article>{% endfor %}
26
+ {% for row in implementation.verifierResults %}<article class="summary-card tone-{{ row.verdict | lower }}"><p class="eyebrow">{{ row.verifier | inline_code }} · <span class="status status-{{ row.verdict | lower }}">{{ row.verdict }}</span></p>{% for label, text in ((t('tasks.implementation.independent-rerun'), row.get("independentValidationRerun")), (t('tasks.implementation.command-log'), row.get("readOnlyCommandLog"))) if text %}<details><summary><strong>{{ label }}</strong> {{ t('tasks.implementation.entry-count') | replace('{count}', text.strip().splitlines() | select | list | length | string) }}</summary><pre>{{ text }}</pre></details>{% endfor %}{% if row.get("executionEvidence") %}<p><strong>{{ t('tasks.implementation.execution-records') }}</strong></p><ul class="evidence-refs" data-report-field="implementation.verifierResults.executionEvidence">{% for ref in row.executionEvidence %}<li><code>{{ ref.checkRef }}</code> run {{ ref.checkRun }} · {% if ref.collection == "complete" %}{{ t('tasks.implementation.exit-code') }} {{ ref.exitCode if ref.exitCode is not none else ref.signal }}{% else %}<span class="status status-incomplete">{{ t('tasks.implementation.incomplete-collection') }}</span> {{ ref.defect | inline_code }}{% endif %} · <code>{{ ref.recordPath }}</code></li>{% endfor %}</ul>{% endif %}{% if row.get("discrepancy") %}<p class="evidence-refs">{{ t('tasks.implementation.discrepancy') }} {{ row.discrepancy | inline_code }}</p>{% endif %}{% if row.get("declinedFixRecommendations") %}<p>{{ row.declinedFixRecommendations | inline_code }}</p>{% endif %}</article>{% endfor %}
27
27
  </section>
28
28
 
29
29
  {% if implementation.get("leadFixes") %}<section data-report-section="lead-fixes" data-report-field="implementation.leadFixes">
@@ -256,3 +256,5 @@ This phase does not declare final acceptance. It says only ready for final-verif
256
256
  | I-1 | An empty independent rerun record fails validation. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_reran_independently` |
257
257
  | I-2 | A verifier cannot report a discrepancy with a PASS verdict. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_discrepancy_is_not_passed` |
258
258
  | I-3 | Frozen legacy instruction pointers resolve within the selected installation without rewriting the frozen profile. | unenforced |
259
+ | I-4 | In a run marked `verificationEvidenceVersion: "1.0"`, each verifier's `executionEvidence` is the latest run of every check under its latest attempt of the invocation bound to the newest generation, with the recorded bytes and observation; a record that is not `completed` is incomplete collection. | `scripts/okstra_ctl/phases/implementation/validation.py::validate_verifier_execution_evidence` |
260
+ | I-5 | In a marked run, a `leadFixes` entry blocks the report, and a stage settled after correction round N shows the records of generation N + 1 of each verifier that generation gives a check it may run. Unmarked runs keep the lead-fix reading. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_lead_fixes`, `validate_settled_round_was_reverified` |