@humanbased/crosscheck 1.2.0 → 1.3.0-beta.81

package/get-started.md

@@ -22,6 +22,7 @@
   - [Multi-PR syntax](#multi-pr-syntax)
   - [watch](#crosscheck-watch)
   - [status](#crosscheck-status)
+  - [skill install](#crosscheck-skill-install-source)
   - [diagnose](#crosscheck-diagnose)
   - [optimize](#crosscheck-optimize)
   - [impact](#crosscheck-impact)
@@ -156,6 +157,52 @@ export LINEAR_API_KEY=lin_api_...
 If it's unset while enrichment is on, crosscheck just skips enrichment and
 reviews the diff as usual — it never errors.
 
+### Linear identity — for writing back to Linear (optional)
+
+Separate from enrichment above, which only *reads*. When `linear.enabled: true`,
+crosscheck mirrors each review verdict onto the PR's Linear issue.
+
+`crosscheck onboard` asks which rung of the attribution ladder you want and writes
+the config for you.
+
+**Start with `api_key`.** It reuses `LINEAR_API_KEY`, works immediately, and posts
+the comment — the feature is fully functional. Comments attribute to your Linear
+account, led by a `🤖 crosscheck · <model>` signature line.
+
+Climb to `client_credentials` when more than one thing writes to your workspace and
+you need them told apart. It uses an OAuth app — one per workspace, not per user —
+so comments post as crosscheck itself with its own icon:
+
+```bash
+export LINEAR_CLIENT_ID=...
+export LINEAR_CLIENT_SECRET=...
+```
+
+A failed T1 token mint aborts the run rather than falling back to `api_key` —
+a silent downgrade would put agent writes back under a human's name.
+
+`crosscheck onboard` walks you through the choice:
+
+<p align="center">
+  <img src="./assets/linear-onboard.svg" alt="crosscheck onboard — choosing a Linear attribution rung" width="700" />
+</p>
+
+Before opening a PR, `crosscheck linear-test` exercises the whole path and posts nothing —
+identity, issue lookup, verdict filter, and the exact comment body:
+
+<p align="center">
+  <img src="./assets/linear-test.svg" alt="crosscheck linear-test — dry-run verification" width="700" />
+</p>
+
+`crosscheck status` shows which rung is active whenever `linear.enabled` is true:
+
+<p align="center">
+  <img src="./assets/linear-status.svg" alt="crosscheck status — the Linear identity section" width="620" />
+</p>
+
+Full walkthrough, including the two Linear UI gotchas that trip people up:
+[docs/linear-identity.md](docs/linear-identity.md).
+
 ---
 
 ## Step 1 — Check your setup
@@ -345,6 +392,8 @@ crosscheck onboard --reconfigure  # re-run setup even if config already exists
 
 **Step 6 — Review quality.** Choose the speed/thoroughness tier for review prompts and reviewer timeouts.
 
+**Step 6.5 — Agent skills.** Choose which preloaded or custom-installed skills are enabled for coding agents. New setups preselect `code-review-skill (by @awesome-skills, MIT)` and `diagnosing-bugs (by @mattpocock, MIT)`. Matt Pocock's `code-review` and `codebase-design` are available but off by default. Re-running onboard preserves your selection. Skills are made available across workflow operations, and each skill's description plus the coding agent decides when it applies.
+
 **Step 7 — Workflow pipeline.** Choose what happens after a review:
 
 ```
@@ -398,6 +447,12 @@ crosscheck onboard
   [1] fast  [2] balanced  [3] thorough
   Choice [2]: 2
 
+  Step 6.5 — agent skills
+  [ ] code-review       (by @mattpocock, MIT)
+  [x] code-review-skill (by @awesome-skills, MIT)
+  [x] codebase-design   (by @mattpocock, MIT)
+  [x] diagnosing-bugs   (by @mattpocock, MIT)
+
   Step 7 — workflow pipeline
   [1] review only  [2] review → fix  [3] review → fix → re-check
   Choice [2]: 3
@@ -721,6 +776,8 @@ crosscheck status
   Config
     mode                   cross-vendor
     quality tier           balanced
+    installed skills       code-review (by @mattpocock, MIT), code-review-skill (by @awesome-skills, MIT), codebase-design (by @mattpocock, MIT), diagnosing-bugs (by @mattpocock, MIT)
+    enabled skills         code-review-skill (by @awesome-skills, MIT), diagnosing-bugs (by @mattpocock, MIT)
     codex auth             subscription
     claude model           sonnet
     per-review budget      $2.00/review
@@ -744,6 +801,41 @@ crosscheck status
 
 ---
 
+### `crosscheck skill install <source>`
+
+Installs an Agent Skill from a Git URL or local directory into `~/.crosscheck/skills`. Crosscheck validates `SKILL.md`, rejects unsafe names and symbolic links, and records source, revision, author, license, and package integrity. Installation does not enable a skill automatically.
+
+Crosscheck itself ships with this preloaded catalog:
+
+| Skill | Onboarding default | Best fit |
+|---|---:|---|
+| [`code-review-skill`](https://github.com/awesome-skills/code-review-skill) (by `@awesome-skills`, MIT) | On | General default: broad language, correctness, security, performance, and architecture coverage |
+| [`codebase-design`](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design) (by `@mattpocock`, MIT) | On | Architecture-heavy changes: deep modules, small interfaces, clean seams, and testability |
+| [`diagnosing-bugs`](https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs) (by `@mattpocock`, MIT) | On | Hard bugs and regressions: reproducible signals, ranked hypotheses, and regression evidence |
+| [`code-review`](https://github.com/mattpocock/skills/tree/main/skills/engineering/code-review) (by `@mattpocock`, MIT) | Off | Evidence-rich repositories: separately checks documented standards and issue/PRD fidelity |
+
+`code-review` and `code-review-skill` are competing review baselines. The onboarding picker highlights the conflict and will not enable one until the selected counterpart is deselected; the runtime broker also rejects activation of a second baseline. The other bundled skills are complementary.
+
+```bash
+crosscheck skill install https://github.com/owner/my-skill.git
+crosscheck skill install /path/to/my-skill
+crosscheck onboard  # enable installed skills
+```
+
+The Git repository or local directory must have `SKILL.md` at its root. For a skill nested in a monorepo, clone it and pass the nested local directory.
+
+`crosscheck status` distinguishes the full installed catalog from the enabled selection and renders attributed identities as `skill-name (by @author, license)`.
+
+At runtime, Crosscheck distinguishes three states: **installed** skills are in the catalog, **enabled** skills are available to agents, and **activated** skills were actually loaded for one workflow step. A skill becomes activated only when the agent successfully calls the Crosscheck broker's `activate_skill` tool for an enabled skill and receives its `SKILL.md` instructions. Listing enabled skills, seeing a skill description, or merely enabling a skill does not count.
+
+Activation is scoped to one step session, such as review, fix, recheck, or conflict resolution. Repeated activation in that session is idempotent, and the receipt survives retries or a reviewer fallback within the same step. Every later step gets a separate empty session, and Crosscheck deletes all step sessions when the workflow run ends. The terminal, logs, and PR comment preserve the completed step's attribution as historical evidence; they do not pre-activate future sessions. For example: `code-review-skill (by @awesome-skills, MIT)`.
+
+Upgrading from an earlier Crosscheck release is opt-in: existing configs default to `skills.enabled: []`. Re-run `crosscheck onboard` to choose the recommended bundle or any additional installed skills.
+
+Review and recheck also honor repository practices in `AGENTS.md` and `CLAUDE.md`. These repository-defined practices take precedence over bundled skill advice. Crosscheck reads the root files plus any nested files whose directory contains a changed path, orders them from broadest to most specific, and lets nested guidance override root guidance. It reads these files from the PR's base branch and disables vendor-native discovery for the run, so guidance added or modified by the PR cannot influence its own review.
+
+---
+
 ### `crosscheck diagnose`
 
 Reads `~/.crosscheck/logs/` and surfaces failure patterns, reviewer performance, and improvement suggestions.
@@ -965,7 +1057,7 @@ If no errors are found in recent logs, crosscheck prints `No errors found in rec
 
 On re-runs, `onboard` updates only the fields it collected answers for. Everything else survives unchanged.
 
-**Updated on every run:** `deployment`, `orgs`, `repos`, `mode`, `clone_protocol`, `vendors.*.enabled`, `vendors.*.effort`, `quality.tier`, `tunnel.*`, `post_review.auto_fix.*`
+**Updated on every run:** `deployment`, `orgs`, `repos`, `mode`, `clone_protocol`, `vendors.*.enabled`, `vendors.*.effort`, `quality.tier`, `skills.enabled`, `tunnel.*`, `post_review.auto_fix.*`
 
 **Never touched by onboard:** per-repo overrides in `~/.crosscheck/workflows/` (owned by `crosscheck alter`), and `~/.crosscheck/workflow.yml` after its first write
 
@@ -1015,7 +1107,8 @@ vendors:
   codex:
     enabled: true
     auth: subscription      # subscription | api-key
-    model: gpt-5.6-terra    # only used when auth: api-key
+    model: gpt-5.6-terra    # pins the review model; unset = tier model (api-key) / CLI default (subscription)
+    effort: medium          # low | medium | high | xhigh | max | ultra (ultra: terra/sol only)
     # timeout_sec: 1200     # max seconds per CLI call; unset = tier-based (300/600/1200)
 
   claude:
@@ -1026,7 +1119,8 @@ vendors:
 
 # ── Quality ───────────────────────────────────────────────────────────────────
 quality:
-  tier: balanced            # fast | balanced | thorough
+  mode: smart               # smart (default) | fixed — see Review thoroughness
+  tier: balanced            # fast | balanced | thorough (fallback under smart)
   focus:                    # narrows review scope (optional)
     - security
     - types
@@ -1034,6 +1128,16 @@ quality:
   custom_prompt: |          # appended to every review prompt
     Be concise. Flag only issues that would block a merge.
 
+# ── Agent skills ──────────────────────────────────────────────────────────────
+# Enabled means available to every coding-agent operation. The skill description
+# and agent decide whether to activate it for a particular step.
+skills:
+  enabled:
+    - code-review-skill     # recommended · @awesome-skills, MIT
+    - diagnosing-bugs       # recommended · @mattpocock, MIT
+    # - code-review         # preloaded, opt-in · @mattpocock, MIT
+    # - codebase-design     # preloaded, opt-in · @mattpocock, MIT
+
 # ── Budget ────────────────────────────────────────────────────────────────────
 budget:
   codex_monthly_usd: 20     # null = unlimited; only applies when auth: api-key
@@ -1144,15 +1248,93 @@ post_review:
 server:
   port: 7891
   webhook_path: /webhook
-```
+
+linear:                       # write review verdicts back to a Linear issue (opt-in)
+  enabled: false
+  auth:
+    mode: api_key             # api_key | client_credentials
+    api_key_env: LINEAR_API_KEY
+    client_id_env: LINEAR_CLIENT_ID
+    client_secret_env: LINEAR_CLIENT_SECRET
+    scopes: "read,write"      # comma-separated; initiative:* are separate scopes
+  identity:
+    actor: crosscheck
+    signature: "🤖 {actor} · {model}"   # {actor} {product} {model} {reviewer} {icon}
+    icon_url: ""              # rendered where {icon} appears; app avatar is preferred
+    per_step_actor: true      # crosscheck/review vs crosscheck/fix in Linear
+  comment_on:                 # verdicts mirrored to the issue (default omits APPROVE)
+    - NEEDS_WORK
+    - BLOCK
+  team_keys: []               # e.g. [IN] — required to match bare refs like IN-42
+```
+
+### Review thoroughness
+
+**`quality.mode: smart` is the default.** Crosscheck classifies each PR from its
+changed-file list and adjusts model and effort to match, rather than applying one
+tier to everything. Classification runs on the already-cloned working copy, so it
+costs one `git diff` and no API call. Set `mode: fixed` to opt out.
+
+| # | PR class | Detected by | Tier | Steps |
+|---|---|---|---|---|
+| 1 | Generated / vendored | every file is a lockfile or build output | — | **PR skipped** |
+| 2 | Security / data-critical | auth, crypto, payment, migration paths; `risk:T3`; hotfix→default | `thorough` | full loop |
+| 3 | Deletion-only | ≤ 5 additions with ≥ 20 deletions | `fast` | review |
+| 4 | Docs / spec | ≥ 50% Markdown | `balanced` | review |
+| 5 | Test-only | every file is a test | `fast` | review, fix |
+| 6 | Config / infra | ≥ 50% config, no source | `balanced` | full loop |
+| 7 | Trivial | ≤ 3 files, ≤ 150 lines | `fast` | review, fix |
+| 8 | Standard | everything else | `balanced` | full loop |
+
+First match wins, and security sits second so it dominates every cheapening rule
+below it — a deletion that removes auth code, or a two-file migration, is never
+routed to `fast`.
+
+The class's step set narrows the configured pipeline and never widens it, so a
+repo pinned to review-only with `crosscheck alter` stays review-only. Rounds past
+the first escalate on measured non-convergence: effort rises where the model
+supports it, the tier is promoted where it does not.
+
+Note that classes 3 and 4 narrow to `review` alone, which also drops
+`conflict-resolve` — review-only never touches code, and auto-conflict-resolve
+is code modification. That rule normally follows an operator's explicit
+`crosscheck alter --review-only`; under smart mode the *classifier* can reach it
+too, so a docs-only or deletion-only PR with a merge conflict is reviewed but not
+auto-resolved. Set `mode: fixed` if you want auto-conflict-resolve on every PR.
+
+Every comment cites the policy that produced it:
+
+```
+<!-- crosscheck: … verdict=BLOCK strategy=1.1.0 class=risky tier=thorough … -->
+```
+
+> **Leave `vendors.*.model` unset under smart mode.** An explicit model outranks
+> the strategy, so pinning one makes per-PR selection a no-op. When that happens
+> crosscheck **withholds** the tier from the comment rather than citing one that
+> did not run. `crosscheck onboard` clears the pin — and prints what it cleared —
+> when you choose smart.
+
+Verify the policy is current with `npm run verify:strategy`. Full rationale:
+[docs/dynamic-thoroughness.md](./docs/dynamic-thoroughness.md).
 
 ### Quality tiers
 
-| Tier | Speed | Depth | Best for |
-|---|---|---|---|
-| `fast` | ~10s | Top issues only | High-volume repos, draft PRs |
-| `balanced` | ~30s | Full review, all issues explained | Default for most teams |
-| `thorough` | ~60–90s | Deep multi-pass, architecture + security | Before merging to main |
+Under `fixed`, the tier applies to every call. Under `smart`, it is the fallback
+when a PR's file list cannot be read.
+
+| Tier | Claude | Codex | Cost per review | Best for |
+|---|---|---|---|---|
+| `fast` | Haiku 4.5 | GPT-5.6 Luna | $0.24 · $0.06 | High-volume repos, draft PRs |
+| `balanced` | Sonnet 5 | GPT-5.6 Terra | $0.72 · $0.58 | Default for most teams |
+| `thorough` | Opus 5 | GPT-5.6 Sol | $1.20 · $1.44 | Before merging to main |
+
+Cost is output-token cost at 48k output tokens, the measured median for one
+review. A review is an agentic session, not a single call — expect 10–16 minutes
+of wall clock (median 643s, p90 984s across 43 logged runs). Tier changes depth
+and the subprocess timeout, not seconds-scale latency.
+
+`claude-fable-5` is banned from review: 2× Opus 5's price for a lower coding
+benchmark score.
 
 ### Issue enrichment
 
@@ -1274,7 +1456,9 @@ If none match, origin is `human` and the PR is skipped in cross-vendor mode.
 codex review --base <base-branch> --title "<pr-title>"
 ```
 
-The `--base` flag diffs current HEAD against the base branch — exactly the PR diff. With `auth: subscription`, no model flag is passed. With `auth: api-key`, the model is selected by quality tier (`fast` → `gpt-5.6-luna`, `balanced` → `gpt-5.6-terra`, `thorough` → `gpt-5.6-sol`).
+The `--base` flag diffs current HEAD against the base branch — exactly the PR diff. An explicit `vendors.codex.model` (or matching `model_tiers` entry) is passed as `-c model=...` under either auth mode. When unset: `auth: subscription` passes no model flag (the Codex CLI picks its default), while `auth: api-key` selects the model by quality tier (`fast` → `gpt-5.6-luna`, `balanced` → `gpt-5.6-terra`, `thorough` → `gpt-5.6-sol`).
+
+Reasoning effort comes from `vendors.codex.effort` and is always passed through as `-c model_reasoning_effort=...` — for the review step and for the auto-fix step (`codex exec`) alike. The values match the codex CLI tiers 1:1 — `low` (Light), `medium`, `high`, `xhigh` (Extra High), `max`, `ultra`. Not every model supports every tier: `ultra` is terra/sol only, and pre-5.6 models stop at `xhigh` — the CLI rejects unsupported combinations. Higher tiers can multiply review wall-clock time; pair them with `timeout_sec`.
 
 ### How Claude reviews run
 
@@ -1289,7 +1473,16 @@ claude \
   "<prompt>"
 ```
 
-`--bare` makes execution fast and deterministic. `--allowedTools` limits Claude to read-only git operations on the cloned repo.
+`--bare` makes execution fast and deterministic. `--allowedTools` limits Claude to read-only git operations on the cloned repo. `vendors.claude.effort` drives `--effort` for every Claude step — review, recheck, auto-fix and conflict-resolve.
+
+Every comment crosscheck posts closes with the model and effort the step actually ran with, plus any skills the agent activated:
+
+```
+---
+_Reviewed with Claude Code via Crosscheck_ _(Opus 5 · high effort)_
+
+_Skills: code-review-skill (by @awesome-skills, MIT)_
+```
 
 ### Deduplication
 
@@ -1309,6 +1502,9 @@ The fix (file lock for same-machine + GitHub commit status for cross-machine) is
 - **Temp isolation** — each PR cloned into a fresh temp dir, deleted after review
 - **Read-only tools** — Claude restricted to `git diff` and `git log` only
 - **Temp credential isolation** — with `clone_protocol: ssh` (default) no tokens touch disk; with `clone_protocol: https` a short-lived token is embedded in the temp clone's remote URL and removed when the temp dir is deleted after review
+- **Skill package validation** — installs reject unsafe names, attribution injection, symbolic links, packages over 1,000 files or 10 MiB, and collisions; Git sources record their checked-out commit
+- **Skill integrity** — Crosscheck verifies every installed package against its SHA-256 receipt before exposing it to agents; modified or malformed packages fail closed and appear as unavailable in `crosscheck status`
+- **Skill execution boundary** — the activation broker exposes instructions and referenced files but never executes bundled scripts itself. Skills are third-party instructions: inspect their source and license before enabling them; the selected coding agent still operates under its normal sandbox and permissions
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanbased/crosscheck",
-  "version": "1.2.0",
+  "version": "1.3.0-beta.81",
   "description": "AI code review pipeline that turns agent-written PRs into merge-ready patches",
   "bin": {
     "crosscheck": "dist/cli.js",
@@ -23,12 +23,13 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc && rm -rf dist/harness && cp -r src/harness dist/harness && cp src/config/review-model-tiers.json dist/config/review-model-tiers.json && chmod +x dist/cli.js dist/ck.js",
+    "build": "tsc && rm -rf dist/harness && cp -r src/harness dist/harness && cp src/config/review-model-tiers.json dist/config/review-model-tiers.json && cp src/config/review-strategy.json dist/config/review-strategy.json && chmod +x dist/cli.js dist/ck.js",
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "lint": "eslint src --ext .ts",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "verify:strategy": "node scripts/verify-review-strategy.mjs"
   },
   "dependencies": {
     "chalk": "^5.3.0",