okstra 0.206.1 → 0.207.0

package/runtime/python/okstra_ctl/worker_dispatch.py

@@ -10,12 +10,18 @@ from typing import Any, Mapping, Sequence
 from . import dispatch_core
 from .adapters.dispatch.cli_wrapper import CliWrapperDispatchPort
 from .application.dispatch_assignments import dispatch_assignments
-from .dispatch_state import DispatchError
+from .dispatch_checkpoints import (
+    record_collect_checkpoints,
+    record_dispatch_checkpoints,
+    settled_initial_dispatches,
+)
+from .dispatch_state import DispatchError, load_json_object
 from .models import provider_wrappers
 from .ports.worker_dispatch import WorkerDispatchRequest
 
 
 SUPPORTED_CLI_WORKERS = provider_wrappers("analyser")
+_SOURCE = "okstra worker-dispatch"
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -38,14 +44,42 @@ def main(argv: Sequence[str] | None = None) -> int:
         if args.dry_run:
             _print_json(_backend_payload(backend_plan, dry_run=True))
             return 0
-        code = dispatch_core.dispatch_cli_wrapper_plan(backend_plan)
-        _print_json({**_backend_payload(backend_plan, dry_run=False), "exitCode": code})
+        code, lines = _dispatch_recording_checkpoints(backend_plan)
+        _print_json({
+            **_backend_payload(backend_plan, dry_run=False),
+            "exitCode": code,
+            "progressLines": lines,
+        })
         return code
     except DispatchError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
 
 
