okstra 0.223.2 → 0.225.0

package/runtime/python/okstra_ctl/code_review_coverage.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from .agent.invocation import AgentInvocationError, verify_standalone_completion
+from .convergence_provenance import id_occurs_wordbounded
+from .coverage_census import CellVerdicts, split_coverage_verdict_section
+from .json_boundary import load_owned_object
+
+
+@dataclass(frozen=True)
+class ReviewCell:
+    target: str
+    group: str
+
+
+@dataclass(frozen=True)
+class ReviewCensus:
+    rules: dict[str, tuple[str, ...]]
+    cells: dict[str, ReviewCell]
+
+
+def _table_fields(line: str) -> list[str]:
+    return [field.strip() for field in line.strip().strip("|").split("|")]
+
+
+def read_review_census(path: Path) -> ReviewCensus:
+    rules: dict[str, list[str]] = {}
+    cells: dict[str, ReviewCell] = {}
+    rule_ids: set[str] = set()
+    pairs: set[tuple[str, str]] = set()
+    references: set[tuple[str, str]] = set()
+    section = ""
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.startswith("## "):
+            section = line.strip()
+        if section not in ("## Rules", "## Cells") or not line.strip().startswith("|"):
+            continue
+        fields = _table_fields(line)
+        header = fields[0] in ("Rule", "Cell")
+        if header or all(re.fullmatch(r"[-:]+", f) for f in fields):
+            continue
+        if len(fields) != 3 or not all(fields):
+            raise ValueError("malformed grouped census row")
+        identity, value, reference = fields
+        if section == "## Rules":
+            if not re.fullmatch(r"[A-Z][A-Z0-9]*", identity) or identity in rule_ids:
+                raise ValueError("invalid or duplicate rule ID")
+            if (value, reference) in references:
+                raise ValueError("duplicate group and rule reference")
+            if value not in ("structural", "semantic", "state-and-tests", "general"):
+                raise ValueError("unknown rule group")
+            rule_ids.add(identity)
+            references.add((value, reference))
+            rules.setdefault(value, []).append(identity)
+        else:
+            if not re.fullmatch(r"C-CR-[0-9]+", identity) or identity in cells:
+                raise ValueError("invalid or duplicate cell ID")
+            if (value, reference) in pairs:
+                raise ValueError("duplicate target and group")
+            target = PurePosixPath(value.partition(":")[0])
+            if target.is_absolute() or ".." in target.parts:
+                raise ValueError("target must be project-relative")
+            pairs.add((value, reference))
+            cells[identity] = ReviewCell(value, reference)
+    if not rules or not cells:
+        raise ValueError("census needs Rules and Cells tables")
+    if any(cell.group not in rules for cell in cells.values()):
+        raise ValueError("cell names an unknown rule group")
+    return ReviewCensus({group: tuple(ids) for group, ids in rules.items()}, cells)
+
+
+def _keyed_values(text: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if text == "-":
+        return values
+    for entry in text.split(";"):
+        key, separator, value = entry.partition("=")
+        key, value = key.strip(), value.strip()
+        if not separator or not key or not value or key in values:
+            raise ValueError("empty or duplicate rule assignment")
+        values[key] = value
+    return values
+
+
+def _source_evidence(project_root: Path, cell: ReviewCell, evidence: str) -> str:
+    match = re.fullmatch(r"(.+):([1-9][0-9]*)", evidence.strip("`"))
+    target = cell.target.partition(":")[0]
+    if match is None or match[1] != target:
+        raise ValueError("evidence must cite the target source path:line")
+    relative = PurePosixPath(target)
+    source = (project_root / target).resolve()
+    if (relative.is_absolute() or ".." in relative.parts
+            or not source.is_relative_to(project_root.resolve())):
+        raise ValueError("source evidence escapes project")
+    if not source.is_file():
+        raise ValueError("source evidence file does not exist")
+    if int(match[2]) > len(source.read_text(encoding="utf-8").splitlines()):
+        raise ValueError("source evidence line does not exist")
+    return evidence
+
+
+def _group_verdict(
+    fields: Sequence[str], expected: Sequence[str], cell: ReviewCell,
+    project_root: Path, references: Sequence[str],
+) -> tuple[str, str]:
+    if len(fields) != 5:
+        raise ValueError("expected Cell, Checked, N/A, Findings, Evidence columns")
+    checked = [] if fields[1] == "-" else [rule.strip() for rule in fields[1].split(",")]
+    excluded = _keyed_values(fields[2])
+    findings = _keyed_values(fields[3])
+    assigned = checked + list(excluded) + list(findings)
+    if len(set(assigned)) != len(assigned):
+        raise ValueError("duplicate or conflicting rule verdicts")
+    unknown = set(assigned) - set(expected)
+    if unknown:
+        raise ValueError("unknown rules: " + ", ".join(sorted(unknown)))
+    missing = set(expected) - set(assigned)
+    if missing:
+        raise ValueError("unchecked rules: " + ", ".join(sorted(missing)))
+    for reason in excluded.values():
+        if re.fullmatch(r"(?:[A-Z][0-9]+|[a-z]+:[0-9]+)", reason):
+            raise ValueError("n/a needs an inline applicability reason, not an alias")
+    for ids in findings.values():
+        for item in ids.split(","):
+            item = item.strip()
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", item):
+                raise ValueError("invalid finding ID")
+            if not any(id_occurs_wordbounded(body, item) for body in references):
+                raise ValueError(f"finding {item} has no finding body")
+    evidence = _source_evidence(project_root, cell, fields[4])
+    if findings:
+        return "finding", "; ".join(findings.values())
+    if checked:
+        return "clean", evidence
+    return "n/a", "; ".join(excluded.values())
+
+
+def _group_results(
+    body: str, census: ReviewCensus, project_root: Path, references: Sequence[str],
+) -> CellVerdicts:
+    section, _ = split_coverage_verdict_section(body)
+    verdicts: dict[str, tuple[str, str]] = {}
+    reasons: dict[str, str] = {}
+    seen: set[str] = set()
+    unknown: list[str] = []
+    for line in section:
+        if not line.strip().startswith("|"):
+            continue
+        fields = _table_fields(line)
+        identity = fields[0]
+        if identity not in census.cells:
+            if identity.startswith("C-") and identity not in unknown:
+                unknown.append(identity)
+            continue
+        if identity in seen:
+            verdicts.pop(identity, None)
+            reasons[identity] = "duplicate cell row"
+            continue
+        seen.add(identity)
+        cell = census.cells[identity]
+        try:
+            verdicts[identity] = _group_verdict(
+                fields, census.rules[cell.group], cell, project_root, references,
+            )
+        except (OSError, ValueError) as exc:
+            reasons[identity] = str(exc)
+    return CellVerdicts(
+        verdicts,
+        {key: reasons.get(key, "no grouped verdict row") for key in census.cells if key not in verdicts},
+        tuple(unknown),
+    )
+
+
+def check_review_coverage(
+    project_root: Path, census_path: Path, completions: Sequence[Path],
+) -> CellVerdicts:
+    census = read_review_census(census_path)
+    if not completions or len(set(completions)) != len(completions):
+        raise ValueError("pass distinct completion paths for one reviewer")
+    bodies: list[str] = []
+    assignment: object = None
+    for path in completions:
+        verified = verify_standalone_completion(
+            path, project_root=project_root, expected_purpose="code-review",
+        )
+        metadata = load_owned_object(
+            verified.prompt_metadata_path, artifact="agent invocation metadata",
+        )
+        if metadata["audience"] != "code-reviewer":
+            raise AgentInvocationError("completion is not a code reviewer")
+        current = metadata["modelAssignment"]
+        if assignment is not None and current != assignment:
+            raise AgentInvocationError("coverage cannot mix reviewer model assignments")
+        assignment = current
+        bodies.append(verified.returned_body)
+    verdicts: dict[str, tuple[str, str]] = {}
+    missing: dict[str, str] = {}
+    unknown: list[str] = []
+    references = [split_coverage_verdict_section(body)[1] for body in bodies]
+    for body in bodies:
+        parsed = _group_results(body, census, project_root, references)
+        unknown.extend(key for key in parsed.unknown if key not in unknown)
+        for key, verdict in parsed.verdicts.items():
+            verdicts.setdefault(key, verdict)
+        missing.update(parsed.missing)
+    return CellVerdicts(
+        verdicts, {key: missing[key] for key in census.cells if key not in verdicts},
+        tuple(unknown),
+    )

package/runtime/python/okstra_ctl/code_review_target.py

@@ -102,6 +102,7 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
 _CLI_EPILOG = r"""Usage:
   okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
   okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] --json
+  okstra code-review check-coverage --census <table-path> --completion <completion-path> [--completion ...] [--project-root <dir>]
   okstra code-review check-lines --base <ref> --head <ref> --cite <path:line> [--cite ...] [--project-root <dir>]
 
 Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
@@ -111,7 +112,8 @@ any citation is not a line the range changed. `--base` sets the base in either m
 mode reads the base commit from the stage registry row and branch mode falls
 back to the merge-base with the default branch. An empty worktreePath means the review reads the branch ref
 instead of a checked-out tree. This is read-only — it never creates
-directories or files.
+directories or files. `check-coverage` prints covered cells, missing rules and unknown cells;
+it exits 1 for incomplete coverage and 2 for invalid input or completion evidence.
 """
 
 
@@ -122,7 +124,7 @@ def _build_parser() -> argparse.ArgumentParser:
         prog="okstra code-review",
         description="Resolve a code review's diff range and result file path, or check finding citations."
     )
