@humanbased/crosscheck 1.3.0-beta.81 → 1.3.0-beta.83

package/get-started.md

@@ -528,6 +528,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 +681,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.
 
@@ -1644,6 +1646,33 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanbased/crosscheck",
-  "version": "1.3.0-beta.81",
+  "version": "1.3.0-beta.83",
   "description": "AI code review pipeline that turns agent-written PRs into merge-ready patches",
   "bin": {
     "crosscheck": "dist/cli.js",