@brainervirus/workit-core 8.24.0 → 8.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.24.0",
+  "version": "8.25.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-fanout/SKILL.md

@@ -40,7 +40,7 @@ units of ~100+ lines each. Coupled work stays with one owner. Workit never spawn
    chain resumes. A fix round and recheck that both fail: a decider, not a
    third round; product choices go to the user (`references/orchestration.md`).
 7. **Verify by the workspace `verification` setting** (`workit grant show`).
-   A report is a pointer, never evidence. `proportional` (default): each slice's lane (`workit pr status`) decides; none needs no verdict, self the author's `--self`, focused (cheap model: Claude Code `model: sonnet`) and full a verifier after the last push. `self`: a verifier that wrote none
+   A report is a pointer, never evidence. `proportional` (default): each slice's lane (`workit pr status`) decides; none needs no verdict, self the author's `--self`, focused (cheap model: Claude Code `model: sonnet`) and full a verifier after the last push; one verdict at a stack's top covers its unchanged lower PRs, and a stale one with `reverify: focused` re-checks only the new diff, reusing green CI. `self`: a verifier that wrote none
    of the slices, or you if you wrote none. `independent` or high risk: a
    separate verifier session, never yours (doctrine: the ledger only refuses
    authors). One verifier may take a batch of slices, one verdict per branch

package/skills/workit-fanout/references/brief.md

@@ -25,7 +25,7 @@ REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
   each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
   anything out of scope as a follow-up, not a diff.
 STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
-WORKTREE: <the path `workit fanout worktree create <slice>` made; the worker runs `workit --cwd <it> …` there>
+WORKTREE: <the path `workit fanout worktree create <slice>` made; the worker runs `workit <verb> --cwd <it> …` there>
   <identity line, per the lead's host: see "Identity and git rules per host" below>
 ```
 
@@ -114,7 +114,7 @@ lead's host (`WORKIT_HOST`, or the host's own session variable):
 
 Once `workit fanout worktree create <slice>` made the worktree, the brief's
 WORKTREE line names it and RULES 1 and 3 run against it on every host:
-`workit --cwd <worktree> git commit …`, `workit --cwd <worktree> check <name>`,
+`workit git --cwd <worktree> commit …`, `workit check --cwd <worktree> <name>`,
 one verb per call. The worktree is already on the branch (MODE new or resume),
 so no branch command comes first. Without one, `MODE: resume` is
 `git switch <branch>` (the branch exists), then continue from its head. A race
@@ -124,13 +124,13 @@ attempt (`--attempt <n>`) follows its host's row with the branch
 ## Worker rules (`workit fanout brief` appends them as RULES)
 
 1. Work only in WORKTREE, already on the branch, one verb per call against it
-   (`workit --cwd <worktree> …`); Workit's hooks deny an implementer's change
+   (`workit <verb> --cwd <worktree> …`); Workit's hooks deny an implementer's change
    outside it. With no worktree made yet: create the branch (`MODE: new`) or
    `git switch` to it (`MODE: resume`), as the table above says.
 2. Decide ambiguities yourself and record them:
    `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
    Stop only for an irreversible action, a security-sensitive one, or a side
    effect outside the worktree.
-3. Commit with `workit --cwd <worktree> git commit -m "<msg>" -- <paths in SCOPE>`;
+3. Commit with `workit git --cwd <worktree> commit -m "<msg>" -- <paths in SCOPE>`;
    push only if the brief says so.
 4. Never record a verdict on your own work.

package/skills/workit-review/SKILL.md

@@ -16,6 +16,8 @@ independent; `type-check-only` never proves a behavior change.
 Depth follows the review lane in `workit pr status`: focused reads the diff and
 runs its tests; full also drives the real surface (verify-<app>). Review once
 per PR after its last push; a second pass on an unchanged head is waste.
+A stale verdict showing `reverify: focused (<files>)` in `workit pr status`: re-check only
+those files since the judged head and reuse green CI there (no fresh install, no full suite).
 
 1. Pin the candidate: `git rev-parse HEAD`, the base, `git diff <base>...HEAD`;
    for a PR, `workit pr status --json` (checks, unresolved threads).

package/skills/workit-ship/SKILL.md

