okstra 0.138.0 → 0.139.0

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); 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.

package/runtime/skills/okstra-code-review/references/census-rules.md

@@ -0,0 +1,100 @@
+# Census rules — turning a diff into the worklist
+
+The census is the worklist: an explicit list of cells, each one a `target × axis` pair, built once by the orchestrator before any reviewer is dispatched. This file defines how a diff becomes cells. The rules a cell is judged against live in the coding-preflight pack; the verdict format lives in `review-calibration.md`.
+
+## Cell granularity — one rule group per axis
+
+**Each axis carries exactly one rule group, and that group is the axis itself.** A cell is `target × <axis>`, never `target × <individual rule>`. Twelve changed files therefore produce twelve `structural` cells, not one per file per rule.
+
+This is what makes the cell count reproducible: the axis list is fixed at four, so the census size depends only on the diff. Splitting an axis per individual rule would make the count depend on how many rules the reader chose to enumerate that day — the exact variance this census exists to remove.
+
+The specific rule a finding violates is named **inside the verdict**, in its `rule` field (`review-calibration.md`), not in the cell label. One cell can therefore carry findings from several rules of its group, and it still counts as one cell for coverage.
+
+## The one principle
+
+**Membership is mechanical; judgment only ever decides a cell's verdict.**
+
+Never ask "does this rule apply to this file?" while building the census — that question is the reviewer's, and its answer is a verdict (`clean` when the rule turns out not to apply). Over-inclusion is cheap: a clean verdict costs one line. A judged exclusion is variance — it is the exact failure this census exists to remove, because the next run judges differently and the review changes shape.
+
+Two consequences:
+
+- A cell exists because a mechanical test matched (file extension, path, "the diff touched this function"), never because the orchestrator expected a violation.
+- The orchestrator never reads a file to decide membership. It reads the diff's file list and hunks, and nothing else.
+
+## The four axes
+
+| Axis | Cell unit | Membership test (mechanical) |
+|---|---|---|
+| `structural` | non-test source file × `structural` | every changed non-test source file |
+| `semantic` | function × `semantic` | every function the diff touched — at least one changed line anywhere in its signature or body. Signature-only and type-annotation-only changes count |
+| `state-and-tests` | non-test source file × `state-and-tests`, test file × `state-and-tests` | every changed non-test source file gets one cell; every changed test file gets one cell |
+| `general` | non-test source file × `general` | every changed non-test source file |
+
+"Is there a mutation or a state boundary in this file?" is **not** a membership question — the `state-and-tests` cell exists for every changed non-test source file, and the reviewer answers with a verdict.
+
+Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) are censused on `state-and-tests` only. They are not excluded: they are covered by a different rule group.
+
+Functions are enumerated from the diff's hunks. A hunk that lands outside any function (imports, module wiring, top-level declarations, class-level constants) is file-level code — it belongs to the file cells, not to a function cell, and it is what the second completion criterion checks for.
+
+## Exclusions
+
+Only these are excluded from the census, and each exclusion is listed **with its reason** in the response and in the report's Coverage section:
+
+- lockfiles (`package-lock.json`, `poetry.lock`, `Cargo.lock`, `*.sum`, …)
+- generated code (anything under a build/output directory, or carrying a "do not edit" generation header)
+- pure configuration and data (`.json`, `.yml`, `.toml`, fixtures) that contains no executable project code
+- prose documentation with no executable or agent-directive content
+- binary files and vendored third-party trees
+
+**Skill, prompt, and agent-directive markdown IS censused.** In a repo whose behaviour is carried by prompts, a markdown file that instructs an agent is the executable surface, and a review that skips it skips the change. Extension is not the test — a `.md` file is excluded only when it is prose a human reads and nothing acts on.
+
+To keep that mechanical rather than judged, a path allowlist overrides the extension list: anything under `skills/**`, `prompts/**`, `agents/**`, or `templates/**` is **always censused**, whatever its extension.
+
+Everything else is censused. When a file is arguably code — a build script, a shell entrypoint, a template that carries logic — it is censused, not excluded; if the rules turn out not to apply, that is a `clean` verdict.
+
+An exclusion without a stated reason is a defect in the census: it is indistinguishable from a file that was forgotten.
+
+## Pack allocation
+
+Step 2 of the skill routes the coding-preflight packs once. Distribute the resulting absolute paths across the axes like this:
+
+| Pack | Goes to |
+|---|---|
+| `clean-code.md` | all four axes — it is language-agnostic and every axis draws from a different part of it |
+| `overview.md` core principles | all four axes (each brief names the principles that are its own; see the skill's axis table) |
+| routed `languages/*.md` | `state-and-tests` (self-mock signals) and `general` (language-specific traps) |
+| routed `frameworks/*.md` | `general` |
+| routed `architectures/*.md` | `structural` |
+
+A pack that the routing did not select is not handed to anyone. A pack a reviewer receives is one it must read before verdicting.
+
+## Unregistered language
+
+When no Stage 1 language rule in `overview.md` matches any changed file, the project's language has no pack. Do not invent one.
+
+1. Ask the user for the project's canonical style guide (a path, a URL, or a named standard) and, if they name one, hand its path to `state-and-tests` and `general` in place of the language pack.
+2. If the user does not answer, run all four axes anyway with `clean-code.md` alone, and state in the report's Coverage section that language-specific rules were not applied and why.
+
+Never skip an axis for a missing pack, and never silently proceed as if the language pack existed.
+
+## Completion criteria
+
+Both must hold exactly, and both are shown in the response before dispatch:
+
+1. **Files:** distinct files censused (in any axis) + files excluded = files in the diff.
+
+   One `git diff --name-status` row is one file, whatever its status letter. A rename row carries two paths (`R100 <old> <new>`) and still counts **once**: census the `<new>` path and never count `<old>` on either side of the equation. A delete row (`D <path>`) counts once too, and it is always an exclusion, with the reason `deleted — no remaining line to anchor a finding on`.
+2. **Hunks:** every hunk in a censused file maps either to a censused function or to file-level code (imports, module wiring, declarations).
+
+A count that does not balance means a file was dropped, not that the diff was odd. Find it before dispatching.
+
+## What to emit
+
+In the orchestrator's response, before Step 3:
+
+- one table per axis, in the order `structural`, `semantic`, `state-and-tests`, `general`, listing every cell
+- the exclusion list, one line per file, each with its reason
+- the applied pack list (absolute paths)
+- the two completion criteria with their actual numbers
+
+Never truncate a table to save space. If the census is large, report the cell count and ask whether to proceed — a silent cut turns "every cell was verdicted" into a false claim.