-    parser.add_argument("command", choices=("target", "check-lines"))
+    parser.add_argument("command", choices=("target", "check-lines", "check-coverage"))
     parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
     parser.add_argument("--stage", type=int, default=0, help="stage number to review")
     parser.add_argument("--branch", default="", help="branch to review")
@@ -135,6 +137,9 @@ def _build_parser() -> argparse.ArgumentParser:
         "--cite", action="append", default=[],
         help="check-lines: a finding's `path:line` (repeatable)",
     )
+    parser.add_argument("--census", default="", help="check-coverage: shared Rules and grouped Cells tables")
+    parser.add_argument("--completion", action="append", default=[],
+                        help="check-coverage: verified reviewer completion (repeat for gap-fills)")
     parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
     parser.add_argument("--project-root", default="", help="explicit project root")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
@@ -249,6 +254,28 @@ def _check_lines(args: argparse.Namespace, project_root: Path) -> int:
     return 0 if all_ok else 1
 
 
+def _check_coverage(args: argparse.Namespace, project_root: Path) -> int:
+    from .agent.invocation import AgentInvocationError
+    from .code_review_coverage import check_review_coverage
+
+    if not args.census or not args.completion:
+        print("check-coverage: pass --census and at least one --completion", file=sys.stderr)
+        return 2
+    try:
+        result = check_review_coverage(
+            project_root, Path(args.census), [Path(path) for path in args.completion],
+        )
+    except (OSError, ValueError, AgentInvocationError) as exc:
+        print(f"check-coverage: {exc}", file=sys.stderr)
+        return 2
+    print(f"Covered cells: {len(result.verdicts)}")
+    for key, reason in result.missing.items():
+        print(f"Missing: {key} — {reason}")
+    for key in result.unknown:
+        print(f"Unknown: {key}")
+    return 1 if result.missing or result.unknown else 0
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _build_parser().parse_args(argv)
     try:
@@ -260,6 +287,8 @@ def main(argv: list[str] | None = None) -> int:
         print(render_code_review_target_text(payload) if args.text else json.dumps(payload))
         return 2
 
+    if args.command == "check-coverage":
+        return _check_coverage(args, Path(project_root))
     if args.command == "check-lines":
         return _check_lines(args, Path(project_root))
     try:

package/runtime/python/okstra_ctl/coverage_census.py

@@ -233,7 +233,7 @@ class CellVerdicts:
     unknown: tuple[str, ...]
 
 
-def _split_verdict_section(text: str) -> tuple[list[str], str]:
+def split_coverage_verdict_section(text: str) -> tuple[list[str], str]:
     """The Coverage Verdicts lines, and the rest of the result."""
     lines = text.splitlines()
     start = next(
@@ -288,7 +288,7 @@ def parse_cell_verdicts(
     gap-fill result can cite an item its worker's first result already raised.
     The first usable line for a cell wins.
     """
-    section, body = _split_verdict_section(result_text)
+    section, body = split_coverage_verdict_section(result_text)
     wanted = list(dict.fromkeys(cell_ids))
     known = set(wanted)
     verdicts: dict[str, tuple[str, str]] = {}

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -335,6 +335,21 @@ class DispatchPlan:
         return payload
 
 
+def existing_dispatch_plan(
+    project_root: Path, workspace_root: Path, run_manifest_path: Path,
+    manifest: Mapping[str, Any],
+) -> DispatchPlan:
+    root = project_root.resolve()
+    return DispatchPlan(
+        project_root=root, workspace_root=workspace_root.resolve(),
+        manifest_path=_resolve_project_path(root, str(run_manifest_path)),
+        team_state_path=_resolve_required_path(root, manifest, "teamStatePath"),
+        lead_events_path=_resolve_required_path(root, manifest, "leadEventsPath"),
+        manifest=manifest, jobs=(),
+        default_backend=str(manifest.get("terminalBackend") or BACKEND_CLI_WRAPPER),
+    )
+
+
 @dataclass(frozen=True)
 class _BuildOptions:
     okstra_bin: Path | None

package/runtime/python/okstra_ctl/domain/worker_exec.py

@@ -18,6 +18,9 @@ SERVED_MODEL_MISMATCH_EXIT_CODE = 78
 # JSON 이벤트 스트림이 result 이벤트 없이 깨끗하게(exit 0) 끝난 run.
 # CLI 가 성공을 주장했지만 답을 내지 않았다 — sysexits 의 EX_PROTOCOL.
 NO_RESULT_EXIT_CODE = 76
+# run 하나에 한 단계, okstra-run 위저드에서 고른다. 강도를 받는 CLI 들이 이 넷을
+# 공통으로 받으므로 각 전략은 철자만 옮긴다.
+REASONING_EFFORTS = ("low", "medium", "high", "xhigh")
 
 
 @dataclass(frozen=True)
@@ -62,6 +65,9 @@ class WorkerExecRequest:
     # issue its own, so the recorded id and the session's own jsonl are
     # guaranteed to name the same session.
     session_id: str = ""
+    # `REASONING_EFFORTS` 중 하나. run 이 고르지 않았으면 빈 값이고, 그때 CLI 는
+    # 자기 설정을 따른다.
+    reasoning_effort: str = ""
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -13,12 +13,13 @@ from .convergence_store import write_json_atomic
 from .final_report_schema import load_schema_version
 from .report_narrative import parse_narrative, writer_owned_data
 from .json_boundary import load_owned_object
+from .plan_item_evidence import dependency_scopes, reusable_item_ids
 from .plan_items import (
     PlanItemContractError,
     content_hash,
+    dispatch_item_ids,
     extract_plan_items,
     planning_stage_ledger,
-    reverify_item_ids,
 )
 
 
@@ -386,7 +387,6 @@ def _carry_unchanged_checklists(
 
 def _recompute_dispatch_queue(
     narrative: Mapping[str, Any],
-    state_items: dict[str, dict],
     stage_ledger: Mapping[str, Any] | None = None,
 ) -> list[str]:
     """이월 뒤 남은 디스패치 큐.
@@ -401,18 +401,6 @@ def _recompute_dispatch_queue(
         extracted = extract_plan_items(_planning(dict(narrative)))
     except (CarryError, PlanItemContractError, KeyError, TypeError):
         return []
-    by_id = {
-        item["id"]: item
-        for item in extracted
-        if isinstance(item.get("id"), str)
-    }
-    previous_hashes = {
-        item_id: content_hash(by_id[item_id])
-        for item_id, row in state_items.items()
-        if row.get("carriedForwardFromSeq") and item_id in by_id
-    }
-    if not previous_hashes:
-        return []
     ledger = planning_stage_ledger(
         _planning(dict(narrative)),
         {
@@ -420,7 +408,7 @@ def _recompute_dispatch_queue(
             for stage, status in (stage_ledger or {}).items()
         },
     )
-    return reverify_item_ids(extracted, previous_hashes, ledger)
+    return dispatch_item_ids(extracted, ledger)
 
 
 def _writer_stage_rows(data: Mapping[str, Any], *, snapshot: str) -> dict[int, dict]:
@@ -495,7 +483,7 @@ def merge_v3_plan_state(
         state_items[item_id] for item_id in sorted(state_items)
     ]
     queue = _recompute_dispatch_queue(
-        narrative, state_items, pbv.get("stageLedger"),
+        narrative, pbv.get("stageLedger"),
     )
     if queue:
         pbv["dispatchQueue"] = queue
@@ -533,6 +521,12 @@ def sync_prepared_dispatch_queue(state_path: Path, merged: Mapping[str, Any]) ->
     if not isinstance(envelope, dict):
         return
     envelope["dispatchQueue"] = queue
+    inputs = envelope.get("reviewInputs")
+    if isinstance(inputs, dict):
+        rows = merged.get("planBodyVerification", {}).get("planItems", [])
+        inputs["dependencies"] = dependency_scopes(rows)
+        inputs["priorReviewHashes"] = {str(row["id"]): str(row.get("verifiedReviewHash", "")) for row in rows}
+        envelope["reusedItems"] = sorted(reusable_item_ids(rows, inputs) - set(queue))
     write_json_atomic(prepared, envelope)
 
 

package/runtime/python/okstra_ctl/phases/final_verification/profile.md

@@ -14,7 +14,7 @@
     - no new defects introduced — the diff does not break previously-working behaviour and adds no new bug (logic/off-by-one, null/empty handling, resource leaks, broken error paths)
     - no security defect on input from outside the process — for every changed file that reads a request body, query, header, upload, message or webhook, or acts on its behalf: work that grows faster than the input (pairwise uniqueness, nested scans, a backtracking regex, input-driven recursion) runs only after a size/count bound has rejected oversized input — check the validation framework's configuration, since class-validator without `stopAtFirstError` still runs `@ArrayUnique` after `@ArrayMaxSize` fails and a byte-size body limit does not bound element count; input reaches SQL, shell commands, file paths, server-side fetch targets, templates and regexes only through parameters, allowlists or escaping; a new route / handler / resolver carries the project's auth guard and compares the caller with the owner of an input-chosen id; no secret, full token, password or personal data reaches source, logs, error messages or responses; nothing evaluates or unsafely deserializes input. Each hit is an Acceptance Blocker citing the triggering input and its effect. The same rules, with examples, are `clean-code.md` "Untrusted input and security" in the installed coding-preflight pack (`~/.okstra/prompts/coding-preflight/clean-code.md`).
     - scope conformance — the delivered diff stays within the approved plan's scope; flag out-of-scope edits, unrelated file changes, leftover debug/commented-out code, and unintended deletions
-    - project review-rule packs — a pack applies when either source names it: the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or `<PROJECT_ROOT>/.okstra/project.json` lists it under `reviewRulePacks` (the project's standing standard, applying whether or not the brief mentions it). The two sources are a union. Read only those files and the `references/*.md` files they directly name. Do not search parent directories or host skill catalogs. Apply the rules as an acceptance overlay (record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited`). This is a static review pass, not a PR-comment workflow — do NOT dispatch reviewer subagents. Because this phase verifies the **whole-task merged diff**, it is the gate that catches **cross-stage findings a per-stage `implementation` verifier structurally cannot see** (each implementation run reviews only its own stage diff): most importantly two cross-stage conditions: (a) the same helper stack / transform / domain rule duplicated across stages or services — byte-identical duplication is always an Acceptance Blocker, and semantically-equivalent transforms across services are blockers unless the approved plan explicitly justified keeping them separate; (b) an API newly orphaned because its only caller was removed in a different stage. A confirmed cross-stage duplication of this kind is an Acceptance Blocker (`major`+) that cites every `path:line` location and names the shared-module location to converge on. (Single-stage scope sees only one stage, so it cannot raise cross-stage findings — note that limitation rather than implying coverage.)
+    - project review-rule packs — a pack applies when either source names it: the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or `<PROJECT_ROOT>/.okstra/project.json` lists it under `reviewRulePacks` (the project's standing standard, applying whether or not the brief mentions it). The two sources are a union. Read only those files and the `references/*.md` files they directly name. Do not search parent directories or host skill catalogs. Apply the rules as an acceptance overlay (record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited`). This is a static review pass, not a PR-comment workflow — do NOT dispatch reviewer subagents. Because this phase verifies the **whole-task merged diff**, it is the gate that catches **cross-stage findings a per-stage `implementation` verifier can miss** (each implementation run reviews only its own stage diff; it compares new blocks with code already on its base, but not with stages that land after it): most importantly two cross-stage conditions: (a) the same helper stack / transform / domain rule duplicated across stages or services, test helpers and test support code included — byte-identical duplication is always an Acceptance Blocker, and semantically-equivalent transforms across services are blockers unless the approved plan explicitly justified keeping them separate; (b) an API newly orphaned because its only caller was removed in a different stage. A confirmed cross-stage duplication of this kind is an Acceptance Blocker (`major`+) that cites every `path:line` location and names the shared-module location to converge on. (Single-stage scope sees only one stage, so it cannot raise cross-stage findings — note that limitation rather than implying coverage.)
   - Residual-tracked — note as Residual Risk unless severe enough to block:
     - unresolved edge cases
     - regression risk in adjacent code paths not directly changed

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md

@@ -38,7 +38,7 @@ Do not scan holistically and stop when it "looks fine". Work the matrix exhausti
    - port / adapter / domain file, when the hexagonal overlay is loaded → `architectures/hexagonal.md`: no business logic in a port body, adapter methods are I/O only (no post-fetch filtering on domain state, no `findValid*`/`findActive*` names hiding a rule), domain objects declared under the domain boundary, no changed domain file importing an ORM / framework / adapter / service (read the import list — mechanical), and a service dependency you add or modify goes through a port rather than a concrete adapter (advisory only while the project has not declared `architecture.style = hexagonal` in `.okstra/project.json` — record it with the port sketch; blocking under that declaration, so fix it in place before the commit rather than record-and-pass, exactly as `_implementation-verifier.md` re-grades this same diff. Either way, the codebase already injecting concrete classes is the debt this pays down, not a reason to skip it).
    - a service file, when the hexagonal overlay is loaded → `architectures/hexagonal.md` Rule H6: a decision this diff puts in a service — an `if`/`else` chain over domain fields, a business formula, a private method named for a domain concept — belongs in a domain function. Orchestration control flow, DTO mapping and calling a domain predicate are not violations.
    - a file that reads input from outside the process (request body, query, header, upload, message, webhook) or acts on its behalf → `clean-code.md` "Untrusted input and security": a size/count bound rejects oversized input before any check that grows faster than the input (a validator that runs every rule, such as class-validator without `stopAtFirstError`, does not stop at a failed `@ArrayMaxSize`), input reaches SQL / shell / paths / server-side fetches / templates / regexes only through parameters, allowlists or escaping, a new entry point carries the auth guard and compares the caller with the owner of an input-chosen id, no secret or personal data reaches code, logs or responses, and nothing evaluates or unsafely deserializes input.
-   - every changed source file → `clean-code.md` "Trace what this change can do wrong": walk the error, partial, concurrent and selection paths this diff creates to their end and fix wherever a wrong result comes out. Name the input that produces it — if you cannot name one, there is nothing to fix here and you move on rather than restructuring code that works.
+   - every changed source file → `clean-code.md` "Trace what this change can do wrong": walk the error, partial, concurrent and selection paths this diff creates to their end — past the failures the plan lists, and including where a cleaning `try` registers its cleanup target relative to each call that can throw — and fix wherever a wrong result comes out. Name the input that produces it — if you cannot name one, there is nothing to fix here and you move on rather than restructuring code that works.
    A file can hold several roles — apply every rule set that fits it.
 3. **Decide clean-or-finding for each cell.** Read the full file when a rule needs context (never judge a port/adapter/domain or a naming rule from the hunk alone).
 4. **Fix each finding in place** before the commit. When a readability finding is real, the fix is a named helper or named intermediate value — sketch the cleaner shape (a few lines) in your audit note, then apply it. When the fix is genuinely out of this stage's scope, record it as an `Out-of-plan` note instead of silently leaving it.

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md

@@ -194,12 +194,12 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
 - **Declared architecture style promotes the placement overlay from advisory to binding.** Take `Architecture style` from that projection and record `architecture-style: <hexagonal|layered|none>` in the worker result next to the `coding-conventions:` line. A declared `hexagonal` counts the overlay as loaded even when none of the router's Stage 3 layout signals matched, so the **Hexagonal** blocking check below applies in full, and the concrete-adapter injection listed under Advisory findings is promoted to a blocking finding → verdict `FAIL`, not a `should-fix`. A declared `layered` has no pack resource; its binding invariant is direction — an upper layer may import a lower one, never the reverse — so a changed file whose import list reaches back up a layer, or around a layer boundary, is a blocking placement violation cited `path:line` from that import list. The `layered` half is worker judgement: no machine check reads layer names, so a missed reverse dependency is a missed finding, not a validator failure. A `none` or absent projected style leaves Stage 3 detection-driven and the placement items advisory. **Enforced:** `scripts/okstra_project/resolver.py` `resolve_architecture` reads the same stored field for the planning-side rule in `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_variation_point_analysis`, and `_validate_verifier_fail_blocks_verdict` keeps the resulting `FAIL` from being dropped during synthesis.
 - **Blocking checks (any hit → verdict `FAIL`, cited `path:line` + rule name, recommended fix recorded — the verifier does NOT apply it):**
   - **Security (every changed file that reads input from outside the process or acts on its behalf — `clean-code.md` "Untrusted input and security"):** work that grows faster than the input — pairwise uniqueness, nested scans, a backtracking regex, input-driven recursion — reachable before a size/count bound has rejected oversized input (read the validation framework's configuration: class-validator without `stopAtFirstError` still runs `@ArrayUnique` after `@ArrayMaxSize` fails, and a byte-size body limit does not bound element count); input concatenated into SQL, a shell command, a file path, a server-side fetch target, a template or a regex; a new route / handler / resolver without the project's auth guard, or a lookup by an input-chosen id that never compares the caller with the owner; a secret, full token, password or personal data written to source, logs, an error message or a response; `eval`, dynamic code, or unsafe deserialization applied to input. Cite the input that triggers it and its effect — for unbounded work, the input size and the measured or derived cost.
-  - **New duplication / DRY:** two or more newly added or meaningfully modified blocks implement the same helper stack, transform, or domain rule. Literal copy-paste is always blocking; semantically equivalent transforms across services are blocking unless the approved plan explicitly justified keeping them separate. Recommend the shared module location.
+  - **New duplication / DRY:** two or more newly added or meaningfully modified blocks implement the same helper stack, transform, or domain rule. Literal copy-paste is always blocking; semantically equivalent transforms across services are blocking unless the approved plan explicitly justified keeping them separate. The comparison is not limited to this diff: a newly added block that is byte-identical to a block already in the repository — base code, or a copy an earlier stage landed — is the same blocking finding, cited at both the new `path:line` and the existing one, because `final-verification` grades that cross-stage copy as an Acceptance Blocker and a per-stage `clean` only defers it. Test helpers and test support code count. Recommend the shared module location.
   - **Self-mocking:** a test for `Foo` stubs/spies a method on the `Foo` instance under test (`jest.spyOn(sut, ...)`, `spyOn(FooService.prototype, ...)` in `foo.*.spec.*`, `vi.mocked(sut)` + stub). Mocking injected collaborators is fine.
   - **Interaction-only assertion:** a test whose only/primary assertion is `toHaveBeenCalled*` / `toHaveBeenCalledTimes` on an internal helper or a non-side-effecting collaborator, with no assertion on the returned value / resulting state / persisted row / emitted event.
   - **Tautological delegation assertion:** a test asserts the SUT result equals a direct call to the same pure helper/collaborator that the SUT delegates to, instead of asserting an independent literal value or observable state.
   - **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that writes/inserts/mutates; an adapter or repository name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*` / `findActive*`).
-  - **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every file you excluded with its reason (lockfiles, generated code, pure config), and close the section with `general: <N> files — all verdicted, <M> excluded`.
+  - **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. The failure modes the plan lists are the floor of this trace, not its ceiling: a verdict scoped to "the modeled failures" is not a verdict on the file. For every `try` whose `catch` / `finally` cleans up, check at each call inside it that can throw (a property write, a read, a call that starts other work) whether the thing to clean up is already registered at that point; when the diff moves or restructures existing code, compare that order with the base version and cite the base `path:line` when it changed. A failure the test fakes cannot produce (a throwing setter or read the fake does not model) is recorded as unverified with the failure named, never folded into `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every file you excluded with its reason (lockfiles, generated code, pure config), and close the section with `general: <N> files — all verdicted, <M> excluded`.
   - **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that decides a business outcome inline — an `if`/`else` chain over domain fields, a business formula in arithmetic, a private method named for a domain concept — instead of calling a domain function (`architectures/hexagonal.md` Rule H6). Orchestration control flow, DTO mapping, and calling a domain predicate are not violations. Blocking when the embedded rule is substantial: money, permissions, a state machine.
   - **Hexagonal (only when the overlay is loaded):** business logic inside a port body; an adapter method that is not pure I/O (post-fetch JS filtering on domain state, domain-rule evaluation); a domain object declared outside the `domain/` boundary; a changed file under the domain folder importing an ORM / DB layer, a framework or its DI decorators, or anything under adapters / infrastructure / services (read the import list — this verdict is mechanical, not a judgment). **The routed pack's project-convention latitude does not reach this cell.** `architectures/hexagonal.md` lets a documented convention resolve conflicts in the project's favour elsewhere in that overlay; here the import list decides, and "matches existing convention" is not an answer to it (see that file's §"How far a project convention reaches"). A run that resolved exactly this finding as project convention returned `clean` and the team's PR review flagged the same import.
   - **gitignored file committed to the branch:** any path in the `git diff --name-only <base>...HEAD` enumeration that `.gitignore` excludes — enumerate them by piping that list through `git check-ignore --stdin --no-index`. A committed ignored file means the executor bulk-added (`git add .`/`-A`) or force-staged (`git add -f`) it, leaking build output, scratch files, or verification artifacts into the eventual PR. This explicitly includes `.okstra/` paths (and `.project-docs/` when the legacy symlink is present): `.okstra/**` is gitignored, so a committed okstra file (qa scripts, conformance results) is always this defect. Cite each path; recommend `git rm --cached <path>` to untrack it while keeping the file on disk. Conformance/qa evidence belongs in the carry sidecar / verifier result, never in git history.