@brainervirus/workit-core 7.6.0 → 8.0.0

package/src/fanout.ts

@@ -18,12 +18,33 @@
 // deterministic suggestion: an owner for known shared files (lockfiles,
 // manifests, barrels, CI config), else a dependency that serializes them.
 //
+// Each slice's `hash` covers what it is (goal, acceptance, verify, forbidden,
+// scope, owns, branch, base, dependencies), not how it is briefed (tier,
+// timebox, context) or where its worktree goes. A re-plan that changes a
+// slice starts a new run for that slice alone: its `hashSince` moves to now,
+// and only ledger rows recorded under its hash (worktree rows carry
+// `sliceHash`) or since then link a gone branch's merged PR to it or count as
+// its worktree. Liveness still reads every row. Its siblings keep their runs.
+//
+// `fanIn: "integration"` is the one-PR mode: the trunk is an integration
+// branch (never origin's default branch), workers merge its tip into their
+// branch before reporting, and the lead fast-forwards it.
+//
 // The CLI never spawns, waits or wakes anything: it only records and checks.
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { GIT_TIMEOUTS, gitCommonDir, pushRemoteName, resolveRef } from "./git/rev";
-import { appendObserved, defaultBase, storeRoot, type LedgerActor } from "./ledger";
+import {
+  activeStanding,
+  appendObserved,
+  isDelegateSession,
+  defaultBase,
+  readLedger,
+  storeRoot,
+  type LedgerActor,
+} from "./ledger";
 import { stackFileName } from "./stack";
 
 export const FANOUT_VERSION = 1;
@@ -48,15 +69,28 @@ export type Slice = {
   forbidden: string[];
   context: string | null;
   timebox: string | null;
+  /** sliceHash of this definition: which run of the slice a ledger row belongs to. */
+  hash: string;
+  /** When a slice with this hash was first planned: older rows are not its run. */
+  hashSince: string;
 };
 
+export const FAN_IN_MODES = ["prs", "integration"] as const;
+export type FanInMode = (typeof FAN_IN_MODES)[number];
+
 export type FanoutFile = {
   v: number;
   name: string;
   trunk: string;
+  /** prs: one PR per slice (default); integration: slices fast-forward one integration branch. */
+  fanIn: FanInMode;
   /** Extra shared-file globs on top of DEFAULT_SHARED. */
   shared: string[];
   slices: Slice[];
+  /** The lead: the session that made the plan or took it over (`--take-lead`). */
+  leadSession: string | null;
+  /** Leads it took over from: their standing orders stay in force until cleared. */
+  formerLeads: string[];
   createdAt: string;
   updatedAt: string;
 };
@@ -308,6 +342,9 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
     if ("error" in normalized) problems.push(`shared "${entry}" ${normalized.error}`);
     else shared.push(normalized.pattern);
   }
+  const fanIn = raw.fanIn ?? "prs";
+  if (!(FAN_IN_MODES as readonly unknown[]).includes(fanIn))
+    problems.push(`fanIn must be one of ${FAN_IN_MODES.join(", ")}`);
   if (!Array.isArray(raw.slices) || raw.slices.length === 0)
     return { ok: false, problems: [...problems, "slices: list at least one slice"] };
 
@@ -388,6 +425,8 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
       forbidden,
       context: optional("context"),
       timebox: optional("timebox"),
+      hash: "",
+      hashSince: "",
     });
   });
 
@@ -419,8 +458,11 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
       v: FANOUT_VERSION,
       name: planName,
       trunk,
+      fanIn: fanIn as FanInMode,
       shared,
       slices,
+      leadSession: null,
+      formerLeads: [],
       createdAt: "",
       updatedAt: "",
     },
@@ -728,6 +770,29 @@ export function worktreeRoot(cwd: string): string {
   return path.join(path.dirname(main), `${path.basename(main)}-wt`);
 }
 