+def _dispatch_recording_checkpoints(backend_plan) -> tuple[int, list[str]]:
+    if not backend_plan.jobs:
+        return dispatch_core.dispatch_cli_wrapper_plan(backend_plan), []
+    before = load_json_object(backend_plan.team_state_path, "team-state")
+    lines: list[str] = []
+    code = dispatch_core.dispatch_cli_wrapper_plan(
+        backend_plan,
+        before_start=lambda prepared: lines.extend(record_dispatch_checkpoints(
+            prepared.project_root, prepared.manifest_path,
+            load_json_object(prepared.team_state_path, "team-state"),
+            prepared.jobs, source=_SOURCE,
+        )),
+    )
+    lines.extend(record_collect_checkpoints(
+        backend_plan.project_root, backend_plan.manifest_path,
+        settled_initial_dispatches(before),
+        settled_initial_dispatches(
+            load_json_object(backend_plan.team_state_path, "team-state")
+        ),
+        source=_SOURCE,
+    ))
+    return code, lines
+
+
 def _dispatch_request(args: argparse.Namespace) -> WorkerDispatchRequest:
     return WorkerDispatchRequest(
         project_root=Path(args.project_root),
@@ -75,6 +109,13 @@ whose persisted runner is 'cli-wrapper'. It verifies each invocation contract
 before execution and uses the persisted provider, model, and registered CLI.
 Native-session assignments remain owned by the active host session.
 
+It records the lead checkpoints it owns and prints them as `progressLines`:
+`phase-3-team-create` when it writes the implicit-team marker,
+`phase-4-dispatch` for each `initial` job, `phase-6-synthesis` on the first
+report-writer dispatch, and `phase-5-collect` for each `initial` dispatch it
+settled. The lead emits those lines instead of calling
+`okstra lead-progress append` for them.
+
 Missing worker prompt files are generated automatically from the immutable run snapshot.
 Existing prompt and metadata files are never overwritten.
 When report-writer completes, this command also runs the idempotent post-report

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -35,6 +35,10 @@ ERRORS_PATH_HEADERS = (
 # itself: the lead's launch prompt carries them, and no worker reads that.
 APPROVED_PLAN_HEADER = "**Approved plan:**"
 IMPLEMENTATION_STAGE_HEADER = "**Stage for this implementation run:**"
+# A stage's verifiers share one worktree and run as one batch. The Tier 3 script
+# (builds, fixed ports) and the self-mock mutation probe (edits sources in place)
+# must each run once, by the verifier named here.
+STAGE_QA_OWNER_HEADER = "**Stage QA owner:**"
 IMPLEMENTATION_HEADERS = (
     "**Worktree:**",
     APPROVED_PLAN_HEADER,
@@ -295,6 +299,21 @@ def worker_assignment(
     return None
 
 
+def stage_qa_owner(manifest: Mapping[str, Any]) -> str:
+    """The first verifier in roster order, or '' when the roster has none.
+
+    Derived from the manifest alone: prompts are published once and reused, and
+    the lead may materialize or re-dispatch one verifier at a time, so an owner
+    taken from the dispatch batch could disagree with a published prompt.
+    """
+    roster = manifest.get("recommendedWorkers")
+    for worker_id in roster if isinstance(roster, list) else []:
+        row = worker_assignment(manifest, worker_id) if isinstance(worker_id, str) else None
+        if row is not None and row.get("role") == "verifier":
+            return worker_id
+    return ""
+
+
 def _plan(
     audience: PromptAudience,
     *,

package/runtime/python/okstra_ctl/worker_runner.py

@@ -29,6 +29,7 @@ from .domain.worker_exec import (
     WorkerExecRequest,
 )
 from .domain.worker_presentation import JsonEvents, Presentation
+from .process_group import MemoryWatch, kill_group, memory_cap_bytes
 from .session_transcript import SessionTranscript
 from .json_boundary import JsonBoundaryError, write_owned_object_atomic
 
@@ -42,6 +43,8 @@ _TERM_GRACE_SECONDS = 5
 # this only has to cover a drain, never a producer.
 _DRAIN_AFTER_EXIT_SECONDS = 2
 _TIMEOUT_EXIT_CODE = 124
+# sysexits 의 EX_OSERR. 워커 그룹이 메모리 상한을 넘어 러너가 죽인 run.
+MEMORY_CAP_EXIT_CODE = 71
 _READ_SIZE = 8192
 _WRITE_SIZE = 8192
 _NO_STATUS_EXTRA: Mapping[str, Any] = {}
@@ -66,6 +69,7 @@ def run_worker(
     _validate_status_extra(status_extra)
     _validate_request_write_contract(request, status_extra)
     command = strategy.build_command(request)
+    memory_watch = MemoryWatch(memory_cap_bytes(request.project_root))
     started_monotonic = time.monotonic()
     status = _started_status(status_extra, log_path)
     _write_status(status_path, status)
@@ -73,11 +77,12 @@ def run_worker(
 
     try:
         with guard:
-            exit_code, timed_out, idle_seconds, raw_model, usage = _launch(
+            exit_code, timed_out, idle_seconds, raw_model, usage, reaped = _launch(
                 command,
                 log_path,
                 presentation=presentation,
                 idle_timeout_seconds=request.idle_timeout_seconds,
+                memory_watch=memory_watch,
                 on_spawn=guard.watch,
             )
             at_exit = getattr(command.presentation, "served_model_at_exit", None)
@@ -107,6 +112,11 @@ def run_worker(
             if failure:
                 status["failure"] = failure
                 exit_code = SERVED_MODEL_MISMATCH_EXIT_CODE
+    if reaped:
+        status["leftoverProcessesKilled"] = True
+    if memory_watch.exceeded_bytes:
+        exit_code = MEMORY_CAP_EXIT_CODE
+        status.update(failure=memory_watch.failure(), terminated_by="memory-cap")
     status["exit_code"] = exit_code
     if timed_out:
         status.update(
@@ -176,8 +186,9 @@ def _launch(
     *,
     presentation: str,
     idle_timeout_seconds: int,
+    memory_watch: MemoryWatch,
     on_spawn: Callable[[subprocess.Popen[bytes]], None],
-) -> tuple[int, bool, int, str | None, Mapping[str, Any] | None]:
+) -> tuple[int, bool, int, str | None, Mapping[str, Any] | None, bool]:
     live = presentation == LIVE
     transcript = SessionTranscript(log_path, live=live)
     observation = _ServedModelObservation()
@@ -211,14 +222,18 @@ def _launch(
             strategy=strategy,
             presentation=presentation,
             idle_timeout_seconds=idle_timeout_seconds,
+            memory_watch=memory_watch,
             stdin_text=command.stdin_text,
         )
+        # 워커가 띄운 빌드 워커·서버는 워커가 끝나도 그룹에 남아 계속 자란다.
+        reaped = kill_group(process.pid)
         return (
             exit_code,
             timed_out,
             idle_seconds,
             observation.raw_model,
             usage_observation.usage,
+            reaped,
         )
     finally:
         transcript.close()
@@ -386,6 +401,7 @@ def _pump(
     strategy: Presentation,
     presentation: str,
     idle_timeout_seconds: int,
+    memory_watch: MemoryWatch,
     stdin_text: str | None = None,
 ) -> tuple[int, bool, int]:
     selector = selectors.DefaultSelector()
@@ -418,6 +434,7 @@ def _pump(
         ):
             timed_out = True
             _terminate(process)
+        memory_watch.check(process.pid, time.monotonic())
         drain_deadline = _drain_deadline(process, drain_deadline)
         if drain_deadline is not None and time.monotonic() >= drain_deadline:
             _stop_reading(selector)
@@ -457,7 +474,8 @@ def _drain_deadline(
     holding the write end of the pipe open for as long as it lives. The shell
     wrappers returned as soon as `wait <pid>` did, so blocking on a grandchild is
     a regression rather than a policy, and the exit code the caller gets stays
-    the worker's own.
+    the worker's own. Whatever is still in the group afterwards is killed
+    (`_launch`).
 
     The deadline is set once and never pushed back: output arriving after the
     worker exited is the grandchild's, and letting it extend the wait would

package/runtime/python/okstra_ctl/write_policy.py

@@ -26,6 +26,7 @@ from .domain.write_policy import (  # noqa: F401 — 재노출(값 코어는 도
     write_policy_digest,
     write_policy_from_payload,
 )
+from .conformance import conformance_result_file
 from .final_report_paths import final_report_data_path
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .path_hints import hydrate_active_run_context
@@ -65,11 +66,15 @@ def build_write_policy(
         ),
         "externalRoots": [str(path) for path in external_roots],
     }
+    artifact_policy: dict[str, Any] = {
+        "allowedRoot": str(project_root),
+        "allowedPaths": list(artifact_paths),
+    }
+    preserved_paths = _relative_paths(invocation.get("preservedPaths", ()))
+    if preserved_paths:
+        artifact_policy["preservedPaths"] = list(preserved_paths)
     policy = WritePolicy(
-        artifact_policy={
-            "allowedRoot": str(project_root),
-            "allowedPaths": list(artifact_paths),
-        },
+        artifact_policy=artifact_policy,
         source_policy=source_policy,
         git_policy=git_policy,
         auxiliary_policy=auxiliary_policy,
@@ -94,9 +99,12 @@ def _role_qa_artifact_paths(role: str, task_root: Path | None) -> tuple[Path, ..
     conformance script, its `tsconfig.json` and any real-IO qa spec under
     `qa/scripts/`, plus the manifest entry naming them
     (`_implementation-executor.md` §"Stage conformance script", §"Real-IO test
-    isolation"). Everything else under `qa/` — the self-mock sidecar and its
-    diff, the conformance run's `result-*.json` — is written while the verifier
-    runs its own gates. Keeping the executor's grant to those two entries is
+    isolation"), plus `qa/output/` for whatever those scripts write when the
+    executor runs them against its own work — a baseline capture, build logs
+    (§"Verifier gates are not yours to run" lets it run them). Everything else
+    under `qa/` — the self-mock sidecar and its diff, the conformance run's
+    `result-*.json` — is written while the verifier runs its own gates.
+    Keeping the executor's grant to those three entries is
     what leaves the audit able to catch an executor that runs the verifier's
     self-mock gate (`_implementation-executor.md` §"Verifier gates are not
     yours to run"); widening it to `qa/` would silence that.
@@ -114,6 +122,7 @@ def _role_qa_artifact_paths(role: str, task_root: Path | None) -> tuple[Path, ..
     if role == "implementer":
         return (
             task_qa_dir(task_root) / "scripts",
+            task_qa_dir(task_root) / "output",
             task_conformance_manifest_file(task_root),
         )
     if role == "verifier":
@@ -121,6 +130,42 @@ def _role_qa_artifact_paths(role: str, task_root: Path | None) -> tuple[Path, ..
     return ()
 
 
+def _inherited_qa_evidence(
+    role: str, task_type: str, task_root: Path | None,
+) -> tuple[Path, ...]:
+    """Existing qa files a final-verification verifier must leave byte-identical.
+
+    Its grant is the whole `qa/` tree, so re-running a plan step that captures a
+    baseline overwrote the implementation's RED evidence and still passed the
+    audit (observed 2026-09-26, dev-11054 `qa/baseline/base.json`). New files and
+    the conformance results it re-runs (`qa/result-<stageKey>.json`, the only qa
+    write `final_verification/boundary.json` names) stay writable.
+    """
+    if role != "verifier" or task_type != "final-verification" or task_root is None:
+        return ()
+    qa_dir = task_qa_dir(task_root)
+    if not qa_dir.is_dir():
+        return ()
+    rerun = {
+        conformance_result_file(qa_dir, key)
+        for key in _conformance_stage_keys(task_root)
+    }
+    return tuple(sorted(
+        path for path in qa_dir.rglob("*")
+        if path.is_file() and not path.is_symlink() and path not in rerun
+    ))
+
+
+def _conformance_stage_keys(task_root: Path) -> tuple[str, ...]:
+    path = task_conformance_manifest_file(task_root)
+    if not path.is_file():
+        return ()
+    entries = _read_json(path, "conformance manifest").get("entries")
+    return tuple(
+        entry["stageKey"] for entry in entries or ()
+        if isinstance(entry, dict) and isinstance(entry.get("stageKey"), str)
+    )
+
 
 def _technical_experiment_paths(
     artifact_paths: Sequence[Path], task_root: Path | None,
@@ -145,6 +190,7 @@ def _technical_experiment_paths(
 def build_invocation_write_contract(
     *,
     role: str,
+    task_type: str,
     project_root: Path,
     worktree: Path | None,
     artifact_paths: Sequence[Path],
@@ -180,6 +226,10 @@ def build_invocation_write_contract(
         "plannedPaths": list(source_paths),
         "plannedPathsDeclared": planned_paths_declared,
         "protectedPaths": [".okstra", ".git"],
+        "preservedPaths": [
+            _relative_to_root(path, root, "preserved")
+            for path in _inherited_qa_evidence(role, task_type, task_root)
+        ],
         "generatedPaths": list(generated_paths),
         "scratchRoots": [str(path) for path in scratch_roots],
         "auxiliaryRoots": [str(path) for path in auxiliary_roots],

package/runtime/python/okstra_project/dirs.py

@@ -87,6 +87,20 @@ def okstra_root(project_root: Path) -> Path:
     return Path(project_root) / OKSTRA_RELATIVE
 
 
+def ensure_okstra_gitignore(project_root: Path) -> Path:
+    """`.okstra/.gitignore` 에 `*` 를 둔다. 이미 있으면 건드리지 않는다.
+
+    전역 gitignore 로만 `.okstra` 를 빼면 그것을 읽지 않는 도구가 산출물을 훑는다.
+    Tailwind v4(4.3.2) 스캐너는 전역 설정은 무시하고 중첩 `.gitignore` 는 따른다
+    (2026-09-27 실측) — 실험 사이트 복사본을 읽어 빌드가 수십 GB 로 커졌다.
+    """
+    path = okstra_root(project_root) / ".gitignore"
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("*\n", encoding="utf-8")
+    return path
+
+
 def project_json_path(project_root: Path) -> Path:
     """`<project_root>/.okstra/project.json` 절대 path."""
     return Path(project_root) / PROJECT_JSON_RELATIVE

package/runtime/python/okstra_project/resolver.py

@@ -11,6 +11,7 @@ from typing import Optional
 from .dirs import (
     OKSTRA_DIR_NAME,
     PROJECT_JSON_RELATIVE,
+    ensure_okstra_gitignore,
     project_json_path,
 )
 
@@ -154,7 +155,7 @@ def upsert_project_json(project_root: Path, project_id: str, *,
     if not project_id:
         raise ResolverError("project_id is required for upsert_project_json")
     target = project_json_path(project_root)
-    target.parent.mkdir(parents=True, exist_ok=True)
+    ensure_okstra_gitignore(project_root)
     when = now or _now_iso()
     abs_root = str(Path(project_root).resolve())
     if target.is_file():

package/runtime/schemas/execution-manifest-v2.schema.json

@@ -137,7 +137,8 @@
           "required": ["allowedRoot", "allowedPaths"],
           "properties": {
             "allowedRoot": {"type": "string", "pattern": "^/"},
-            "allowedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "minItems": 1, "uniqueItems": true}
+            "allowedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "minItems": 1, "uniqueItems": true},
+            "preservedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "uniqueItems": true}
           },
           "additionalProperties": false
         },

package/runtime/skills/okstra-code-review/SKILL.md

@@ -6,9 +6,10 @@ description: >-
   unrelated to an okstra run. The tell is a review request over a diff:
   "review this stage", "review my branch", "code review", "leave the review
   in a file". The orchestrator censuses the diff into an explicit worklist,
-  four parallel reviewers return a verdict for every cell against this
-  project's coding-preflight rules, and a coverage audit re-dispatches any
-  gap. NOT for writing a PR body (okstra-pr-gen), starting a run
+  one or two reviewers (the user picks) each return a verdict for every cell
+  against this project's coding-preflight rules, a coverage audit
+  re-dispatches any gap, and the orchestrator settles what the reviewers
+  disagree on. NOT for writing a PR body (okstra-pr-gen), starting a run
   (okstra-run), or inspecting a finished task (okstra-inspect).
 ---
 
@@ -79,7 +80,7 @@ okstra code-review target --task-key <taskKey> --stage <N> --project-root <proje
 okstra code-review target --branch <name> [--base <ref>] --project-root <projectRoot> --text
 ```
 
-`Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, and `Round`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
+`Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, `Round`, and `Report language`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
 
 `Status: error` carries `Failure stage` and `Failure reason`. Report both and stop, unless the Exceptions table names that case.
 
@@ -95,7 +96,7 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
 
 **You never derive the base.** Pass `--base <ref>` only when the user named one; otherwise the CLI resolves it. `baseCommit` is a **ref, not necessarily a commit id** — a caller-supplied `--base` passes through verbatim — so use it as given in `git diff <baseCommit>..<headCommit>` and never present it as "commit `<sha>`".
 
-**Where to run git.** Use `worktreePath` when it is non-empty; otherwise run git in `projectRoot` and read the stage's `branch` ref. An empty `worktreePath` does **not** mean the stage is gone: a completed stage's registry row is `released`, so the field is empty even when the directory is still on disk. Either way the commits are on the branch.
+**Where to run git.** Use `worktreePath` when it is non-empty; otherwise run git in `projectRoot` and read the stage's `branch` ref. An empty `worktreePath` does **not** mean the stage is gone: a completed stage's registry row is `released`, so the field is empty even when the directory is still on disk. Either way the commits are on the branch. With no worktree there is no checked-out tree to read whole files from, so every brief tells the reviewer to read a file at the reviewed commit with `git -C <projectRoot> show <headCommit>:<path>` — never from the project root's working tree, which holds a different commit.
 
 **Then show the base and confirm it — branch mode and stage mode alike.** The CLI's answer is a recommendation the user has not seen yet, and a base nobody looked at is how unrelated commits slip into a review unnoticed. Print `baseCommit` verbatim next to `git -C <workdir> log -1 --oneline <baseCommit>` so the commit it names is legible, then ask with a 3-option picker:
 
@@ -117,43 +118,49 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
 
 A large census is never truncated. Report the cell count and confirm before dispatching — a silent cut is a false "I looked at everything" signal.
 
-## Step 3 — Materialize and dispatch four reviewers in parallel
+## Step 3 — Materialize and dispatch the reviewers in parallel
 
-Ask the runtime what this operation runs — do not choose the role, the providers, or the reviewer count
-here:
+**Ask how many reviewers** with a 3-option picker:
+
+1. `2 reviewers` — **the recommendation**: two different models each review the whole census, and you settle only where they disagree.
+2. `1 reviewer` — cheaper; you adjudicate every finding it returns.
+3. `Enter directly` — always last; accept only `1` or `2`.
+
+Then ask the runtime what those reviewers run — do not choose the role or the providers here:
 
 ```
-okstra agent-prompt resolve-operation --operation code-review
+okstra agent-prompt resolve-operation --operation code-review --count <1|2>
 ```
 
 It prints the duty, the role, the reviewer count, and one `slot` line per reviewer carrying that slot's
-provider and model. The contract owns those values (`agents/operations/code-review.json`), so a machine
-with too few distinct models fails here rather than quietly running fewer reviewers. Dispatch exactly the
-slots it prints.
+provider and model. The contract owns those values (`agents/operations/code-review.json`, whose `count` is
+the ceiling), so a machine with too few distinct models fails here rather than quietly running fewer
+reviewers. Dispatch exactly the slots it prints.
 
 Every reviewer and later gap-fill is a separate auditable standalone invocation. For each slot, create
 `.okstra/agent-invocations/code-review/<invocation-id>.instructions.md` from that reviewer's brief, then run
-`okstra agent-prompt materialize` with `--purpose code-review`, `--audience <dutyId>`, that slot's
-`--provider` and `--model <modelRef>`, and the canonical `.prompt.md` path beside it; the returned
-assignment is authoritative. Run `okstra agent-prompt verify` against the returned `metadataPath` before
+`okstra agent-prompt materialize --project-root <projectRoot> --invocation-id <invocation-id> --host-runtime <runtime> --provider <slot provider> --model <slot model> --model-role <role> --audience <duty> --purpose code-review --instruction <instructions-path> --prompt <prompt-path>`,
+copying `role`, `duty`, and the slot's `provider` and `model` verbatim from `resolve-operation` (`--model`
+takes the `provider/model` value the slot line prints). The prompt path is the canonical `.prompt.md` beside
+the instructions file; the returned assignment is authoritative. Run `okstra agent-prompt verify` against the returned `metadataPath` before
 invoking any model.
 
 For a native host call, pass the verified prompt body and `hostModelValue`. For a deterministic provider
 process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path>`
 with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
 standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
-`.log`. Never substitute one model value for the other. Dispatch the four verified calls in parallel when the host supports
-it. Every brief carries:
+`.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
+it. **Every reviewer receives the same brief** — two reviewers are worth their cost only when both look at every cell. Every brief carries:
 
-- the diff, plus the work directory path so the reviewer can read whole files for context
+- the diff, plus how to read whole files at the reviewed commit: the `worktreePath` when it is non-empty, otherwise `git -C <projectRoot> show <headCommit>:<path>`
 - the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
-- **its own axis's cell list**, verbatim from the census
-- the absolute paths of the packs its axis reads (from step 2's routing)
+- **the whole census** — every cell of all four axes, verbatim
+- the absolute paths of every applied pack (from step 2's routing)
 - the calibration path, written out in full as Step 2 fixed it — `~/.agents/skills/okstra-code-review/references/review-calibration.md`. The verdict format, the severity points, and the rules for a legitimate `clean` are defined there, not in the brief; a reviewer that cannot open this file cannot return a usable verdict, so never hand it a relative path or a "next to the skill" hint
 
 Each axis is **one rule group**, so a cell is `target × <axis>` — never `target × <individual rule>`. The reviewer names the specific rule it found violated inside the verdict's `rule` field, and one cell may carry findings from several rules of its group.
 
-Axis scope — the `Reads` column names that group's rules, and a brief never restates them; the bodies are in the packs:
+Axis scope — each reviewer works all four axes; the `Reads` column names each group's rules, and a brief never restates them; the bodies are in the packs:
 
 | Axis | Cell | Reads |
 |---|---|---|
@@ -172,18 +179,47 @@ review result and cannot contribute a verdict.
 
 ## Step 3.5 — Audit the coverage
 
-Diff each reviewer's verified `returnedBody` cells against the slice you handed it. Any cell without a verdict
-→ dispatch **one gap-fill invocation per axis**, carrying only the missing cells and the same brief. Each
+Diff each reviewer's verified `returnedBody` cells against the census. Any cell without a verdict
+→ dispatch **one gap-fill invocation per reviewer**, on that reviewer's slot, carrying only its missing cells and the same brief. Each
 gap-fill uses a new invocation ID and repeats the full materialize → verify → dispatch → materialize-result →
-complete → verify-completion boundary from Step 3. Repeat until every cell of every axis has a verdict.
+complete → verify-completion boundary from Step 3. Repeat until every reviewer has a verdict for every cell.
+
+A missing verdict is unfinished work, never an implicit `clean`. Do not start Step 3.6 while a single cell is unaccounted for.
+
+## Step 3.6 — Check every citation
+
+Reviewers miscount lines. Pass every finding's `path:line` to one call:
+
+```bash
+okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
+```
+
+`ok` keeps the citation. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
+
+## Step 3.7 — Settle the findings
+
+Reviewers are wrong in a way a census cannot catch: a claim about code they did not open. What you settle depends on the reviewer count. A `must-fix` or `should-fix` with no `failure` or no `evidence` is rejected as "no failure scenario" in either case — the calibration requires both.
+
+**Two reviewers.** Pair the findings first: two findings are the same finding when they cite the same `path:line` and describe the same defect. Then:
+
+- **Agreed** — both reviewers report it with the same severity and timing. It stands as reported; you do not adjudicate it.
+- **Graded differently** — both report it, with a different severity or timing. Pick one of the two values after reading the code, and record both values and your reason in the finding. Never pick a third value.
+- **One-sided** — one reviewer reports it and the other returned `clean` for that cell or reported something else. Adjudicate it as below.
+
+**One reviewer.** Adjudicate every finding it returns.
+
+**Adjudicating** a finding: open each `evidence` location at `headCommit`, plus the definition of every symbol its `failure` depends on, and check the `failure` against that code.
+
+- **Confirmed** — the code produces the stated failure. The finding keeps its severity and timing.
+- **Rejected** — the code contradicts the claim (the called function never reads `this`, the value cannot be null there, the branch is unreachable). Move it to `Rejected` with the contradicting `path:line` and one sentence on what it shows.
 
-A missing verdict is unfinished work, never an implicit `clean`. Do not start Step 4 while a single cell is unaccounted for.
+Rejecting is a statement about the code, so it always carries a `path:line`. Never reject for being unconvinced. Apart from choosing between two reviewers' values, never promote, demote, or re-time a finding. Confirmed and agreed `park` findings go to `Parked`, unscored.
 
 ## Step 4 — Merge and write
 
 1. **Read `references/review-calibration.md`** (next to this file) and follow its report section — you are the one writing the file, and it fixes the Coverage sentence, the per-finding line format, the Score table columns, and the total row. The reviewers were given it for their verdicts; the report obeys it too.
-2. **Dedupe across axes.** The same defect surfaced by two axes stays once, under the rule that explains it best.
-3. **Severity is the reviewer's.** The merge concatenates and dedupes; it never re-grades. If a verdict looks wrong, the brief was wrong — improve the brief for next run and ship this one as returned.
+2. **Dedupe across axes and reviewers.** The same defect surfaced by two axes or two reviewers stays once, under the rule that explains it best, and each finding says how it was settled: `agreed`, `graded by orchestrator`, or `confirmed by orchestrator`.
+3. **Severity is the reviewers'; truth is yours.** The merge never re-grades or re-times a finding except by choosing between two reviewers' values in Step 3.7.
 4. **Write the report to `reviewPath`** with the Write tool (it creates the parent directories). Frontmatter fields, in this order:
 
 ```yaml
@@ -192,14 +228,15 @@ taskKey: <task-key>          # stage mode
 branch: <branch>             # branch mode
 stage: <N>                   # stage mode only
 round: <round>
+reviewers: [<provider/model>, ...]   # the slots Step 3 dispatched
 baseCommit: <exactly as the CLI returned it>
 headCommit: <headCommit>
 packs: [<applied coding-preflight pack paths>]
 generatedAt: <YYYY-MM-DD HH:MM>
 ```
 
-   Body sections, in this order: `## Coverage`, `## Must-fix`, `## Should-fix`, `## Nits`, `## Score`. Empty severity sections are omitted; `Coverage` and `Score` are always present, and a review with no findings still emits the Score table with a total of 0.
-5. **In the session, print only** the `reviewPath`, the count per severity, and the score total. The file is the deliverable — do not replay the findings in chat.
+   Body sections, in this order: `## Coverage`, `## Must-fix`, `## Should-fix`, `## Nits`, `## Parked`, `## Rejected`, `## Score`. Empty sections are omitted; `Coverage` and `Score` are always present, and a review with no confirmed `now` findings still emits the Score table with a total of 0. The score counts confirmed `now` findings only. Write the prose in the `Report language` from Step 1.
+5. **In the session, print only** the `reviewPath`, the count per severity, the parked and rejected counts, and the score total. The file is the deliverable — do not replay the findings in chat.
 
 ## Exceptions
 
@@ -207,7 +244,7 @@ generatedAt: <YYYY-MM-DD HH:MM>
 |---|---|
 | `preflight` reports `Okstra preflight: failed` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
 | `unknown command: code-review` | the `okstra` binary predates this skill — tell the user to update it (`npm i -g okstra@latest`) and stop |
-| `worktreePath` is empty | not a hard stop and not a missing stage: run git in `projectRoot` against the stage's `branch` ref and continue |
+| `worktreePath` is empty | not a hard stop and not a missing stage: run git in `projectRoot` against the stage's `branch` ref, and have reviewers read whole files with `git -C <projectRoot> show <headCommit>:<path>` |
 | `baseCommit` is not an ancestor of `headCommit` — `git -C <workdir> rev-list --count <headCommit>..<baseCommit>` returns a **non-zero** count, meaning a rebase or squash rewrote the history the stage was recorded against, and `<baseCommit>..<headCommit>` would drag predecessor work in backwards | code-review is read-only, so do not force a reconcile. Offer two options: review against the branch's current tip, or run `okstra git-reconcile` first and retry |
 | the diff is empty | dispatch no reviewers; write the "no changes" report to `reviewPath` and stop. It is a normal report, not a free-form note: the same frontmatter, `## Coverage` reading "0 changed files → 0 cells on every axis, 0 files excluded" plus the applied packs, every severity section omitted, and `## Score` carrying the table with its single total row reading 0 |
 | the census is large | never truncate — report the cell count and confirm before dispatching |
@@ -215,9 +252,10 @@ generatedAt: <YYYY-MM-DD HH:MM>
 
 ## Principles
 
-- **Stay in the diff.** Every finding cites a line this diff changed. A cell whose only wart sits on untouched lines verdicts `clean` — pre-existing issues are not this change's problem.
+- **Stay in the diff.** Every finding cites a line this diff changed, and Step 3.6 checks it. A cell whose only wart sits on untouched lines verdicts `clean` — pre-existing issues are not this change's problem.
 - **Don't manufacture findings.** A census fully verdicted `clean` is a valid, useful result.
 - **No finding without a fix.** Readability findings carry a pseudocode sketch; naming findings carry a concrete alternative name.
 - **The census is law.** A reviewer that rebuilds its own worklist reintroduces exactly the run-to-run variance this skill exists to kill.
 - **Every cell gets a verdict.** `clean` is a result, not an omission; the audit treats a gap as unfinished work.
-- **The report prose is Korean.** Paths, identifiers, rule names, and quoted code stay verbatim.
+- **Only a checked claim scores.** A finding reaches the score after its citation is on a changed line and its failure holds against the code; everything else is `Parked` or `Rejected`, with its reason.
+- **The report prose follows `Report language`.** Paths, identifiers, rule names, and quoted code stay verbatim.