@@ -51,7 +51,7 @@ the same check. Fix round and recheck both failed: a decider (workit-fanout).
    allows; no sleep loop. Red: read `logTail`, classify. Flake or infra: one
    `workit ci rerun --failed --reason flake|infra` per head. Real: reproduce
    with `workit check`, fix the root cause, batch every fix in one push.
-6. **Verified.** The lane in `workit pr status` decides: none, no verdict; self, your `--self` verdict; focused or full (or `verification: self|independent`), one non-author verifier per PR after the last push, never per push (workit-review), on Claude Code `model: sonnet` when focused. Land only when
+6. **Verified.** The lane in `workit pr status` decides: none, no verdict; self, your `--self` verdict; focused or full (or `verification: self|independent`), one non-author verifier per PR after the last push, never per push (workit-review), on Claude Code `model: sonnet` when focused. A docs-only push (or test-only under a unit verdict) keeps the verdict (`carried`); `reverify: focused` re-checks only the new diff, reusing green CI; one verdict at a stack's top covers its unchanged lower PRs. Land only when
    granted: `workit stack land` or `workit pr merge`; `--unverified --reason` if user-asked.
 7. **Observe it landed:** `workit verify-delivery pr` or `merge`. After a failed
    verdict or a check red 3+ times, at any endpoint: offer `/wk-retro` in one

package/src/core/methods.ts