+/** Whose standing orders count: the lead and those it took over from; null before leads. */
+export const planLeads = (
+  plan: Pick<FanoutFile, "leadSession" | "formerLeads">,
+): string[] | null => (plan.leadSession ? [plan.leadSession, ...plan.formerLeads] : null);
+
+/**
+ * sha256 (16 hex) of the slice's definition. Brief-only fields (tier,
+ * timebox, context) and the worktree path are left out, so fixing a typo in
+ * them never re-dispatches landed work.
+ */
+export function sliceHash(slice: Slice): string {
+  const {
+    worktree: _worktree,
+    hash: _hash,
+    hashSince: _since,
+    tier: _tier,
+    timebox: _timebox,
+    context: _context,
+    ...definition
+  } = slice;
+  return createHash("sha256").update(JSON.stringify(definition)).digest("hex").slice(0, 16);
+}
+
 // ---------------------------------------------------------------------------
 // store
 
@@ -777,8 +842,12 @@ function parseStored(raw: unknown): FanoutFile | null {
       forbidden: list(item.forbidden),
       context: typeof item.context === "string" ? item.context : null,
       timebox: typeof item.timebox === "string" ? item.timebox : null,
+      hash: text(item.hash),
+      // A plan written before slice hashes: its run began at createdAt.
+      hashSince: text(item.hashSince) || text(raw.createdAt),
     });
   }
+  for (const slice of slices) slice.hash ||= sliceHash(slice);
   const shared = globs(raw.shared);
   const ids = new Set(slices.map((slice) => slice.id));
   if (
@@ -788,13 +857,18 @@ function parseStored(raw: unknown): FanoutFile | null {
     findCycle(slices)
   )
     return null;
+  const fanIn = raw.fanIn === "integration" ? "integration" : "prs";
+  const createdAt = text(raw.createdAt);
   return {
     v: typeof raw.v === "number" ? raw.v : FANOUT_VERSION,
     name: raw.name,
     trunk: raw.trunk,
+    fanIn,
     shared,
     slices,
-    createdAt: text(raw.createdAt),
+    leadSession: typeof raw.leadSession === "string" && raw.leadSession ? raw.leadSession : null,
+    formerLeads: list(raw.formerLeads),
+    createdAt,
     updatedAt: text(raw.updatedAt),
   };
 }
