okstra 0.138.0 → 0.140.0

package/runtime/prompts/profiles/release-handoff.md

@@ -44,7 +44,7 @@
        - `change base branch` — return to Q2 and re-ask the base selection.
        - `cancel` — end the run without push or PR; record the cancellation in the final report.
      - The probe is read-only. It MUST NOT run `git merge`, `git rebase`, `git pull`, or any command that mutates the working tree or local refs.
-  3. **PR title + PR body confirmation** — show the lead's inline draft verbatim and capture one of:
+  3. **PR title + PR body confirmation** — show the lead's inline draft verbatim, together with the filled-body self-check result (either `body self-check: clean` or the list of hits with their lines, per the drafting rules below), and capture one of:
      - `use as-is` — proceed with the drafted text.
      - `edit then proceed` — accept inline edits from the user, then proceed with the edited text.
      - `cancel` — end the run without executing push or PR commands; record the cancellation in the final report.
@@ -54,6 +54,7 @@
   - produce **two artifacts** before showing them to the user:
     1. **PR title** — by default the subject of the most recent implementation commit, or a concise Conventional Commits-style summary of the committed range.
     2. **PR body** — markdown filled from `PR_TEMPLATE_PATH`. The user-confirmation step's diff (Q3 `edit then proceed`) is computed against the filled template, not against the raw template file.
+  - **Filled-body self-check (runs on the drafted body, before Q3 shows it).** "Fill in the placeholders" is only observable if someone checks that they were filled, so scan the drafted body for these and carry the result into Q3: a residual HTML comment or template marker (`<!-- … -->`, `_Describe your changes…_`, a bare `TODO` / `FIXME` the diff did not introduce), an unchecked `- [ ]` box with no inline N/A justification, a section heading whose body is empty, and a whole body short enough to carry no substance. Each hit is reported to the user with its line — never silently left in, and never auto-filled with invented content. The user remains free to accept it; the point is that they see it before choosing `use as-is`.
 - Allowed actions during the run (Claude lead only):
   - read-only inspection: `git status`, `git status --short`, `git diff`, `git log`, `git rev-parse`, `git ls-remote --heads origin <name>`, `gh pr list --head <branch>`, `gh pr view <url>`.
   - merge-conflict probe (only when the user picked `push + PR`): `git fetch origin <chosen-base>` and `git merge-tree --write-tree --merge-base origin/<chosen-base> HEAD origin/<chosen-base>`. Both are non-mutating with respect to the working tree.

package/runtime/python/okstra_ctl/code_review_paths.py

