@humanbased/crosscheck 1.3.1-beta.7 → 1.6.0-beta.5

package/docs/growth/launch/posts.md

@@ -0,0 +1,175 @@
+# Launch posts — drafts
+
+> **Not published.** These are drafts for a human to post. Every number traces to
+> [`docs/dynamic-thoroughness.md`](../../dynamic-thoroughness.md). Read
+> [`README.md`](./README.md) in this folder before posting anything — particularly the
+> self-promotion rules per community, which differ and are enforced.
+
+The through-line in all of them: **the reviewer being correct was not the bottleneck.** That is the one non-obvious thing we learned, and it is what earns attention. Lead with it rather than with the product.
+
+---
+
+## X / Twitter
+
+**Version A — the finding (recommended)**
+
+> We built an AI code reviewer. Of 40 BLOCK findings sampled, 39 were verifiable; none were false.
+>
+> Yet 62% of PRs merged past its findings. Median review-to-merge gap: 4 minutes.
+>
+> Being right isn't a gate. [link]
+
+**Version B — the failure mode**
+
+> Ask the agent that wrote a patch to review it and it'll say it's good. The reasoning that produced the bug is now judging it.
+>
+> Not a prompt problem: blind spot and reviewer share a context window.
+>
+> Our Claude PRs go to Codex, and back. [link]
+
+**Version C — one concrete defect**
+
+> A function took an `expected_mode` param for dual-control confirmation and never put it in the request body. Two lines apart. Dual control silently bypassed. Tests passed.
+>
+> The agent that wrote it called it done. A different agent caught it.
+>
+> [link]
+
+Thread continuation for A or B, if you want one:
+
+> 2/ The census: 400 merged PRs, 199 crosscheck-engaged, one week.
+>
+> Reviews landed before merge 94% of the time. 38% of PRs reached APPROVE. 56% of the rest merged within five minutes of the review — or before it landed.
+>
+> 3/ The reason was ours: crosscheck created a lifecycle status while a run was in flight, but the verdict lived only in a comment. `crosscheck/review` wasn't required by branch protection, so GitHub merged the second CI went green.
+>
+> 4/ The trap: gating first would have made it worse. Findings never stopped arriving, so an enforced unbounded loop turns "merged in 4 minutes" into "blocked for two days."
+>
+> Bound the loop, then gate, then optimize latency. In that order.
+>
+> 5/ MIT, shells out to configured vendor CLIs. With subscription-authenticated Claude and Codex, there's no separate hosted service or per-review API bill; API-key auth is also supported.
+>
+> Try it with Crosscheck's own writes suppressed: `crosscheck run <pr-url> --dry-run` (the vendor CLI still runs under its configured permissions).
+>
+> [repo link]
+
+---
+
+## LinkedIn
+
+> **We measured our AI code reviewer and the result inverted the roadmap.**
+>
+> We build with coding agents daily. The failure mode that costs us isn't a broken build — CI catches those. It's what we've started calling early victory: a patch that passes CI, reads as complete, has a confident summary attached, and quietly carries a regression or a half-finished fix.
+>
+> Asking the agent that wrote the patch to review it doesn't help. The reasoning that produced the bug is the reasoning now judging it.
+>
+> In our two-vendor setup, we routed each PR to a *different* agent — Claude-authored PRs to Codex, and back — with findings returning to the author agent for repair and a recheck before merge.
+>
+> Then we ran a census: 400 merged PRs over one week, 199 of them reviewed by the system. We sampled 40 of its blocking findings and hand-read each against the file it cited.
+>
+> Of 40 sampled findings, 39 were verifiable and none were false; one was unverifiable. ~85% of the verifiable findings were genuine defects. Reviews landed before merge 94% of the time.
+>
+> And 62% of PRs merged straight past them. Median gap from last review to merge: four minutes.
+>
+> The problem was never review quality. The verdict lived in a comment, and `crosscheck/review` wasn't required by branch protection, so GitHub merged the moment CI went green.
+>
+> The counter-intuitive part: adding the gate first would have made things worse. Findings never stopped arriving across rounds, and enforcing an unbounded loop converts "merged past findings in four minutes" into "blocked for two days." Bound the loop, then gate, then optimize latency.
+>
+> Two things I'd take to any team shipping agent-authored code:
+>
+> → Don't let the author review its own work. Treat it as an architectural constraint, not a prompt preference.
+> → Measure whether your review changes the merge decision — the share of real defects fixed inside the merge window. Not findings per PR.
+>
+> Crosscheck is MIT and shells out to configured vendor CLIs. With subscription authentication, there is no separate per-review API bill; API-key authentication is also supported. Full census, including the two analytical approaches we abandoned, is in the repo.
+>
+> [repo link]
+
+---
+
+## Hacker News — Show HN
+
+**Title** (80 char limit; both fit)
+
+- `Show HN: Crosscheck – route agent-authored PRs to a different agent for review`
+- `Show HN: We measured our AI code reviewer; being correct wasn't the bottleneck`
+
+Prefer the first for a Show HN — it says what the thing is. Use the second as a regular submission of the essay if the Show HN doesn't land.
+
+**First comment** (post immediately after submitting)
+
+> Author here. When both vendors are configured, Crosscheck routes each agent-authored PR to a *different* agent than the one that wrote it — Claude-authored PRs to Codex and vice versa — then sends findings back to the author agent to fix and rechecks before the PR is merge-ready. It shells out to the configured CLIs rather than adding a hosted service. With subscription authentication, there is no separate per-review API bill; API-key authentication is also supported.
+>
+> The motivating failure isn't broken builds. It's patches that pass CI, read as complete, and carry a regression or a fix that addresses the symptom rather than the cause. Asking the authoring agent to review its own work doesn't catch those — the reasoning that produced the bug is the one judging it.
+>
+> The part I'd actually like feedback on is what happened when we measured it. We censused 400 merged PRs over a week (199 crosscheck-engaged), sampled 40 BLOCK findings, and hand-read each against the file it cited at the reviewed sha: 39 were verifiable and none were false; one was unverifiable. ~85% of the verifiable findings were genuine defects, and 94% of reviews landed before merge.
+>
+> And 62% of PRs merged past them anyway, median four minutes after the last review. The cause was structural and ours: crosscheck created a lifecycle status while a run was in flight, but the verdict lived only in a comment and `crosscheck/review` wasn't required by branch protection. GitHub merged as soon as CI went green.
+>
+> What surprised me is that fixing that first would have been harmful. Findings kept arriving across rounds, so enforcing an unbounded loop turns "merged past findings in four minutes" into "blocked for two days." The order has to be: bound the loop, then gate, then reduce latency.
+>
+> Honest limits: it never merges on its own — only a person running `crosscheck merge` can reach the gated merge path. It doesn't replace human review, and your diff reaches Anthropic/OpenAI through their own CLIs under their terms — crosscheck adds no separate upload path. The census is one team, one week, our conventions; I'd be interested in whether the 4-minute number reproduces elsewhere or whether we're just undisciplined.
+>
+> First run with Crosscheck's GitHub writes suppressed: `crosscheck run <pr-url> --dry-run`. It still clones locally and invokes the configured vendor CLI under that CLI's permissions.
+>
+> MIT: [repo link]. The census, including two analytical approaches we abandoned, is in docs/dynamic-thoroughness.md.
+
+**Notes for the poster**
+
+- Submit the repo URL, not the essay, for a Show HN.
+- Be present for the first two hours. The questions to expect: "isn't this just two LLMs agreeing with each other," "what's the token cost per PR," "why not use existing review bots," and "0 false positives is not believable." Answer the last one with the labelling method (hand-read against the cited sha, seeded sample, 6 severity-inflated cases counted as *true*) rather than restating the number.
+- Do not seed upvotes or comments. HN detects it and it ends the launch.
+
+---
+
+## Reddit
+
+Community rules on self-promotion differ, several ban it outright, and moderators enforce it. Check each sidebar before posting; where promotion is restricted, post the essay's finding as a discussion and mention the tool only if asked.
+
+### r/ExperiencedDevs — discussion framing, no product lead
+
+**Title:** `39 verifiable AI code-review findings, 0 false — and 62% of PRs merged past them anyway.`
+
+> We ship a lot of agent-authored PRs and built an independent reviewer for them (a different model than the one that wrote the patch). Before trusting it we ran a census: 400 merged PRs over a week, sampled 40 of its blocking findings, and hand-read each one against the file it cited at the sha it was reviewed at.
+>
+> Of the 40 sampled findings, 39 were verifiable and none were false; one was unverifiable. ~85% of the verifiable findings were genuine defects. 94% of reviews landed before the merge.
+>
+> Then the uncomfortable number: only 38% of PRs reached an approving verdict, and the median gap between the last review and the merge was 4 minutes. Most PRs merged straight past correct findings.
+>
+> The cause turned out to be structural rather than about review quality: the verdict lived only in a PR comment. Crosscheck created a lifecycle status while the run was in flight, but that status did not represent the verdict and appeared in no branch protection rule, so nothing stopped a merge the moment CI went green.
+>
+> What I didn't expect: adding the required check first would have made it worse. Findings kept arriving in later rounds, so enforcing an unbounded review loop converts "merged in 4 minutes" into "blocked for two days." We had to bound the loop before gating it.
+>
+> Curious whether others measuring review effectiveness see the same thing — that precision and latency aren't the binding constraint, and the review simply isn't part of the merge decision. And how you bounded the loop without capping it somewhere arbitrary.
+
+### r/ClaudeAI and r/ClaudeCode — practitioner framing
+
+**Title:** `Stopped letting Claude review its own PRs — routed them to Codex instead. Here's what the findings looked like.`
+
+> I use Claude Code as my main author. Asking it to review its own patch was consistently useless — not wrong exactly, just agreeable. The reasoning that wrote the bug is the reasoning judging it, and it already convinced itself once.
+>
+> So I wired up both vendors: Claude-authored PRs go to Codex, Codex-authored PRs go to Claude, findings return to the original author agent to fix, then a recheck.
+>
+> Sampled 40 of the blocking findings and hand-checked them against the source. Of 39 verifiable findings, none were false; one was unverifiable. The good ones weren't lint-grade — they read the repo's own convention docs and traced call paths across services. One caught a function that accepted an `expected_mode` param for dual-control confirmation and never put it in the request body. Two lines apart, tests green.
+>
+> It shells out to the configured `claude` and `codex` CLIs. With subscription authentication, there is no separate per-review API bill; API-key authentication is also supported. MIT.
+>
+> To suppress Crosscheck's own GitHub writes on a first run: `crosscheck run <pr-url> --dry-run`. It still clones locally and invokes the vendor CLI under that CLI's configured permissions.
+>
+> [repo link]
+
+### r/ChatGPTCoding — same shape, Codex-first
+
+Use the r/ClaudeAI draft with the vendors swapped: Codex as the author, Claude as the reviewer. Keep the concrete defect example — it is what makes the post land.
+
+---
+
+## What not to say
+
+Guardrails, so nothing in this launch has to be walked back:
+
+- **No invented numbers.** Everything quotable is in `docs/dynamic-thoroughness.md`. If a number isn't there, it doesn't get posted.
+- **No comparison to CR-Bench precision without the caveat.** 3.6–5.1% vs ~85% is not apples to apples; quoting it bare is the kind of claim that gets correctly torn apart.
+- **No "catches every bug."** 6 of 40 findings were severity-inflated. Say so when it comes up.
+- **No fake adoption.** No user counts, no "teams are using," no testimonials we don't have.
+- **No claim that it replaces human review.** It makes agent output reviewable.
+- **No implication that source stays local.** It reaches the model vendors through their CLIs, and the trust doc says so plainly.