@@ -125,7 +125,7 @@ Autonomy contract:
 CLI first: if a step has one right answer, use the \`workit\` verb instead of
 hand-running git, gh or glab (\`workit git|pr|ci|check|help\`;
 else \`npx -y @brainervirus/workit-cli\`).
-Other checkout: \`workit --cwd <dir> <verb>\` (Codex: \`<verb> --cwd <dir>\`); one workit
+Other checkout: \`workit <verb> --cwd <dir> …\` (verb first: host rules match it); one workit
 verb per shell call, never \`cd <dir> && workit\`. zsh-safe: no \`echo =====\`
 (\`printf '%s\\n' ---\`), quote globs and URLs, no variable named \`status\` or \`path\`.
 Add Co-Authored-By via \`workit git commit --trailer "K: v" -- <paths>\`, never
@@ -137,7 +137,7 @@ authorizes an effect. Judge work once with
 \`workit policy assess --judge risk= behavior= product-choice= plan=\`.
 Across repositories, bind items to checkout, branch and endpoint, resolve
 competing targets before a mutation, and reconcile an uncertain
-external effect before a retry.
+effect before a retry.
 
 Mid-task: never silently drop or resume an objective (workit-continue).
 

package/src/core/policy/carry.ts

@@ -0,0 +1,74 @@
+// Verdict carry-over across a follow-up change (#334, decision mvk5q3io): a
+// verdict judged head H; the branch is now at H'. The branch's own change
+// since H (what came from the base left out, see lane.ts driftFiles) is
+// classified with the review lane, and the verdict still applies when:
+//
+//   lane-none   that change is lane `none`: docs, comment or formatting-only
+//               edits, generated copies (by the base's .gitattributes), or
+//               nothing at all (an empty commit);
+//   tests-only  the verdict is kind `unit` and the change is lane `self`
+//               (small) with every behavior file a test: test files off risk
+//               paths, no lockfile, no binary.
+//
+// Everything else is stale, failing closed: a behavior or risk-path change,
+// an opaque file, an unreadable diff, a judged head git no longer has. A
+// stale verdict whose change is lane `self` (small, no risk path, nothing
+// opaque) asks only a focused re-verify of the changed files.
+import { mergeBase, fileAt } from "../../git/rev";
+import { computeLane, driftFiles, kindOf, parseRiskPaths, RISK_PATHS_FILE } from "./lane";
+
+export type CarryRule = "lane-none" | "tests-only";
+
+export type Drift =
+  | { carries: true; rule: CarryRule; since: string; files: string[] }
+  | {
+      carries: false;
+      since: string;
+      /** The changed files, or null when they cannot be read. */
+      files: string[] | null;
+      /** A focused re-verify of `files` is enough (lane self). */
+      focused: boolean;
+      reason: string;
+    };
+
+const TEST_ONLY_KINDS: ReadonlySet<string> = new Set(["doc", "cosmetic", "generated", "test"]);
+
+/**
+ * Whether a `kind` verdict at `from` (keyed against `fromBase`, a commit)
+ * still applies at `to` (against `toBase`).
+ */
+export function verdictDrift(
+  cwd: string,
+  input: { from: string; to: string; fromBase: string; toBase: string; kind: string },
+): Drift {
+  const since = input.from;
+  const stale = (reason: string, files: string[] | null = null, focused = false): Drift => ({
+    carries: false,
+    since,
+    files,
+    focused,
+    reason,
+  });
+  const fromFork = mergeBase(cwd, input.fromBase, input.from);
+  const toFork = mergeBase(cwd, input.toBase, input.to);
+  const files =
+    fromFork && toFork
+      ? driftFiles(cwd, { from: input.from, to: input.to, fromFork, toFork })
+      : null;
+  if (!fromFork || !toFork || !files)
+    return stale(`the change since ${since.slice(0, 12)} cannot be read`);
+  // Repo risk paths from both base revisions: they only tighten.
+  const riskPaths = [fromFork, toFork].flatMap((fork) =>
+    parseRiskPaths(fileAt(cwd, fork, RISK_PATHS_FILE) ?? ""),
+  );
+  const lane = computeLane({ files, riskPaths });
+  const paths = files.map((file) => file.path);
+  if (lane.lane === "none") return { carries: true, rule: "lane-none", since, files: paths };
+  if (
+    input.kind === "unit" &&
+    lane.lane === "self" &&
+    files.every((file) => TEST_ONLY_KINDS.has(kindOf(file)))
+  )
+    return { carries: true, rule: "tests-only", since, files: paths };
+  return stale(lane.reasons[0] ?? `lane ${lane.lane}`, paths, lane.lane === "self");
+}

package/src/core/policy/lane.ts

@@ -25,15 +25,18 @@ import {
   diffNumstat,
   diffRaw,
   fileAt,
+  isTracked,
   mergeBase,
+  ownChangeDrift,
   readBlobs,
   resolveRef,
   treeFilesNamed,
   untrackedFiles,
+  worktreeTop,
 } from "../../git/rev";
 import type { VerificationMode } from "../../autonomy";
-import { git } from "../../git/ops";
-import { defaultBase, type VerdictCheck } from "../../ledger";
+import { defaultBase } from "../../git/default-base";
+import type { VerdictCheck } from "../../ledger";
 import { generatedByAttributes } from "./attributes";
 import { cosmeticChange, hasOpaqueLineBreak } from "./substance";
 
@@ -117,14 +120,21 @@ const LOCKFILES = new Set([
   "composer.lock",
 ]);
 
-/** Docs are told by extension only: code under `docs/` is code. */
-const DOC_EXT = /\.(?:md|mdx|markdown|rst|adoc|txt)$/iu;
+/**
+ * Docs are told by prose extension only: code under `docs/` is code. `.txt`
+ * is not a doc: requirements.txt, CMakeLists.txt or robots.txt change behavior.
+ */
+const DOC_EXT = /\.(?:md|mdx|markdown|rst|adoc)$/iu;
 const DOC_NAMES = /^(?:license|licence|notice|authors|changelog|changes|contributors)$/iu;
 /** Markdown that steers agents is behavior, not docs. */
 const INSTRUCTIONS =
   /(?:^|\/)(?:AGENTS|CLAUDE|GEMINI|SKILL)\.md$|(?:^|\/)(?:skills|agents|commands|rules|prompts)\/[^/]+/iu;
-const TEST_PATH =
-  /(?:^|\/)(?:test|tests|__tests__|spec|specs|fixtures)\/|\.(?:test|spec)\.[^/]+$/iu;
+/**
+ * A test file: under a `test/`, `tests/` or `__tests__/` folder, or named
+ * `*.test.*`, `*.spec.*` or `*_test.*`. A `fixtures/` or `spec/` folder can
+ * hold runtime data or code, so it is not a test path (it reads as behavior).
+ */
+const TEST_PATH = /(?:^|\/)(?:test|tests|__tests__)\/|\.(?:test|spec)\.[^/]+$|_test\.[^/]+$/iu;
 
 export type ChangedFile = {
   path: string;
@@ -156,7 +166,7 @@ export type LaneAssessment = {
   riskFiles: string[];
 };
 
-type FileKind = "doc" | "cosmetic" | "generated" | "lockfile" | "test" | "behavior";
+export type FileKind = "doc" | "cosmetic" | "generated" | "lockfile" | "test" | "behavior";
 
 const basename = (file: string): string => file.slice(file.lastIndexOf("/") + 1);
 
@@ -165,7 +175,7 @@ const isDoc = (file: string): boolean =>
   !INSTRUCTIONS.test(file) && (DOC_EXT.test(file) || DOC_NAMES.test(basename(file)));
 
 /** What a file off risk paths is; risk paths are decided before (see computeLane). */
-function kindOf(file: ChangedFile): FileKind {
+export function kindOf(file: ChangedFile): FileKind {
   if (file.binary) return "behavior";
   if (file.generated) return "generated";
   if (LOCKFILES.has(basename(file.path))) return "lockfile";
@@ -360,7 +370,13 @@ function generatedAt(cwd: string, fork: string, paths: readonly string[]): Set<s
 const forkOf = (cwd: string, base: string, head: string | null): string | null =>
   mergeBase(cwd, base, head ?? "HEAD");
 
-function laneFiles(cwd: string, fork: string, head: string | null): ChangedFile[] | null {
+/** The files of `fork..head`; generated copies are read from `attributesAt` (the base revision). */
+function laneFiles(
+  cwd: string,
+  fork: string,
+  head: string | null,
+  attributesAt: string = fork,
+): ChangedFile[] | null {
   const stats = diffNumstat(cwd, fork, head);
   const cosmetic = stats ? cosmeticFiles(cwd, fork, head) : null;
   if (!stats || !cosmetic) return null;
@@ -374,7 +390,7 @@ function laneFiles(cwd: string, fork: string, head: string | null): ChangedFile[
   ];
   const generated = generatedAt(
     cwd,
-    fork,
+    attributesAt,
     files.map((entry) => entry.path),
   );
   return files.map((entry) => ({
@@ -383,6 +399,41 @@ function laneFiles(cwd: string, fork: string, head: string | null): ChangedFile[
   }));
 }
 
+/**
+ * The files whose own change differs between two versions of a branch: the
+ * judged `from` (forked from `fromFork`) and the current `to` (forked from
+ * `toFork`). Generated copies are read from `toFork` only.
+ *
+ * - Same fork: the plain `from..to` diff, comments and formatting read as
+ *   in the lane.
+ * - Moved fork (a rebase): each file the branch touches is compared by exact
+ *   blob (see ownChangeDrift): it counts when the branch's resulting file
+ *   differs, or when the base changed it too between the forks. Their lines
+ *   come from `from..to`, which may include base edits (over-counting is the
+ *   safe direction), and none is cosmetic.
+ *
+ * Null when git cannot read either side.
+ */
+export function driftFiles(
+  cwd: string,
+  range: { from: string; to: string; fromFork: string; toFork: string },
+): ChangedFile[] | null {
+  if (range.fromFork === range.toFork) return laneFiles(cwd, range.from, range.to, range.toFork);
+  const drifted = ownChangeDrift(cwd, range);
+  const stats = drifted ? diffNumstat(cwd, range.from, range.to) : null;
+  if (!drifted || !stats) return null;
+  const byPath = new Map(stats.map((entry) => [entry.path, entry]));
+  const generated = generatedAt(cwd, range.toFork, drifted);
+  return drifted.map((file) => ({
+    path: file,
+    added: byPath.get(file)?.added ?? 0,
+    deleted: byPath.get(file)?.deleted ?? 0,
+    ...(byPath.get(file)?.binary ? { binary: true } : {}),
+    cosmetic: false,
+    generated: generated.has(file),
+  }));
+}
+
 /**
  * The changed files of `merge-base(base, head)..head`, or with `head` null
  * of the working tree (tracked changes plus untracked files) since
@@ -455,11 +506,9 @@ export function branchLane(
  * it is committed there. Null when there is nothing to warn about.
  */
 export function untrackedRiskPathsWarning(cwd: string): string | null {
-  const top = git(cwd, ["rev-parse", "--show-toplevel"]);
-  const root = top.ok ? top.stdout.trim() : "";
+  const root = worktreeTop(cwd);
   if (!root || !existsSync(path.join(root, RISK_PATHS_FILE))) return null;
-  const tracked = git(root, ["ls-files", "--error-unmatch", "--", RISK_PATHS_FILE]);
-  return tracked.ok
+  return isTracked(root, RISK_PATHS_FILE)
     ? null
     : `${RISK_PATHS_FILE} is not committed: it does not apply until it is committed on the base branch`;
 }

package/src/fanout-brief.ts

@@ -13,7 +13,7 @@
 // workers export nothing (the host derives the id);
 // Cursor, CI and plain terminals export `<lead>-w-<slice>`. Once
 // `workit fanout worktree create` made the slice's worktree, WORKTREE and the
-// RULES name it: every git and check command runs as `workit --cwd <worktree> …`.
+// RULES name it: every git and check command runs as `workit <verb> --cwd <worktree> …`.
 // The lead must have a WORKIT_SESSION_ID: worker ids derive from it. A
 // worker id longer than the ledger's 128 characters hashes its slice part. The fan-in line follows the plan's `fanIn`:
 // one PR per slice forbids every merge; integration mode has the worker merge
@@ -96,8 +96,9 @@ const identityLines = (identity: BriefIdentity, session: string): string[] => {
 
 /**
  * RULES. With the slice's worktree made (`worktree`), every git and check
- * command names it (`workit --cwd <worktree> …`, one verb per call) and it is
- * already on the branch; Workit's hooks keep an implementer inside it (#310).
+ * command names it (`workit <verb> --cwd <worktree> …`, verb first so host
+ * allow rules match, one verb per call) and it is already on the branch;
+ * Workit's hooks keep an implementer inside it (#310).
  */
 const rules = (
   mode: BriefMode,
@@ -105,17 +106,18 @@ const rules = (
   base: string,
   worktree: string | null,
 ): string[] => {
-  const workit = worktree ? `workit --cwd ${worktree}` : "workit";
+  const workit = (verb: string) =>
+    worktree ? `workit ${verb} --cwd ${worktree}` : `workit ${verb}`;
   let first = `  1. First command: \`workit git branch ${branch} --base ${base}\` (your worktree may start on another name).`;
   if (worktree)
