okstra 0.138.0 → 0.140.0

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.

package/runtime/skills/okstra-code-review/references/review-calibration.md

@@ -0,0 +1,86 @@
+# Review calibration — verdicts, severity, and the report
+
+Read this before verdicting. It defines the shape of an answer, not the rules — the rules are in the coding-preflight pack paths your brief listed, and you read those directly.
+
+## One verdict per cell
+
+Return verdicts in census order, one per cell. A clean cell is a single line — do not pad it with prose:
+
+```
+- cell: src/orders/pricing.py × structural — verdict: clean
+```
+
+A cell covers its whole rule group, so it can carry several findings from several rules; repeat the cell once per finding and name the violated rule in each:
+
+```
+- cell: src/orders/pricing.py × structural
+  verdict: finding
+  rule: DRY
+  line: 42
+  severity: must-fix
+  snippet: `discount = subtotal * 0.15 if tier == "gold" else 0`
+  note: The same tier→rate table is already in `domain/tiers.py:18`; a rate change now has two homes. Call the existing lookup instead of re-expressing it here.
+```
+
+Fields: `cell` (`target × axis`, exactly as the census wrote it — the axis is the rule group, and there is never one cell per individual rule), `verdict` (`clean` | `finding`), `rule` (the specific rule this finding violates, spelled as its pack spells it; omitted on `clean`), `line` (a line **this diff changed**), `severity`, `snippet` (the quoted changed line), `note` (1–2 sentences: what is wrong plus a concrete fix).
+
+There is no length budget. Dropping a real finding to stay brief is the failure this review exists to prevent, and a missing cell is re-dispatched as unfinished work, never read as a clean.
+
+## Severity and points
+
+| Severity | Meaning | Points |
+|---|---|---|
+| `must-fix` | a defect, or a rule violation that will cost real work later — wrong behavior, a swallowed error, a duplicated decision, a self-mocked test that proves nothing | 3 |
+| `should-fix` | a clear rule violation with no immediate breakage — a name that misleads, a function that fails the plain-English test, business logic in the wrong layer | 2 |
+| `nit` | real but small; the fix is cheap and obviously better | 1 |
+
+Grade the defect, not your confidence. If you are not confident, the verdict is `clean` — see the hedge test below.
+
+## When `clean` is the right verdict
+
+`clean` is a result, not a concession. Return it when:
+
+- **The defect sits only on lines this diff did not change.** Findings anchor on changed lines; pre-existing warts are not this change's problem.
+- **The rule does not apply to this cell.** The census over-includes on purpose, so cells where a rule turns out to be irrelevant are expected — that is exactly what a `clean` verdict records.
+- **The change is mechanical for this rule.** A signature-only or type-annotation-only edit does not reopen a function's body-level rules; a function the diff neither added nor renamed does not reopen its name.
+
+**The hedge test breaks a borderline `must-fix` or `should-fix`.** At those two severities the finding is one you would defend without qualifiers. If your draft note reaches for a softener that questions whether the point is worth raising at all — "marginal", "arguably", "if you are touching it anyway" — you are looking at a `nit` or at nothing: downgrade it or verdict `clean`, but never ship a hedged `should-fix`.
+
+The test does not empty the `nit` tier. A `nit` says the defect is small because that is the tier's definition, not because the reviewer is hedging — it still names a concrete defect on a changed line and a concrete fix.
+
+## Every finding carries its fix
+
+A finding without a fix is a complaint. Specifically:
+
+- **Readability findings** carry a pseudocode sketch — 4 to 6 lines that convey the intended reading experience, not a full refactor. If the sketch does not make a reader think "yes, that reads like prose", rewrite the sketch.
+- **Naming findings** carry a concrete alternative name, and one clause saying what the new name encodes that the old one did not.
+- **Structural findings** name the destination: which layer, module, or existing symbol the code should move to or call.
+
+## Test files
+
+Loose typing in test files (`any`, dynamic casts, untyped fixtures) is a **typing** carve-out only — never flag it on typing grounds alone. It stops being a carve-out the moment the cast is the vehicle for another violation: reaching into privates, or stubbing the unit under test. The self-mock rules apply through the cast exactly as they do without it — what is judged is the behavior, not the cast.
+
+## The report
+
+Merged by the orchestrator, written to `reviewPath`. Sections, in this order, empty ones omitted except `Coverage` and `Score`:
+
+```
+## Coverage
+## Must-fix
+## Should-fix
+## Nits
+## Score
+```
+
+- **Coverage** — one or two lines: N changed files → S `structural` / F `semantic` / T `state-and-tests` / G `general` cells, all verdicted; M files excluded with reasons; the applied packs, and any pack that was unavailable. The four counts are cell counts at the census's granularity — one cell per target per axis.
+- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix.
+- **Score** — every finding gets a row, and the table is emitted even when there are none, with a single total row reading 0:
+
+```
+| # | Location | Rule | Severity | Points |
+|---|---|---|---|---|
+| 1 | `src/orders/pricing.py:42` | DRY | must-fix | 3 |
+|   |   |   | **Total** | **3** |
+```
+
+The report's prose is written in Korean. Paths, identifiers, rule names, and quoted code stay verbatim.

package/src/cli-registry.mjs

@@ -145,6 +145,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Resolve a bare task-id to candidate task-keys from the catalog"],
   },
+  {
+    name: "code-review",
+    module: "./commands/inspect/code-review.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Resolve a code review's diff range and result file path"],
+  },
   {
     name: "set-work-status",
     module: "./commands/inspect/set-work-status.mjs",

package/src/commands/inspect/code-review.mjs

@@ -0,0 +1,35 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra code-review — resolve a code review's diff range and result path
+
+Usage:
+  okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] --json
+  okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] --json
+
+Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
+reviewPath, round }. Stage mode reads the base commit from the stage
+registry row; branch mode falls back to the merge-base with the default
+branch. An empty worktreePath means the review reads the branch ref
+instead of a checked-out tree. This is read-only — it never creates
+directories or files.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "target") {
+    process.stderr.write(
+      `error: unknown subcommand '${subcommand ?? ""}'\n\n${USAGE}`,
+    );
+    return 2;
+  }
+  const result = await runPythonModule({
+    module: "okstra_ctl.code_review_target",
+    args: rest,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/lib/skill-catalog.mjs

@@ -17,6 +17,7 @@ export const USER_SKILL_NAMES = Object.freeze([
   "okstra-container-build",
   "okstra-pr-gen",
   "okstra-user-response",
+  "okstra-code-review",
 ]);
 
 // Names okstra used to install as skills before they were renamed or moved