package/docs/trust.md

@@ -79,10 +79,25 @@ The workflow is a sequence of steps, and each step's mutations are listed below.
 | **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. |
+| **`crosscheck merge`** (never automatic) | Merges the pull request. Not a workflow step — no verdict, webhook, or scheduled run reaches it; it happens only when a person types the command. See below. |
 
 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 merges on its own.** No verdict, webhook, or scheduled run reaches a merge — there is no code path from a review to one. The single exception is explicit: `crosscheck merge <pr-url>`, which merges only when a person runs it, and only when the gate below is satisfied. `watch`, `run`, `kickass` and `scan` cannot merge anything.
+
+  This boundary used to be absolute, and the change is worth stating plainly rather than leaving for you to notice: earlier versions had no merge code at all. If you relied on "crosscheck cannot merge, whatever it is told to do", the guarantee is now "crosscheck cannot merge unless a human invokes one specific command", which is a weaker promise. Nothing else in this document changed.
+
+  | Invocation | Merges when |
+  |---|---|
+  | `crosscheck merge <pr>` | an `APPROVE` verdict covers the exact commit being merged, and GitHub reports the PR mergeable |
+  | `--loose` | the standing verdict covers HEAD and is not `BLOCK` (so `NEEDS WORK` merges) |
+  | `--tight` | the default, plus every check green and no unresolved blocking finding |
+  | `--force` | no verdict gate at all. Logged as `merge_completed` with the verdict it overrode |
+  | `--dry-run` | never — evaluates the gate and reports |
+
+  Three things hold at every level, `--force` included. A conflicted PR is refused, because `--force` overrides crosscheck's opinion and not git's. The merge is submitted with the head SHA the gate evaluated, so GitHub rejects it if the branch moved in between — an approval can never be applied to a commit that arrived after it. And branch protection is GitHub's to enforce: crosscheck asks, and a protected branch can still say no.
+
+  To keep the old absolute guarantee, do not grant the token `contents: write`, or simply do not run the command — nothing else invokes it.
 - **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.

