@brainervirus/workit-core 8.23.0 → 8.25.0

package/src/core/policy/substance.ts

@@ -0,0 +1,365 @@
+// Is a changed file cosmetic (#333, review finding mvkcoxgb)? Each side of
+// the file is reduced to its substance by a small lexer that knows the
+// file's strings and comments: comments drop out, whitespace outside strings
+// is normalized, strings stay verbatim. Equal substance on both sides is a
+// cosmetic change. The lexer fails closed: a syntax it does not know keeps
+// its comments, an indentation-sensitive or unknown type keeps all but
+// trailing whitespace, and anything it cannot read (invalid UTF-8, a NUL
+// byte, an unterminated string or comment, a regex across lines) is
+// substantive. Languages it would read wrongly stay unlexed (C-family, Rust,
+// SQL, shell, Ruby, YAML): only trailing whitespace is cosmetic there.
+
+type Syntax = {
+  /** Line comment openers. */
+  line: readonly string[];
+  /** Block comment delimiters (not nested). */
+  block: readonly (readonly [string, string])[];
+  /** String quotes with backslash escapes. */
+  quotes: string;
+  /** String quotes without escapes (TOML literal strings). */
+  literal?: string;
+  /** `"""` and `'''` strings. */
+  triple?: boolean;
+  /** JavaScript template literals with `${}` and regex literals. */
+  js?: boolean;
+  /** Go raw strings in backticks. */
+  rawBacktick?: boolean;
+  /** Strings may span lines. */
+  multiline?: boolean;
+  /** Python: an f-string with an unbalanced `{` holds a nested string this cannot read. */
+  fstring?: boolean;
+  /** CSS: an unquoted `url(` body is no string or comment this can read. */
+  cssUrl?: boolean;
+  /** Only trailing whitespace is cosmetic (indentation matters). */
+  indented?: boolean;
+};
+
+const SLASH_BLOCK = [["/*", "*/"]] as const;
+const C_LIKE: Syntax = { line: ["//"], block: SLASH_BLOCK, quotes: `"'` };
+const SYNTAXES: Record<string, Syntax> = Object.fromEntries([
+  // Not jsx or tsx: JSX text (`don't`, `</a>`) is no lexable string or regex.
+  ...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => [ext, { ...C_LIKE, js: true }]),
+  ...["java", "kt", "kts", "scala", "swift", "dart", "groovy"].map((ext) => [
+    ext,
+    { ...C_LIKE, triple: true },
+  ]),
+  ["go", { ...C_LIKE, rawBacktick: true }],
+  ...["css", "scss", "less"].map((ext) => [
+    ext,
+    { line: [], block: SLASH_BLOCK, quotes: `"'`, cssUrl: true },
+  ]),
+  ...["py", "pyi"].map((ext) => [
+    ext,
+    { line: ["#"], block: [], quotes: `"'`, triple: true, indented: true, fstring: true },
+  ]),
+  ["toml", { line: ["#"], block: [], quotes: `"`, literal: "'", triple: true }],
+  ...["html", "htm", "xml", "svg", "xhtml"].map((ext) => [
+    ext,
+    // Text and <pre> whitespace can matter: only trailing whitespace is cosmetic.
+    { line: [], block: [["<!--", "-->"]], quotes: "", indented: true },
+  ]),
+]);
+
+/** Comments that steer a compiler, linter, bundler or runtime are code. */
+const DIRECTIVE =
+  /@ts-|eslint|prettier|biome|oxlint|istanbul|\bc8\b|\bv8\b|@jsx|@flow|@vite|webpack|__PURE__|__NO_SIDE_EFFECTS__|source(?:Mapping)?URL|^\/\s*<|go:|\+build|nolint|noqa|type:|pyright|mypy|pylint|pragma|coding[:=]|fmt:|NOSONAR|@license|@preserve|@refresh|environment|language=|cython|ruff|isort|deno-|@vitest|@jest|swiftlint|ktlint|checkstyle|suppress|nullable|#(?:end)?region/iu;
+
+const extensionOf = (file: string): string => {
+  const name = file.slice(file.lastIndexOf("/") + 1);
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+};
+
+/** CI and workflow definitions are read as written: their comments are never stripped. */
+const CI_PATH =
+  /^\.github\/|(?:^|\/)(?:\.gitlab-ci\.ya?ml|Jenkinsfile|azure-pipelines\.ya?ml|\.pre-commit-config\.ya?ml|\.circleci\/.*)$/u;
+
+/** The syntax `file` is lexed with; null keeps comments and all but trailing whitespace. */
+const syntaxOf = (file: string): Syntax | null =>
+  CI_PATH.test(file) ? null : (SYNTAXES[extensionOf(file)] ?? null);
+
+const SPACE = /[ \t\r\f\v]/u;
+const WORD = /[\w$]/u;
+const NO_SPACE_AFTER = "([{,;";
+const NO_SPACE_BEFORE = ")]},;";
+const REGEX_AFTER = "(,=:[!&|?{};+-*%<>~^";
+const REGEX_KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "case",
+  "do",
+  "else",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "throw",
+  "yield",
+  "await",
+]);
+
+type Frame = { kind: "code"; braces: number } | { kind: "template" };
+
+/**
+ * The substance of `text` for `file`: what stays after comments and
+ * insignificant whitespace are removed. Null when it cannot be read with
+ * certainty (the caller then counts the file as a behavior change).
+ */
+export function substanceOf(file: string, text: string): string | null {
+  const syntax = syntaxOf(file);
+  if (!syntax) return plainSubstance(text);
+  const markup = syntax.block.some(([open]) => open === "<!--");
+  // Markup with scripts, styles, CDATA or processing instructions holds
+  // other languages; a comment opener after anything but a tag end may sit
+  // in an attribute value.
+  if (
+    markup &&
+    (/<(?:script|style)\b|<!\[CDATA\[|<\?/iu.test(text) || /[^>\s][ \t]*<!--/u.test(text))
+  )
+    return plainSubstance(text);
+  return lex(syntax, text);
+}
+
+/** No lexer: only trailing whitespace and blank lines are cosmetic. */
+function plainSubstance(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => line.replace(/[ \t\r\f\v]+$/u, ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+function lex(syntax: Syntax, text: string): string | null {
+  const collapse = !syntax.indented;
+  let out = "";
+  let lineStart = 0;
+  /** Output before this index is string content: trailing-space trimming stops there. */
+  let kept = 0;
+  let pendingSpace = false;
+  const frames: Frame[] = [{ kind: "code", braces: 0 }];
+  let index = 0;
+
+  // A shebang line is code, read as written.
+  if (text.startsWith("#!")) {
+    const end = text.indexOf("\n");
+    out = end < 0 ? text : text.slice(0, end);
+    kept = out.length;
+    index = end < 0 ? text.length : end;
+  }
+
+  const emitCode = (chunk: string) => {
+    if (collapse && pendingSpace && out.length > lineStart) {
+      const before = out[out.length - 1];
+      if (!NO_SPACE_AFTER.includes(before) && !NO_SPACE_BEFORE.includes(chunk[0])) out += " ";
+    }
+    pendingSpace = false;
+    out += chunk;
+  };
+  const emitVerbatim = (chunk: string) => {
+    emitCode(chunk);
+    kept = out.length;
+  };
+  const newline = () => {
+    if (!collapse) {
+      let end = out.length;
+      while (end > Math.max(lineStart, kept) && SPACE.test(out[end - 1])) end -= 1;
+      out = out.slice(0, end);
+    }
+    pendingSpace = false;
+    if (out.length > lineStart) {
+      out += "\n";
+      lineStart = out.length;
+    }
+  };
+  /** Can a `/` start a regex here? After an operator or a keyword, not after a value. */
+  const regexAllowed = (): boolean => {
+    let end = out.length;
+    while (end > 0 && /\s/u.test(out[end - 1])) end -= 1;
+    if (end === 0 || REGEX_AFTER.includes(out[end - 1])) return true;
+    let start = end;
+    while (start > 0 && WORD.test(out[start - 1])) start -= 1;
+    return REGEX_KEYWORDS.has(out.slice(start, end));
+  };
+  /** Scan a quoted string from `index`; returns false when it does not close. */
+  const scanString = (quote: string, escapes: boolean, multiline: boolean): boolean => {
+    const prefix = text.slice(Math.max(0, index - 2), index).match(/[a-z]*$/iu)?.[0] ?? "";
+    const fstring = syntax.fstring === true && /f/iu.test(prefix);
+    let end = index + quote.length;
+    while (end < text.length) {
+      const char = text[end];
+      if (escapes && char === "\\") {
+        end += 2;
+        continue;
+      }
+      if (text.startsWith(quote, end)) {
+        if (fstring && unbalanced(text.slice(index + quote.length, end))) return false;
+        emitVerbatim(text.slice(index, end + quote.length));
+        index = end + quote.length;
+        return true;
+      }
+      if (char === "\n" && !multiline) return false;
+      end += 1;
+    }
+    return false;
+  };
+
+  while (index < text.length) {
+    const frame = frames[frames.length - 1];
+    const char = text[index];
+    if (frame.kind === "template") {
+      if (char === "\\") {
+        emitVerbatim(text.slice(index, index + 2));
+        index += 2;
+      } else if (char === "`") {
+        emitVerbatim(char);
+        frames.pop();
+        index += 1;
+      } else if (text.startsWith("${", index)) {
+        emitVerbatim("${");
+        frames.push({ kind: "code", braces: 0 });
+        index += 2;
+      } else {
+        // Template text, newlines included, is the string's value.
+        out += char;
+        kept = out.length;
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "\n") {
+      newline();
+      index += 1;
+      continue;
+    }
+    if (SPACE.test(char)) {
+      if (collapse) pendingSpace = true;
+      else out += char;
+      index += 1;
+      continue;
+    }
+    const lineOpener = syntax.line.find((opener) => text.startsWith(opener, index));
+    if (lineOpener) {
+      const end = text.indexOf("\n", index);
+      const comment = text.slice(index, end < 0 ? text.length : end);
+      if (DIRECTIVE.test(comment.slice(lineOpener.length))) emitVerbatim(comment);
+      else pendingSpace = true;
+      index = end < 0 ? text.length : end;
+      continue;
+    }
+    const block = syntax.block.find(([open]) => text.startsWith(open, index));
+    if (block) {
+      const end = text.indexOf(block[1], index + block[0].length);
+      if (end < 0) return null;
+      const comment = text.slice(index, end + block[1].length);
+      if (DIRECTIVE.test(comment.slice(block[0].length, -block[1].length))) emitVerbatim(comment);
+      else pendingSpace = true;
+      // A newline inside the comment still ends the code line before it.
+      if (comment.includes("\n")) newline();
+      index = end + block[1].length;
+      continue;
+    }
+    if (syntax.triple && (char === '"' || char === "'") && text.startsWith(char.repeat(3), index)) {
+      if (!scanString(char.repeat(3), !syntax.literal?.includes(char), true)) return null;
+      continue;
+    }
+    if (syntax.quotes.includes(char)) {
+      if (!scanString(char, true, Boolean(syntax.multiline))) return null;
+      continue;
+    }
+    if (syntax.literal?.includes(char)) {
+      if (!scanString(char, false, false)) return null;
+      continue;
+    }
+    if (syntax.rawBacktick && char === "`") {
+      if (!scanString("`", false, true)) return null;
+      continue;
+    }
+    if (syntax.js && char === "`") {
+      emitVerbatim(char);
+      frames.push({ kind: "template" });
+      index += 1;
+      continue;
+    }
+    if (syntax.cssUrl && /^url\(\s*[^"')\s]/iu.test(text.slice(index, index + 64))) return null;
+    if (syntax.js && char === "/" && !regexAllowed() && out.trimEnd().endsWith(")")) {
+      // Division after `)` may be a regex after `if (x)`: with another `/` on
+      // the line the two readings differ on what is code, so give up.
+      const lineEnd = text.indexOf("\n", index);
+      if (text.slice(index + 1, lineEnd < 0 ? text.length : lineEnd).includes("/")) return null;
+    }
+    if (syntax.js && char === "/" && regexAllowed()) {
+      let end = index + 1;
+      let inClass = false;
+      while (end < text.length && (inClass || text[end] !== "/")) {
+        if (text[end] === "\n") return null;
+        if (text[end] === "\\") end += 1;
+        else if (text[end] === "[") inClass = true;
+        else if (text[end] === "]") inClass = false;
+        end += 1;
+      }
+      if (end >= text.length) return null;
+      emitVerbatim(text.slice(index, end + 1));
+      index = end + 1;
+      continue;
+    }
+    if (frames.length > 1 && frame.kind === "code") {
+      if (char === "{") frame.braces += 1;
+      else if (char === "}") {
+        if (frame.braces === 0) {
+          emitVerbatim(char);
+          frames.pop();
+          index += 1;
+          continue;
+        }
+        frame.braces -= 1;
+      }
+    }
+    emitCode(char);
+    index += 1;
+  }
+  if (frames.length !== 1) return null;
+  newline();
+  return out;
+}
+
+/** Does an f-string body hold a `{` that never closes, once `{{` and `}}` are set aside? */
+function unbalanced(body: string): boolean {
+  let depth = 0;
+  for (const part of body.replaceAll("{{", "").replaceAll("}}", "")) {
+    if (part === "{") depth += 1;
+    else if (part === "}") depth = Math.max(0, depth - 1);
+  }
+  return depth > 0;
+}
+
+/**
+ * A lone CR (not followed by LF), U+2028 or U+2029: some readers end a line
+ * there and others do not, so a comment can hide code from one of them.
+ */
+export function hasOpaqueLineBreak(text: string): boolean {
+  return /\r(?!\n)|[\u2028\u2029]/u.test(text);
+}
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** The UTF-8 text of `bytes`, or null for binary (a NUL byte) or invalid UTF-8. */
+export function textOf(bytes: Uint8Array): string | null {
+  if (bytes.includes(0)) return null;
+  try {
+    return decoder.decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/** Is the change from `before` to `after` of `file` cosmetic (equal substance)? */
+export function cosmeticChange(file: string, before: Uint8Array, after: Uint8Array): boolean {
+  const left = textOf(before);
+  const right = textOf(after);
+  if (left === null || right === null) return false;
+  if (hasOpaqueLineBreak(left) || hasOpaqueLineBreak(right)) return false;
+  const a = substanceOf(file, left);
+  return a !== null && a === substanceOf(file, right);
+}

package/src/core/workspaces.ts

@@ -142,7 +142,7 @@ const workspaceConfigSchema = z
      */
     defaultEndpoint: z.unknown().optional(),
     /** How a normal-risk behavior change is verified (S17); same rules as grants. */
-    verification: z.enum(["self", "independent"]).optional(),
+    verification: z.enum(["proportional", "self", "independent"]).optional(),
     /**
      * Who does the work (skills and `fanout plan` read it): `inline-first`
      * (default) keeps the lead working itself and refuses a slice without a

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

@@ -24,6 +24,7 @@ import {
   resolveAutonomy,
   type AutonomySource,
   type DefaultEndpoint,
+  type VerificationMode,
 } from "../autonomy";
 import { branchKindOf, flowRoute, gitFlowOf, isProtectedTarget } from "../core/branch";
 import { vcsConfig } from "../core/vcs-config";
@@ -34,12 +35,15 @@ 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";
 import type { ResolvedForge } from "./resolve";
 import { failure, success, type ForgeResult, type MergeMethod, type PrRef } from "./types";
@@ -361,7 +365,26 @@ export type MergeOutcome = {
   head: string;
   method: MergeMethod;
   mergeSha: string | null;
-  verdict: { required: boolean; accepted: boolean; verdictId: string | null };
+  /**
+   * `required`: the gate asked for a verdict (false under lane none or a
+   * bypass); `accepted`: an accepted independent verdict covers the head;
+   * `verdictId`: the verdict the merge relied on (the author's own under lane
+   * self, shown as self-reviewed); `lane`/`need`: the review lane and what it
+   * asked (`need` is non-author outside `verification: proportional`).
+   */
+  verdict: {
+    required: boolean;
+    accepted: boolean;
+    verdictId: string | null;
+    review: "verified" | "self-reviewed" | "none";
+    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;
   grant: { source: AutonomySource };
@@ -644,14 +667,29 @@ export async function mergePullRequest(
   }
   const ledger = readLedger(cwd, { integrity: true });
   if (!ledger.ok) return ledger;
-  const check = checkVerdicts(cwd, branch, ledger.value.rows);
-  const summary = { head: check.head, accepted: check.accepted, authors: check.authors };
-  const covered = check.head === head && check.accepted.accepted;
+  // 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,
+    accepted: check.accepted,
+    authors: check.authors,
+    lane: gate.lane.lane,
+    need: gate.need,
+  };
+  // Lane none needs no verdict, so no verdict head either.
+  const covered = gate.satisfied && (gate.need === "none" || check.head === head);
   let verdict: MergeOutcome["verdict"] = {
-    required: true,
-    accepted: covered,
-    verdictId:
-      covered && typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null,
+    required: gate.need !== "none",
+    accepted: check.head === head && check.accepted.accepted,
+    verdictId: covered ? gate.verdictId : null,
+    review: covered ? gate.review : "none",
+    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.
@@ -679,9 +717,9 @@ export async function mergePullRequest(
         "failed",
         `unverified_unrecorded: the --unverified bypass could not be recorded (${recorded.error}); nothing was merged`,
       );
-    verdict = { required: false, accepted: false, verdictId: null };
+    verdict = { ...verdict, required: false, accepted: false, verdictId: null, review: "none" };
     unverified = { reason, recorded: String(recorded.value.id) };
-  } else if (check.head !== head)
+  } else if (!covered && check.head !== head)
     return refuse(
       `head_mismatch: the verdict check reads ${branch} at ${check.head?.slice(0, 12) ?? "(missing)"} but ${label} is at ${head.slice(0, 12)}`,
       `git fetch && git switch ${branch} && git merge --ff-only @{u}  # then re-verify that head`,
@@ -693,12 +731,21 @@ export async function mergePullRequest(
       tamperedUnblock(cwd),
       { reason: "ledger_tampered", verdict: summary },
     );
-  else if (!covered)
+  else if (!covered) {
+    const bypassHint = grant.allowUnverified
+      ? `; or, only if the user asks to merge unverified: workit pr merge --unverified --reason "<why>"`
+      : "";
+    const lane = gate.verification === "proportional" ? `, ${laneLabel(gate)}` : "";
     return refuse(
-      `NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)} (${check.accepted.reasons.join(", ")})`,
-      `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}${grant.allowUnverified ? `; or, only if the user asks to merge unverified: workit pr merge --unverified --reason "<why>"` : ""}`,
+      gate.need === "self"
+        ? `NEEDS_VERDICT: ${label} has no verdict for ${head.slice(0, 12)}${lane}: the author's own --self verdict is enough (${check.accepted.reasons.join(", ")})`
+        : `NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)}${lane} (${check.accepted.reasons.join(", ")})`,
+      gate.need === "self"
+        ? `after an observed passing \`workit check test\`, the author runs: workit ledger verdict tests-verified --self --how "<what you ran>" --branch ${branch} (or a verifier records one)${bypassHint}`
+        : `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}${bypassHint}`,
       { reason: "needs_verdict", verdict: summary },
     );
+  }
 
   const squashMessage = squashMessageFor(cwd, resolved, input, doc);
   if (squashMessage && !squashMessage.ok) return squashMessage;
@@ -714,6 +761,8 @@ export async function mergePullRequest(
     base: doc.base,
     method: input.method,
     verdictId: verdict.verdictId,
+    review: verdict.review,
+    lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
     grant: grant.source,
   });
@@ -747,6 +796,8 @@ export async function mergePullRequest(
     mergeSha: merged.data.mergeSha,
     method: input.method,
     verdictId: verdict.verdictId,
+    review: verdict.review,
+    lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
     grant: grant.source,
     intent: intentId,

package/src/forge/report.ts

@@ -428,7 +428,7 @@ export function buildStatusDoc(
 
 /**
  * Record what the forge said about a PR as a CLI-observed `pr.status` row
- * (pr, branch, head, state: open|merged|closed, checks), only when it
+ * (pr, branch, head, base, state: open|merged|closed, checks), only when it
  * differs from the newest row for that PR, so polling never floods the
  * ledger. Hooks read it without calling the forge: an open PR's checks
  * (passing|failing|pending; one without gating checks is not recorded), and
@@ -455,7 +455,8 @@ export function recordPrStatus(cwd: string, doc: PrStatusDoc, actor: LedgerActor
       last &&
       last.head === doc.head.sha &&
       last.checks === checks &&
-      (last.state ?? "open") === state
+      (last.state ?? "open") === state &&
+      (last.base ?? null) === (doc.base ?? null)
     )
       return;
     appendObserved(cwd, {
@@ -468,6 +469,7 @@ export function recordPrStatus(cwd: string, doc: PrStatusDoc, actor: LedgerActor
       forge: doc.forge,
       state,
       checks,
+      base: doc.base,
     });
   } catch {
     // The row is an observation for hooks; the verb's answer stands without it.

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;
+}