okstra 0.230.0 → 0.231.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -3
- package/docs/architecture/storage-model.md +67 -6
- package/docs/architecture.md +6 -2
- package/docs/coding-rules.md +15 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +2 -2
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/coding-preflight/clean-code.md +8 -0
- package/runtime/prompts/coding-preflight/overview.md +1 -0
- package/runtime/prompts/launch.template.md +2 -0
- package/runtime/prompts/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
- package/runtime/python/okstra_ctl/agent/invocation.py +48 -4
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/conformance_evidence.py +148 -67
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
- package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
- package/runtime/python/okstra_ctl/paths.py +19 -4
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +1 -0
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +1 -0
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +5 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +20 -4
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +2 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +230 -30
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
- package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +28 -0
- package/runtime/python/okstra_ctl/render.py +15 -0
- package/runtime/python/okstra_ctl/report_assembly.py +102 -1
- package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
- package/runtime/python/okstra_ctl/report_inputs.py +28 -0
- package/runtime/python/okstra_ctl/report_narrative.py +12 -3
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +8 -0
- package/runtime/python/okstra_ctl/run.py +16 -0
- package/runtime/python/okstra_ctl/stage_close.py +52 -6
- package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
- package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
- package/runtime/python/okstra_ctl/team.py +3 -1
- package/runtime/python/okstra_ctl/verification_dispatch.py +8 -2
- package/runtime/python/okstra_ctl/verification_evidence.py +26 -7
- package/runtime/python/okstra_ctl/verification_generation.py +12 -4
- package/runtime/python/okstra_ctl/verification_inputs.py +10 -0
- package/runtime/python/okstra_ctl/verification_invocation.py +2 -1
- package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
- package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
- package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
- package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- package/runtime/schemas/final-report-v3.0.schema.json +184 -1
- package/runtime/skills/okstra-run/SKILL.md +5 -1
- package/runtime/templates/reports/html/i18n/en.json +7 -0
- package/runtime/templates/reports/html/i18n/ko.json +7 -0
- package/runtime/validators/validate-run.py +27 -11
- package/runtime/validators/validate-workflow.sh +1 -1
|
@@ -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 =
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
|
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=
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
391
|
+
stage_ledger: Mapping[str, Any] | None,
|
|
392
|
+
rows: list[dict],
|
|
391
393
|
) -> list[str]:
|
|
392
394
|
"""이월 뒤 남은 디스패치 큐.
|
|
393
395
|
|
|
@@ -408,7 +410,8 @@ def _recompute_dispatch_queue(
|
|
|
408
410
|
for stage, status in (stage_ledger or {}).items()
|
|
409
411
|
},
|
|
410
412
|
)
|
|
411
|
-
|
|
413
|
+
candidates = queue_candidate_ids(extracted, ledger, verified_content_hashes(rows))
|
|
414
|
+
return [item["id"] for item in extracted if item["id"] in candidates]
|
|
412
415
|
|
|
413
416
|
|
|
414
417
|
def _writer_stage_rows(data: Mapping[str, Any], *, snapshot: str) -> dict[int, dict]:
|
|
@@ -483,7 +486,7 @@ def merge_v3_plan_state(
|
|
|
483
486
|
state_items[item_id] for item_id in sorted(state_items)
|
|
484
487
|
]
|
|
485
488
|
queue = _recompute_dispatch_queue(
|
|
486
|
-
narrative, pbv.get("stageLedger"),
|
|
489
|
+
narrative, pbv.get("stageLedger"), pbv["planItems"],
|
|
487
490
|
)
|
|
488
491
|
if queue:
|
|
489
492
|
pbv["dispatchQueue"] = queue
|
|
@@ -244,12 +244,17 @@ class RunRef:
|
|
|
244
244
|
) -> Path:
|
|
245
245
|
"""The directory holding every run of `check_ref` (`kind:id`) in one attempt."""
|
|
246
246
|
segment = check_ref.replace(":", "-", 1)
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
247
|
+
if not _EXECUTION_SEGMENT_RE.fullmatch(segment):
|
|
248
|
+
raise ValueError(f"verification execution segment is unsafe: {segment}")
|
|
249
|
+
return self._verification_attempt_dir(invocation_ref, attempt) / segment
|
|
250
|
+
|
|
251
|
+
def _verification_attempt_dir(self, invocation_ref: str, attempt: int) -> Path:
|
|
252
|
+
if not _EXECUTION_SEGMENT_RE.fullmatch(invocation_ref):
|
|
253
|
+
raise ValueError(
|
|
254
|
+
f"verification execution segment is unsafe: {invocation_ref}")
|
|
250
255
|
_positive_int(attempt, "verification execution attempt")
|
|
251
256
|
return (self.verification_dir / f"executions{self._suffix}" / invocation_ref
|
|
252
|
-
/ f"attempt-{attempt}"
|
|
257
|
+
/ f"attempt-{attempt}")
|
|
253
258
|
|
|
254
259
|
def verification_execution_dir(
|
|
255
260
|
self, invocation_ref: str, attempt: int, check_ref: str, check_run: int,
|
|
@@ -269,6 +274,16 @@ class RunRef:
|
|
|
269
274
|
) if match]
|
|
270
275
|
return max(numbers, default=None)
|
|
271
276
|
|
|
277
|
+
def verification_check_refs(self, invocation_ref: str, attempt: int) -> list[str]:
|
|
278
|
+
"""The checks (`kind:id`) one attempt ran, sorted."""
|
|
279
|
+
attempt_dir = self._verification_attempt_dir(invocation_ref, attempt)
|
|
280
|
+
return sorted(
|
|
281
|
+
path.name.replace("-", ":", 1)
|
|
282
|
+
for path in (attempt_dir.iterdir() if attempt_dir.is_dir() else ())
|
|
283
|
+
if path.is_dir() and "-" in path.name
|
|
284
|
+
and _EXECUTION_SEGMENT_RE.fullmatch(path.name)
|
|
285
|
+
)
|
|
286
|
+
|
|
272
287
|
@property
|
|
273
288
|
def convergence_state(self) -> Path:
|
|
274
289
|
"""이 run 의 finding convergence 상태 파일.
|
|
@@ -33,6 +33,7 @@
|
|
|
33
33
|
- **Defect-class sweep:** a confirmed defect is one instance of a class, and finding it does not end the search. Name its mechanism in one sentence (for example "after a recovery the editor keeps a copy of server data taken before the recovery"). Enumerate every location in the verified diff and its direct callers where that mechanism can occur, and the cases that change its outcome (for example same version, version changed, two recoveries overlapping, cancelled request). Judge every location × case cell `defective`, `sound`, `unverified`, or `not-applicable` with evidence, and report every defective cell in this run. Each blocker records the sweep as `defectClass` (`mechanism`, `cells[]`, `recurrence`). Its fix is the whole class: every `defective` cell names the `regressionTest` that must fail before the fix and pass after it. Sweep a Residual Risk's class the same way before writing it; a residual row has no `defectClass` field, so the sweep goes into its `item` text. **Enforced:** `phases/final_verification/validation.py` `_validate_defect_class_sweep` refuses a blocker without `defectClass`, without a `defective` cell, or with a `defective` cell that names no `regressionTest`. Whether the enumeration is complete is a judgement no validator can make.
|
|
34
34
|
- **Prior-run carry-in:** when an earlier final-verification run of the same target exists, the analysis packet carries its blockers under `## Prior Final-Verification Blockers` (`phases/final_verification/prior_blockers.py`). Re-check each carried blocker's whole class on the current head. A blocker whose mechanism matches a carried one is `recurrence: recurring` and cites it in `priorBlockers` as `final-verification-NNN AB-NNN`; a class a single-point fix already failed to close is re-planned, so a report with a `recurring` blocker routes to `error-analysis`, `implementation-option-selection`, or `implementation-planning`, never to `implementation`. **Enforced:** `validation.py` `_validate_defect_class_sweep` refuses a `recurring` blocker with no `priorBlockers`, and `_validate_recurring_class_routing` refuses any other routing target. Marking a matching class `new` is a judgement the validator cannot see.
|
|
35
35
|
- **Tier 1 and Tier 2 read-only validation:** Follow the `**Verification inputs:**` declaration-source rule when that header is present. The legacy lookup supplies only the sources that rule leaves unfrozen: Tier 1 is the originating brief/approved plan `validation` set, and Tier 2 is the `Project QA Commands` section from `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). A missing or unreadable referenced snapshot is missing verification input, not permission to substitute current settings. Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token. Tier 2 is already screened by prepare, so this check catches a Tier 1 command the brief or plan named.
|
|
36
|
+
- **Evidence mode (verification evidence contract):** a prompt that carries `**Verification generation path:**` belongs to a run marked `verificationEvidenceVersion: "1.0"`. Run every frozen Tier 2 `qaCommands` entry with `okstra worktree-lock --project-root <PROJECT_ROOT> --invocation-metadata <Invocation metadata path> --check qa:<id>`, and every in-scope Tier 3 stage the generation seals with `--check conformance:<stageKey>`; every verifier runs Tier 3, and none writes `qa/result-<stageKey>.json`. The command, worktree and locks come from the sealed generation, so pass no `--worktree` or `--command`. Judge each call by its `okstra worktree-lock: evidence <status>: <record path>` stderr line: `completed` is the command's result whatever its exit code, any other status is no evidence (exit 70, or 128+N after a signal), and `evidence refused:` means nothing ran; the plain lock mode is never a substitute. Report assembly writes one `readonlyCommandLog` row per record, so do not author executed Tier 2 or Tier 3 rows. Tier 1 runs as before. **Enforced:** `phases/final_verification/validation.py` `validate_command_log_execution_evidence` (spec FV-5) and the evidence branch of `validators/validate-run.py` `_validate_conformance`.
|
|
36
37
|
- **External QA outcome policy:** continue to attempt every in-scope Tier 3
|
|
37
38
|
command. For an entry requiring `db`, `http`, or `external`, record non-PASS
|
|
38
39
|
as a Tier 3 `advisory` command, add a user-owned Residual Risk and exact
|
|
@@ -47,6 +47,14 @@
|
|
|
47
47
|
{% if final.manualUserTest.applicable %}{% for row in final.manualUserTest.results %}<article class="summary-card tone-{{ row.result }}"><h3>{{ row.target | inline_code }} · {{ row.result }}</h3><p>{{ row.performed | inline_code }}</p><p>{{ row.observed | inline_code }}</p></article>{% endfor %}{% else %}<p>{{ final.manualUserTest.exemptionReaffirm | inline_code }}</p>{% endif %}
|
|
48
48
|
</section>
|
|
49
49
|
|
|
50
|
+
{% if final.get("readonlyCommandLog") %}
|
|
51
|
+
<section data-report-section="read-only-commands" data-report-field="finalVerification.readonlyCommandLog">
|
|
52
|
+
<h2>{{ t('tasks.final-verification.read-only-commands') }}</h2>
|
|
53
|
+
<div class="table-scroll"><table><thead><tr><th>#</th><th>{{ t('tasks.final-verification.tier') }}</th><th>{{ t('tasks.final-verification.command') }}</th><th>{{ t('macros.layout.status') }}</th><th>{{ t('tasks.final-verification.exit-code') }}</th><th>{{ t('tasks.final-verification.execution-record') }}</th></tr></thead>
|
|
54
|
+
<tbody>{% for row in final.readonlyCommandLog %}<tr><td>{{ row.number }}</td><td>{{ row.tier }}</td><td>{{ row.command | inline_code }}</td><td><span class="status status-{{ row.status }}">{{ row.status }}</span>{% if row.get("statusReason") %} {{ row.statusReason | inline_code }}{% endif %}</td><td>{{ row.exitCode if row.exitCode is not none else "" }}</td><td>{% if row.get("executionEvidence") %}<code>{{ row.executionEvidence.checkRef }}</code> run {{ row.executionEvidence.checkRun }} · <code>{{ row.executionEvidence.recordPath }}</code>{% endif %}</td></tr>{% endfor %}</tbody></table></div>
|
|
55
|
+
</section>
|
|
56
|
+
{% endif %}
|
|
57
|
+
|
|
50
58
|
<section data-report-section="verified-source" data-report-field="finalVerification.sourceImplementationReport">
|
|
51
59
|
<h2>{{ t('tasks.final-verification.what-was-verified') }}</h2>
|
|
52
60
|
<table><tbody><tr><th>{{ t('tasks.final-verification.implementation-report') }}</th><td><code>{{ final.sourceImplementationReport.path }}</code></td></tr><tr><th>{{ t('tasks.final-verification.worktree') }}</th><td><code>{{ final.sourceImplementationReport.worktreePath }}</code></td></tr><tr><th>{{ t('tasks.final-verification.base-commit') }}</th><td><code>{{ final.sourceImplementationReport.implementationBaseRef }}</code> → <code>{{ final.sourceImplementationReport.capturedHeadSha }}</code></td></tr><tr><th>{{ t('tasks.final-verification.diff-summary') }}</th><td>{{ final.sourceImplementationReport.diffSummaryQuote | inline_code }}</td></tr><tr><th>{{ t('tasks.final-verification.uncommitted-state') }}</th><td>{{ final.sourceImplementationReport.gitStatusShort | inline_code }}</td></tr></tbody></table>
|
|
@@ -10,6 +10,7 @@ This directory is the canonical home of the final-verification phase. Report fie
|
|
|
10
10
|
| FV-2 | A release-handoff route requires a release-ready verdict | `validators/validate-run.py::_refuse_unsuitable_final_verification_route` |
|
|
11
11
|
| FV-3 | The final-verification destination list matches the report schema | unenforced |
|
|
12
12
|
| FV-4 | The phase profile is not also stored under prompts/profiles | unenforced |
|
|
13
|
+
| FV-5 | In a run marked `verificationEvidenceVersion: "1.0"`, every executed Tier 2 or Tier 3 read-only command row is one current execution record of a verifier, and the row's command, status, exit code and output are the record's | `scripts/okstra_ctl/phases/final_verification/validation.py::validate_command_log_execution_evidence` |
|
|
13
14
|
|
|
14
15
|
## Process
|
|
15
16
|
|
|
@@ -10,6 +10,10 @@ import re
|
|
|
10
10
|
from collections.abc import Mapping
|
|
11
11
|
from pathlib import Path
|
|
12
12
|
|
|
13
|
+
from okstra_ctl.report_execution_evidence import (
|
|
14
|
+
EXECUTION_EVIDENCE_BLOCKING, RECORD_DERIVED_TIERS, collect_report_evidence,
|
|
15
|
+
command_row, execution_evidence_contract, omitted_records, reference_errors,
|
|
16
|
+
)
|
|
13
17
|
from okstra_ctl.verification_target import TARGET_FIELD_RES, read_verification_target
|
|
14
18
|
|
|
15
19
|
_ADDED_SURFACE_NO_CALLER_RE = re.compile(r"^\s*none\b", re.IGNORECASE)
|
|
@@ -280,3 +284,52 @@ def validate_verification_target_match(
|
|
|
280
284
|
f"(`{relative}`). A verdict must not be rendered for a stage set "
|
|
281
285
|
"nobody prepared evidence for."
|
|
282
286
|
)
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def validate_command_log_execution_evidence(
|
|
291
|
+
data: dict, project_root: Path, manifest_path: Path, run_manifest: Mapping,
|
|
292
|
+
failures: list[str],
|
|
293
|
+
) -> None:
|
|
294
|
+
"""Every read-only command row of an evidence-contract run that executed a
|
|
295
|
+
Tier 2 or Tier 3 check is one current execution record of a verifier.
|
|
296
|
+
|
|
297
|
+
A row's reference must be the latest run of a check under a verifier's
|
|
298
|
+
latest attempt of the invocation bound to the run's newest generation, and
|
|
299
|
+
the row's command, status, exit code and output must be the record's.
|
|
300
|
+
"""
|
|
301
|
+
if not execution_evidence_contract(run_manifest, failures):
|
|
302
|
+
return
|
|
303
|
+
try:
|
|
304
|
+
verifiers = list(collect_report_evidence(project_root, manifest_path).values())
|
|
305
|
+
except ValueError as exc:
|
|
306
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} verification execution "
|
|
307
|
+
f"evidence could not be collected: {exc}")
|
|
308
|
+
return
|
|
309
|
+
final = data.get("finalVerification")
|
|
310
|
+
rows = final.get("readonlyCommandLog") if isinstance(final, Mapping) else None
|
|
311
|
+
matched: set[str] = set()
|
|
312
|
+
for index, row in enumerate(rows if isinstance(rows, list) else []):
|
|
313
|
+
if not isinstance(row, Mapping):
|
|
314
|
+
continue
|
|
315
|
+
where = f"finalVerification.readonlyCommandLog[{index}]"
|
|
316
|
+
if "executionEvidence" not in row:
|
|
317
|
+
if row.get("status") == "executed" and row.get("tier") in RECORD_DERIVED_TIERS:
|
|
318
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} {where} records an "
|
|
319
|
+
f"executed Tier {row.get('tier')} check without its "
|
|
320
|
+
"execution record")
|
|
321
|
+
continue
|
|
322
|
+
errors, paths = reference_errors(
|
|
323
|
+
f"{where}.executionEvidence", row["executionEvidence"], verifiers,
|
|
324
|
+
)
|
|
325
|
+
failures.extend(f"{EXECUTION_EVIDENCE_BLOCKING} {error}" for error in errors)
|
|
326
|
+
if paths and not errors:
|
|
327
|
+
derived = command_row(row.get("number"), row["executionEvidence"])
|
|
328
|
+
if dict(row) != derived:
|
|
329
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} {where} differs from "
|
|
330
|
+
f"its execution record {sorted(paths)[0]}")
|
|
331
|
+
matched |= paths
|
|
332
|
+
omitted = omitted_records(verifiers, matched)
|
|
333
|
+
if omitted:
|
|
334
|
+
failures.append(f"{EXECUTION_EVIDENCE_BLOCKING} finalVerification."
|
|
335
|
+
f"readonlyCommandLog omits execution records {omitted}")
|
|
@@ -51,6 +51,10 @@ If `render-bundle` fails with a `PrepareError` containing `Recorded stage SHAs n
|
|
|
51
51
|
|
|
52
52
|
If the anchor (`implementation_base_commit`) is reported unresolvable, run the same command's `--reset-anchor <ref>` after user confirmation. Correcting a confirm item without the picker is forbidden — the runtime also rejects a confirm correction without `--use-ref`.
|
|
53
53
|
|
|
54
|
+
### Predecessor merge conflict (merge-base gate)
|
|
55
|
+
|
|
56
|
+
A stage that depends on two or more stages starts from a merge-base branch that okstra builds from the implementation anchor by merging each predecessor's completion commit with `--no-ff`, in stage order. If two predecessors conflict, `render-bundle` fails with a `PrepareError` containing `merge conflict while merging stage <N>`. okstra never resolves the conflict itself. When it was creating the branch, it deletes the half-built branch and the steps start from the anchor. When it was advancing an existing branch to a newer predecessor commit, the branch stays at its previous tip and the steps check it out and merge only the commits it lacks. Do not edit the registry or consumers, and do not merge a predecessor into a stage branch. Stop and show the user the conflicting paths and the steps from the error verbatim: the branch name, the `git worktree add` command, and one `git merge --no-ff --no-edit <commit>` per predecessor in the listed order. Those commands disable repository hooks the way okstra's own merges do. The user, or you on the user's instruction, runs those steps, resolves the conflict, runs the project's checks, commits the merge and removes that worktree. Then retry the failed `render-bundle` with the same arguments. It reuses the branch only when the branch contains the anchor and every predecessor commit and carries no other non-merge commit; otherwise it fails and names the problem.
|
|
57
|
+
|
|
54
58
|
### Next stage not yet ready — normal termination (not an exception gate)
|
|
55
59
|
Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
|
|
56
60
|
|
|
@@ -58,4 +62,4 @@ Because of the dependency closure, the chain queue **may include a stage that an
|
|
|
58
62
|
A verifier FAIL that a passing lead minor fix answered does not make the verdict `FAIL` (`_implementation-deliverable.md` "Lead minor fix"); that stage settles `done` and the queue continues. When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
|
|
59
63
|
|
|
60
64
|
### Exception gate during chaining
|
|
61
|
-
If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch)
|
|
65
|
+
If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch), git stale-SHA reconciliation (git-reconcile branch) or a predecessor merge conflict (merge-base gate), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these branches do not discard the queue; they wait for user resolution.)
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md
CHANGED
|
@@ -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:
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md
CHANGED
|
@@ -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`).
|
|
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
|
|
package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html
CHANGED
|
@@ -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` |
|