@@ -0,0 +1,64 @@
+"""Filesystem layout for code-review result files.
+
+The two modes deliberately live under different roots: an okstra session
+review belongs to its task bundle, while a session-independent branch
+review belongs to the authoring tree. Centralising the assembly here keeps
+skill markdown from re-deriving literal paths.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from . import paths
+
+REVIEW_DIRNAME = "code-reviews"
+BRANCH_REVIEW_ROOT = ".project-docs"
+
+_STAGE_FILE_RE = re.compile(r"^stage-(\d+)(?:-r(\d+))?\.md$")
+_BRANCH_FILE_RE = re.compile(r"^(\d{4}-\d{2}-\d{2})-(\d+)\.md$")
+
+
+def stage_review_dir(project_root: Path, task_group: str, task_id: str) -> Path:
+    """Review directory inside the task bundle."""
+    return paths.task_dir(project_root, task_group, task_id) / REVIEW_DIRNAME
+
+
+def branch_review_dir(project_root: Path, branch: str) -> Path:
+    """Review directory for a branch. Slashes stay as nested directories."""
+    return Path(project_root) / BRANCH_REVIEW_ROOT / REVIEW_DIRNAME / branch
+
+
+def _existing_names(review_dir: Path) -> list[str]:
+    if not Path(review_dir).is_dir():
+        return []
+    return [entry.name for entry in Path(review_dir).iterdir() if entry.is_file()]
+
+
+def next_stage_review(review_dir: Path, stage: int) -> tuple[Path, int]:
+    """Next round's file path and round number for one stage.
+
+    Round 1 carries no suffix; later rounds are `-r<N>`.
+    """
+    highest = 0
+    for name in _existing_names(review_dir):
+        matched = _STAGE_FILE_RE.match(name)
+        if not matched or int(matched.group(1)) != stage:
+            continue
+        highest = max(highest, int(matched.group(2) or 1))
+    round_no = highest + 1
+    stem = f"stage-{stage:02d}"
+    suffix = "" if round_no == 1 else f"-r{round_no}"
+    return Path(review_dir) / f"{stem}{suffix}.md", round_no
+
+
+def next_branch_review(review_dir: Path, date: str) -> tuple[Path, int]:
+    """Next file path and sequence number for a branch review on `date`."""
+    highest = 0
+    for name in _existing_names(review_dir):
+        matched = _BRANCH_FILE_RE.match(name)
+        if not matched or matched.group(1) != date:
+            continue
+        highest = max(highest, int(matched.group(2)))
+    seq = highest + 1
+    return Path(review_dir) / f"{date}-{seq:02d}.md", seq

package/runtime/python/okstra_ctl/code_review_target.py

@@ -0,0 +1,152 @@
+"""코드 리뷰가 무엇을 읽고 결과 파일을 어디에 쓰는지 해소한다.
+
+두 모드를 한 진입점에 모아 스킬이 base 커밋도, 리뷰 파일 경로도, 회차도 다시
+유도하지 않게 한다. stage 모드는 read side 에 그대로 위임하고, branch 모드만
+여기서 해소한다 — caller 가 base 를 지정하지 않으면 기본 브랜치와의
+merge-base 를 쓴다. 이 모듈은 인자 검증과 JSON 정형화만 하고, 경로·회차 조립은
+code_review_paths 가, stage 규칙은 code_review_target_snapshot 이 소유한다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+from okstra_project import (
+    ResolverError,
+    StateError,
+    code_review_target_snapshot,
+    resolve_project_root,
+)
+
+from .code_review_paths import branch_review_dir, next_branch_review
+
+DEFAULT_BRANCH_CANDIDATES = ("main", "master")
+
+_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def _git_out(repo: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(repo), *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _default_branch_ref(repo: Path) -> str:
+    """merge-base 를 잴 기준 ref — origin/HEAD 가 있으면 그것, 없으면 관례 이름."""
+    remote_head = _git_out(repo, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+    if remote_head:
+        return remote_head
+    for candidate in DEFAULT_BRANCH_CANDIDATES:
+        if _git_out(repo, "rev-parse", "--verify", "--quiet", candidate):
+            return candidate
+    return ""
+
+
+def _merge_base(repo: Path, branch: str) -> str:
+    default_ref = _default_branch_ref(repo)
+    merge_base = _git_out(repo, "merge-base", default_ref, branch) if default_ref else ""
+    if not merge_base:
+        raise StateError(
+            f"no merge-base for {branch!r} against the default branch — "
+            "pass --base explicitly",
+            stage="base_unresolved",
+        )
+    return merge_base
+
+
+def _review_date(raw: str) -> str:
+    """branch 결과 파일명에 쓸 날짜.
+
+    next_branch_review 는 넘겨받은 문자열을 그대로 파일명에 쓰지만 되읽을 때는
+    `YYYY-MM-DD` 만 인식한다. 어긋난 날짜를 통과시키면 회차가 늘 1 로 돌아가
+    직전 리뷰 파일을 덮어쓴다.
+    """
+    if not raw:
+        return date.today().isoformat()
+    if not _DATE_RE.match(raw):
+        raise StateError(f"--date must be YYYY-MM-DD, got {raw!r}", stage="args")
+    return raw
+
+
+def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> dict:
+    head = _git_out(repo, "rev-parse", branch)
+    if not head:
+        raise StateError(f"branch {branch!r} not found", stage="branch_missing")
+    base_commit = base or _merge_base(repo, branch)
+    review_path, seq = next_branch_review(branch_review_dir(repo, branch), review_date)
+    return {
+        "mode": "branch",
+        "worktreePath": str(repo),
+        "branch": branch,
+        "baseCommit": base_commit,
+        "headCommit": head,
+        "reviewPath": str(review_path),
+        "round": seq,
+    }
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Resolve a code review's diff range and result file path."
+    )
+    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")
+    parser.add_argument("--base", default="", help="explicit base ref for branch mode")
+    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")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    return parser
+
+
+def _resolve(args: argparse.Namespace, project_root: Path) -> dict:
+    if args.task_key:
+        if args.stage < 1:
+            raise StateError("--task-key needs --stage <N>, N >= 1", stage="args")
+        return code_review_target_snapshot(project_root, args.task_key, args.stage)
+    if args.branch:
+        return _branch_snapshot(
+            project_root, args.branch, args.base, _review_date(args.date)
+        )
+    raise StateError("pass either --task-key --stage or --branch", stage="args")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    try:
+        project_root = resolve_project_root(
+            explicit_root=args.project_root, cwd=args.cwd
+        )
+    except ResolverError as exc:
+        print(json.dumps({"ok": False, "stage": "resolve", "reason": str(exc)}))
+        return 2
+
+    try:
+        snapshot = _resolve(args, Path(project_root))
+    except StateError as exc:
+        print(json.dumps({
+            "ok": False,
+            "stage": exc.stage or "target",
+            "reason": str(exc),
+        }))
+        return 1
+
+    print(json.dumps(
+        {"ok": True, "projectRoot": str(project_root), **snapshot},
+        ensure_ascii=False, indent=2,
+    ))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/worktree.py

@@ -57,8 +57,9 @@ from .seeding import (
 # worktree at provision time. Symlinks (not copies) so every task sees the
 # live shared state and disk/CPU cost stays near zero; the trade-off is
 # that any write through the link reaches the main worktree, which is
-# acceptable because okstra only writes inside its own task-scoped
-# subdirectory (e.g. `.okstra/tasks/<task-id>/runs/...`).
+# acceptable because okstra writes only to paths it owns: its task-scoped
+# subdirectory (e.g. `.okstra/tasks/<task-id>/runs/...`) and, for a
+# branch-mode code review, `.project-docs/code-reviews/<branch>/`.
 #
 # Override precedence (most-specific first):
 #   1. `OKSTRA_WORKTREE_SYNC_DIRS` env var — colon-separated list, REPLACES

package/runtime/python/okstra_project/__init__.py

@@ -28,6 +28,7 @@ from .resolver import (
 )
 from .state import (
     StateError,
+    code_review_target_snapshot,
     find_task_root,
     list_project_tasks,
     parse_task_key,
@@ -53,6 +54,7 @@ __all__ = [
     "StateError",
     "TASKS_RELATIVE",
     "TASK_CATALOG_RELATIVE",
+    "code_review_target_snapshot",
     "discovery_dir",
     "find_task_root",
     "list_project_tasks",

package/runtime/python/okstra_project/state.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import json
 import re
+import subprocess
 from pathlib import Path
 from typing import Optional
 
@@ -404,3 +405,144 @@ def stage_map_read_side_snapshot(project_root: Path, task_key: str) -> dict:
         "stages": stages,
         "doneStages": done,
     }
+
+
+def code_review_target_snapshot(
+    project_root: Path, task_key: str, stage: int
+) -> dict:
+    """stage 코드 리뷰가 무엇을 읽고 결과를 어디에 쓰는지 해소한다.
+
+    stage_map_read_side_snapshot 과 같은 결: caller 는 registry 행도, run-root
+    레이아웃도, stage base 규칙도 보지 않는다. stage_targets 의
+    StageTargetError 도 StateError 로 바꿔 던진다 — caller 가 그 예외를 잡으려고
+    okstra_ctl 을 import 하지 않도록.
+
+    base 는 stage worktree 를 만들 때 registry 행에 적힌 `base_ref` 다 — 그
+    stage 가 실제로 갈라져 나온 커밋. 리뷰 시점에 규칙으로 다시 계산하면
+    표류한다: 다중의존 stage 는 오늘의 task-key worktree HEAD 를 받게 되어
+    whole-task final-verification 이 stage 들을 병합한 뒤에는 base..head 구간이
+    비거나 뒤집히고, 단일의존 stage 는 선행 stage 가 재실행되면 어긋난다.
+    """
+    from okstra_ctl import code_review_paths, worktree_registry
+    from okstra_ctl.implementation_outcome import load_stage_map
+
+    identity = resolve_task_identity(project_root, task_key)
+    task_root = Path(identity["taskRoot"])
+    stages = load_stage_map(task_root, identity["manifest"])
+    selected = next((s for s in stages if s["stage_number"] == stage), None)
+    if selected is None:
+        raise StateError(
+            f"stage {stage} is not in the Stage Map for {task_key}",
+            stage="stage_missing",
+        )
+
+    coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
+    stage_row = worktree_registry.get_stage_row(*coords, stage) or {}
+    worktree_view = _stage_worktree_view(project_root, stage_row, stage)
+    base_commit = stage_row.get("base_ref") or _legacy_stage_base_commit(
+        identity, stages, selected
+    )
+    review_path, round_no = code_review_paths.next_stage_review(
+        code_review_paths.stage_review_dir(
+            project_root, identity["taskGroup"], identity["taskId"]
+        ),
+        stage,
+    )
+    return {
+        "mode": "stage",
+        "taskKey": identity["taskKey"],
+        "taskRoot": identity["taskRoot"],
+        "stage": stage,
+        **worktree_view,
+        "baseCommit": base_commit,
+        "reviewPath": str(review_path),
+        "round": round_no,
+    }
+
+
+def _legacy_stage_base_commit(
+    identity: dict, stages: list[dict], selected: dict
+) -> str:
+    """`base_ref` 를 남기지 않은 옛 registry 행의 base 를 규칙에서 되살린다.
+
+    provision 이 base_ref 를 기록하기 전에 만들어진 stage 행에만 쓰인다. 규칙
+    자체는 stage_targets 가 소유하며 여기서 다시 유도하지 않는다.
+    """
+    from okstra_ctl import stage_targets, worktree_registry
+    from okstra_ctl.paths import RunRef
+
+    coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
+    plan_run_root = RunRef.from_task_root(
+        Path(identity["taskRoot"]), "implementation-planning"
+    ).run_dir
+    lifecycle = stage_targets.read_stage_lifecycle_snapshot(
+        stages, plan_run_root, recover_from_carry=True
+    )
+    # The anchor and the multi-dep candidate base must come from the task-key
+    # worktree HEAD, where stage work accumulates — not from the invocation
+    # cwd, which may sit on an older or unrelated commit.
+    task_entry = worktree_registry.lookup(*coords)
+    task_worktree = Path(
+        (task_entry.worktree_path if task_entry else "") or identity["projectRoot"]
+    )
+    anchor = worktree_registry.get_implementation_base(*coords) or ""
+    try:
+        return stage_targets.resolve_stage_base_commit(
+            selected,
+            lifecycle.done_rows,
+            anchor_base_commit=anchor,
+            candidate_base=_git_out(task_worktree, "rev-parse", "HEAD"),
+            project_root=task_worktree,
+            plan_run_root=plan_run_root,
+        )
+    except stage_targets.StageTargetError as exc:
+        raise StateError(
+            f"stage {selected['stage_number']} has no recorded base_ref and its "
+            f"base could not be derived: {exc}",
+            stage="stage_base_unresolved",
+        ) from exc
+
+
+def _stage_worktree_view(project_root: Path, stage_row: dict, stage: int) -> dict:
+    """한 stage 의 worktree 경로 / 브랜치 / head 커밋.
+
+    철거된 stage worktree 는 오류가 아니다: whole-task final-verification 이
+    디렉터리를 지워도 브랜치는 남고, 리뷰가 필요한 커밋은 그 브랜치에 그대로
+    있다.
+    """
+    branch = stage_row.get("branch") or ""
+    if not branch:
+        raise StateError(
+            f"stage {stage} has no registry branch — review it in branch mode",
+            stage="stage_branch_missing",
+        )
+    worktree_path = ""
+    if stage_row.get("status") == "active" and stage_row.get("worktree_path"):
+        candidate = Path(stage_row["worktree_path"])
+        if candidate.is_dir():
+            worktree_path = str(candidate)
+    head_source = Path(worktree_path) if worktree_path else Path(project_root)
+    head_ref = "HEAD" if worktree_path else branch
+    head_commit = _git_out(head_source, "rev-parse", head_ref)
+    if not head_commit:
+        raise StateError(
+            f"stage {stage} head could not be resolved: branch {branch!r} is "
+            f"not readable from {head_source}",
+            stage="stage_head_unresolved",
+        )
+    return {
+        "worktreePath": worktree_path,
+        "branch": branch,
+        "headCommit": head_commit,
+    }
+
+
+def _git_out(repo: Path, *args: str) -> str:
+    """git 호출의 stdout. 실패는 빈 문자열 — 호출자가 부재를 판단한다."""
+    result = subprocess.run(
+        ["git", "-C", str(repo), *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout.strip() if result.returncode == 0 else ""

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

@@ -0,0 +1,180 @@
+---
+name: okstra-code-review
+description: >-
+  Use when the user wants changed code reviewed and the result written to a
+  file — either an okstra task's implementation stage, or any branch
+  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
+  (okstra-run), or inspecting a finished task (okstra-inspect).
+---
+
+# OKSTRA Code Review
+
+Review what a diff changed — one okstra implementation stage, or any branch — against this project's coding-preflight rules, and leave the result as a file under the project.
+
+## What makes this one-run-complete
+
+A reviewer left to build its own worklist enumerates the diff differently every run, so every run finds different things. Here the worklist — the **census** — is built **once, by you, deterministically**, before any reviewer is dispatched. Reviewers receive their slice as input; they never rebuild, reinterpret, or extend it.
+
+Each reviewer returns a **verdict for every cell it was given** (`clean`, or findings), so a skipped cell is visible instead of silently absent, and Step 3.5 re-dispatches every cell that came back without one. Same census + full verdicts = the same process every run.
+
+## Rules
+
+The rules themselves are **not in this skill**. They live in this project's coding-preflight pack — `overview.md` (core principles plus the three-stage resource routing), `clean-code.md`, and the routed `languages/` / `frameworks/` / `architectures/` resources. Step 2 decides which of them apply; reviewers read them from the absolute paths in their brief. Never restate a rule in a brief or in the report — point at it.
+
+This skill owns review calibration only:
+
+- `references/census-rules.md` — how a diff becomes cells: the four axes, pack allocation, exclusions, and the two completion criteria.
+- `references/review-calibration.md` — the per-cell verdict format, severity definitions and points, when `clean` is the correct verdict, and the report's section order.
+
+## Step 0 — Preflight
+
+<!-- BEGIN FRAGMENT: bash-invocation-rule -->
+Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+<!-- END FRAGMENT: bash-invocation-rule -->
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+Branch on the stdout JSON:
+- `ok: true` → carry `projectRoot` as a literal string; every later step is anchored on it.
+- `ok: false` → the check only sees the cwd of the Bash call, so a project that is not the cwd reads as missing setup. Ask whether the user pointed at a specific project directory; if they did, re-run targeting it: `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this **also** returns `ok:false` do you tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+
+<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
+If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
+<!-- END FRAGMENT: preflight-outdated-cli -->
+
+<!-- BEGIN FRAGMENT: python-bootstrap-note -->
+Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+<!-- END FRAGMENT: python-bootstrap-note -->
+
+## Step 1 — Resolve the review target
+
+Pick the mode from what the user actually gave you:
+
+- an okstra task token (a task-id like `DEV-9184`, or a full `project-id:task-group:task-id` key) → **stage mode**
+- a branch name → **branch mode**
+- neither → ask which of the two first. Do not guess a mode.
+
+**Stage mode.**
+
+1. `okstra resolve-task-key <token> --project-root <projectRoot> --json` → branch on `matches[]`: **0** → report the task cannot be found and stop; **1** → take that entry's `taskKey`; **N** → list the candidates (with `updatedAt`) and ask via a 3-option picker (1–2 recommendations + `Enter directly`).
+2. `okstra stage-map <taskKey> --project <projectRoot> --json` → `stages[]` (`stage_number`, `title`, `depends_on`) and `doneStages[]`.
+3. Choose the stage with a 3-option picker — recommend the highest done stage (the work that just finished) first, a second plausible stage if there is one, and `Enter directly` last. Pick silently only when exactly one stage exists.
+
+**Branch mode.**
+
+1. If the user named no branch, list `git -C <projectRoot> branch --format='%(refname:short)'` and offer a 3-option picker with the current branch as the first recommendation.
+2. Detached HEAD — `git -C <projectRoot> symbolic-ref --quiet HEAD` prints nothing — is refused: ask the user to name a branch. Do not review a bare commit.
+
+**Then call the target CLI.** One call resolves everything the rest of this skill needs; the only reason to call it again is a base the user overrides in the confirmation step below.
+
+```bash
+okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --json
+okstra code-review target --branch <name> [--base <ref>] --project-root <projectRoot> --json
+```
+
+`ok: true` carries `projectRoot`, `mode`, `worktreePath`, `branch`, `baseCommit`, `headCommit`, `reviewPath`, `round`; stage mode adds `taskKey`, `taskRoot`, `stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
+
+`ok: false` carries `stage` (a failure code) and `reason`. Report both and stop, unless the Exceptions table names that case.
+
+**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.
+
+**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:
+
+1. `Use <baseCommit>` — **the recommendation**, the value the CLI returned.
+2. `Show what this range covers` — print `git -C <workdir> log --oneline <baseCommit>..<headCommit>`, then ask the same three options again.
+3. `Enter directly` — always last: the user types a ref, and you call the target CLI a second time with `--base <that ref>`. Every field from the second call replaces the first call's, including `reviewPath` and `round`.
+
+## Step 2 — Census the diff
+
+1. **Read `references/census-rules.md`** (next to this file) and follow it. It owns the cells; this step owns only the inputs and what you print.
+2. Collect the diff from the work directory chosen in Step 1 — `git -C <workdir> diff --name-status <baseCommit>..<headCommit>` for the file list, and `git -C <workdir> diff <baseCommit>..<headCommit>` for the hunks. Before trusting that range, run `git -C <workdir> rev-list --count <headCommit>..<baseCommit>`: anything but `0` is the rewritten-history case in the Exceptions table. An empty diff skips Steps 3–3.5 (also in Exceptions).
+3. **Route the packs once, here — and fix both absolute paths the briefs carry.** `okstra paths --field home` prints the okstra home; read `<okstraHome>/prompts/coding-preflight/overview.md` and walk all three stages of its routed resource selection over the changed-file list. The result is the applied pack list — the absolute paths reviewers will read. This routing happens exactly once per run; no reviewer repeats it.
+
+   The second path is this skill's own calibration file. A subagent has no "next to this file" coordinate, so the brief must spell it out: the installed skill home is `~/.claude/skills/okstra-code-review/`, making the literal path `~/.claude/skills/okstra-code-review/references/review-calibration.md` — the same string whether the skill was copied in or dev-linked. Carry it, together with the pack list, into every Step 3 brief.
+4. Build the cells per `references/census-rules.md` and print, in this response: one cell table per axis, the exclusion list with a reason on every entry, and the applied pack list.
+5. Restate both completion criteria and show they hold: censused files + exclusions = files in the diff, and every hunk maps to a censused function or to file-level code.
+
+**Membership is mechanical; judgment only ever decides a cell's verdict.** Never drop a cell because you doubt the rule applies to it — that doubt is the reviewer's answer, and its name is `clean`. Over-inclusion costs one line; a judged exclusion is the run-to-run variance this census exists to remove.
+
+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 — Dispatch four reviewers in parallel
+
+Send all four Agent calls in **one message**, `subagent_type: "general-purpose"`. Every brief carries:
+
+- the diff, plus the work directory path so the reviewer can read whole files for context
+- 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 calibration path, written out in full as Step 2 fixed it — `~/.claude/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 | Cell | Reads |
+|---|---|---|
+| `structural` | non-test source file × `structural` | core principles 1, 2, 3, 6; `clean-code.md` DRY / KISS / SOLID / YAGNI; the completion sweep's domain-literal and documented-fork items; plus the architecture pack when one was routed |
+| `semantic` | function × `semantic` | core principles 4, 5; `clean-code.md` meaningful naming, functions-do-one-thing, the plain-English summary test, the 50-line cap, nesting depth, magic numbers, comments-explain-why |
+| `state-and-tests` | non-test source file × `state-and-tests`, test file × `state-and-tests` | `clean-code.md` "Mutation and state boundaries" and "Testing discipline"; plus the routed language pack's self-mock signals |
+| `general` | non-test source file × `general` | correctness bugs, swallowed errors, security, clear performance problems, core principle 7 (fix at the cause — nothing previously green edited to silence a failure); `clean-code.md` "Wrapping a third-party call" — a recovery branch the library already performs, a comment naming a condition the call site never establishes, a rethrow that drops the original error; plus the routed language pack's language-specific traps |
+
+Say it plainly in every brief: **the census is law** — work the cells exactly as given, return a verdict for every one, never re-derive the list. There is no length budget; dropping a finding to stay brief is the failure this skill exists to prevent.
+
+## Step 3.5 — Audit the coverage
+
+Diff each reviewer's returned cells against the slice you handed it. Any cell without a verdict → re-dispatch **one gap-fill agent per axis**, carrying only the missing cells and the same brief. Repeat until every cell of every axis has a verdict.
+
+A missing verdict is unfinished work, never an implicit `clean`. Do not start Step 4 while a single cell is unaccounted for.
+
+## 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.
+4. **Write the report to `reviewPath`** with the Write tool (it creates the parent directories). Frontmatter fields, in this order:
+
+```yaml
+mode: stage | branch
+taskKey: <task-key>          # stage mode
+branch: <branch>             # branch mode
+stage: <N>                   # stage mode only
+round: <round>
+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.
+
+## Exceptions
+
+| Situation | Handling |
+|---|---|
+| `preflight` returns `ok:false` | 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 |
+| `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 |
+| detached HEAD (branch mode) | refuse and ask the user to name a branch |
+
+## 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.
+- **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.