@humanbased/crosscheck 1.2.0-beta.81 → 1.3.0-beta.100

package/docs/metrics.md

@@ -0,0 +1,115 @@
+# Metrics: what Crosscheck records, and where it stays
+
+Crosscheck records what it did so you can tell whether it is working. Every number comes from local log files, and **nothing is transmitted**: there is no endpoint, no account, no upload, and no network call in any of the code that produces or reads these metrics. Telemetry is opt-in in the strongest available sense — it does not exist yet.
+
+This document is the field-by-field inventory. If you find a field written to disk that is not listed here, that is a bug worth reporting.
+
+---
+
+## Where it lives
+
+| | |
+|---|---|
+| Location | `~/.crosscheck/logs/<YYYY-MM-DD>.ndjson` — one JSON object per line |
+| On by default | Yes (`logs.enabled: true`) |
+| Retention | `logs.retention_days`, default 30 — older files are deleted at startup |
+| Turn it off | `logs.enabled: false` in `crosscheck.config.yml` |
+
+Turning logging off is supported and costs you the reader commands: `crosscheck adoption`, `impact`, `diagnose`, and `optimize` all read these files and have nothing else to read.
+
+---
+
+## Reading it
+
+```bash
+crosscheck adoption                      # activation, usage, weekly active repos, latency, first-run failures
+crosscheck adoption --json               # the same report as JSON
+crosscheck adoption --since 2026-07-01   # narrow the window
+```
+
+`crosscheck adoption` answers "is this being used, and does a PR get a verdict fast enough to matter". Its sibling `crosscheck impact` prices reviews that already happened. Both read the same files and neither makes a network call.
+
+What the report shows:
+
+| Metric | Derived from |
+|---|---|
+| onboard started / completed / abandoned | `onboard_started`, `onboard_completed` |
+| reviews started / completed | `review_started`, `review_complete` |
+| rechecks completed | `review_complete` with `step_type: recheck` |
+| blocking findings posted | `blocking_finding_posted` |
+| fixes applied | `fix_complete` with `applied_count > 0` |
+| active repos, weekly active repos | distinct `repo` on `review_complete`, bucketed by ISO week |
+| PR open → verdict (median, p90, slowest) | `open_to_verdict_ms` on `review_complete` |
+| first-run failures | first `error` in a session that never logged a `review_complete` |
+
+Two honest limits worth knowing before you quote a number:
+
+- **Latency is only measured when the PR event carried an open time.** Hand-built events and some third-party webhook redeliveries do not. Those verdicts are excluded and counted separately as `unmeasured` rather than being given an invented start time.
+- **Everything is bounded by the retention window.** A 30-day default means a "total" is a 30-day total. Raise `logs.retention_days` if you need a longer baseline.
+
+---
+
+## What is recorded
+
+Identifying fields, on every event that has them:
+
+| Field | Example | Why |
+|---|---|---|
+| `ts` | `2026-07-08T10:00:00.000Z` | ordering, weekly bucketing |
+| `event` | `review_complete` | what happened |
+| `repo` | `acme/web` | which repo — this is a name, and it is the most identifying field written |
+| `pr` | `245` | which PR number |
+
+Everything else is a count, an enum, a duration, or a commit sha:
+
+| Field | Shape |
+|---|---|
+| `verdict` | `APPROVE` / `NEEDS WORK` / `BLOCK` |
+| `reviewer`, `model`, `effort` | vendor and model identifiers |
+| `step_type`, `step_name`, `round`, `trigger` | which step ran, and why |
+| `duration_ms` | how long the reviewer ran |
+| `open_to_verdict_ms` | PR open → verdict, in ms |
+| `tokens_used`, `input_tokens`, `output_tokens` | integer counts |
+| `applied_count`, `commentCount` | integer counts |
+| `sha`, `head_sha` | commit shas |
+| `category` | error class: `auth`, `permission`, `rate_limit`, `overloaded`, `budget`, `timeout`, `network`, `git`, `subprocess`, `unknown` |
+| `message`, `stack`, `stderr` | on error events only — the failure text, truncated |
+| `outcome`, `stage` | on `onboard_completed`: `completed` / `abandoned`, and where it stopped |
+| `deployment`, `repos`, `orgs`, `quality_tier`, `quality_mode`, `pipeline`, `tunnel`, `linear` | on `onboard_completed`: the **shape** of the setup — counts and enums, never repo or org names |
+
+## What is not recorded
+
+Standard logs never contain:
+
+- **source code or diffs**
+- **reviewer prompts**
+- **review text** — the verdict is recorded; the prose is not
+- **PR titles or bodies**
+- **PR author logins**
+- **tokens, keys, or secrets** — the one place a token could appear is the clone URL, which is redacted to `x-access-token:[REDACTED]` on every path that could log it
+
+Error events are the one place free text lands, because a failure you cannot read is a failure you cannot fix. `message`, `stack`, and `stderr` come from the failing subprocess or API call and are truncated. They can quote a file path or a git ref. They are local files, like everything else here.
+
+### The extended tier
+
+Richer fields — PR title, body, file paths, review text, author — exist behind `logs.extended.enabled`, which is:
+
+- **off by default**,
+- **not settable from any CLI flag** and not offered by `crosscheck onboard`, so it can only be turned on by hand-editing config, and
+- **tagged** — every line it writes carries `"_extended": true`, so it can be filtered or scrubbed independently of standard logs.
+
+If you have not deliberately edited your config, this tier is off and nothing in the product will nudge you toward it.
+
+---
+
+## Transmission
+
+There is none. To be specific about what that means:
+
+- No Crosscheck-operated server exists, so there is nowhere for a payload to go.
+- No code in `src/lib/adoption.ts` or `src/commands/adoption.ts` opens a socket.
+- Reporting is a local CLI command that prints to your terminal.
+
+If opt-in transmission is ever built, it will be per-category, individually documented, off unless you turn it on, and it will print the payload that leaves your machine. Until then, "opt-in telemetry" describes a design in `prd.md`, not shipped behaviour — and the metrics above are yours alone.
+
+Related: [docs/trust.md](./trust.md) covers what leaves your machine during normal operation, which is a different question from what gets logged.