-    first = `  1. Work only in WORKTREE, already on ${branch}${mode === "resume" ? " at its head" : ""}: edit files under it and run each git and check command against it, one verb per call (\`${workit} git commit …\`, \`${workit} check <name>\`), never \`cd … &&\` chains or \`$VAR\` paths. An implementer's change outside it is denied.`;
+    first = `  1. Work only in WORKTREE, already on ${branch}${mode === "resume" ? " at its head" : ""}: edit files under it and run each git and check command against it, one verb per call (\`${workit("git")} commit …\`, \`${workit("check")} <name>\`), never \`cd … &&\` chains or \`$VAR\` paths. An implementer's change outside it is denied.`;
   else if (mode === "resume")
     first = `  1. First command: \`git switch ${branch}\`, then continue from its head.`;
   return [
     "RULES:",
     first,
     '  2. Decide ambiguities yourself: `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`; stop only for an irreversible, security-sensitive or out-of-worktree action.',
-    `  3. Commit with \`${workit} git commit -m <msg> -- <paths in SCOPE>\`; push only if this brief says so.`,
+    `  3. Commit with \`${workit("git")} commit -m <msg> -- <paths in SCOPE>\`; push only if this brief says so.`,
     "  4. Never record a verdict on your own work.",
     "  5. Run tests, lint, typecheck and builds only through `workit check` (a named check, or `workit check --heavy -- <cmd>`): one machine-wide lease queues every agent, so never a hand-made flock; `workit lock status` shows who holds it.",
     "  6. A failed review gets one fix round and one recheck. Still failing: stop and report the open finding, never a third round (the lead spawns a decider). A product choice is the user's: report it, do not decide it.",

package/src/fanout-worktree.ts

@@ -480,7 +480,7 @@ export function releaseSliceWorktree(
     return fanoutFail(
       "blocked",
       `this command runs inside ${entry.path}`,
-      `run it from the main checkout: workit --cwd <main checkout> fanout worktree release ${slice.id}`,
+      `run it from the main checkout: workit fanout --cwd <main checkout> worktree release ${slice.id}`,
     );
   if (entry.branch !== null && entry.branch !== `refs/heads/${slice.branch}`)
     return fanoutFail(

package/src/forge/pr-ops.ts

@@ -35,12 +35,13 @@ import { spawnSync } from "node:child_process";
 import { currentBranch, fetchRefs, GIT_TIMEOUTS, remoteRefTip, resolveRef } from "../git/rev";
 import {
   appendObserved,
-  checkVerdicts,
   tamperedUnblock,
   readLedger,
+  type CarryNote,
   type LedgerActor,
   type VerdictCheck,
 } from "../ledger";
+import { checkVerdictsCovered, type StackCover } from "../verdict-cover";
 import type { LaneNeed, ReviewLane } from "../core/policy/lane";
 import { laneLabel, prLaneGate } from "../core/policy/pr-lane";
 import { buildStatusDoc, selectPr, type PrStatusDoc } from "./report";
@@ -379,6 +380,10 @@ export type MergeOutcome = {
     lane: ReviewLane;
     need: LaneNeed;
     verification: VerificationMode;
+    /** The stack verdict above this PR that covers it (#334), when it has none of its own. */
+    cover?: StackCover | null;
+    /** How a verdict on an older head carried to this one over a follow-up change (#334). */
+    carry?: CarryNote | null;
   };
   /** Set when `--unverified` bypassed the verdict: the reason and its ledger row. */
   unverified: { reason: string; recorded: string } | null;
@@ -662,7 +667,8 @@ export async function mergePullRequest(
   }
   const ledger = readLedger(cwd, { integrity: true });
   if (!ledger.ok) return ledger;
-  const check = checkVerdicts(cwd, branch, ledger.value.rows);
+  // A lower PR of a stack may be covered by the verdict at its top (#334).
+  const check = checkVerdictsCovered(cwd, branch, ledger.value.rows);
   const gate = prLaneGate(cwd, check, { branch, base: doc.base, head });
   const summary = {
     head: check.head,
@@ -681,6 +687,9 @@ export async function mergePullRequest(
     lane: gate.lane.lane,
     need: gate.need,
     verification: gate.verification,
+    ...(covered && gate.review === "verified"
+      ? { cover: check.cover, carry: check.cover ? null : check.carry }
+      : {}),
   };
   let unverified: MergeOutcome["unverified"] = null;
   // The bypass covers a missing verdict, never a rejection.

package/src/git/default-base.ts

@@ -0,0 +1,49 @@
+// The default base for patch-ids, author trailers and review lanes. Its own
+// module so the lane (core/policy/lane.ts) and the ledger can both read it
+// without importing each other.
+import { vcsConfig } from "../core/vcs-config";
+import { originHeadRef, resolveRef } from "./rev";
+
+const safeRef = (value: string): boolean => value.length > 0 && !value.startsWith("-");
+
+/**
+ * The PR target of the release track the checkout is on, when the workspace
+ * configures tracks (as `fanout plan` and `stack plan` pick their trunk); a
+ * plain workspace default does not override origin's default branch.
+ */
+const trackTrunk = (cwd: string): string | null => {
+  try {
+    const resolved = vcsConfig("resolve", cwd);
+    if (resolved.ok === false || !resolved.releaseTrack || resolved.releaseTrack.blocking)
+      return null;
+    const target = String(resolved.defaultTargetBranch ?? "").trim();
+    return target && safeRef(target) ? target : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The default base for patch-ids and author trailers: the release track's PR
+ * target (origin's copy, else the local one) when tracks are configured, else
+ * origin's HEAD branch, else the first of origin/main, origin/master, main,
+ * master, origin/develop, develop that exists.
+ */
+export function defaultBase(cwd: string): string | null {
+  const trunk = trackTrunk(cwd);
+  if (trunk)
+    for (const candidate of [`origin/${trunk}`, trunk])
+      if (resolveRef(cwd, candidate)) return candidate;
+  const originHead = originHeadRef(cwd);
+  if (originHead && resolveRef(cwd, originHead)) return originHead;
+  for (const candidate of [
+    "origin/main",
+    "origin/master",
+    "main",
+    "master",
+    "origin/develop",
+    "develop",
+  ])
+    if (resolveRef(cwd, candidate)) return candidate;
+  return null;
+}

package/src/git/rev.ts

@@ -515,6 +515,117 @@ export function resolveRef(cwd: string, ref: string): string | null {
   return line(git(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]));
 }
 
+/** The branch origin's HEAD names (`origin/main`), or null. */
+export function originHeadRef(cwd: string): string | null {
+  return line(git(cwd, ["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"]));
+}
+
+/** The top of the working tree, or null outside one. */
+export function worktreeTop(cwd: string): string | null {
+  return line(git(cwd, ["rev-parse", "--show-toplevel"]));
+}
+
+/** Whether git tracks `file` (repo-relative) in the index of the checkout at `top`. */
+export function isTracked(top: string, file: string): boolean {
+  return git(top, ["ls-files", "--error-unmatch", "--", file]).ok;
+}
+
+/**
+ * The files whose own change differs between two versions of a branch: the
+ * judged `from` (forked from `fromFork`) and the current `to` (forked from
+ * `toFork`), compared by exact blob and mode, never by diff text (#334). A
+ * file the branch touches on one side only differs. A file it touches on
+ * both sides is unchanged only when the base left it alone between the forks
+ * and the branch's resulting blob is identical, so a hunk moved within a
+ * file, a re-indent or a base edit in a file the branch touches always
+ * counts. Null when git cannot read either side: the caller fails closed.
+ */
+export function ownChangeDrift(
+  cwd: string,
+  range: { from: string; to: string; fromFork: string; toFork: string },
+): string[] | null {
+  const before = diffRaw(cwd, range.fromFork, range.from);
+  const after = diffRaw(cwd, range.toFork, range.to);
+  if (!before || !after) return null;
+  const judged = new Map(before.map((entry) => [entry.path, entry]));
+  const current = new Map(after.map((entry) => [entry.path, entry]));
+  const same = (a: RawEntry | undefined, b: RawEntry | undefined): boolean =>
+    a !== undefined &&
+    b !== undefined &&
+    a.oldMode === b.oldMode &&
+    a.oldBlob === b.oldBlob &&
+    a.newMode === b.newMode &&
+    a.newBlob === b.newBlob;
+  return [...new Set([...judged.keys(), ...current.keys()])]
+    .filter((file) => !same(judged.get(file), current.get(file)))
+    .toSorted();
+}
+
+/**
+ * Whether the branch's own files are identical at `from` (on `fromBase`) and
+ * `to` (on `toBase`): ownChangeDrift from each head's fork is empty. The
+ * exactness behind every patch-equal carry; false when git cannot tell.
+ */
+export function sameOwnChange(
+  cwd: string,
+  range: { from: string; to: string; fromBase: string; toBase: string },
+): boolean {
+  const fromFork = mergeBase(cwd, range.fromBase, range.from);
+  const toFork = mergeBase(cwd, range.toBase, range.to);
+  if (!fromFork || !toFork) return false;
+  return ownChangeDrift(cwd, { from: range.from, to: range.to, fromFork, toFork })?.length === 0;
+}
+
+/**
+ * The verbatim patch-ids of the non-merge commits of `fork..head` (empty
+ * commits have none) and how many merge commits the range holds: unlike
+ * `--stable`, whitespace counts, so a re-indent is another patch. Diff
+ * options are pinned as in patchId. Null when git fails, or has no
+ * `patch-id --verbatim`: the caller fails closed.
+ */
+export function commitPatchIds(
+  cwd: string,
+  fork: string,
+  head: string,
+): { patchIds: string[]; merges: number } | null {
+  if (!safeArg(fork) || !safeArg(head)) return null;
+  const range = `${fork}..${head}`;
+  const merges = line(git(cwd, ["rev-list", "--count", "--merges", range]));
+  const log = git(
+    cwd,
+    [
+      "log",
+      "--no-merges",
+      "-p",
+      "-U3",
+      "--diff-algorithm=myers",
+      "--indent-heuristic",
+      "--no-color",
+      "--no-ext-diff",
+      "--no-textconv",
+      "--no-renames",
+      "--full-index",
+      "--src-prefix=a/",
+      "--dst-prefix=b/",
+      "--format=commit %H",
+      range,
+      "--",
+    ],
+    { timeoutMs: GIT_TIMEOUTS.worktree },
+  );
+  if (merges === null || !log.ok) return null;
+  if (!log.stdout.trim()) return { patchIds: [], merges: Number(merges) };
+  const ids = git(cwd, ["patch-id", "--verbatim"], { input: log.stdout });
+  if (!ids.ok) return null;
+  return {
+    patchIds: ids.stdout
+      .split("\n")
+      .map((entry) => entry.trim().split(/\s+/u)[0])
+      .filter(Boolean),
+    merges: Number(merges),
+  };
+}
+
 /** Pinned diff options for the review-lane reads: user config never changes them. */
 const LANE_DIFF = [
   "-c",