@@ -890,6 +964,7 @@ function writeFanout(cwd: string, plan: FanoutFile): FanoutResult<string> {
 export type PlanOutcome = {
   name: string;
   trunk: string;
+  fanIn: FanInMode;
   file: string;
   created: boolean;
   slices: Array<
@@ -899,6 +974,8 @@ export type PlanOutcome = {
   waves: string[][];
   landingOrder: string[];
   notes: string[];
+  /** A new plan under a name that still has standing orders in force (an earlier run's?). */
+  warnings: string[];
 };
 
 /** Above this many slices in one wave, the lead queues the rest (4-6 in flight). */
@@ -906,11 +983,31 @@ export const IN_FLIGHT_CAP = 6;
 
 export function planFanout(
   cwd: string,
-  input: { raw: unknown; name: string | null; trunk: string | null; actor: LedgerActor },
+  input: {
+    raw: unknown;
+    name: string | null;
+    trunk: string | null;
+    actor: LedgerActor;
+    /** Record this session as the lead (a lead resuming in a new session). */
+    takeLead?: boolean;
+  },
   now: Date = new Date(),
 ): FanoutResult<PlanOutcome> {
   const dir = fanoutsDir(cwd);
   if (!dir.ok) return dir;
+  const session = input.actor.session;
+  if (input.takeLead && !session)
+    return fanoutFail(
+      "blocked",
+      "--take-lead needs a session: WORKIT_SESSION_ID is not set",
+      "export WORKIT_SESSION_ID=<your session id>, then plan again with --take-lead",
+    );
+  if (input.takeLead && isDelegateSession(session))
+    return fanoutFail(
+      "blocked",
+      `session ${session} is a worker or verifier id; only a lead takes the lead`,
+      "run --take-lead from the lead's own session",
+    );
   const parsed = parsePlan(
     input.trunk && isRecord(input.raw) ? { ...input.raw, trunk: input.trunk } : input.raw,
     {
@@ -928,6 +1025,12 @@ export function planFanout(
       { problems: parsed.problems },
     );
   const plan = parsed.plan;
+  if (plan.fanIn === "integration" && plan.trunk === defaultTrunk(cwd))
+    return fanoutFail(
+      "invalid_input",
+      `fanIn "integration" needs an integration branch as the trunk, not ${plan.trunk}`,
+      `workit git branch <integration-branch> --base ${plan.trunk}, then plan with --trunk <integration-branch>`,
+    );
   const badBranches = plan.slices
     .filter((slice) => !gitRun(cwd, ["check-ref-format", "--branch", slice.branch]).ok)
     .map((slice) => `slice ${slice.id}: ${slice.branch} is not a valid branch name`);
@@ -975,20 +1078,60 @@ export function planFanout(
   const existing = readFanout(cwd, plan.name);
   const previous = existing.ok ? existing.data : null;
   plan.createdAt = previous?.createdAt || now.toISOString();
+  // A re-plan keeps the lead (and a plan from before leads stays without one)
+  // unless this session takes it over.
+  plan.leadSession = input.takeLead ? session : previous ? previous.leadSession : session;
+  plan.formerLeads = [
+    ...new Set([
+      ...(previous?.formerLeads ?? []),
+      ...(previous?.leadSession && previous.leadSession !== plan.leadSession
+        ? [previous.leadSession]
+        : []),
+    ]),
+  ].filter((former) => former !== plan.leadSession);
   plan.updatedAt = now.toISOString();
+  // Per slice: the same definition continues its run; a changed one starts anew.
+  for (const slice of plan.slices) {
+    slice.hash = sliceHash(slice);
+    const before = previous?.slices.find((old) => old.id === slice.id);
+    slice.hashSince =
+      before && before.hash === slice.hash ? before.hashSince || plan.updatedAt : plan.updatedAt;
+  }
   const written = writeFanout(cwd, plan);
   if (!written.ok) return written;
+  if (previous && plan.leadSession !== previous.leadSession)
+    appendObserved(cwd, {
+      type: "fanout.lead.changed",
+      actor: input.actor,
+      fanout: plan.name,
+      from: previous.leadSession,
+      to: plan.leadSession,
+    });
   appendObserved(cwd, {
     type: "fanout.planned",
     actor: input.actor,
     fanout: plan.name,
     trunk: plan.trunk,
+    fanIn: plan.fanIn,
     slices: plan.slices.length,
     ids: plan.slices.slice(0, 20).map((slice) => slice.id),
   });
 
   const grouped = waves(plan.slices);
   const notes: string[] = [];
+  const warnings: string[] = [];
+  if (!input.takeLead && previous?.leadSession && session && session !== previous.leadSession)
+    notes.push(
+      `the lead stays ${previous.leadSession}; this session is ${session}. Leading from this session now? workit fanout plan <plan.json> --take-lead`,
+    );
+  if (previous === null) {
+    const ledger = readLedger(cwd);
+    const inForce = ledger.ok ? activeStanding(ledger.value.rows, plan.name, planLeads(plan)) : [];
+    if (inForce.length)
+      warnings.push(
+        `${inForce.length} standing order${inForce.length === 1 ? " is" : "s are"} already in force for fanout ${plan.name}, and every brief will carry ${inForce.length === 1 ? "it" : "them"}: ${inForce.map((row) => `"${String(row.what)}"`).join("; ")}. From an earlier run? workit ledger standing clear --fanout ${plan.name}`,
+      );
+  }
   if (!ref)
     notes.push(
       `trunk ${plan.trunk} does not resolve here; only sample paths of each glob were compared`,
@@ -1009,6 +1152,7 @@ export function planFanout(
     data: {
       name: plan.name,
       trunk: plan.trunk,
+      fanIn: plan.fanIn,
       file: written.data,
       created: previous === null,
       slices: plan.slices.map(({ id, branch, base, worktree, tier, dependsOn, scope, owns }) => ({
@@ -1025,6 +1169,7 @@ export function planFanout(
       waves: grouped,
       landingOrder: landingOrder(plan.slices),
       notes,
+      warnings,
     },
   };
 }

package/src/forge/pr-ops.ts

@@ -9,13 +9,19 @@
 // merge: three independent gates, all required:
 //   1. the S10 status document reads READY (required checks green, no
 //      conflicts, threads, review or draft blockers);
-//   2. an accepted S13 verdict for that exact head (fresh or carried), unless
-//      the workspace grants `merge: true`;
+//   2. an accepted S13 verdict for that exact head (fresh or carried). Under
+//      `merge: true` only, `--unverified --reason` bypasses it, and the bypass
+//      is recorded (`merge.unverified`) before the merge call;
 //   3. the `merge` grant (autonomy.ts `requireGrant`; S16 fills the defaults).
 // The merge call carries the head SHA (GitHub `sha=`, GitLab `sha=`), so a
 // head that moves after the gates refuses instead of merging unverified code.
 // --delete-branch deletes with a lease on that same SHA.
-import { requireGrant, type AutonomySource } from "../autonomy";
+import {
+  requireGrant,
+  resolveAutonomy,
+  type AutonomySource,
+  type DefaultEndpoint,
+} from "../autonomy";
 import { isProtectedTarget } from "../core/branch";
 import { vcsConfig } from "../core/vcs-config";
 import { workspaceReleaseTracks } from "../core/release-tracks";
@@ -64,6 +70,20 @@ export type CreateOutcome = {
   created: boolean;
   draft: boolean;
   recorded: { id: string } | { error: string };
+  /** The review step and what the effective endpoint does after it. */
+  next: string;
+};
+
+const AFTER_REVIEW: Record<DefaultEndpoint, string> = {
+  commit: "stop here; review comes when the user asks",
+  pr: "stop here; review comes when the user asks",
+  green: "babysit it to merge-ready, never merging",
+  merged: "babysit it, then land it after verification",
+};
+
+const createNext = (cwd: string): string => {
+  const endpoint = resolveAutonomy(cwd).effectiveEndpoint;
+  return `a non-author verifies the head (workit-review); the endpoint is ${endpoint}, so ${AFTER_REVIEW[endpoint]}`;
 };
 
 /**
@@ -231,6 +251,7 @@ export async function createPullRequest(
     created,
     draft: input.draft,
     recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
+    next: createNext(cwd),
   });
 }
 
@@ -247,6 +268,8 @@ export type MergeInput = {
    * comes from this branch, re-checked right before the merge call.
    */
   expect?: { base: string; branch: string };
+  /** Merge without a verdict (`merge: true` only); the reason is recorded. */
+  unverified?: { reason: string };
 };
 
 export type MergeOutcome = {
@@ -258,6 +281,8 @@ export type MergeOutcome = {
   method: MergeMethod;
   mergeSha: string | null;
   verdict: { required: boolean; accepted: boolean; verdictId: string | null };
+  /** Set when `--unverified` bypassed the verdict: the reason and its ledger row. */
+  unverified: { reason: string; recorded: string } | null;
   grant: { source: AutonomySource };
   deletedBranch: boolean | { error: string };
   recorded: { id: string } | { error: string };
@@ -294,6 +319,8 @@ const mergeBackFor = (cwd: string, base: string): { track: string | null; branch
 export type MergeRefusal = {
   reason:
     | "grant_required"
+    | "unverified_refused"
+    | "failed_verdict"
     | "not_ready"
     | "needs_verdict"
     | "head_mismatch"
@@ -346,6 +373,15 @@ export async function mergePullRequest(
 ): Promise<MergeResult> {
   const grant = requireGrant(cwd, "merge");
   if (!grant.allowed) return refuse(grant.error, grant.unblock, { reason: "grant_required" });
+  const bypass = input.unverified ?? null;
+  if (bypass && !bypass.reason.trim())
+    return failure("invalid_input", "--unverified needs --reason <why the user asked for it>");
+  if (bypass && !grant.allowUnverified)
+    return refuse(
+      `unverified_refused: workspace ${grant.workspace ? `"${grant.workspace}"` : "(none)"} grants merge: "verified", which never merges without an accepted independent verdict`,
+      "a non-author session verifies the head (workit-review), then merge without --unverified",
+      { reason: "unverified_refused" },
+    );
 
   const number = selectPr(cwd, resolved, { pr: input.pr });
   if (!number.ok) return number;
@@ -404,34 +440,57 @@ export async function mergePullRequest(
         { reason: "protected_branch" },
       );
   }
+  const ledger = readLedger(cwd);
+  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;
   let verdict: MergeOutcome["verdict"] = {
-    required: grant.requireVerdict,
-    accepted: false,
-    verdictId: null,
+    required: true,
+    accepted: covered,
+    verdictId:
+      covered && typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null,
   };
-  if (grant.requireVerdict) {
-    const ledger = readLedger(cwd);
-    if (!ledger.ok) return ledger;
-    const check = checkVerdicts(cwd, branch, ledger.value.rows);
-    const summary = { head: check.head, accepted: check.accepted, authors: check.authors };
-    if (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`,
-        { reason: "head_mismatch", verdict: summary },
-      );
-    if (!check.accepted.accepted)
-      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}`,
-        { reason: "needs_verdict", verdict: summary },
+  let unverified: MergeOutcome["unverified"] = null;
+  // The bypass covers a missing verdict, never a rejection.
+  if (!covered && bypass && check.accepted.reasons.includes("failing_verdict"))
+    return refuse(
+      `failed_verdict: ${label} has a current independent failed verdict${typeof check.accepted.verdict?.id === "string" ? ` (${check.accepted.verdict.id})` : ""}; --unverified never merges over a rejection`,
+      "a new independent verdict on the head supersedes it",
+      { reason: "failed_verdict", verdict: summary },
+    );
+  if (!covered && bypass) {
+    // Recorded before the merge call: a bypass that cannot be audited never merges.
+    const reason = bypass.reason.trim();
+    const recorded = appendObserved(cwd, {
+      type: "merge.unverified",
+      actor: input.actor,
+      branch,
+      head,
+      pr: doc.number,
+      base: doc.base,
+      reason,
+      grant: grant.source,
+    });
+    if (!recorded.ok)
+      return failure(
+        "failed",
+        `unverified_unrecorded: the --unverified bypass could not be recorded (${recorded.error}); nothing was merged`,
       );
-    verdict = {
-      required: true,
-      accepted: true,
-      verdictId: typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null,
-    };
-  }
+    verdict = { required: false, accepted: false, verdictId: null };
+    unverified = { reason, recorded: String(recorded.value.id) };
+  } else if (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`,
+      { reason: "head_mismatch", verdict: summary },
+    );
+  else if (!covered)
+    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>"` : ""}`,
+      { reason: "needs_verdict", verdict: summary },
+    );
 
   const merged = resolved.forge.merge(doc.number, { sha: head, method: input.method });
   if (!merged.ok) return merged;
@@ -470,6 +529,7 @@ export async function mergePullRequest(
     mergeSha: merged.data.mergeSha,
     method: input.method,
     verdictId: verdict.verdictId,
+    ...(unverified ? { unverified: unverified.recorded } : {}),
     grant: grant.source,
   });
   return {
@@ -483,6 +543,7 @@ export async function mergePullRequest(
       method: input.method,
       mergeSha: merged.data.mergeSha,
       verdict,
+      unverified,
       grant: { source: grant.source },
       deletedBranch,
       recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },