okstra 0.226.0 → 0.228.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +43 -7
- package/docs/project-structure-overview.md +13 -3
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -0
- package/runtime/prompts/lead/convergence.md +5 -19
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
- package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
- package/runtime/python/okstra_ctl/brief_sources.py +162 -44
- package/runtime/python/okstra_ctl/code_review_coverage.py +81 -19
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +115 -55
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
- package/runtime/python/okstra_ctl/fixed_text.py +31 -9
- package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
- package/runtime/python/okstra_ctl/json_registry.py +3 -18
- package/runtime/python/okstra_ctl/manager_split.py +201 -84
- package/runtime/python/okstra_ctl/model_io/references.py +31 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
- package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
- package/runtime/python/okstra_ctl/path_hints.py +13 -1
- package/runtime/python/okstra_ctl/paths.py +4 -0
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +9 -11
- package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/prior_planning.py +6 -17
- package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
- package/runtime/python/okstra_ctl/qa_commands.py +66 -1
- package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
- package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
- package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +123 -6
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
- package/runtime/python/okstra_ctl/verification_plan.py +116 -0
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
- package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/python/okstra_project/dirs.py +22 -0
- package/runtime/python/okstra_project/resolver.py +10 -0
- package/runtime/schemas/final-report-v3.0.schema.json +5 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
- package/runtime/skills/okstra-code-review/SKILL.md +59 -63
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-run/SKILL.md +21 -1
- package/runtime/skills/okstra-setup/SKILL.md +2 -0
- package/runtime/skills/okstra-setup/references/project-config.md +2 -0
- package/runtime/validators/validate-brief.py +21 -5
|
@@ -13,7 +13,37 @@ from typing import Any, Mapping
|
|
|
13
13
|
from okstra_project import StateError, parse_task_key, slugify
|
|
14
14
|
|
|
15
15
|
from ..json_boundary import JsonBoundaryError, load_owned_object
|
|
16
|
-
from ..
|
|
16
|
+
from ..convergence import ConvergenceContractError, validated_run_authority
|
|
17
|
+
from ..paths import RunRef, okstra_home
|
|
18
|
+
from ..ports.verification_inputs import VerificationInputStore
|
|
19
|
+
from ..verification_input_ref import VerificationInputReference
|
|
20
|
+
from ..verification_input_types import VerificationInputs
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _load_verification_input(
|
|
24
|
+
run_manifest: Path, store: VerificationInputStore,
|
|
25
|
+
) -> tuple[VerificationInputReference, VerificationInputs]:
|
|
26
|
+
try:
|
|
27
|
+
authority = validated_run_authority(run_manifest)
|
|
28
|
+
reference = VerificationInputReference.from_artifact_fields(authority.payload)
|
|
29
|
+
if reference is None:
|
|
30
|
+
raise ValueError("run has no verification input reference")
|
|
31
|
+
sequence = authority.payload["runSequencesByCategory"]["manifests"]
|
|
32
|
+
expected = RunRef.from_run_dir(
|
|
33
|
+
authority.run_dir, seq=int(sequence),
|
|
34
|
+
).verification_inputs
|
|
35
|
+
if reference.relative_path != expected.relative_to(
|
|
36
|
+
authority.project_root,
|
|
37
|
+
).as_posix():
|
|
38
|
+
raise ValueError("verification inputs do not match canonical run")
|
|
39
|
+
path = _fixed_owned_artifact_path(
|
|
40
|
+
authority.project_root,
|
|
41
|
+
expected.relative_to(authority.project_root / ".okstra"),
|
|
42
|
+
"verification inputs",
|
|
43
|
+
)
|
|
44
|
+
return reference, store.read(path, reference.digest)
|
|
45
|
+
except (ConvergenceContractError, OSError, ValueError) as exc:
|
|
46
|
+
raise JsonBoundaryError(run_manifest, "verification inputs", str(exc)) from exc
|
|
17
47
|
|
|
18
48
|
|
|
19
49
|
def _fixed_owned_artifact_path(
|
|
@@ -16,9 +16,10 @@ from ..convergence import (
|
|
|
16
16
|
validated_run_authority,
|
|
17
17
|
)
|
|
18
18
|
from ..error_zip import last_output_path
|
|
19
|
-
from ..fixed_text import line as _line, scalar as _value
|
|
19
|
+
from ..fixed_text import line as _line, scalar as _value, quoted_value_lines
|
|
20
20
|
from ..json_boundary import JsonBoundaryError, load_owned_object
|
|
21
21
|
from ..paths import find_asset_root, okstra_home
|
|
22
|
+
from ..ports.verification_inputs import VerificationInputStore
|
|
22
23
|
from ..phases.catalog import PhaseAssetError, profile_markdown
|
|
23
24
|
from ..recap import assemble_group_recap, assemble_recap
|
|
24
25
|
from ..role_requirements import RoleProfileError, load_role_profile
|
|
@@ -42,6 +43,7 @@ from .references import (
|
|
|
42
43
|
_group_segment,
|
|
43
44
|
_latest_task_pointer,
|
|
44
45
|
_load_project,
|
|
46
|
+
_load_verification_input,
|
|
45
47
|
_owned_run_manifest_path,
|
|
46
48
|
_owned_task_manifest_path,
|
|
47
49
|
_owned_tasks_root,
|
|
@@ -145,6 +147,31 @@ def render_project_context(project_root: Path, task_ref: str = "") -> str:
|
|
|
145
147
|
)
|
|
146
148
|
|
|
147
149
|
|
|
150
|
+
def render_verification_input(
|
|
151
|
+
run_manifest: Path, store: VerificationInputStore,
|
|
152
|
+
) -> str:
|
|
153
|
+
reference, inputs = _load_verification_input(run_manifest, store)
|
|
154
|
+
rows = [
|
|
155
|
+
"# Okstra Verification Input\n\n",
|
|
156
|
+
_line("Verification inputs", reference.relative_path),
|
|
157
|
+
_line("Verification inputs digest", reference.digest),
|
|
158
|
+
_line("Source root", inputs["sourceRoot"]),
|
|
159
|
+
"\nThese are frozen declarations, not command-execution evidence.\n",
|
|
160
|
+
"Scalar values below use JSON quoting; preserve escaped characters "
|
|
161
|
+
"when reading commands and procedure bodies.\n",
|
|
162
|
+
"\n## QA Commands\n\n",
|
|
163
|
+
*quoted_value_lines("QA commands", inputs["qaCommands"]),
|
|
164
|
+
"\n## Procedures\n\n",
|
|
165
|
+
*quoted_value_lines("Procedures", inputs["procedures"]),
|
|
166
|
+
]
|
|
167
|
+
if "approvedPlan" in inputs:
|
|
168
|
+
rows.extend([
|
|
169
|
+
"\n## Approved Plan\n\n",
|
|
170
|
+
*quoted_value_lines("Approved plan", inputs["approvedPlan"]),
|
|
171
|
+
])
|
|
172
|
+
return "".join(rows)
|
|
173
|
+
|
|
174
|
+
|
|
148
175
|
def render_run_input(run_manifest: Path) -> str:
|
|
149
176
|
"""런 매니페스트의 간결한 비밀 없는 실행 식별자를 렌더한다."""
|
|
150
177
|
run_manifest = _owned_run_manifest_path(run_manifest)
|
|
@@ -182,6 +209,8 @@ def render_run_input(run_manifest: Path) -> str:
|
|
|
182
209
|
+ _line("Task manifest", run.get("taskManifestPath"))
|
|
183
210
|
+ _line("Instruction set", run.get("instructionSetPath"))
|
|
184
211
|
+ _line("Reference expectations", run.get("referenceExpectationsPath"))
|
|
212
|
+
+ _line("Verification inputs", run.get("verificationInputsPath"))
|
|
213
|
+
+ _line("Verification inputs digest", run.get("verificationInputsDigest"))
|
|
185
214
|
+ _line("Report template", run.get("reportTemplatePath"))
|
|
186
215
|
)
|
|
187
216
|
|
|
@@ -10,6 +10,7 @@ import sys
|
|
|
10
10
|
from pathlib import Path
|
|
11
11
|
|
|
12
12
|
from .json_boundary import JsonBoundaryError
|
|
13
|
+
from .registry.verification_inputs_store import default_verification_input_store
|
|
13
14
|
from .model_io.renderers import (
|
|
14
15
|
render_active_context_input,
|
|
15
16
|
render_code_review_input,
|
|
@@ -24,12 +25,14 @@ from .model_io.renderers import (
|
|
|
24
25
|
render_schedule_input,
|
|
25
26
|
render_status_input,
|
|
26
27
|
render_task_selection_input,
|
|
28
|
+
render_verification_input,
|
|
27
29
|
)
|
|
28
30
|
|
|
29
31
|
|
|
30
32
|
_CLI_EPILOG = r"""Usage:
|
|
31
33
|
okstra model-io project-context --project-root <dir> [--task-ref <task-id|task-key|task-manifest-path>]
|
|
32
34
|
okstra model-io run-input --run-manifest <path>
|
|
35
|
+
okstra model-io verification-input --run-manifest <path>
|
|
33
36
|
okstra model-io active-context-input --project-root <dir> --run-manifest <path>
|
|
34
37
|
okstra model-io schedule-input --project-root <dir> --task-group <id>
|
|
35
38
|
okstra model-io code-review-input --project-root <dir> --base <ref> --head <ref>
|
|
@@ -52,6 +55,8 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
52
55
|
project.add_argument("--task-ref", default="")
|
|
53
56
|
run = commands.add_parser("run-input")
|
|
54
57
|
run.add_argument("--run-manifest", required=True)
|
|
58
|
+
verification = commands.add_parser("verification-input")
|
|
59
|
+
verification.add_argument("--run-manifest", required=True)
|
|
55
60
|
active = commands.add_parser("active-context-input")
|
|
56
61
|
active.add_argument("--project-root", required=True)
|
|
57
62
|
active.add_argument("--run-manifest", required=True)
|
|
@@ -93,6 +98,10 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
93
98
|
text = render_project_context(Path(args.project_root), args.task_ref)
|
|
94
99
|
elif args.command == "run-input":
|
|
95
100
|
text = render_run_input(Path(args.run_manifest))
|
|
101
|
+
elif args.command == "verification-input":
|
|
102
|
+
text = render_verification_input(
|
|
103
|
+
Path(args.run_manifest), default_verification_input_store(),
|
|
104
|
+
)
|
|
96
105
|
elif args.command == "active-context-input":
|
|
97
106
|
text = render_active_context_input(
|
|
98
107
|
Path(args.project_root), Path(args.run_manifest)
|
|
@@ -19,6 +19,9 @@ from .paths import (
|
|
|
19
19
|
task_timeline_file,
|
|
20
20
|
)
|
|
21
21
|
from .worker_artifacts import worker_artifact_paths
|
|
22
|
+
from .verification_input_ref import (
|
|
23
|
+
VerificationInputReference, artifact_fields, artifact_fields_from_context,
|
|
24
|
+
)
|
|
22
25
|
|
|
23
26
|
RUN_CONTEXT_KIND = "run-context"
|
|
24
27
|
RUN_CONTEXT_SCHEMA_VERSION = "2.0"
|
|
@@ -45,6 +48,7 @@ def compact_run_context(ctx: Mapping[str, Any]) -> dict[str, Any]:
|
|
|
45
48
|
"runTimestampIso": ctx.get("RUN_TIMESTAMP_ISO", ""),
|
|
46
49
|
"taskDate": ctx.get("TASK_DATE", ""),
|
|
47
50
|
},
|
|
51
|
+
**artifact_fields_from_context(ctx),
|
|
48
52
|
}
|
|
49
53
|
|
|
50
54
|
|
|
@@ -72,6 +76,7 @@ def compact_active_run_context(
|
|
|
72
76
|
"executorWorktree": dict(_mapping(payload.get("executorWorktree"))),
|
|
73
77
|
"verificationTarget": dict(_mapping(payload.get("verificationTarget"))),
|
|
74
78
|
"lazyReadPlan": dict(_mapping(payload.get("lazyReadPlan"))),
|
|
79
|
+
**artifact_fields_from_context(ctx),
|
|
75
80
|
}
|
|
76
81
|
|
|
77
82
|
|
|
@@ -83,7 +88,11 @@ def hydrate_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
|
|
|
83
88
|
identity = payload.get("identity")
|
|
84
89
|
if not isinstance(hints, Mapping) or not isinstance(identity, Mapping):
|
|
85
90
|
return dict(payload)
|
|
86
|
-
|
|
91
|
+
ctx = _hydrate_from_hints(identity, hints, payload.get("timestamps", {}))
|
|
92
|
+
reference = VerificationInputReference.from_artifact_fields(payload)
|
|
93
|
+
if reference is not None:
|
|
94
|
+
ctx.update(reference.to_context(Path(str(identity.get("projectRoot", "")))))
|
|
95
|
+
return ctx
|
|
87
96
|
|
|
88
97
|
|
|
89
98
|
def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
|
|
@@ -92,11 +101,13 @@ def hydrate_active_run_context(payload: Mapping[str, Any]) -> dict[str, Any]:
|
|
|
92
101
|
return dict(payload)
|
|
93
102
|
identity = _mapping(payload.get("identity"))
|
|
94
103
|
hints = _mapping(payload.get("pathHints"))
|
|
104
|
+
reference = VerificationInputReference.from_artifact_fields(payload)
|
|
95
105
|
ctx = hydrate_run_context({
|
|
96
106
|
"kind": RUN_CONTEXT_KIND,
|
|
97
107
|
"identity": identity,
|
|
98
108
|
"pathHints": hints,
|
|
99
109
|
"timestamps": {},
|
|
110
|
+
**artifact_fields(reference),
|
|
100
111
|
})
|
|
101
112
|
return {
|
|
102
113
|
"schemaVersion": "1.0",
|
|
@@ -305,6 +316,7 @@ def _hydrate_active_source_artifacts(ctx: Mapping[str, str]) -> dict[str, str]:
|
|
|
305
316
|
"runContextPath": ctx.get("RUN_CONTEXT_RELATIVE_PATH", ""),
|
|
306
317
|
"runInputsPath": ctx.get("RUN_INPUTS_RELATIVE_PATH", ""),
|
|
307
318
|
"historyTimelinePath": ctx.get("TIMELINE_RELATIVE_PATH", ""),
|
|
319
|
+
**artifact_fields_from_context(ctx),
|
|
308
320
|
}
|
|
309
321
|
|
|
310
322
|
|
|
@@ -219,6 +219,10 @@ class RunRef:
|
|
|
219
219
|
def manifest(self) -> Path:
|
|
220
220
|
return self.run_dir / "manifests" / f"run-manifest{self._suffix}.json"
|
|
221
221
|
|
|
222
|
+
@property
|
|
223
|
+
def verification_inputs(self) -> Path:
|
|
224
|
+
return self.run_dir / "verification" / f"inputs{self._suffix}.json"
|
|
225
|
+
|
|
222
226
|
@property
|
|
223
227
|
def convergence_state(self) -> Path:
|
|
224
228
|
"""이 run 의 finding convergence 상태 파일.
|
|
@@ -12,41 +12,61 @@ from __future__ import annotations
|
|
|
12
12
|
|
|
13
13
|
import re
|
|
14
14
|
from collections.abc import Mapping
|
|
15
|
+
from dataclasses import dataclass
|
|
15
16
|
from pathlib import Path
|
|
16
17
|
|
|
17
18
|
from okstra_ctl.final_report_paths import final_report_data_path
|
|
18
|
-
from okstra_ctl.
|
|
19
|
+
from okstra_ctl.phases.final_verification.validation import acceptance_blocker_rows
|
|
20
|
+
from okstra_ctl.prior_run_summary import load_prior_object, one_line
|
|
19
21
|
|
|
20
22
|
_REPORT_RE = re.compile(r"^final-report-final-verification-(\d{3,})\.data\.json$")
|
|
21
23
|
_SUMMARY_LIMIT = 300
|
|
22
|
-
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True)
|
|
27
|
+
class _PriorReport:
|
|
28
|
+
seq: str
|
|
29
|
+
data: Mapping
|
|
30
|
+
problem: str
|
|
23
31
|
|
|
24
32
|
|
|
25
33
|
def prior_blockers_packet_block(final_report_path: Path) -> str:
|
|
26
|
-
"""
|
|
27
|
-
|
|
34
|
+
"""Summary of the reports numbered before this run's report.
|
|
35
|
+
|
|
36
|
+
Empty when no earlier report carries a blocker, none was skipped as
|
|
37
|
+
unreadable or malformed, and the latest readable one left no residual risk.
|
|
38
|
+
"""
|
|
39
|
+
priors = _earlier_reports(Path(final_report_path))
|
|
40
|
+
readable = [prior for prior in priors if not prior.problem]
|
|
41
|
+
latest = readable[-1] if readable else None
|
|
42
|
+
risk_lines = _risk_lines(latest.data) if latest else []
|
|
43
|
+
skipped = len(readable) < len(priors)
|
|
44
|
+
has_blockers = any(acceptance_blocker_rows(prior.data) for prior in readable)
|
|
45
|
+
if not has_blockers and not skipped and not risk_lines:
|
|
46
|
+
return ""
|
|
47
|
+
return _render_block(priors, latest, risk_lines)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _earlier_reports(final_report_path: Path) -> list[_PriorReport]:
|
|
51
|
+
current = _REPORT_RE.match(final_report_data_path(final_report_path).name)
|
|
28
52
|
current_seq = int(current.group(1)) if current else None
|
|
29
|
-
reports_dir = Path(final_report_path).parent
|
|
30
53
|
priors = []
|
|
31
|
-
|
|
54
|
+
pattern = "final-report-final-verification-*.data.json"
|
|
55
|
+
for path in final_report_path.parent.glob(pattern):
|
|
32
56
|
match = _REPORT_RE.match(path.name)
|
|
33
57
|
if match is None:
|
|
34
58
|
continue
|
|
35
|
-
|
|
36
|
-
if current_seq is not None and seq >= current_seq:
|
|
59
|
+
if current_seq is not None and int(match.group(1)) >= current_seq:
|
|
37
60
|
continue
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
risk_lines = _risk_lines(latest)
|
|
48
|
-
if not any(line.startswith(" - AB-") for line in run_lines) and not risk_lines:
|
|
49
|
-
return ""
|
|
61
|
+
priors.append(_PriorReport(match.group(1), *_load(path)))
|
|
62
|
+
return sorted(priors, key=lambda prior: int(prior.seq))
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _render_block(
|
|
66
|
+
priors: list[_PriorReport],
|
|
67
|
+
latest: _PriorReport | None,
|
|
68
|
+
risk_lines: list[str],
|
|
69
|
+
) -> str:
|
|
50
70
|
parts = [
|
|
51
71
|
"## Prior Final-Verification Blockers",
|
|
52
72
|
"",
|
|
@@ -59,20 +79,31 @@ def prior_blockers_packet_block(final_report_path: Path) -> str:
|
|
|
59
79
|
"`final-verification-NNN AB-NNN`, and route to a phase that re-plans",
|
|
60
80
|
"the class, never to `implementation`.",
|
|
61
81
|
"",
|
|
62
|
-
*run_lines,
|
|
63
82
|
]
|
|
64
|
-
|
|
83
|
+
for prior in priors:
|
|
84
|
+
if prior.problem:
|
|
85
|
+
parts.append(
|
|
86
|
+
f"- `final-verification-{prior.seq}`: {prior.problem} — skipped"
|
|
87
|
+
)
|
|
88
|
+
else:
|
|
89
|
+
parts.extend(_run_lines(prior.seq, prior.data))
|
|
90
|
+
if any(prior.problem for prior in priors):
|
|
65
91
|
parts.extend([
|
|
66
92
|
"",
|
|
67
|
-
|
|
93
|
+
"A skipped run left a report this prepare could not read. Open it",
|
|
94
|
+
"before assuming that run raised no blocker.",
|
|
95
|
+
])
|
|
96
|
+
if latest and risk_lines:
|
|
97
|
+
parts.extend([
|
|
98
|
+
"",
|
|
99
|
+
f"Residual risks `final-verification-{latest.seq}` left open:",
|
|
68
100
|
*risk_lines,
|
|
69
101
|
])
|
|
70
102
|
return "\n".join(parts)
|
|
71
103
|
|
|
72
104
|
|
|
73
105
|
def _run_lines(seq: str, data: Mapping) -> list[str]:
|
|
74
|
-
fv = data.get("finalVerification")
|
|
75
|
-
fv = fv if isinstance(fv, Mapping) else {}
|
|
106
|
+
fv = data.get("finalVerification") or {}
|
|
76
107
|
verdict = _one_line((data.get("finalVerdict") or {}).get("verdictToken")) or "unrecorded"
|
|
77
108
|
routing = fv.get("routingRecommendation")
|
|
78
109
|
target = _one_line(routing.get("target")) if isinstance(routing, Mapping) else ""
|
|
@@ -80,9 +111,7 @@ def _run_lines(seq: str, data: Mapping) -> list[str]:
|
|
|
80
111
|
f"- `final-verification-{seq}`: verdict `{verdict}`, routed "
|
|
81
112
|
f"`{target or 'unrecorded'}`"
|
|
82
113
|
]
|
|
83
|
-
for row in
|
|
84
|
-
if not isinstance(row, Mapping):
|
|
85
|
-
continue
|
|
114
|
+
for row in acceptance_blocker_rows(data):
|
|
86
115
|
defect_class = row.get("defectClass")
|
|
87
116
|
mechanism = (
|
|
88
117
|
_one_line(defect_class.get("mechanism"))
|
|
@@ -100,29 +129,42 @@ def _run_lines(seq: str, data: Mapping) -> list[str]:
|
|
|
100
129
|
|
|
101
130
|
|
|
102
131
|
def _risk_lines(data: Mapping) -> list[str]:
|
|
103
|
-
|
|
104
|
-
rows = fv.get("residualRisk") if isinstance(fv, Mapping) else None
|
|
132
|
+
rows = (data.get("finalVerification") or {}).get("residualRisk") or []
|
|
105
133
|
return [
|
|
106
134
|
f"- {_one_line(row.get('id')) or '<no id>'}: {_one_line(row.get('item'))}"
|
|
107
|
-
for row in rows
|
|
135
|
+
for row in rows
|
|
108
136
|
if isinstance(row, Mapping)
|
|
109
137
|
]
|
|
110
138
|
|
|
111
139
|
|
|
112
|
-
def _load(path: Path) -> Mapping:
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
140
|
+
def _load(path: Path) -> tuple[Mapping, str]:
|
|
141
|
+
"""The report and ``""``, or an empty mapping and why the report is skipped."""
|
|
142
|
+
data, reason = load_prior_object(path, artifact="prior final-verification report")
|
|
143
|
+
if reason is not None:
|
|
144
|
+
return {}, f"report unreadable ({_one_line(reason)})"
|
|
145
|
+
problem = _shape_problem(data)
|
|
146
|
+
if problem:
|
|
147
|
+
return {}, f"report malformed ({problem})"
|
|
148
|
+
return data, ""
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _shape_problem(data: Mapping) -> str:
|
|
152
|
+
"""The first container this block reads that has the wrong type, or ``""``.
|
|
153
|
+
|
|
154
|
+
The loader checks only the top-level object, and a report validate-run.py
|
|
155
|
+
refused stays in the reports directory this block scans.
|
|
156
|
+
"""
|
|
157
|
+
for key in ("finalVerdict", "finalVerification"):
|
|
158
|
+
value = data.get(key)
|
|
159
|
+
if value is not None and not isinstance(value, Mapping):
|
|
160
|
+
return f"`{key}` is not an object"
|
|
161
|
+
fv = data.get("finalVerification") or {}
|
|
162
|
+
for key in ("acceptanceBlockers", "residualRisk"):
|
|
163
|
+
value = fv.get(key)
|
|
164
|
+
if value is not None and not isinstance(value, list):
|
|
165
|
+
return f"`finalVerification.{key}` is not a list"
|
|
166
|
+
return ""
|
|
120
167
|
|
|
121
168
|
|
|
122
169
|
def _one_line(value: object) -> str:
|
|
123
|
-
|
|
124
|
-
return ""
|
|
125
|
-
collapsed = _WHITESPACE_RE.sub(" ", value).strip()
|
|
126
|
-
if len(collapsed) <= _SUMMARY_LIMIT:
|
|
127
|
-
return collapsed
|
|
128
|
-
return collapsed[: _SUMMARY_LIMIT - 1].rstrip() + "…"
|
|
170
|
+
return one_line(value, _SUMMARY_LIMIT)
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
- requirement & acceptance coverage — every must-pass point in the brief's `## Expected Behavior` / `## Preserved Behavior` / `## Expected Outcome` (and the approved plan's requirements) is covered with a cited artifact or raised as an Acceptance Blocker; no silent omissions
|
|
8
8
|
- over-delivery — every surface the merged diff **adds** is traced back to a requirement. Enumerate them: each identifier, module, and configuration entry the diff introduces, searched for its callers across the whole repository (a declaration, its own test, or a commented-out line is not a caller). Record one `addedSurfaceAudit` row per surface with its disposition. `traced` names the brief requirement it serves. `exempt` names one of the legitimate exits and cites it — the approved plan reserves it for a named later stage, or something outside project code calls it (framework entrypoint, implemented interface method, migration hook, published-package API). `over-delivery` is everything else, and it is graded by callers: **no caller anywhere** is an Acceptance Blocker (delete it, or fold an added parameter back into its single call site), while **called but serving no requirement** is a Conditional Acceptance Condition with `blocksReleaseHandoff: false` — the judgement there rests on reading intent, so it travels to the PR body instead of stopping the release. The baseline is the brief, not the approved plan: a surface the plan authorised but no requirement asked for is still over-delivery, and this is the last gate that can see it. **Enforced:** `scripts/okstra_ctl/phases/final_verification/validation.py` `_validate_added_surface_audit` refuses a `traced` row naming no requirement, and an `over-delivery` row whose note does not cite the `AB-NNN` / `CA-NNN` row it became.
|
|
9
9
|
- delivered artifacts match recorded expected values in `reference-expectations` (config files, deployment manifests, other recorded expected states); when reference-expectations are absent, record it as missing information rather than assuming a match
|
|
10
|
-
- test & validation suite pass status — independently re-run the read-only two-tier command set
|
|
10
|
+
- test & validation suite pass status — independently re-run the read-only two-tier command set selected by the declaration-source rule below and confirm each passes on the verified head, citing exact command + exit code
|
|
11
11
|
- test correctness — delivered tests actually assert the intended behaviour: no gutted/weakened assertions, no tautological or always-passing tests, no tests exercising only mocks; new behaviour has matching coverage. For an `external-interface` / `transformation-mapping` surface specifically, treat a test whose only oracle is a self-authored synthetic fixture (no captured-real-sample provenance) as NOT establishing external correctness — it shows only that the parser agrees with its author's assumed shape, never that the shape matches reality; record that surface's external correctness as a user-owned external advisory gap (a Residual Risk carrying the exact "capture a real sample and confirm" next step, per the Coverage check in the self-review pass below), never as covered — the same non-blocking treatment the External QA advisory policy gives a live external check
|
|
12
12
|
- DB / IO / SQL real-execution evidence — trigger: the diff touches DB/IO/SQL (ORM / query-builder, `*.repository.*`, model / `migrations/**` / `*.sql`, or changed query strings). Then Validation Evidence MUST cite a real (or faithful-replica) DB execution — the `db-test` command + exit code — not a mock-only suite. Rationale: a mock-only suite cannot observe the SQL actually emitted (observed failure class: `prompts/profiles/_implementation-verifier.md` §"DB / IO / SQL change — real-execution gate"). A DB-touching change whose only evidence is mocked, or for which no `db-test` ran, is an **Acceptance Blocker** (`major`+; per the Verdict vocabulary below, any blocker moves the verdict off `accepted`). This gate stops an unverified DB change from reaching `release-handoff` and being pushed.
|
|
13
13
|
- **External Tier 3 de-duplication exception.** A DB/IO/SQL surface covered by an in-scope Tier 3 entry whose `requires` include `db`, `http`, or `external` is governed by the External QA outcome policy. Its non-PASS or unavailable result MUST NOT generate a second legacy db-test-not-configured or mock-only blocker solely for that same Tier 3 non-PASS or unavailable result. Tier 1 or Tier 2 failures remain blocking, and DB surfaces without declared external Tier 3 coverage remain blocking.
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
- **Evidence:** attach file:line, exact command + exit code, log excerpt, or MCP SELECT evidence to every finding. Mark a requirement as covered only when the cited artifact demonstrates it.
|
|
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
|
-
- **Tier 1 and Tier 2 read-only validation:** Tier 1 is the originating brief/approved plan `validation` set
|
|
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
36
|
- **External QA outcome policy:** continue to attempt every in-scope Tier 3
|
|
37
37
|
command. For an entry requiring `db`, `http`, or `external`, record non-PASS
|
|
38
38
|
as a Tier 3 `advisory` command, add a user-owned Residual Risk and exact
|
|
@@ -102,13 +102,21 @@ flowchart TD
|
|
|
102
102
|
SelfReview --> Persist[final report + manifests]
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
The validation command is never guessed automatically. When independent re-verification is needed, there are only two tiers of command source.
|
|
105
|
+
The validation command is never guessed automatically. When independent re-verification is needed, there are only two tiers of command source. The generated `worker_prompt_headers.py::verification_input_headers` instruction selects their declarations when frozen inputs are recorded; the legacy lookup supplies only what it leaves unfrozen.
|
|
106
|
+
|
|
107
|
+
This is a worker guideline, not command-execution evidence or an execution-log
|
|
108
|
+
validator. The named `model-io verification-input` projection validates the run
|
|
109
|
+
and snapshot before exposing frozen declarations as quoted scalar rows.
|
|
110
|
+
`test_verification_input_projection_rejects_invalid_input_before_output` checks
|
|
111
|
+
the read boundary. `tests/contract/test_docs_runtime_contract.py::test_qa_phase_sources_follow_frozen_input_headers`
|
|
112
|
+
checks instruction/spec alignment. Existing read-only execution, target scope,
|
|
113
|
+
independent QA and outcome policies remain in force.
|
|
106
114
|
|
|
107
115
|
```mermaid
|
|
108
116
|
flowchart LR
|
|
109
117
|
Need[needs validation command] --> Tier1{task brief / approved plan<br/>validation set?}
|
|
110
118
|
Tier1 -->|yes| Deny[Deny-list self-check]
|
|
111
|
-
Tier1 -->|no| Tier2{project
|
|
119
|
+
Tier1 -->|no| Tier2{Selected project baseline<br/>qaCommands?}
|
|
112
120
|
Tier2 -->|yes| Deny
|
|
113
121
|
Tier2 -->|no| Missing[record<br/>qa-command not configured]
|
|
114
122
|
Deny -->|clean| Run[execute read-only command]
|
|
@@ -99,8 +99,12 @@ def _added_surface_row_failures(
|
|
|
99
99
|
return []
|
|
100
100
|
|
|
101
101
|
|
|
102
|
-
def
|
|
103
|
-
rows
|
|
102
|
+
def acceptance_blocker_rows(data: Mapping) -> list[Mapping]:
|
|
103
|
+
"""The object rows of `acceptanceBlockers`; none when a container is mistyped."""
|
|
104
|
+
fv = data.get("finalVerification")
|
|
105
|
+
rows = fv.get("acceptanceBlockers") if isinstance(fv, Mapping) else None
|
|
106
|
+
if not isinstance(rows, list):
|
|
107
|
+
return []
|
|
104
108
|
return [row for row in rows if isinstance(row, Mapping)]
|
|
105
109
|
|
|
106
110
|
|
|
@@ -108,10 +112,9 @@ def _validate_defect_class_sweep(data: dict, failures: list[str]) -> None:
|
|
|
108
112
|
"""차단 사유마다 그것이 속한 결함 계열을 위치×경우 칸 단위로 훑었는지 본다.
|
|
109
113
|
|
|
110
114
|
위치 하나만 적은 차단 사유는 다음 run 이 같은 원리의 다른 위치나 다른 경우를
|
|
111
|
-
새로 찾게 만들었다.
|
|
112
|
-
드러났다(dev-11562 stage 1, 001-004).
|
|
115
|
+
새로 찾게 만들었다.
|
|
113
116
|
"""
|
|
114
|
-
for row in
|
|
117
|
+
for row in acceptance_blocker_rows(data):
|
|
115
118
|
row_id = str(row.get("id") or "<id 없음>")
|
|
116
119
|
defect_class = row.get("defectClass")
|
|
117
120
|
if not isinstance(defect_class, Mapping):
|
|
@@ -121,10 +124,15 @@ def _validate_defect_class_sweep(data: dict, failures: list[str]) -> None:
|
|
|
121
124
|
"and case that shares it before reporting the blocker."
|
|
122
125
|
)
|
|
123
126
|
continue
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
127
|
+
raw_cells = defect_class.get("cells")
|
|
128
|
+
if not isinstance(raw_cells, list):
|
|
129
|
+
failures.append(
|
|
130
|
+
f"final-verification: acceptance blocker {row_id} "
|
|
131
|
+
"`defectClass.cells` is not a list — record one cell per "
|
|
132
|
+
"location and case the mechanism reaches."
|
|
133
|
+
)
|
|
134
|
+
continue
|
|
135
|
+
cells = [cell for cell in raw_cells if isinstance(cell, Mapping)]
|
|
128
136
|
defective = [cell for cell in cells if cell.get("verdict") == "defective"]
|
|
129
137
|
if not defective:
|
|
130
138
|
failures.append(
|
|
@@ -164,14 +172,14 @@ def _validate_recurring_class_routing(data: dict, failures: list[str]) -> None:
|
|
|
164
172
|
"""이전 run 이 이미 막았던 계열은 한 지점 수정으로 다시 보내지 않고 재계획한다."""
|
|
165
173
|
recurring = [
|
|
166
174
|
str(row.get("id") or "<id 없음>")
|
|
167
|
-
for row in
|
|
175
|
+
for row in acceptance_blocker_rows(data)
|
|
168
176
|
if isinstance(row.get("defectClass"), Mapping)
|
|
169
177
|
and row["defectClass"].get("recurrence") == "recurring"
|
|
170
178
|
]
|
|
171
179
|
if not recurring:
|
|
172
180
|
return
|
|
173
181
|
routing = (data.get("finalVerification") or {}).get("routingRecommendation")
|
|
174
|
-
target = str(
|
|
182
|
+
target = str(routing.get("target") or "") if isinstance(routing, Mapping) else ""
|
|
175
183
|
if target not in _CLASS_REPLANNING_TARGETS:
|
|
176
184
|
failures.append(
|
|
177
185
|
f"final-verification: acceptance blockers {recurring} are "
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md
CHANGED
|
@@ -86,12 +86,12 @@ Changing a test's expected value is allowed here when the finding shows the orac
|
|
|
86
86
|
|
|
87
87
|
1. Record the stage HEAD as `<base>` (`git rev-parse HEAD` in the stage worktree).
|
|
88
88
|
2. Write the executor instruction with `okstra correction prompt --run-manifest <path> --round <N> --role executor --base <base> --stage-base <stage base> --finding <F-id> [--finding <F-id> ...]` into a file under the run's `state/`, then materialize it with `okstra agent-prompt materialize` — `--audience implementation-executor`, `--assignment-ref initial/<executor worker id>`, `--dispatch-kind correction-r<N>`, a new `--invocation-id` ending `-correction-r<N>-<executor worker id>`, and a result path `<executor worker id>-worker-correction-r<N>-implementation-<seq>.md`. Build a jobs file with `okstra agent-prompt jobs --dispatch-kind correction-r<N>`, dispatch it alone with `okstra team dispatch --jobs-file <path> --dispatch-kind correction-r<N>`, and settle it with `okstra team await`.
|
|
89
|
-
`--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the
|
|
89
|
+
`--stage-base` (the carry's `stageCommitRange.base`) adds a `FILE-SIZE:<path>` finding for each file the stage diff leaves over the 500-line limit, computed by `okstra correction file-size`; a `FILE-SIZE-ADVISORY:` line (the 300-line target) never opens or joins a round; a round may hold only those findings, and `findingIds` records them by that id. Leave out a convergence finding id that restates a `FILE-SIZE:` line, or the executor reads it twice.
|
|
90
90
|
3. Do the same for every verifier with `--role verifier`, `--audience implementation-verifier`, its own `initial/<verifier worker id>` assignment, and result `<verifier worker id>-worker-correction-r<N>-implementation-<seq>.md`; dispatch the verifiers in one batch without the executor.
|
|
91
91
|
4. Converge the re-verification results in round `<N>`'s own namespace, leaving the initial convergence as written. Run Phase 5.5 again with `correction-r<N>` before `<task-type>` in every state name: `okstra convergence prepare-groups --correction-round <N>` writes `convergence-groups-correction-r<N>-<task-type>-<seq>.json`; seed it with `--work-state …/convergence-work-correction-r<N>-<task-type>-<seq>.json` and `--final-state …/convergence-correction-r<N>-<task-type>-<seq>.json`; name round plans and results `convergence-round-<k>-plan-correction-r<N>-<task-type>-<seq>.json`. A reverify round in it passes `--correction-round <N>` to `reverify-prompt` and `collect-results`, materializes with `--invocation-id` ending `-correction-r<N>-reverify-r<k>-<worker id>`, and names its result `<worker id>-worker-correction-r<N>-reverify-r<k>-<task-type>-<seq>.md`. Never reseed the initial paths: a terminal final there is reused, and `--restart-from-round0` refuses it. Round `<N+1>`'s `okstra correction prompt` reads its findings from this round's final, and the report writer's synthesis packet carries it as `Convergence state (correction-r<N>)` beside the initial `Convergence state` (`report_synthesis_packet._source_specs`); report assembly projects it into `crossVerification.correctionRounds[]` and appends the evidence it promotes to `evidence.primary` with source `convergence correction-r<N>` (`report_assembly._correction_round_convergence`).
|
|
92
92
|
5. No re-verification verdict is `FAIL`: the round `result` is `pass` and the run continues to persistence with the post-fix head. Otherwise `result: fail`; start round `<N+1>` if the cap allows and the entry rules still hold, or end the run `FAIL`.
|
|
93
93
|
|
|
94
|
-
**Enforced:** `okstra convergence seed` (`scripts/okstra_ctl/convergence.py` `_seed`) accepts state paths only in the initial or a `correction-r<N>` namespace, refuses a round grouping before every grouped verifier returned an `ok` round `<N>` result (`convergence_provenance.missing_scope_results`), and checks its cited items against that round's results (`discovery_attempts` per namespace); `convergence_migration.decide_seed_action` refuses `--restart-from-round0` without an invalid working state; `plan-round` refuses to overwrite a round plan whose namespace already dispatched that round (`_refuse_dispatched_plan_overwrite`); `collect-results` reads only the namespace's reverify invocations (`correction_round.reverify_invocation_in_scope`). `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the
|
|
94
|
+
**Enforced:** `okstra convergence seed` (`scripts/okstra_ctl/convergence.py` `_seed`) accepts state paths only in the initial or a `correction-r<N>` namespace, refuses a round grouping before every grouped verifier returned an `ok` round `<N>` result (`convergence_provenance.missing_scope_results`), and checks its cited items against that round's results (`discovery_attempts` per namespace); `convergence_migration.decide_seed_action` refuses `--restart-from-round0` without an invalid working state; `plan-round` refuses to overwrite a round plan whose namespace already dispatched that round (`_refuse_dispatched_plan_overwrite`); `collect-results` reads only the namespace's reverify invocations (`correction_round.reverify_invocation_in_scope`). `scripts/okstra_ctl/dispatch_core.py` `_validate_correction_rounds` (via `correction_round.validate_correction_dispatch`) refuses a round past the cap, a verifier dispatch before that round's executor returned an `ok` result, a second executor fix in the same round, and round `<N+1>` before round `<N>` was re-verified. `validators/validate-run.py` `_validate_correction_rounds` (blocking) fails a report whose `correctionRounds` differ from the correction rounds the run dispatched, whose rounds are not 1, 2 in order, whose `result` contradicts its verdicts, or whose `verifierResults` are not the last round's verdicts. The entry rules are instructions only. `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range breaks the 500-line file-size limit and names the `--stage-base` to pass, so a size violation no verifier reported still reaches a correction round, or ends the run `FAIL` when no round is left.
|
|
95
95
|
|
|
96
96
|
## Self-review pass before finalising the report (the Okstra lead runs this; do not delegate it)
|
|
97
97
|
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md
CHANGED
|
@@ -9,6 +9,8 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
|
|
|
9
9
|
|
|
10
10
|
## Executor role binding (carried over from the thin core)
|
|
11
11
|
|
|
12
|
+
Follow the `**Verification inputs:**` declaration-source rule when that header is present. References to project `qaCommands` in this sidecar mean the baseline selected by that rule. The legacy lookup uses the existing plan and project baseline only where no frozen declaration replaces them.
|
|
13
|
+
|
|
12
14
|
- **Moving dependency bases:** never run `git merge <predecessor>` or merge an old origin branch into this stage to update its base. Runtime preparation rebases downstream stages in dependency order through `okstra_ctl.stage_rebase`; a predecessor moving during execution requires stopping and re-entering preparation after the current stage claim is released. Do not rewrite another active stage or repair registry/ledger SHAs by hand. Enforcement of preparation ordering and conflict recovery is covered by `tests/worktree/test_stage_rebase.py`.
|
|
13
15
|
- The `Executor` (bound in `implementation.md` thin core) is the **only worker permitted to mutate project files**. All other workers run read-only. A `runner=native-session` executor uses the selected host adapter's native edit and command primitives. A `runner=cli-wrapper` executor mutates files inside its provider CLI's auto-edit mode. The safety rules in this sidecar apply identically to both runners.
|
|
14
16
|
- When the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files. If a file outside the worktree is genuinely needed, treat it as a planning gap: record it in `Out-of-plan edits` and continue.
|
|
@@ -52,7 +54,7 @@ template's check; that template is gone.
|
|
|
52
54
|
- **External-source adapters — structure AND fixture both derive from a captured real sample; a self-authored fixture is NOT reality evidence:** when this run's diff builds or changes an `external-interface` or `transformation-mapping` surface (an HTTP / network client, or a parser / mapper of a third-party payload — HTML / JSON / XML / CSV originating outside this repo), the adapter's structural assumptions (selectors, field paths, expected response shape) AND the static fixture / golden that tests them MUST BOTH derive from a **captured real sample** of that payload — the capture cited in the stage's `external-interface` / `transformation-mapping` design-prep item, or one captured this run and recorded with its `source` + capture time. The captured sample is a static fixture (no live socket), so a parser test against it stays in source like any unit test — the Real-IO isolation rule below governs *live* calls, not the captured bytes. Do NOT hand-invent the shape and then hand-write a fixture that agrees with it: the passing test then only proves the code matches your assumption, never that the assumption matches reality (self-confirming oracle — the observed failure was a parser whose selectors existed in its synthetic fixture and in zero real pages: hundreds of green units over a fiction, and the whole structure built on the wrong shape). When no real sample is reachable (no network this run, or the brief supplied none), do NOT synthesize a stand-in and present its green tests as correctness: mark the adapter's shape `reality-unverified (no captured sample)` in `Validation evidence`, keep any placeholder fixture explicitly labelled an assumption (never validation evidence), and surface an explicit **user-owned** item in the routing recommendation to confirm against real data. Unlike the DB gate above this does NOT itself block acceptance — live external verification stays a user-owned item per `final-verification`'s External QA advisory policy — but a synthetic external fixture presented as reality-verified is exactly the mock-only external evidence the `final-verification` test-correctness pass is meant to reject.
|
|
53
55
|
- **Real-IO test isolation (BLOCKING).** A test that exercises a **real** datastore, HTTP endpoint, external service, message queue, or filesystem — a live DB connection / DSN, a real `fetch` / `axios` / `http` request, an actual S3 / queue client, anything the project's normal CI test suite cannot run because that backend is absent — MUST be written under the task's qa scripts directory `<task_root>/qa/scripts/` (`<TASK_QA_PATH>/scripts`; the `qa/` root itself holds only data sidecars — the Tier 3 conformance manifest and `result-*.json`). It MUST NOT be written into the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, or anywhere the project's lint/test globs collect. Two reasons: (a) the project's CI / normal suite has no real DB or network, so a real-IO test placed in source silently breaks the pipeline; (b) it is an okstra verification artifact, and the artifact-home rule confines okstra outputs to `.okstra/`. **The dividing line is the IO, not the intent:** a unit test that stubs/spies only *injected collaborators* (mock — no real socket, no real DB handle) is a TDD red-green artifact and stays in source; the moment a test opens a real connection or makes a real network call it belongs in qa. A stage's real-IO requirement check is a Tier 3 conformance script under `<task_root>/qa/scripts/` (declared via the implementation-planning conformance entry) — never smuggle real IO into a `*.spec.*` in source to make it run "as a unit test". The `db-test` real-execution gate above is satisfied by the conformance/db-test path against the replica, NOT by adding a live-DB `*.spec.*` to the project suite. **Author qa specs with the project's own test framework — never hand-roll `describe`/`it`/`expect`.** When the project ships a test runner as a devDependency (jest / vitest / pytest …), the qa spec uses it, invoked with the project config plus a discovery override pointing at the qa scripts dir (jest: `npx jest --config <project jest config> --roots <task_root>/qa/scripts --runInBand <spec-name>`) — the project config keeps module aliases resolving while the default sweep never collects the file; never widen the project's own test config to include qa paths. For TypeScript qa specs also write `<task_root>/qa/scripts/tsconfig.json` (`extends` the project tsconfig, adds the runner's `types` entry, `"include": ["**/*.ts"]`) so editors resolve path aliases and test globals — it is a qa artifact like the rest (untracked). **These qa artifacts stay untracked — never commit them.** `.okstra/**` is gitignored (the artifact-home rule); conformance scripts and their results are *executed* and recorded in the carry sidecar / verifier result, never written into git history. A committed `.okstra/qa` file is a stage-branch defect that leaks okstra internals into the eventual PR (see the `git add` rules below).
|
|
54
56
|
- **Stage conformance script (BLOCKING when the approved plan declared `Conformance tests:`).** Planning only declared the path and `requires`. This run MUST write the script to that path under `<task_root>/qa/scripts/` and add the matching `<task_root>/qa/conformance-manifest.json` entry: `stageKey` (= `<task-id>-stage-<N>`), `script`, `runCommand`, `requirementIds`, `requires` (the set the plan declared, widened by any db/io/http/external surface this stage's diff touches that the plan left out — never narrowed; `validate-run.py` `_declared_conformance_errors` accepts a superset and rejects a subset), `passContract`, `exemption: null`, `waiver: null`. Do not skip this when the plan declared tests. If the plan declared `Conformance exemption:`, do not invent a script — with one exception: when this stage's diff touches a db/io/http/external surface the exemption promised it would not (the verifier's diff-surface cross-check names the surface), write the script and the manifest entry for this stage exactly as for a declared stage, with `requires` covering those surfaces. The approved plan is not rewritten; `validate-run.py` `_declared_conformance_errors` accepts an entry for a stage the plan exempted and still rejects one for a stage the plan does not have. The script's standard interface: a `main` that exits `0`=PASS / non-zero=FAIL, and whose stdout ends with `QA-RESULT: PASS|FAIL` followed by one `REQ <id>: PASS|FAIL: <reason>` line per requirement. The verifier runs `runCommand` from the **worktree cwd**, and that cwd is the tree under test. `runCommand` MUST NOT repoint it: a leading `cd <checkout> &&` sends the script at a tree without this stage's changes. Absolute paths are fine and usually necessary — the script and its `tsconfig` live under `<task_root>/qa/scripts/`, i.e. under `.okstra/`, and a worktree does not carry `.okstra/`. Point at those by absolute path; leave the cwd alone. **Enforced:** `scripts/okstra_ctl/conformance.py` `_check_entry` rejects a `runCommand` whose first word in any `&&` / `;` segment changes directory; `validators/validate-run.py` `_validate_conformance` fails the run if the inherited declaration has no script file.
|
|
55
|
-
- read the stage extract at this prompt's `**Approved plan stage extract:**` anchor end-to-end. It is the approved plan projected onto this run's stage: the whole Stage Map (`stageMap`), this stage's entry, the requirement-coverage
|
|
57
|
+
- read the stage extract at this prompt's `**Approved plan stage extract:**` anchor end-to-end. It is the approved plan projected onto this run's stage: the whole Stage Map (`stageMap`), this stage's entry, the requirement-coverage and validation rows that name this stage, name no stage, or are cited by this stage's entry, every rollback and risk row, each of these with the `planItemId` (`P-Val-4`, `P-Rb-2`) directives cite it by, and the clarification items. Its `omitted` object names everything left out and why. The plan at the `**Approved plan:**` anchor stays the source of record: open it only for a targeted lookup of a key the extract omits, never end-to-end. When the prompt has no extract anchor (a Markdown plan, or a prompt published before the extract existed), read the approved plan end-to-end and parse its Stage Map instead. Read this prompt's `**Stage for this implementation run:**` anchor: the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`. Both anchors are generated headers; when either is missing, stop and report `contract-violated` rather than inferring the value.
|
|
56
58
|
- load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(this stage)` and inject them into the executor's working context as "runtime carry-in". For a `depends-on (none)` stage, no sidecar load — task-brief only.
|
|
57
59
|
- this stage's `depends-on` are all already `status:done`. Its file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope.
|
|
58
60
|
- **Clarification answers carried in (read before the first edit):** when the user answered the approved plan's `## 1. Clarification Items` rows, those answers arrive with this prompt under the heading `# Clarification answers carried in (authoritative)`, or as the `Clarification response` path under `## Inputs`. Treat each answer as an authoritative refinement of the plan's scope for the matching row; an answer that contradicts or expands the approved scope beyond the plan is a re-plan trigger (route to a new `implementation-planning` run), not a silent in-run change.
|
|
@@ -92,7 +94,7 @@ template's check; that template is gone.
|
|
|
92
94
|
The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
|
|
93
95
|
- **Verifier gates are not yours to run (BLOCKING).** The self-mock detector (`validators/detect_self_mock.py`) belongs to the implementation verifier and is never delegated to you (`_implementation-verifier.md` §"Self-mock detection"). The coding-conventions preflight names it as the enforcement behind the no-self-mocking principle — that names who will check your diff, not a command for you to run. You MUST NOT invoke it and MUST NOT write `<task_root>/qa/self-mock-*.json`; running it early does not pre-satisfy the gate, because the verifier runs it again under its own duty. **Enforced:** that sidecar is not among the paths your attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so the write audit closes the attempt as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`) — a stage whose every gate passed still lands as a failed run. The same holds for the conformance results `<task_root>/qa/result-*.json`: you may run a conformance script to check your work — a baseline capture or `--compare` target goes under `<task_root>/qa/baseline/` and anything else it writes (build logs, measurements) under `<task_root>/qa/output/`, the only qa directories besides `qa/scripts/` your attempt may write — but the verifier records every result, including an earlier stage's result that your rewrite of its script made stale. When the approved plan tells you to write one, leave it and name it in your result as a plan step the verifier owns.
|
|
94
96
|
- **An external Tier 3 non-PASS does NOT withhold the carry evidence.** A Tier 3 entry whose `requires` include `http`, `external`, or `db` is advisory. Its FAIL, MISSING, no result, startup failure, or credential / network / service absence gets recorded honestly — exact command, exit code, output tail, marked `ADVISORY` in `Validation evidence` — and you emit the carry evidence anyway. Only Tier 1 and Tier 2 failures withhold it. Withholding on an external result is what actually blocks the stage: the carry file is the only thing that can mark a stage `done`, the verifier re-runs that same command from the host (where a call your sandbox could not complete often passes), and a stage the verifier then PASSes can never be closed because its evidence was never written.
|
|
95
|
-
- **File size: aim for 300 lines, never
|
|
97
|
+
- **File size: aim for 300 lines, never take a file past 500 (BLOCKING at 500).** The 500 limit is broken by a new file over it or an existing file taken from 500 or fewer past it; the 300 target is broken those two ways and by a file already over it that grows by any net line, including a file already over 500 at the stage base. Lines are physical lines. Breaking 500 is a blocking finding; breaking only 300 is an advisory recommendation the verifiers record. Put a new responsibility — a group of functions, a class, a `describe` block — in a new module or test file beside the existing one instead of appending, and when a file would pass 500, split it by responsibility; never compress code or drop comments to meet the number. Lockfiles, data (JSON / YAML), Markdown, fixtures, snapshots, generated and vendored files are exempt, as are languages okstra has no coding preflight for. Check with `okstra correction file-size --base <stage-base>` before you emit the carry evidence; it writes nothing, so you may run it. **Enforced:** every verifier runs the same command and reports each `FILE-SIZE:` line (500) as a blocking finding and each `FILE-SIZE-ADVISORY:` line (300) as a recommendation, and `okstra stage-done` (`scripts/okstra_ctl/stage_done.py` `_check_file_size`) refuses to settle a stage whose carry range still breaks 500, so the stage goes to a correction round.
|
|
96
98
|
- **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. The terminal row belongs to the lead's post-stage persistence and is verdict-gated — `status:"done"` with `carry_path` on a non-`FAIL` verdict, `status:"failed"` on `FAIL` (`_implementation-deliverable.md` §"Lead post-stage persistence").
|
|
97
99
|
- **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.
|
|
98
100
|
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md
CHANGED
|
@@ -17,7 +17,7 @@ fails, fix it or surface the violation — do not claim done on a failing item.
|
|
|
17
17
|
|
|
18
18
|
- diff-review done: the `Pre-commit diff review sweep` ran over the full diff and its `Coverage:` footer is in your audit sidecar — every changed file named, with each applied rule set carrying its outcome (`clean` or `fixed <n>`). No footer, or entries with no outcome → the sweep is unfinished; do not claim done.
|
|
19
19
|
- functions: every new/edited function ≤50 effective lines, single purpose — cite the longest function's actual line count, not "all under 50"
|
|
20
|
-
- file size: no source or test file this diff adds
|
|
20
|
+
- file size: no source or test file this diff adds ends over 500 physical lines, and no file at 500 or fewer at the stage base ends over 500 (a file already over 500 may grow; that is advisory) — paste the output of `okstra correction file-size --base <stage-base>`; it must end `QA-RESULT: PASS`. Aim for 300: for each `FILE-SIZE-ADVISORY:` line it prints, split the file or say why not. A responsibility that would push a file over goes into its own new module or test file
|
|
21
21
|
- conventions: applied the routed pack + project patterns (name which ones)
|
|
22
22
|
- names & comments: names say what, comments say why; no obvious-restatement comments; no truthful-name violations
|
|
23
23
|
- verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"
|