package/docs/trust.md

@@ -0,0 +1,159 @@
+# Trust: what Crosscheck reaches, sends, and changes
+
+Crosscheck runs on your machine, holds your GitHub token, clones your code, and pushes commits. This document says exactly what that means, so you can decide whether to run it without reading the source.
+
+Everything below is behaviour of the current release. Where a default is risky, it is called out as a default rather than buried.
+
+**The short version.** Crosscheck has no server. There is no Crosscheck-operated endpoint, no telemetry, no account, no phone-home, and no analytics — install it and nothing is reported anywhere. It talks to GitHub with your token, and it runs the Claude Code and Codex CLIs on your machine under *their* credentials and *their* privacy terms. On a default `watch` setup, one third party you may not expect is in the path: the webhook tunnel. See [What leaves your machine](#what-leaves-your-machine).
+
+---
+
+## What leaves your machine
+
+Five destinations, and nothing else.
+
+| Destination | What goes there | When | Avoidable? |
+|---|---|---|---|
+| `api.github.com`, `github.com` | Your token; PR reads; git clone/fetch; the comments, commit statuses, commits, branches and PRs Crosscheck writes | Every command | No — this is the product |
+| Claude Code CLI → Anthropic | The reviewer prompt, plus whatever the agent reads from the clone (it is allowed `git diff` and `git log`) — so in practice your diff and relevant source | Review, fix, recheck, conflict-resolve steps | Yes — disable the vendor in config |
+| Codex CLI → OpenAI | Same, for Codex-assigned steps | Same | Yes — disable the vendor in config |
+| Tunnel relay — `localhost.run` (default) or `smee.io` | GitHub's webhook deliveries for your monitored repos: PR metadata, author, branch, head sha, and PR body as GitHub sends it | `crosscheck watch` only | Yes — see below |
+| `api.linear.app` | Issue reads (enrichment) and verdict comments | Only when Linear is configured; off by default | Yes — leave it off |
+
+Two things to be precise about, because they are the parts people get wrong:
+
+**Crosscheck does not upload your code. The vendor CLIs do.** Crosscheck clones your repo to a temp directory and runs `claude` or `codex` as a subprocess pointed at that directory. Your diff reaches Anthropic or OpenAI through those CLIs, under the credentials you already logged into them with and under their data-handling terms — the same exposure you have when you run `claude` in your own checkout. Crosscheck adds no separate upload path. If a repo cannot go to a model vendor, Crosscheck is not the tool that changes that.
+
+**The webhook tunnel is a third party in the path.** `crosscheck watch` needs a public URL for GitHub to POST to, and by default it opens an SSH tunnel through `localhost.run`. GitHub's webhook payloads for your monitored repos therefore transit a relay operated by someone else. Deliveries are HMAC-signed and Crosscheck rejects anything whose signature does not verify (`webhook_sig_invalid`), so a relay cannot *forge* events — but it can *see* payloads, which include PR titles, bodies, branch names and author logins. Payloads carry no source diff and no token.
+
+To avoid the relay entirely, don't run `watch`. Everything Crosscheck does is available as a one-shot command that needs no inbound connection:
+
+```bash
+crosscheck run https://github.com/acme/web/pull/245
+```
+
+Run that from cron, from CI, or by hand. Or use `tunnel.backend: smee` with your own [smee.io](https://smee.io/new) channel if you prefer a named relay that queues events while you are offline — same trade, different operator. Self-hosting the relay is not supported today.
+
+---
+
+## GitHub permissions
+
+Crosscheck uses whatever token `gh auth login` already produced — it does not mint its own, and it never asks you to paste one into a config file.
+
+| Scope | Needed for | Required? |
+|---|---|---|
+| `repo` | Clone, fetch, push; read PRs; post comments; write the `crosscheck/review` commit status | Yes |
+| `admin:repo_hook` | Register the webhook on individual repos | `watch` with repo-level scopes only |
+| `admin:org_hook` (`write:org`) | Register one webhook per org instead of per repo | `watch` with org-level scopes only |
+
+`repo` is a coarse scope, and it is coarse because git push over HTTPS needs it. If that is more than you want to grant, the narrow path is a fine-grained PAT limited to the specific repositories you intend to review, exported as `GITHUB_TOKEN`. Crosscheck reads the token from `gh`'s keyring first and falls back to `GITHUB_TOKEN` / `GH_TOKEN`, so a scoped PAT in your shell is a drop-in.
+
+Without the hook scopes, `watch` still runs — it just cannot register its own webhook, and you point one at the tunnel URL yourself.
+
+---
+
+## Webhooks: registration and removal
+
+`crosscheck watch` registers hooks at startup and removes them at shutdown.
+
+**Registered:** one hook per monitored org (preferred) or per monitored repo, `active: true`, events `pull_request` and `issue_comment` only, `content_type: json`, pointed at your tunnel URL, with an HMAC secret. If a Crosscheck hook already exists, the existing one is reused and its event list patched rather than a second one created — restarts do not accumulate hooks.
+
+**Removed:** on `Ctrl-C` or `SIGTERM`, `watch` deletes every hook it registered in that session before exiting.
+
+**The gap you should know about:** an abnormal exit — uncaught exception, `SIGKILL`, power loss — skips that cleanup, and the hook stays registered and pointed at a tunnel URL that no longer answers. GitHub will retry deliveries, fail, and eventually show the hook as failing. Nothing leaks (the endpoint is gone, and the payload was going to your machine), but the hook is orphaned. Two ways to clear it:
+
+- Start `watch` again. It finds the existing hook and reuses it, which also repoints it at the new tunnel URL.
+- Delete it by hand: repo or org **Settings → Webhooks**, remove the entry whose payload URL is your old tunnel.
+
+Note that with `tunnel.backend: smee`, the channel URL is stable and hooks are *meant* to outlive the session — that is the point of using smee. They persist until you delete them.
+
+---
+
+## What Crosscheck can change
+
+The workflow is a sequence of steps, and each step's mutations are listed below. What runs is `~/.crosscheck/workflow.yml`, narrowable per repo — so this table is also the menu of what you can switch off.
+
+| Step | What it writes to your repo |
+|---|---|
+| **review** | One PR comment (the review, with a hidden `<!-- crosscheck: ... -->` annotation). One commit status, context `crosscheck/review`: `pending` while running, then `success` or `failure`. Optionally one Linear comment. **No code.** |
+| **recheck** | Same as review — a second comment, and release of the pending status. **No code.** |
+| **fix** | Code. Commits to the PR's own branch and pushes there, plus a "fix applied" comment. If that push cannot land (protected branch, deleted branch, fork), it pushes the same commit to `fix/cr-<pr>-review-issues`, opens a follow-up PR targeting the original branch, and labels it `cr-autofix`. In `delivery.mode: comment` it pushes nothing and posts the diff as a suggestion instead. |
+| **conflict-resolve** | Code. Merges the base branch into the PR branch, resolves conflicts, and pushes the merge commit to the PR branch, plus a comment. Skipped for fork PRs. |
+
+Boundaries that hold across every step:
+
+- **Never merges.** No command merges a pull request — there is no code path from any verdict to a merge. `crosscheck scan` will tell you a PR looks merge-ready; a human or your own automation acts on that.
+- **Never touches your base branch.** Pushes go to the PR's head branch or to a new `fix/cr-*` branch. `main` and `staging` are only ever read.
+- **Never force-pushes over your work.** A rejected non-fast-forward push is retried by rebasing onto the remote branch; if that fails it gives up and falls back to the follow-up PR.
+- **Never edits outside the clone.** All work happens in a `mkdtemp` directory that is deleted when the step finishes, pass or fail.
+- **Repo review guidance is read from the base branch,** not from the PR — a PR cannot rewrite the rules it will be reviewed under.
+- **Automation triggers are authenticated.** The comment bridge that advances a workflow only fires for annotations posted by the token's own account; a comment from anyone else carrying the same hidden marker is ignored and logged as `annotation_injection_blocked`.
+
+One boundary is *not* Crosscheck's to enforce, and you should know which: **what the reviewer agent may execute inside the clone is the vendor CLI's decision, not Crosscheck's.** Crosscheck itself never runs your project's code — no install, no test, no build. For Claude steps it passes an explicit tool allowlist of `Bash(git diff)` and `Bash(git log)`, so a review is confined to reading history. For Codex steps it invokes `codex exec` and passes no sandbox override, so the agent operates under Codex's own default policy for non-interactive runs — which necessarily permits writing files in the clone, since that is how a Codex fix lands. If your threat model requires a specific sandbox for agent execution, set it in the Codex CLI's own configuration; Crosscheck will not override it.
+
+---
+
+## Trying it on one PR first
+
+Fully read-only. Clones the repo, runs the review, prints the comment it *would* post, and exits. No comment, no commit status, no Linear write, no lock:
+
+```bash
+crosscheck run https://github.com/acme/web/pull/245 --dry-run
+```
+
+When you want the comment but still no code changes:
+
+```bash
+crosscheck run https://github.com/acme/web/pull/245 --review-only
+```
+
+Neither command needs a webhook, a tunnel, or `watch`. There is also a [public fixture PR](./fixture-pr.md) if you would rather not point a first run at your own code.
+
+---
+
+## Turning off auto-fix
+
+Three levels, from narrowest to broadest.
+
+**One repo, permanently** — review and recheck only, no code ever pushed to it:
+
+```bash
+crosscheck alter acme/legacy-service --review-only
+```
+
+The override lands in `~/.crosscheck/workflows/acme__legacy-service.yml` and is read per PR event, so it takes effect without restarting `watch`. `crosscheck alter acme/legacy-service --show` prints what is in force.
+
+**Everywhere, but keep the suggestions** — fixes are posted as a diff in a comment instead of pushed:
+
+```yaml
+post_review:
+  auto_fix:
+    delivery:
+      mode: comment
+```
+
+**Everywhere, entirely** — remove the `fix` and `recheck` steps from `~/.crosscheck/workflow.yml`, or narrow each repo with `crosscheck alter <repo> --steps review`.
+
+---
+
+## Secrets and local logs
+
+**Secrets are never written to config.** `crosscheck.config.yml` stores environment variable *names* (`api_key_env: LINEAR_API_KEY`), never values. The GitHub token comes from `gh`'s keyring or your environment at call time. The webhook HMAC secret is read from your environment.
+
+**The one place a token is embedded is the clone URL** (`https://x-access-token:<token>@github.com/...`), which is how git authenticates over HTTPS. Every log and error path that could carry that URL runs it through a redactor first, so it appears as `x-access-token:[REDACTED]`. Use `clone_protocol: ssh` if you would rather it never be constructed.
+
+**Logs are local files, and that is the only place they go.** `~/.crosscheck/logs/<date>.ndjson`, one JSON object per line, enabled by default (`logs.enabled`), pruned by age (`logs.retention_days`, default 30). They power `crosscheck diagnose`, `optimize`, and `impact` — all of which read these files and make no network calls.
+
+What a standard log line contains: repo and PR number, event name, verdict, vendor and model, token counts, durations, commit shas, error category. What it deliberately does not contain: **source code, diffs, prompts, review text, PR titles or bodies, or author logins.**
+
+Those richer fields exist behind `logs.extended.enabled`, which is **off by default and not exposed by any CLI flag or by `onboard`** — it can only be turned on by hand-editing config, and every line it writes is tagged `"_extended": true` so it can be filtered or scrubbed separately. Turning it on is a deliberate act; nothing in the product nudges you toward it.
+
+To keep no local history at all, set `logs.enabled: false`. `diagnose`, `optimize` and `impact` will have nothing to read, which is the whole trade.
+
+Other state under `~/.crosscheck/`: your config, per-repo workflow overrides, and small caches of already-seen commit shas and diff hashes (used to avoid re-reviewing the same code). Shas and hashes, no content.
+
+---
+
+## Reporting a security issue
+
+Email <yi@inductive.network> rather than opening a public issue.

package/get-started.md

@@ -26,6 +26,7 @@
   - [diagnose](#crosscheck-diagnose)
   - [optimize](#crosscheck-optimize)
   - [impact](#crosscheck-impact)
+  - [adoption](#crosscheck-adoption)
   - [issue](#crosscheck-issue)
 - [Configuration](#configuration)
 - [How it works](#how-it-works)
@@ -235,6 +236,8 @@ crosscheck review https://github.com/owner/repo/pull/123 --reviewer codex
 
 If this step fails, fix the specific auth, clone, reviewer, or comment-posting error before enabling `watch`.
 
+If you'd rather nothing be written to the PR on a first run, use `crosscheck run <pr-url> --dry-run` instead: it clones, reviews, and prints the comment it would post without touching GitHub. (`--dry-run` lives on `run`, `fix`, `recheck`, and `resolve` — not on `review`, which always posts.) [docs/trust.md](./docs/trust.md) covers what leaves your machine at each step, which permissions each command needs, and exactly what `watch` can change.
+
 ## Step 3 — Choose a deployment mode
 
 After one-shot review works, run the guided setup:
@@ -528,6 +531,8 @@ crosscheck alter humanbased-ai/xny-monorepo --reset                  # remove th
 
 The depths differ in what happens after the initial review:
 
+In every depth, an `APPROVE` stops all work on the commit it covers, and a later push re-opens the PR — see [What happens after a PR is approved?](#what-happens-after-a-pr-is-approved).
+
 - **`review`** — review each new SHA; never modify code.
 - **`review,fix`** — crosscheck auto-applies fixes when the verdict isn't `APPROVE`, and stops there; its own fix commit is not re-reviewed.
 - **`review,fix,recheck`** — same, then rechecks its own fix commit. `max_rounds` in `~/.crosscheck/workflow.yml` bounds that fix→recheck cycle.
@@ -679,7 +684,7 @@ crosscheck scan --json
 
 ### `crosscheck kickass`
 
-Selects all actionable PRs (any PR where a next step is needed: review, fix, recheck) and advances each one. Stale PRs are shown first. APPROVE PRs appear as a read-only "needs merge (manual)" section — visible so you know what's ready, but not dispatched automatically. The command revalidates the PR head before each mutation and prints an execution summary when it finishes.
+Selects all actionable PRs (any PR where a next step is needed: resolve, review, fix, recheck) and advances each one. A PR with merge conflicts is dispatched as a `resolve` leg first — conflicts block everything downstream, and a base-branch move that conflicts a PR fires no webhook, so a scan is the only thing that notices. Stale PRs are shown first. APPROVE PRs appear as a read-only "needs merge (manual)" section — visible so you know what's ready, but not dispatched automatically. The command revalidates the PR head before each mutation and prints an execution summary when it finishes.
 
 Each PR dispatch uses `detect-step` to read live PR comment history and advances **exactly the next needed step** — kickass drives one step per PR, then `watch` picks up continuation via the webhooks that step produces.
 
@@ -976,6 +981,65 @@ crosscheck impact  (all time · 47 reviews)
 | `--json` | Output the full report as JSON |
 | `-c, --config <path>` | Config file path |
 
+---
+
+### `crosscheck adoption`
+
+Reports whether crosscheck is actually being used, and how long a PR waits for a verdict. Where `impact` prices reviews that happened, `adoption` measures activation and reach. Reads from `~/.crosscheck/logs/` — no network calls, nothing transmitted.
+
+```bash
+crosscheck adoption
+crosscheck adoption --since 2026-07-01
+crosscheck adoption --json
+```
+
+```
+crosscheck adoption  (2026-06-15 → 2026-07-14)
+
+  Activation
+  ──────────────────────────────────────────────
+  onboard started            3
+  onboard completed          2
+  abandoned                  1
+
+  Usage
+  ──────────────────────────────────────────────
+  reviews started            51
+  reviews completed          47
+  rechecks completed         12
+  blocking findings posted   19
+  fixes applied              11
+  active repos               6
+
+  Weekly active repos
+  ──────────────────────────────────────────────
+  2026-06-22  ████████          3 repos  14 reviews
+  2026-06-29  ████████████      4 repos  18 reviews
+  2026-07-06  ████████████████  6 repos  15 reviews
+
+  PR open → verdict
+  ──────────────────────────────────────────────
+  median                     22m
+  p90                        1.8h
+  slowest                    2d
+  measured on 41 verdicts
+  ⓘ 6 verdicts had no PR open time in the event — excluded
+
+  First-run failures  (sessions that never reached a verdict)
+  ──────────────────────────────────────────────
+  auth                       2
+
+  ⓘ derived from local logs only (30d retention) — nothing is transmitted. See docs/metrics.md
+```
+
+| Flag | Description |
+|---|---|
+| `--since <YYYY-MM-DD>` | Limit the analysis to logs from this date onward |
+| `--json` | Output the full report as JSON |
+| `-c, --config <path>` | Config file path |
+
+Every field these numbers are derived from is inventoried in **[docs/metrics.md](./docs/metrics.md)**, including what is deliberately never written to disk.
+
 The monetary estimate formula: `(hours_saved × hourly_rate_usd) + (issues_caught × defect_cost_usd)`. Defaults: `$150/hr`, `$150/issue`. Both configurable in `crosscheck.config.yml` under `impact`.
 
 ---
@@ -1138,6 +1202,17 @@ skills:
     # - code-review         # preloaded, opt-in · @mattpocock, MIT
     # - codebase-design     # preloaded, opt-in · @mattpocock, MIT
 
+  # Codex only. Codex reaches the skill broker (an MCP server) only when its
+  # sandbox is disabled: under -s read-only, -s workspace-write, -a never and
+  # --full-auto alike it cancels every tool call, so skills silently do nothing.
+  # Turning this on lets codex run unsandboxed against the PR checkout — which is
+  # untrusted code — in exchange for skills actually working. Crosscheck removes
+  # the git credential from the checkout and passes codex an allowlisted
+  # environment (no GITHUB_TOKEN) either way, but a prompt injection can still
+  # read the working tree and reach the network. Claude needs none of this: its
+  # broker works sandboxed.
+  codex_full_access: false
+
 # ── Budget ────────────────────────────────────────────────────────────────────
 budget:
   codex_monthly_usd: 20     # null = unlimited; only applies when auth: api-key
@@ -1174,6 +1249,13 @@ routing:
   #   2. Commit message Co-Authored-By: trailers (API call, non-fatal if it fails)
   #   3. Branch prefix (claude/ or codex/)
   #   4. author_routes fallback (last resort)
+  # These say who WROTE the code, not who reviewed it.
+  #
+  # Crosscheck's own attribution — its fix-PR footer and `Crosscheck-Reviewer`
+  # commit trailers — is recognised ALWAYS, whatever you put here. Setting either
+  # list replaces the defaults, so if these markers lived in the list a pinned
+  # config would misread crosscheck's own fix PRs as human-authored. Your patterns
+  # are checked first and still win.
   codex_reviews_patterns:
     - "Generated with \\[Claude Code\\]"    # Claude Code attribution footer
     - "Co-Authored-By: Claude"              # commit trailer
@@ -1222,8 +1304,9 @@ post_review:
   auto_fix:
     delivery:
       mode: pull_request      # pull_request | commit | comment
-      # pull_request → fix PR targets original branch; human approves before merge
-      # commit       → fixes pushed directly onto the original PR branch
+      # pull_request → fixes land on the original PR branch; a separate fix PR is
+      #                opened only if that push can't land (branch merged/deleted/protected)
+      # commit       → fixes pushed directly onto the original PR branch (no fallback)
       # comment      → suggested fixes posted as review comments only
       pr_title: "fix: address CR issues in #{original_pr_title}"
       label: cr-autofix       # GitHub label applied to the fix PR
@@ -1529,7 +1612,7 @@ agent opens PR #42  →  opposite vendor reviews  →  issues found?
 | Setting | Default | Why |
 |---|---|---|
 | `fixer: same-as-author` | the vendor that wrote the PR also fixes it | The authoring agent knows its own code and style best |
-| `delivery: pull_request` | opens a new PR, doesn't push directly | You stay in the loop — no code lands without your approval |
+| `delivery: pull_request` | pushes the fix onto the PR's own branch, so the fix, recheck, and approval stay on one PR; opens a separate fix PR only when that push can't land | Keeps everything on the original PR while still covering merged/protected branches |
 | `trigger: on_issues` | only fires when the reviewer found warnings or worse | Skips the fix step on clean PRs |
 | `min_severity: warning` | ignores info/cosmetic findings | Avoids noisy fix PRs for style-only comments |
 
@@ -1644,11 +1727,38 @@ Each cycle is one `[crosscheck]` fix commit followed by one recheck. The loop st
 
 `max_rounds` is respected by both `crosscheck watch` and `crosscheck run`. `watch` re-triggers on each pushed fix commit; `run` loops inline within the same session.
 
+### My PR became conflicted — will crosscheck resolve it?
+
+Yes, if your workflow has a `conflict-resolve` step (the `onboard` default does). Conflicts are handled independently of the review ladder, because a PR usually conflicts when the **base branch** moves — which changes nothing about the code that was reviewed.
+
+The catch is that a base-branch move fires no webhook on your PR, so `watch` never hears about it. `crosscheck scan` and `crosscheck kickass` are what notice: a conflicted PR shows `next=resolve` and is dispatched ahead of review, fix, and recheck. An approved PR that can no longer merge is resolved too — the merge commit then moves HEAD off the approved SHA, so the merged code gets a fresh review.
+
+```bash
+crosscheck kickass          # picks up conflicted PRs along with everything else
+crosscheck resolve <pr-url> # or force just the conflict-resolve step
+```
+
+Fork PRs are skipped, same as with auto-fix — crosscheck cannot push to them. Repos narrowed to `review` or `review,recheck` never resolve conflicts either, since that would modify code.
+
+### What happens after a PR is approved?
+
+Crosscheck stops working on that commit. Once the newest verdict is `APPROVE` and it covers the PR's current HEAD, no further step runs — not a recheck, not a re-review. `watch` skips further events on that SHA, `crosscheck run` prints `this commit is already approved — nothing to do until new commits land`, and `kickass` lists the PR under "needs merge (manual)" instead of dispatching it.
+
+**A push re-opens it.** New commits materially change what was approved, so the approval no longer applies: the next event runs a fresh review (round *n*+1) on the new code, and the full fix/recheck loop resumes from there. An `APPROVE` posted before the annotation carried a `sha=` field can't prove which commit it covers, so it is treated the same way — one review re-establishes it.
+
+To force another pass on the approved commit itself, name the steps explicitly — that bypasses history detection:
+
+```bash
+crosscheck run https://github.com/owner/repo/pull/123 --steps review
+```
+
+`crosscheck detect-step <pr-url>` shows the stop reason for any PR.
+
 ### Can I disable the auto-fix step?
 
 Yes. Set `post_review.auto_fix.enabled: false` in your config, or set `trigger: never`. You can also raise `min_severity` to `error` to limit fixes to blocking issues only.
 
-To push fixes directly without a separate PR (skipping your review), switch to `delivery: commit`. To get suggested fixes as review comments without any code push, use `delivery: comment`.
+Both `delivery: pull_request` (the default) and `delivery: commit` push the fix directly onto the PR's own branch. The only difference is the fallback: `pull_request` opens a separate fix PR if that push can't land (branch merged, deleted, or protected), whereas `commit` surfaces the push failure instead. To get suggested fixes as review comments without any code push, use `delivery: comment`.
 
 ### Why does the fixer use the same vendor that wrote the PR?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanbased/crosscheck",
-  "version": "1.2.0-beta.81",
+  "version": "1.3.0-beta.100",
   "description": "AI code review pipeline that turns agent-written PRs into merge-ready patches",
   "bin": {
     "crosscheck": "dist/cli.js",
@@ -43,8 +43,10 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "eslint": "^9.39.5",
     "tsx": "^4.16.0",
     "typescript": "^5.5.0",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^3.2.4"
   },
   "keywords": [