okstra 0.227.0 → 0.228.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 +1 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +15 -3
- package/docs/project-structure-overview.md +12 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/coding-preflight/clean-code.md +24 -18
- package/runtime/prompts/coding-preflight/overview.md +6 -6
- 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 +1 -1
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
- 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 +11 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +46 -10
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- 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-executor.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
- 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/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/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/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +108 -5
- 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/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_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 +39 -45
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- 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
|
@@ -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-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.
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md
CHANGED
|
@@ -29,7 +29,9 @@ A target mismatch or changed fingerprint invalidates this check's evidence. Reco
|
|
|
29
29
|
|
|
30
30
|
### Two-tier command lookup (NO auto-detection)
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
Follow the `**Verification inputs:**` declaration-source rule when that header is present. References to project `qaCommands` throughout this sidecar, including the DB gate, mean the baseline selected by that rule. The legacy lookup below supplies only the sources that rule leaves unfrozen. A missing or unreadable referenced snapshot is missing verification input, not permission to substitute current settings.
|
|
33
|
+
|
|
34
|
+
The legacy lookup obtains the QA command set from two declared sources, in order — there is **no fallback to guessing tools from manifest files**.
|
|
33
35
|
|
|
34
36
|
1. **Tier 1 — plan validation set (task-specific):** every command listed under the approved plan's `validation` block (pre / mid / post). The plan is the file at this prompt's `**Approved plan:**` anchor, scoped to the stage its `**Stage for this implementation run:**` anchor names; both are generated headers, so a missing one is `contract-violated`, never a value to infer. Each checklist row also carries `phase`, and the phase is part of what the row asserts: `pre` runs before the stage edits, `mid` between the edits and the stage commit, `post` after the commit. A `mid` diff-scope check (`git diff --name-only` listing the touched paths) is reproduced over the stage range — `git diff --name-only <stage base>...HEAD` — once the stage has committed; its empty output on the clean post-commit tree is the plan's own step order, not a divergence. A `Discrepancy` that cites a checklist row names the row and its phase as `VC-NNN (phase: mid)`; a verifier that reads the command without the phase has read half the row. **Enforced:** `_validate_verifier_discrepancy_names_checklist_phase` in `validators/validate-run.py` fails a divergence that cites a `VC-` row without that row's phase.
|
|
35
37
|
2. **Tier 2 — project baseline:** the project's standing QA baseline from the `Project QA Commands` section emitted by `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names).
|
|
@@ -130,6 +130,20 @@ These outcomes are enforced by
|
|
|
130
130
|
|
|
131
131
|
## 4. executor and verifier
|
|
132
132
|
|
|
133
|
+
The generated `worker_prompt_headers.py::verification_input_headers` instruction
|
|
134
|
+
owns declaration-source selection when the run records frozen inputs. The
|
|
135
|
+
verifier follows it before the legacy lookup throughout its sidecar, including
|
|
136
|
+
the DB gate. The named `model-io verification-input` projection validates run
|
|
137
|
+
ownership, snapshot schema, cross-field constraints and digest before exposing
|
|
138
|
+
frozen scalar fields. Quoted strings preserve command and procedure characters.
|
|
139
|
+
`test_verification_input_projection_rejects_invalid_input_before_output` checks
|
|
140
|
+
the read boundary. Snapshot references
|
|
141
|
+
are not command-execution evidence; stage scope, checklist timing and independent
|
|
142
|
+
QA ownership remain in force. This is a worker guideline, not an execution-log
|
|
143
|
+
validator. `tests/contract/test_docs_runtime_contract.py::test_qa_phase_sources_follow_frozen_input_headers`
|
|
144
|
+
checks instruction/spec alignment, and the header and recovery tests cover the
|
|
145
|
+
generated reference contract.
|
|
146
|
+
|
|
133
147
|
```mermaid
|
|
134
148
|
flowchart TD
|
|
135
149
|
Lead[Okstra lead<br/>host native] --> Exec[Executor<br/>selected provider]
|
|
@@ -55,7 +55,8 @@ def requirement_instructions(original_requirement_ids: Sequence[str], participat
|
|
|
55
55
|
"`feasible`, `safetyBlockers` is empty, and every "
|
|
56
56
|
"`unresolvedFeasibilityFacts` entry is a `deferred-gate` fact that names "
|
|
57
57
|
"its `gate`. A candidate whose `splitAcceptance.clarificationRef` names "
|
|
58
|
-
"the user's `accept-risk` answer to
|
|
58
|
+
"the user's `accept-risk` answer to that candidate's own split needs one "
|
|
59
|
+
"`feasible` vote, "
|
|
59
60
|
"and its remaining facts stay on the row as the accepted risk; never set "
|
|
60
61
|
"`splitAcceptance` before that answer is recorded.",
|
|
61
62
|
("Classify each `unresolvedFeasibilityFacts` entry with `resolutionKind`: "
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
- **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --task-manifest <taskManifestPath> --narrative <report writer narrative>` before assembly. For each analyser it names, dispatch one vote-completion assignment asking for that analyser's own feasibility verdict, rationale, and counterevidence on the named candidate — no new candidate, so the run stays in `candidate-comparison` mode. The command reports no gap when a vote cannot settle the block (safety blockers, unresolved feasibility facts, too few feasible verdicts); that is the honest `blocked`.
|
|
29
29
|
- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
|
|
30
30
|
- Classify every `unresolvedFeasibilityFacts` entry with `resolutionKind`: `user-decision` requires nonempty `clarificationRefs` naming the actual C-NNN records for that fact; `technical-verification` requires source review, design evidence, or experiments and does not require a user question. `deferred-gate` marks a fact that no technical-verification run can close because closing it needs something that phase forbids, such as a deployed environment (for example, a cold-start measurement of a deployed Lambda); it requires `gate`, naming where the fact closes (a brief `External Gates` entry, or final-verification user-owned external QA), and it does not make the candidate invalid. A fact that a probe, a source read, or a disposable local service can close is `technical-verification`, not `deferred-gate`. The selected direction snapshot carries every remaining fact of the chosen option as `deferredFeasibilityFacts`, so planning schedules its gate. Enforced by `blocking_feasibility_facts` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`. Preserve `fact`, `whyItMatters`, and `evidence`. Reuse answered questions and their recorded dispositions; never reopen one merely to save the report. An unrelated open question does not satisfy a missing reference. Historical unclassified entries remain readable, but blocked report reassembly requires the writer to classify them explicitly. Enforced by `validate_blocked_answer_channel` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`. Saving preserves `routing: blocked` and does not make a candidate valid. In `humanSummary.actions`, `verdictCard.nextStep`, and selection guidance, distinguish pending user decisions from remaining technical verification; after the pilot route is answered, carry the selected route and remove the old answer-waiting instruction.
|
|
31
|
-
- **A split vote ends in a user decision, not another run.** When no candidate is valid only because its votes split (at least one `feasible`, the others `uncertain` or `not-feasible`, no `safetyBlockers`), another option-selection or technical-verification run asks the same designers the same question and returns the same split (fontradar dev-11562: three runs, `feasible` against `uncertain` each time). Before you route `blocked` or `technical-verification` on such a candidate, open one approval decision for it with `okstra approval-decision open --ledger <approvalDecisionsPath>` (classification `noncritical-dissent`): the recommended option is `accept-risk` (proceed with this direction and carry the dissent and the remaining facts into planning), the alternative is `request-revision` (keep the run blocked). Ask the user in-session; record the answer with `okstra approval-decision resolve`. On `accept-risk`, the writer sets `splitAcceptance.clarificationRef` on that candidate, which makes it valid with one `feasible` vote; it then follows the ordinary routing (`implementation-planning` for a validated preselected direction, `pending-direction-selection` in `candidate-comparison`). Leave the votes and facts on the row. When the user is not present, publish the report `blocked` with that approval row open; the next run carries the answer. Enforced by `validate_split_acceptance` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`.
|
|
31
|
+
- **A split vote ends in a user decision, not another run.** When no candidate is valid only because its votes split (at least one `feasible`, the others `uncertain` or `not-feasible`, no `safetyBlockers`), another option-selection or technical-verification run asks the same designers the same question and returns the same split (fontradar dev-11562: three runs, `feasible` against `uncertain` each time). Before you route `blocked` or `technical-verification` on such a candidate, open one approval decision for it with `okstra approval-decision open --ledger <approvalDecisionsPath> --candidate-ref <IO-NNN>` naming that candidate (classification `noncritical-dissent`): the recommended option is `accept-risk` (proceed with this direction and carry the dissent and the remaining facts into planning), the alternative is `request-revision` (keep the run blocked). Ask the user in-session; record the answer with `okstra approval-decision resolve`. On `accept-risk`, the writer sets `splitAcceptance.clarificationRef` on that candidate, which makes it valid with one `feasible` vote; it then follows the ordinary routing (`implementation-planning` for a validated preselected direction, `pending-direction-selection` in `candidate-comparison`). Leave the votes and facts on the row. The answer accepts that candidate only; no other candidate cites it. When the user is not present, publish the report `blocked` with that approval row open; the next run carries the answer. Enforced by `validate_split_acceptance` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`.
|
|
32
32
|
{{INCLUDE:_clarification-recommendation.md}}
|
|
33
33
|
- Cross-verification mode:
|
|
34
34
|
- Phase 5.5 convergence runs in adversarial mode (`convergence.adversarial=true`).
|
|
@@ -7,7 +7,7 @@ import json
|
|
|
7
7
|
import re
|
|
8
8
|
from collections import Counter
|
|
9
9
|
from dataclasses import dataclass
|
|
10
|
-
from collections.abc import Mapping, Sequence
|
|
10
|
+
from collections.abc import Iterator, Mapping, Sequence
|
|
11
11
|
from typing import Any
|
|
12
12
|
|
|
13
13
|
from okstra_ctl.clarification_items.dispositions import (
|
|
@@ -269,6 +269,30 @@ def blocking_feasibility_facts(option: Mapping[str, object]) -> list[object]:
|
|
|
269
269
|
]
|
|
270
270
|
|
|
271
271
|
|
|
272
|
+
def _required_feasible_votes_for(
|
|
273
|
+
option: Mapping[str, object], participating_analysers: Sequence[str],
|
|
274
|
+
) -> int:
|
|
275
|
+
# 갈린 표는 같은 분석자들에게 다시 물어도 갈린다. 사용자가 위험 감수로
|
|
276
|
+
# 받아들인 후보는 `feasible` 한 표로 충분하다 — 방향을 낸 근거가 있어야
|
|
277
|
+
# 받아들일 대상이 있다.
|
|
278
|
+
if split_acceptance_ref(option):
|
|
279
|
+
return 1
|
|
280
|
+
return required_feasible_votes(participating_analysers)
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
def _ungated_deferred_fact_errors(
|
|
284
|
+
option_id: str, option: Mapping[str, object],
|
|
285
|
+
) -> list[str]:
|
|
286
|
+
return [
|
|
287
|
+
f"{option_id} unresolvedFeasibilityFacts[{index}]: a "
|
|
288
|
+
f"{DEFERRED_GATE_KIND} fact must name the gate that closes it"
|
|
289
|
+
for index, fact in enumerate(option.get("unresolvedFeasibilityFacts") or ())
|
|
290
|
+
if isinstance(fact, Mapping)
|
|
291
|
+
and fact.get("resolutionKind") == DEFERRED_GATE_KIND
|
|
292
|
+
and not _is_deferred_gate_fact(fact)
|
|
293
|
+
]
|
|
294
|
+
|
|
295
|
+
|
|
272
296
|
def _validate_option_feasibility(
|
|
273
297
|
option: Mapping[str, object],
|
|
274
298
|
participating_analysers: Sequence[str],
|
|
@@ -291,11 +315,7 @@ def _validate_option_feasibility(
|
|
|
291
315
|
isinstance(vote, Mapping) and vote.get("verdict") == "feasible"
|
|
292
316
|
for vote in votes
|
|
293
317
|
)
|
|
294
|
-
|
|
295
|
-
# 받아들인 후보는 `feasible` 한 표로 충분하다 — 방향을 낸 근거가 있어야
|
|
296
|
-
# 받아들일 대상이 있다.
|
|
297
|
-
accepted = bool(split_acceptance_ref(option))
|
|
298
|
-
required = 1 if accepted else required_feasible_votes(participating_analysers)
|
|
318
|
+
required = _required_feasible_votes_for(option, participating_analysers)
|
|
299
319
|
if require_valid and feasible < required:
|
|
300
320
|
errors.append(
|
|
301
321
|
f"{option_id} must have at least {required} feasible vote(s); a split "
|
|
@@ -311,16 +331,7 @@ def _validate_option_feasibility(
|
|
|
311
331
|
f"{DEFERRED_GATE_KIND} facts that name their gate, or accepted through "
|
|
312
332
|
"splitAcceptance"
|
|
313
333
|
)
|
|
314
|
-
|
|
315
|
-
if (
|
|
316
|
-
isinstance(fact, Mapping)
|
|
317
|
-
and fact.get("resolutionKind") == DEFERRED_GATE_KIND
|
|
318
|
-
and not _is_deferred_gate_fact(fact)
|
|
319
|
-
):
|
|
320
|
-
errors.append(
|
|
321
|
-
f"{option_id} unresolvedFeasibilityFacts[{index}]: a "
|
|
322
|
-
f"{DEFERRED_GATE_KIND} fact must name the gate that closes it"
|
|
323
|
-
)
|
|
334
|
+
errors.extend(_ungated_deferred_fact_errors(option_id, option))
|
|
324
335
|
copied = _copied_votes(votes)
|
|
325
336
|
for first, second in copied:
|
|
326
337
|
errors.append(
|
|
@@ -447,6 +458,15 @@ class VoteGap:
|
|
|
447
458
|
feasible_votes: int
|
|
448
459
|
|
|
449
460
|
|
|
461
|
+
def selection_candidates(
|
|
462
|
+
selection: Mapping[str, object],
|
|
463
|
+
) -> Iterator[Mapping[str, object]]:
|
|
464
|
+
for key in ("rankedOptions", "candidateAudit"):
|
|
465
|
+
for row in selection.get(key) or ():
|
|
466
|
+
if isinstance(row, Mapping):
|
|
467
|
+
yield row
|
|
468
|
+
|
|
469
|
+
|
|
450
470
|
def vote_gaps(
|
|
451
471
|
selection: Mapping[str, object],
|
|
452
472
|
participating_analysers: Sequence[str],
|
|
@@ -460,20 +480,15 @@ def vote_gaps(
|
|
|
460
480
|
IO-001·IO-002·IO-003 이 각각 `feasible` 2표를 받고도 빠진 분석자가 하나씩
|
|
461
481
|
달라 전부 탈락했고, 그 run 은 후보 0건으로 차단됐다.
|
|
462
482
|
|
|
463
|
-
여기서 세는 것은 **표만 모자란** 후보다. `safetyBlockers
|
|
464
|
-
`
|
|
465
|
-
|
|
483
|
+
여기서 세는 것은 **표만 모자란** 후보다. A candidate with `safetyBlockers`,
|
|
484
|
+
blocking facts (`blocking_feasibility_facts`), or copied votes is excluded,
|
|
485
|
+
because more votes would not make it valid. 남은 표를 다 받아도 `feasible` 이
|
|
466
486
|
`required_feasible_votes` 에 못 미치는 후보도 제외한다 — 부쳐 봐야 결과가
|
|
467
487
|
같다.
|
|
468
488
|
"""
|
|
469
489
|
roster = list(dict.fromkeys(str(name) for name in participating_analysers))
|
|
470
490
|
gaps: list[VoteGap] = []
|
|
471
|
-
for candidate in (
|
|
472
|
-
row
|
|
473
|
-
for key in ("rankedOptions", "candidateAudit")
|
|
474
|
-
for row in (selection.get(key) or ())
|
|
475
|
-
if isinstance(row, Mapping)
|
|
476
|
-
):
|
|
491
|
+
for candidate in selection_candidates(selection):
|
|
477
492
|
if candidate.get("safetyBlockers") or blocking_feasibility_facts(candidate):
|
|
478
493
|
continue
|
|
479
494
|
votes = candidate.get("feasibilityVotes") or ()
|
|
@@ -535,10 +550,7 @@ def validate_blocked_answer_channel(
|
|
|
535
550
|
)
|
|
536
551
|
}
|
|
537
552
|
errors: list[str] = []
|
|
538
|
-
for candidate in (
|
|
539
|
-
row for key in ("rankedOptions", "candidateAudit")
|
|
540
|
-
for row in (selection.get(key) or ()) if isinstance(row, Mapping)
|
|
541
|
-
):
|
|
553
|
+
for candidate in selection_candidates(selection):
|
|
542
554
|
for index, fact in enumerate(candidate.get("unresolvedFeasibilityFacts") or ()):
|
|
543
555
|
label = f"{candidate.get('id')} unresolvedFeasibilityFacts[{index}]"
|
|
544
556
|
if not isinstance(fact, Mapping):
|
|
@@ -571,6 +583,9 @@ def validate_split_acceptance(report_data: Mapping[str, object]) -> list[str]:
|
|
|
571
583
|
서술 검증(`validate_implementation_option_selection`)은 clarification 행을
|
|
572
584
|
보지 못한다. 리드 원장이 합쳐진 뒤에만 이 인용이 실제 `accept-risk` 답인지
|
|
573
585
|
알 수 있으므로 조립과 `validate-run.py` 가 이 함수를 따로 부른다.
|
|
586
|
+
|
|
587
|
+
The cited row must name the citing candidate in `candidateRef`: the user's
|
|
588
|
+
answer accepts the risk of one direction, not of every candidate that cites it.
|
|
574
589
|
"""
|
|
575
590
|
selection = report_data.get("implementationOptionSelection")
|
|
576
591
|
if not isinstance(selection, Mapping):
|
|
@@ -581,26 +596,27 @@ def validate_split_acceptance(report_data: Mapping[str, object]) -> list[str]:
|
|
|
581
596
|
if isinstance(row, Mapping)
|
|
582
597
|
}
|
|
583
598
|
errors: list[str] = []
|
|
584
|
-
for candidate in (
|
|
585
|
-
row for key in ("rankedOptions", "candidateAudit")
|
|
586
|
-
for row in (selection.get(key) or ()) if isinstance(row, Mapping)
|
|
587
|
-
):
|
|
599
|
+
for candidate in selection_candidates(selection):
|
|
588
600
|
ref = split_acceptance_ref(candidate)
|
|
589
601
|
if not ref and "splitAcceptance" not in candidate:
|
|
590
602
|
continue
|
|
603
|
+
candidate_id = candidate.get("id")
|
|
591
604
|
row = rows.get(ref)
|
|
592
605
|
if (
|
|
593
606
|
row is None
|
|
594
607
|
or str(row.get("blocks") or "").strip().lower() != "approval"
|
|
595
608
|
or str(row.get("status") or "").strip().lower() == "obsolete"
|
|
596
609
|
or clarification_disposition(row) != SPLIT_ACCEPTANCE_DISPOSITION
|
|
610
|
+
or row.get("candidateRef") != candidate_id
|
|
597
611
|
):
|
|
598
612
|
errors.append(
|
|
599
|
-
f"{
|
|
600
|
-
"`blocks: approval` clarification
|
|
613
|
+
f"{candidate_id} splitAcceptance {ref!r} must name a "
|
|
614
|
+
f"`blocks: approval` clarification opened for {candidate_id} "
|
|
615
|
+
f"(`candidateRef: {candidate_id}`) that the user answered with "
|
|
601
616
|
f"`{SPLIT_ACCEPTANCE_DISPOSITION}`; open it with `okstra "
|
|
602
|
-
"approval-decision open --ledger <approvalDecisionsPath
|
|
603
|
-
"the answer with `okstra
|
|
617
|
+
"approval-decision open --ledger <approvalDecisionsPath> "
|
|
618
|
+
f"--candidate-ref {candidate_id}`, record the answer with `okstra "
|
|
619
|
+
"approval-decision resolve`, then reassemble"
|
|
604
620
|
)
|
|
605
621
|
return errors
|
|
606
622
|
|
|
@@ -148,7 +148,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
148
148
|
**Pick the cases by distinct outcome, not by line coverage.** When the stage writes or reconciles state, its meaningfully different outcomes are usually more than three — normal success, target already in the desired state (resume), existing data reused rather than created, a conflicting concurrent state, target absent, and mid-way failure with rollback. Enumerate the ones this stage actually implements and route them across the three lines (the `boundary` line is where resume / already-done / reuse belongs; `failure` carries conflict, absence, and rollback), naming each in the cell rather than collapsing them into "edge input". An implemented outcome with no declared case is a coverage gap the executor will not backfill.
|
|
149
149
|
- **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
|
|
150
150
|
- `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
|
|
151
|
-
- `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** **File size:** the implementation run aims for 300 physical lines per source and test file and enforces 500 — a new file over 500 and an existing file taken from 500 or fewer past 500 are blocking findings the executor must split in a correction round; a file already over 500 that grows is advisory, as is a new, crossing or growing file over 300. When a step would add code or tests to a file near or over 300 lines (`wc -l`), plan a new module or test file for that responsibility in `plannedPaths` instead of appending to the existing one. **Enforced at implementation:** `okstra correction file-size` (`scripts/okstra_ctl/file_size_cap.py`), re-run by `okstra stage-done`. A plan does not say how many lines a step adds, so planning cannot apply the limit; instead `okstra plan-items prepare`, correction preflight (`check-corrections`) and the plan verifier prompt report one `File-size headroom` line per existing source or test file the plan's `plannedPaths` name that has more than 300 and at most 500 lines, with the lines left before 500 and every stage that writes it (`file_size_cap.planned_file_headroom`). The report is information for the plan's readers: it never blocks, and it is not a verdict criterion or a reason for a correction. Files the plan creates and files already over 500 are not listed. `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. The design-surface detector maps every selected-option `fileStructure` path to the stage whose `files` or `plannedPaths` names it; a path neither names fails the draft check that correction preflight and `plan-items prepare` share (`scripts/okstra_ctl/report_assembly.py` `validate_plan_draft`). When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
|
|
151
|
+
- `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** **File size:** the implementation run aims for 300 physical lines per source and test file and enforces 500 — a new file over 500 and an existing file taken from 500 or fewer past 500 are blocking findings the executor must split in a correction round; a file already over 500 that grows is advisory, as is a new, crossing or growing file over 300. When a step would add code or tests to a file near or over 300 lines (`wc -l`), plan a new module or test file for that responsibility in `plannedPaths` instead of appending to the existing one. **Enforced at implementation:** `okstra correction file-size` (`scripts/okstra_ctl/file_size_cap.py`), re-run by `okstra stage-done`. A plan does not say how many lines a step adds, so planning cannot apply the limit; instead `okstra plan-items prepare`, correction preflight (`check-corrections`) and the plan verifier prompt report one `File-size headroom` line per existing source or test file the plan's `plannedPaths` name that has more than 300 and at most 500 lines, with the lines left before 500 and every stage that writes it (`file_size_cap.planned_file_headroom`). The report is information for the plan's readers: it never blocks, and it is not a verdict criterion or a reason for a correction. Files the plan creates and files already over 500 are not listed. `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. The design-surface detector maps every selected-option `fileStructure` path to the stage whose `files` or `plannedPaths` names it; a path neither names fails the draft check that correction preflight and `plan-items prepare` share (`scripts/okstra_ctl/report_assembly.py` `validate_plan_draft`). The one exception is an executor-owned conformance script under `qa/scripts/`: the detector skips it (`scripts/okstra_ctl/design_surfaces.py` `_stages_for_selected_path`), and no step lists it in `files` or `plannedPaths`, because the implementation run writes it (see `Conformance tests:` below). When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
|
|
152
152
|
- **Real-IO tests stay out of the plan's committed steps (BLOCKING).** A step never creates, edits, or runs a test that opens a real database connection, makes a real network call, or talks to a real external service inside the project source test tree (`src/**`, `test/**`, `tests/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, `*.e2e-spec.*`), and no step's `PASS` depends on a reachable database or service. The implementation executor refuses such a step before its first edit (`_implementation-executor.md` "Real-IO test isolation"), so a plan that contains one stops the stage with zero changes (observed 2026-10-18, dev-11374: a live-MySQL `test/font-pairing.e2e-spec.ts` planned in steps 1, 4 and 5). The committed RED/GREEN steps test the adapter with its injected collaborator stubbed — the exact query text, its replacements, and the returned rows — and run without any backend. Real-backend verification is declared only as this stage's `Conformance tests:` line below (`requires=[db|http|external]`): the implementation run writes that script under `<task_root>/qa/scripts/`, runs it against a local or replica backend when one is reachable, never commits it, and records a non-PASS or unreachable backend as advisory. Read a brief line such as `verify: integration test against a test database` as that conformance declaration, not as a committed test. Do not plan a shared real-DB guard, a test DDL fixture, or an edit to an existing real-IO suite in source to support it. **Enforced:** every `P-Step-*` item of the §5.5.9 plan-body round carries this rule to its verifiers (`okstra_ctl.phases.implementation_planning.authoring._REAL_IO_STEP_NOTE`), which vote `DISAGREE(b)` on a step that breaks it; no path pattern tells a mocked test from a live one, so no validator checks it.
|
|
153
153
|
- **The `command` cell runs inside an okstra task worktree, not a bare checkout (BLOCKING).** okstra provisions `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and — for `implementation` — a nested `stage-<N>/` worktree into the tree the step executes in. Two consequences bind every command you write:
|
|
154
154
|
- **Clean-tree assertions use `okstra worktree-status --check-clean`.** A bare `git status --porcelain` is never empty there, so an assertion built on one fails on okstra's scaffolding rather than on the stage's work. The okstra command asks the same question over source paths only and exits 1 when dirty, so it stands alone as a step's assertion: `okstra worktree-status --check-clean`. Validator S13 rejects the bare form. Do not add a `git tag stage-<N>-exit` to the step. Stage completion records the commit in the consumer ledger without creating or moving git tags.
|