package/get-started.md

@@ -323,6 +323,22 @@ Waiting for PR events — Ctrl+C to stop.
 
 When you press `Ctrl+C`, the SSH tunnel and any registered webhooks are cleaned up automatically.
 
+**Browsing the session history.** The live board holds every PR the session has
+handled, not just the ones on screen. The footer says where you are:
+
+```
+  live · page 1/4  │  showing 18 of 61  │  ctrl+< older  ctrl+> newer
+```
+
+Press `ctrl+<` (or plain `<`) to page back through the history and `ctrl+>` (or
+plain `>`) to return to the live page. `ctrl+←` / `ctrl+→` work too, for
+terminals that swallow modified punctuation — macOS Terminal never forwards
+`cmd`, so use the bare `<` / `>` keys there. The live page keeps its place while
+you browse: new PR events land on it without yanking you forward. Per-event
+narration (routing decisions, strategy picks) is no longer printed between the
+rows — it goes to the file log at `~/.crosscheck/logs/`, which `crosscheck
+status` points at.
+
 **Token scope for org webhooks:** `GITHUB_TOKEN` needs `write:org` scope for org-level coverage. For repo-level, `repo` scope is sufficient.
 
 **Review-only for a repo:** make a repo post reviews and nothing else with `crosscheck alter <repo> --review-only` — crosscheck never runs the fix, recheck, or conflict-resolve steps for it, and never pushes commits to its PRs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanbased/crosscheck",
-  "version": "1.3.1-beta.7",
+  "version": "1.6.0-beta.5",
   "description": "AI code review pipeline that turns agent-written PRs into merge-ready patches",
   "bin": {
     "crosscheck": "dist/cli.js",
@@ -29,7 +29,11 @@
     "test": "vitest run",
     "lint": "eslint src --ext .ts",
     "prepublishOnly": "npm run typecheck && npm run build",
-    "verify:strategy": "node scripts/verify-review-strategy.mjs"
+    "verify:strategy": "node scripts/verify-review-strategy.mjs",
+    "demo:capture": "tsx demo/capture.ts",
+    "demo:play": "tsx demo/replay.ts",
+    "demo:record": "vhs demo/block-to-approve.tape && vhs demo/block-to-approve-short.tape",
+    "demo:time": "tsx demo/measure.ts"
   },
   "dependencies": {
     "chalk": "^5.3.0",
@@ -75,5 +79,9 @@
     "url": "https://github.com/humanbased-ai/crosscheck/issues"
   },
   "author": "Humanbased PTE LTD",
-  "license": "MIT"
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
 }