@brainervirus/workit-core 7.2.0 → 7.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "7.2.0",
+  "version": "7.3.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

@@ -10,41 +10,49 @@ verifiable alone. Code-coupled work stays with one owner, who fans out after
 the blocking part lands. A worker whose whole job is re-running one command is
 ceremony; do it yourself.
 
-1. **Slice** (workit-shape): each slice gets a branch, a file-scope manifest
-   (the globs it may write) and, if it depends on another, its stack parent.
-2. **Check disjointness.** No two manifests overlap. Shared files (lockfile,
-   registry, barrel exports) belong to one slice, or to you after fan-in.
-3. **Brief each worker** with the fixed template and refuse to spawn while a
-   field is empty: GOAL, SCOPE (the manifest), CONTEXT (pointers, not pasted
-   text), ACCEPTANCE (Given/When/Then), VERIFY (exact commands), TIMEBOX,
-   FORBIDDEN, REPORT, STANDING. STANDING is every standing order and user
-   directive so far, pasted verbatim into each spawn and respawn, because
-   directives decay across resumes. Template: `references/brief.md`.
-4. **Spawn all workers in one message**, in the background, each in its own
+1. **Plan the slices** (workit-shape) in a plan file (`references/brief.md`):
+   per slice an id, branch, TIER, the file-scope manifest (SCOPE globs),
+   `owns` for shared files (lockfile, registry, barrels), `dependsOn` only for
+   a real dependency (independent PRs off trunk are the default), and the
+   brief fields. `workit fanout plan <plan.json>` refuses an empty brief field
+   (exit 2) and two slices that may write one file (exit 3) with a fix: an
+   owner for a shared file, or a dependency that serializes them. Apply it and
+   re-run: refuse to spawn while a field is empty or the plan is refused.
+   Its `waves` say which slices may run together; keep 4-6 in flight.
+2. **Brief each worker** from its slice with the fixed template: GOAL, SCOPE,
+   CONTEXT (pointers, not pasted text), ACCEPTANCE (Given/When/Then), VERIFY
+   (exact commands), TIER, TIMEBOX, FORBIDDEN, REPORT, STANDING. STANDING is
+   every standing order and user directive so far, pasted verbatim into each
+   spawn and respawn, because directives decay across resumes.
+3. **Spawn all workers in one message**, in the background, each in its own
    worktree (Claude Code: the `implementer` agent; elsewhere
    `git worktree add --detach ../<repo>-wt/<slug> origin/<base>`). The first
    command a worker runs is `workit git branch <branch> --base <base>`.
-5. **Judge liveness by side effects only:** new commits and pushes
+4. **Judge liveness by side effects only:** new commits and pushes
    (`git log <branch>`), PR and check changes (`workit pr status --branch <b>`).
    No progress past the timebox means stuck. Stop the old worker and observe
    that it exited (a timeout is not proof). `git worktree remove --force`
    drops its uncommitted changes, so first record `git -C <wt> status --short`
-   in the ledger or your report; only then remove the worktree. Respawn with the brief in
-   `MODE: resume` (consolidated: original, later directives, its last report):
+   in the ledger or your report; only then remove the worktree. Respawn with
+   the brief in `MODE: resume` (original, later directives, its last report):
    the new worker runs `git switch <branch>` in its fresh worktree instead of
    `workit git branch`. Never two live workers on one branch. Replace at most
    twice, then re-slice or report the gap. Never chain resumes.
-6. **Verify each slice independently.** A fresh agent that did not write it
+5. **Verify each slice independently.** A fresh agent that did not write it
    (Claude Code: the `verifier` agent) runs VERIFY and verify-<app>, then
    `workit ledger verdict <result> --branch <b> --how "<evidence>"` under the
    session you started it with (`WORKIT_SESSION_ID=<lead>-v<n>`, set by you,
    never chosen by the author; Claude Code: the hook names one).
    A worker's report is a pointer, never evidence.
-7. **Fan in.** Compare `git diff --name-only <base>...<b>` with the slice's
-   SCOPE: any file outside it stops the fan-in with a report. Then
-   `workit ledger check --branch <b>` for each slice; restack
-   stacked slices with `workit stack sync`. Only you touch topology: workers
-   never rebase, retarget or merge. Then workit-ship.
+6. **Fan in** with `workit fanout check`: out-of-scope files (any file outside
+   it stops the fan-in), and `git merge-tree` conflicts with trunk and between
+   siblings, charged to the slice that lands later. Fix what it names (an
+   out-of-scope edit becomes a follow-up slice) until it exits 0. A landed
+   slice reads as not found: re-plan without it and drop it from dependents'
+   `dependsOn`. Then `workit ledger check --branch <b>` per slice; land in its
+   order. Stacked slices: `workit stack plan <bottom> … <top>` once, then
+   `workit stack sync` and `land`. Only you touch topology: workers never
+   rebase, retarget or merge. Then workit-ship.
 
 ## Example
 
@@ -58,5 +66,6 @@ counts; SCOPE: `src/routes/usage.ts`, `test/usage.test.ts`; VERIFY:
 ## Check
 
 ```sh
+workit fanout check                # exit 0: in scope, no conflicts, landing order printed
 workit ledger check --branch <b>   # per slice: accepted (current, passing, independent)
 ```

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

@@ -12,6 +12,7 @@ CONTEXT: <pointers: spec section, ledger decisions, the neighbour file to imitat
 ACCEPTANCE:
   - Given <state>, When <action>, Then <observable result>
 VERIFY: <exact commands, e.g. `workit check test`, the verify-<app> feature to drive>
+TIER: <mundane | standard | hard: how much model the slice needs>
 TIMEBOX: <wall clock or turn budget; past it without a new commit you will be replaced>
 FORBIDDEN: <no edits outside SCOPE; no rebase, retarget, merge or force-push; no new dependencies; ...>
 REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
@@ -34,12 +35,56 @@ ACCEPTANCE:
   - Given 3 runs today and 1 yesterday, When GET /v1/usage, Then the last two entries are {"runs":1} and {"runs":3}
   - Given no auth header, When GET /v1/usage, Then the status is 401
 VERIFY: `workit check test`; verify-api feature "usage"
+TIER: standard
 TIMEBOX: 45 minutes
 FORBIDDEN: no edits outside SCOPE; no schema migration; no rebase or force-push; no new packages
 REPORT: as in the template
 STANDING: conventional commits; no comments that restate code; ask nothing, record rulings instead
 ```
 
+## Plan file
+
+`workit fanout plan <plan.json>` records the slices before any spawn. Each
+slice carries the brief fields the plan checks (goal, scope, acceptance,
+verify, forbidden must be filled; tier is mundane, standard or hard). `base`
+defaults to the trunk, or to the branch of a single `dependsOn` slice (a
+stack); `worktree` defaults to `../<repo>-wt/<id>`. `owns` claims a shared
+file another slice's glob also matches. Globs that match no file yet are compared
+through a sample path. Escape literal brackets: `"app/\\[id\\]/page.tsx"`.
+
+```json
+{
+  "name": "usage",
+  "trunk": "main",
+  "slices": [
+    {
+      "id": "usage-endpoint",
+      "branch": "feature/usage-endpoint",
+      "tier": "standard",
+      "scope": ["src/routes/usage.ts", "src/queries/usage.ts", "test/usage.test.ts"],
+      "owns": ["package.json"],
+      "goal": "GET /v1/usage returns the run count per UTC day for the last 7 days",
+      "acceptance": ["Given no auth header, When GET /v1/usage, Then the status is 401"],
+      "verify": ["workit check test"],
+      "forbidden": ["no edits outside SCOPE", "no rebase or force-push"],
+      "context": "docs/usage/spec.md Behavior",
+      "timebox": "45 minutes"
+    },
+    {
+      "id": "usage-docs",
+      "branch": "docs/usage",
+      "tier": "mundane",
+      "dependsOn": ["usage-endpoint"],
+      "scope": ["docs/usage/**"],
+      "goal": "The API guide documents GET /v1/usage",
+      "acceptance": ["Given the guide, When a reader looks up usage, Then the response shape is shown"],
+      "verify": ["workit check docs"],
+      "forbidden": ["no edits outside SCOPE"]
+    }
+  ]
+}
+```
+
 ## Worker rules (paste into the brief when the host has no implementer agent)
 
 1. First command. `MODE: new`: `workit git branch <branch> --base <base>` (the

package/src/fanout-check.ts

@@ -0,0 +1,294 @@
+// `workit fanout check` (G2): the fan-in gate over a recorded fanout plan.
+//
+// For each slice branch it reads what git says, never what a worker reported:
+// - scope: `git diff --name-only <base>...<branch>` against the slice's
+//   manifest (its scope and owns, minus files another slice owns); any other
+//   file is an out-of-scope edit;
+// - trunk: `git merge-tree --write-tree` of the branch with the trunk;
+// - siblings: the same merge between every pair of slice branches, so two
+//   PRs that would conflict once the first lands are caught before either
+//   does. A pairwise conflict is charged to the slice that lands later; the
+//   earlier one stays landable.
+// The landing order puts dependencies first, then the plan's order. A slice
+// is ready when none of the above fired and every slice it depends on is
+// ready. Verdicts are reported (`workit ledger check`) but gated by
+// `workit pr merge`, not here. Refs are read as they are locally: fetch first.
+import { checkVerdicts, readLedger, type ReadRow } from "./ledger";
+import {
+  FANOUT_VERSION,
+  branchRef,
+  fanoutFail,
+  gitRun,
+  inScope,
+  landingOrder,
+  nulList,
+  trunkRef,
+  type FanoutFile,
+  type FanoutResult,
+  type Slice,
+} from "./fanout";
+
+export type SliceStatus = "ready" | "blocked";
+
+export type SliceCheck = {
+  id: string;
+  branch: string;
+  head: string | null;
+  base: string;
+  status: SliceStatus;
+  changed: number;
+  outOfScope: string[];
+  trunkConflicts: string[];
+  siblingConflicts: Array<{ with: string; paths: string[] }>;
+  waitsFor: string[];
+  verdict: { accepted: boolean; basis: string };
+  reasons: string[];
+};
+
+export type SiblingConflict = {
+  /** Lands first in the landing order. */
+  first: string;
+  /** Lands second; it carries the conflict. */
+  second: string;
+  paths: string[];
+  /** The two branches name one file with different case (one file on macOS and Windows). */
+  caseOnly?: true;
+  resolution: string;
+};
+
+export type CheckOutcome = {
+  name: string;
+  trunk: string;
+  trunkRef: string;
+  ready: boolean;
+  slices: SliceCheck[];
+  conflicts: SiblingConflict[];
+  landingOrder: string[];
+  next: string;
+  notes: string[];
+};
+
+const SAFE = (value: string | null): value is string => Boolean(value) && !value?.startsWith("-");
+
+/** Paths both sides change incompatibly, [] when clean, or an error. */
+function mergeConflicts(cwd: string, a: string, b: string): string[] | { error: string } {
+  const run = gitRun(cwd, [
+    "merge-tree",
+    "--write-tree",
+    "--name-only",
+    "--no-messages",
+    "-z",
+    a,
+    b,
+  ]);
+  if (run.status === 0) return [];
+  if (run.status === 1) return [...new Set(nulList(run.stdout).slice(1))];
+  const first = run.stderr.trim().split("\n")[0] || `git merge-tree exited ${run.status}`;
+  return {
+    error: /write-tree|usage: git merge-tree/u.test(run.stderr)
+      ? `${first} (needs git >= 2.38 for merge-tree --write-tree)`
+      : first,
+  };
+}
+
+const isAncestor = (cwd: string, a: string, b: string): boolean =>
+  gitRun(cwd, ["merge-base", "--is-ancestor", a, b]).ok;
+
+export function checkFanout(
+  cwd: string,
+  plan: FanoutFile,
+  options: { only?: readonly string[]; trunkRef?: string | null } = {},
+): FanoutResult<CheckOutcome> {
+  const unknown = (options.only ?? []).filter((id) => !plan.slices.some((s) => s.id === id));
+  if (unknown.length)
+    return fanoutFail(
+      "invalid_input",
+      `${unknown.join(", ")}: not a slice of fanout ${plan.name}`,
+      `slices: ${plan.slices.map((slice) => slice.id).join(", ")}`,
+    );
+  const trunk = options.trunkRef ?? trunkRef(cwd, plan.trunk);
+  if (!SAFE(trunk) || !resolves(cwd, trunk))
+    return fanoutFail(
+      "unavailable",
+      `trunk ${options.trunkRef ?? plan.trunk} does not resolve here`,
+      `git fetch, or pass --base <ref>`,
+    );
+  const order = landingOrder(plan.slices);
+  const byId = new Map(plan.slices.map((slice) => [slice.id, slice]));
+  const tips = new Map(plan.slices.map((slice) => [slice.id, branchRef(cwd, slice.branch)]));
+  const ledger = readLedger(cwd);
+  const rows: readonly ReadRow[] = ledger.ok ? ledger.value.rows : [];
+
+  const checks = new Map<string, SliceCheck>();
+  const changedBy = new Map<string, string[]>();
+  for (const slice of plan.slices)
+    checks.set(slice.id, inspect(cwd, plan, slice, trunk, tips, rows, changedBy));
+
+  // Pairwise siblings: skip a pair where one contains the other (a stacked child).
+  const conflicts: SiblingConflict[] = [];
+  for (let i = 0; i < order.length; i += 1)
+    for (let j = i + 1; j < order.length; j += 1) {
+      const first = order[i];
+      const second = order[j];
+      const a = tips.get(first);
+      const b = tips.get(second);
+      if (!a || !b || isAncestor(cwd, a, b) || isAncestor(cwd, b, a)) continue;
+      const check = checks.get(second) as SliceCheck;
+      const theirs = new Map(
+        (changedBy.get(first) ?? []).map((file) => [file.toLowerCase(), file]),
+      );
+      const cased = (changedBy.get(second) ?? []).flatMap((file) => {
+        const other = theirs.get(file.toLowerCase());
+        return other !== undefined && other !== file ? [`${other} ~ ${file}`] : [];
+      });
+      if (cased.length) {
+        conflicts.push({
+          first,
+          second,
+          paths: cased,
+          caseOnly: true,
+          resolution: `use ${first}'s spelling on ${second} (git mv), then workit fanout check`,
+        });
+        check.siblingConflicts.push({ with: first, paths: cased });
+        check.reasons.push(`differs only in case from ${first}: ${cased.join(", ")}`);
+      }
+      const result = mergeConflicts(cwd, a, b);
+      if (!Array.isArray(result)) {
+        check.reasons.push(`cannot merge with ${first}: ${result.error}`);
+        continue;
+      }
+      if (result.length === 0) continue;
+      const related = byId.get(second)?.dependsOn.includes(first);
+      conflicts.push({
+        first,
+        second,
+        paths: result,
+        resolution: related
+          ? `rebase ${second} onto ${byId.get(first)?.branch} (its dependency), then workit fanout check`
+          : `land ${first} first, then rebase ${second} onto ${plan.trunk} and run workit fanout check; or make ${second} depend on ${first}`,
+      });
+      check.siblingConflicts.push({ with: first, paths: result });
+      check.reasons.push(`conflicts with ${first} on ${result.join(", ")}`);
+    }
+
+  for (const id of order) {
+    const check = checks.get(id) as SliceCheck;
+    check.waitsFor = (byId.get(id)?.dependsOn ?? []).filter(
+      (dep) => checks.get(dep)?.status !== "ready",
+    );
+    if (check.waitsFor.length) check.reasons.push(`waits for ${check.waitsFor.join(", ")}`);
+    check.status = check.reasons.length ? "blocked" : "ready";
+  }
+
+  const selected = options.only?.length ? new Set(options.only) : null;
+  const slices = order
+    .filter((id) => !selected || selected.has(id))
+    .map((id) => checks.get(id) as SliceCheck);
+  const ready = slices.every((check) => check.status === "ready");
+  const blocked = slices.find((check) => check.status === "blocked");
+  const notes =
+    plan.v === FANOUT_VERSION
+      ? []
+      : [
+          `plan file version ${plan.v} is not ${FANOUT_VERSION}; read leniently (re-plan to rewrite it)`,
+        ];
+  const next = blocked
+    ? unblockFor(blocked, plan)
+    : `land in this order: ${slices.map((check) => check.id).join(", ")} (workit pr merge each once verified; stacked slices with workit stack land)`;
+  return {
+    ok: true,
+    data: {
+      name: plan.name,
+      trunk: plan.trunk,
+      trunkRef: trunk,
+      ready,
+      slices,
+      conflicts: conflicts.filter(
+        (conflict) => !selected || selected.has(conflict.first) || selected.has(conflict.second),
+      ),
+      landingOrder: order,
+      notes,
+      next,
+    },
+  };
+}
+
+const resolves = (cwd: string, ref: string): boolean =>
+  gitRun(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).ok;
+
+function inspect(
+  cwd: string,
+  plan: FanoutFile,
+  slice: Slice,
+  trunk: string,
+  tips: ReadonlyMap<string, string | null>,
+  rows: readonly ReadRow[],
+  changedBy: Map<string, string[]>,
+): SliceCheck {
+  const head = tips.get(slice.id) ?? null;
+  const check: SliceCheck = {
+    id: slice.id,
+    branch: slice.branch,
+    head,
+    base: slice.base,
+    status: "blocked",
+    changed: 0,
+    outOfScope: [],
+    trunkConflicts: [],
+    siblingConflicts: [],
+    waitsFor: [],
+    verdict: { accepted: false, basis: "missing" },
+    reasons: [],
+  };
+  if (!head) {
+    check.reasons.push(`branch ${slice.branch} not found (not started, landed, or not fetched)`);
+    return check;
+  }
+  const parent = plan.slices.find((other) => other.branch === slice.base);
+  const baseRef =
+    slice.base === plan.trunk
+      ? trunk
+      : parent
+        ? (tips.get(parent.id) ?? null)
+        : branchRef(cwd, slice.base);
+  if (!SAFE(baseRef)) {
+    check.reasons.push(`base ${slice.base} not found`);
+    return check;
+  }
+  const diff = gitRun(cwd, ["diff", "--name-only", "--no-renames", "-z", `${baseRef}...${head}`]);
+  if (!diff.ok) {
+    check.reasons.push(`cannot diff ${slice.base}...${slice.branch}: ${diff.stderr.trim()}`);
+    return check;
+  }
+  const changed = nulList(diff.stdout);
+  changedBy.set(slice.id, changed);
+  check.changed = changed.length;
+  if (changed.length === 0) check.reasons.push(`no changes beyond ${slice.base}`);
+  check.outOfScope = changed.filter((file) => !inScope(plan, slice, file)).toSorted();
+  if (check.outOfScope.length)
+    check.reasons.push(`edits outside its scope: ${check.outOfScope.join(", ")}`);
+  const trunkResult = mergeConflicts(cwd, trunk, head);
+  if (Array.isArray(trunkResult)) {
+    check.trunkConflicts = trunkResult;
+    if (trunkResult.length)
+      check.reasons.push(`conflicts with ${plan.trunk} on ${trunkResult.join(", ")}`);
+  } else check.reasons.push(`cannot merge with ${plan.trunk}: ${trunkResult.error}`);
+  const verdict = checkVerdicts(cwd, slice.branch, rows);
+  check.verdict = { accepted: verdict.accepted.accepted, basis: verdict.current.basis };
+  return check;
+}
+
+function unblockFor(check: SliceCheck, plan: FanoutFile): string {
+  if (!check.head)
+    return `start or fetch ${check.branch}, then workit fanout check; if it landed, re-plan without slice ${check.id}`;
+  if (check.outOfScope.length)
+    return `move ${check.outOfScope.join(", ")} off ${check.branch} (a follow-up slice), or widen slice ${check.id}'s scope with workit fanout plan, then workit fanout check`;
+  if (check.trunkConflicts.length)
+    return `rebase ${check.branch} onto ${plan.trunk} and resolve ${check.trunkConflicts.join(", ")}, then workit fanout check`;
+  if (check.siblingConflicts.length) {
+    const first = check.siblingConflicts[0].with;
+    return `land ${first} first, then rebase ${check.branch} onto ${plan.trunk} and run workit fanout check`;
+  }
+  if (check.waitsFor.length) return `unblock ${check.waitsFor.join(", ")} first`;
+  return check.reasons[0] ?? "workit fanout check";
+}

package/src/fanout.ts

@@ -0,0 +1,916 @@
+// `workit fanout plan` (G1): the slice registry for parallel work.
+//
+// A plan names the slices one lead fans out: each has an id, a branch, a base,
+// a worktree, a model TIER, its dependencies and a brief (GOAL, SCOPE as a
+// file-scope manifest, ACCEPTANCE, VERIFY, FORBIDDEN). The file lives at
+// `<store>/fanouts/<name>.json` (D13: under the git common dir, shared by
+// every worktree, surviving worktree removal), next to the stacks, and each
+// plan appends an observed `fanout.planned` ledger row.
+//
+// Planning refuses (`invalid_input`) a brief with an empty or placeholder
+// field, unknown or cyclic dependencies and malformed scopes, and refuses
+// (`blocked`) two slices that may write the same file unless that is
+// resolved: exactly one slice lists the file under `owns`, or the slices are
+// serialized by a dependency. Overlap is evaluated on the trunk's tracked
+// files plus one sample path per glob (`src/new/**` -> `src/new/<any>`), so
+// directories nobody has created yet are compared too, and paths differing
+// only in case count as one file. Each unresolved overlap carries one
+// deterministic suggestion: an owner for known shared files (lockfiles,
+// manifests, barrels, CI config), else a dependency that serializes them.
+//
+// The CLI never spawns, waits or wakes anything: it only records and checks.
+import { spawnSync } from "node:child_process";
+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 { stackFileName } from "./stack";
+
+export const FANOUT_VERSION = 1;
+export const TIERS = ["mundane", "standard", "hard"] as const;
+export type Tier = (typeof TIERS)[number];
+
+export type Slice = {
+  id: string;
+  branch: string;
+  /** The branch it is cut from and diffed against: the trunk, or its single dependency's branch. */
+  base: string;
+  worktree: string;
+  tier: Tier;
+  dependsOn: string[];
+  /** The file-scope manifest: globs (`*`, `**`, `?`, `{a,b}`) relative to the repo root. */
+  scope: string[];
+  /** Shared files this slice alone may write, even where another scope matches them. */
+  owns: string[];
+  goal: string;
+  acceptance: string[];
+  verify: string[];
+  forbidden: string[];
+  context: string | null;
+  timebox: string | null;
+};
+
+export type FanoutFile = {
+  v: number;
+  name: string;
+  trunk: string;
+  /** Extra shared-file globs on top of DEFAULT_SHARED. */
+  shared: string[];
+  slices: Slice[];
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type FanoutError = {
+  ok: false;
+  code: "blocked" | "busy" | "failed" | "unavailable" | "not_found" | "invalid_input";
+  error: string;
+  unblock?: string;
+  data?: Record<string, unknown>;
+};
+export type FanoutResult<T> = { ok: true; data: T } | FanoutError;
+
+export const fanoutFail = (
+  code: FanoutError["code"],
+  error: string,
+  unblock?: string,
+  data?: Record<string, unknown>,
+): FanoutError => ({
+  ok: false,
+  code,
+  error,
+  ...(unblock ? { unblock } : {}),
+  ...(data ? { data } : {}),
+});
+
+/** Files that every slice tends to touch; overlap on them is resolved by an owner. */
+export const DEFAULT_SHARED: readonly string[] = [
+  "**/package.json",
+  "**/{package-lock.json,npm-shrinkwrap.json,bun.lock,bun.lockb,pnpm-lock.yaml,pnpm-workspace.yaml,yarn.lock}",
+  "**/{Cargo.lock,go.mod,go.sum,poetry.lock,uv.lock,Gemfile.lock,composer.lock}",
+  "**/index.{ts,tsx,js,jsx,mjs,cjs}",
+  "**/tsconfig.json",
+  ".github/**",
+  ".gitlab-ci.yml",
+  "CHANGELOG.md",
+];
+
+// ---------------------------------------------------------------------------
+// scope globs
+
+const escapeRegExp = (text: string): string => text.replace(/[.+^$()|[\]\\{}*?]/gu, "\\$&");
+/** The pattern with `\x` escapes resolved: what a wildcard-free pattern names. */
+const unescape = (pattern: string): string => pattern.replace(/\\(.)/gu, "$1");
+/** Has an unescaped `*`, `?` or `{`. */
+const hasWildcard = (pattern: string): boolean => /[*?{]/u.test(pattern.replace(/\\./gu, ""));
+
+/**
+ * One concrete path the pattern matches, standing in for files nobody has
+ * created yet: `src/new/**` -> `src/new/<any>`, `src/*.ts` -> `src/<any>.ts`.
+ */
+export function scopeSamples(pattern: string): string[] {
+  // A plain path covers what is below it too, so `src/new` and `src/new/**`
+  // overlap through `src/new/<any>` without a second sample.
+  if (!hasWildcard(pattern)) return [unescape(pattern)];
+  let out = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "\\" && index + 1 < pattern.length) {
+      out += pattern[index + 1];
+      index += 1;
+    } else if (char === "*" && pattern[index + 1] === "*") {
+      const atSegmentStart = index === 0 || pattern[index - 1] === "/";
+      if (atSegmentStart && pattern[index + 2] === "/") index += 2;
+      else {
+        out += "<any>";
+        index += 1;
+      }
+    } else if (char === "*") out += "<any>";
+    else if (char === "?") out += "x";
+    else if (char === "{" && pattern.indexOf("}", index) > index) {
+      const close = pattern.indexOf("}", index);
+      out += pattern.slice(index + 1, close).split(",")[0];
+      index = close;
+    } else out += char;
+  }
+  return [out];
+}
+
+function globSource(pattern: string): string {
+  let out = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "\\" && index + 1 < pattern.length) {
+      out += escapeRegExp(pattern[index + 1]);
+      index += 1;
+    } else if (char === "*" && pattern[index + 1] === "*") {
+      const atSegmentStart = index === 0 || pattern[index - 1] === "/";
+      if (atSegmentStart && pattern[index + 2] === "/") {
+        out += "(?:[^/]*/)*";
+        index += 2;
+      } else {
+        out += ".*";
+        index += 1;
+      }
+    } else if (char === "*") out += "[^/]*";
+    else if (char === "?") out += "[^/]";
+    else if (char === "{" && pattern.indexOf("}", index) > index) {
+      // An unclosed brace is a literal `{` (stored plans are not trusted).
+      const close = pattern.indexOf("}", index);
+      const alternatives = pattern
+        .slice(index + 1, close)
+        .split(",")
+        .map(globSource);
+      out += `(?:${alternatives.join("|")})`;
+      index = close;
+    } else out += escapeRegExp(char);
+  }
+  return out;
+}
+
+const compiled = new Map<string, RegExp>();
+
+/**
+ * Does `file` (repo-relative, `/`-separated) fall under `pattern`? Dotfiles
+ * match like any other name, the same on every runtime. A pattern without
+ * wildcards also covers everything below it, so `src/api` is a directory
+ * scope as well as a file.
+ */
+export function matchesScope(pattern: string, file: string): boolean {
+  let regex = compiled.get(pattern);
+  if (!regex) {
+    regex = new RegExp(`^${globSource(pattern)}$`, "u");
+    compiled.set(pattern, regex);
+  }
+  return regex.test(file) || (!hasWildcard(pattern) && file.startsWith(`${unescape(pattern)}/`));
+}
+
+const matchesAny = (patterns: readonly string[], file: string): boolean =>
+  patterns.some((pattern) => matchesScope(pattern, file));
+
+/** A scope entry in canonical form, or why it is refused. */
+function normalizePattern(raw: string): { pattern: string } | { error: string } {
+  // A backslash escapes a glob character (`app/\\[id\\]`); any other one is a
+  // Windows separator.
+  let pattern = raw.trim().replace(/\\(?![[\]{}*?])/gu, "/");
+  while (pattern.startsWith("./")) pattern = pattern.slice(2);
+  if (pattern === "." || pattern === "") pattern = raw.trim() ? "**" : "";
+  if (pattern.endsWith("/")) pattern = `${pattern}**`;
+  if (!pattern) return { error: "is empty" };
+  if (pattern.startsWith("/") || /^[A-Za-z]:/u.test(pattern))
+    return { error: "must be relative to the repository root" };
+  if (pattern.split("/").includes("..")) return { error: "must not contain .." };
+  const bare = pattern.replace(/\\./gu, "");
+  if (/[[\]]/u.test(bare))
+    return {
+      error:
+        'has an unescaped [ or ]: write \\[ and \\] for literal brackets (app/\\[id\\]/page.tsx; in JSON "app/\\\\[id\\\\]/page.tsx")',
+    };
+  if (bare.startsWith("!")) return { error: "uses ! (negation is not supported)" };
+  let depth = 0;
+  for (const char of bare) {
+    if (char === "{") depth += 1;
+    if (char === "}") depth -= 1;
+    if (depth < 0 || depth > 1) return { error: "has unbalanced or nested braces" };
+  }
+  if (depth !== 0) return { error: "has unbalanced or nested braces" };
+  return { pattern };
+}
+
+/** The slice may write `file`: its scope or owns matches, and no other slice owns it. */
+export function inScope(plan: FanoutFile, slice: Slice, file: string): boolean {
+  if (matchesAny(slice.owns, file)) return true;
+  if (!matchesAny(slice.scope, file)) return false;
+  return !plan.slices.some((other) => other.id !== slice.id && matchesAny(other.owns, file));
+}
+
+// ---------------------------------------------------------------------------
+// parse (input and stored file; D17: unknown keys are ignored)
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const PLACEHOLDER = /^(?:<[^>]*>|tbd|todo|fixme|\?+|\.\.\.|…)$/iu;
+const filled = (text: string): boolean => text.trim() !== "" && !PLACEHOLDER.test(text.trim());
+
+/** A string or list of strings; null when absent or of another type. */
+const textList = (value: unknown): string[] | null => {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value;
+  return null;
+};
+
+const ID = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+
+export type PlanDefaults = {
+  trunk: string;
+  /** Where default worktrees go: `<repo>-wt/` next to the main checkout. */
+  worktreeRoot: string;
+};
+
+type Parsed = { ok: true; plan: FanoutFile } | { ok: false; problems: string[] };
+
+/**
+ * Validate a plan document. Every problem is reported at once, so one edit
+ * fixes them all; the brief fields GOAL, SCOPE, ACCEPTANCE, VERIFY and
+ * FORBIDDEN must be non-empty and not a template placeholder.
+ */
+export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string | null): Parsed {
+  const problems: string[] = [];
+  if (!isRecord(raw)) return { ok: false, problems: ["the plan must be a JSON object"] };
+  const planName = name ?? (typeof raw.name === "string" ? raw.name.trim() : "");
+  if (!planName || planName.length > 200 || /\p{Cc}/u.test(planName))
+    problems.push('name: pass --name or set a 1-200 character "name"');
+  const trunk =
+    typeof raw.trunk === "string" && raw.trunk.trim() ? raw.trunk.trim() : defaults.trunk;
+  const shared: string[] = [];
+  for (const entry of textList(raw.shared ?? []) ?? ["<not a list>"]) {
+    const normalized = normalizePattern(entry);
+    if ("error" in normalized) problems.push(`shared "${entry}" ${normalized.error}`);
+    else shared.push(normalized.pattern);
+  }
+  if (!Array.isArray(raw.slices) || raw.slices.length === 0)
+    return { ok: false, problems: [...problems, "slices: list at least one slice"] };
+
+  const slices: Slice[] = [];
+  const seenIds = new Set<string>();
+  const seenBranches = new Map<string, string>();
+  raw.slices.forEach((item, index) => {
+    const where =
+      isRecord(item) && typeof item.id === "string" ? `slice ${item.id}` : `slice #${index + 1}`;
+    if (!isRecord(item)) {
+      problems.push(`${where}: must be an object`);
+      return;
+    }
+    const id = typeof item.id === "string" ? item.id : "";
+    if (!ID.test(id)) problems.push(`${where}: id must match ${ID.source}`);
+    else if (seenIds.has(id)) problems.push(`${where}: duplicate id`);
+    seenIds.add(id);
+    const branch = typeof item.branch === "string" ? item.branch.trim() : "";
+    if (!branch) problems.push(`${where}: branch is empty`);
+    else if (seenBranches.has(branch))
+      problems.push(`${where}: branch ${branch} is also slice ${seenBranches.get(branch)}'s`);
+    else seenBranches.set(branch, id);
+    if (branch === trunk) problems.push(`${where}: branch must not be the trunk ${trunk}`);
+
+    const goal = typeof item.goal === "string" ? item.goal.trim() : "";
+    if (!filled(goal)) problems.push(`${where}: goal is empty`);
+    const brief = (field: string): string[] => {
+      const list = textList(item[field]);
+      const kept = (list ?? []).map((entry) => entry.trim()).filter(filled);
+      if (kept.length === 0) problems.push(`${where}: ${field} is empty`);
+      return kept;
+    };
+    const acceptance = brief("acceptance");
+    const verify = brief("verify");
+    const forbidden = brief("forbidden");
+    const scope: string[] = [];
+    const owns: string[] = [];
+    for (const [field, out] of [
+      ["scope", scope],
+      ["owns", owns],
+    ] as const) {
+      const list = textList(item[field] ?? []);
+      if (list === null) {
+        problems.push(`${where}: ${field} must be a list of globs`);
+        continue;
+      }
+      for (const entry of list.filter(filled)) {
+        const normalized = normalizePattern(entry);
+        if ("error" in normalized)
+          problems.push(`${where}: ${field} "${entry}" ${normalized.error}`);
+        else out.push(normalized.pattern);
+      }
+    }
+    if (scope.length === 0 && textList(item.scope ?? []) !== null)
+      problems.push(`${where}: scope is empty`);
+    const tier = item.tier;
+    if (typeof tier !== "string" || !(TIERS as readonly string[]).includes(tier))
+      problems.push(`${where}: tier must be one of ${TIERS.join(", ")}`);
+    const dependsOn = textList(item.dependsOn ?? []);
+    if (dependsOn === null) problems.push(`${where}: dependsOn must be a list of slice ids`);
+    const optional = (field: string): string | null =>
+      typeof item[field] === "string" && filled(item[field]) ? item[field].trim() : null;
+    slices.push({
+      id,
+      branch,
+      base: optional("base") ?? "",
+      worktree: optional("worktree") ?? path.join(defaults.worktreeRoot, id),
+      tier: tier as Tier,
+      dependsOn: [...new Set(dependsOn ?? [])],
+      scope,
+      owns,
+      goal,
+      acceptance,
+      verify,
+      forbidden,
+      context: optional("context"),
+      timebox: optional("timebox"),
+    });
+  });
+
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  const byBranch = new Map(slices.map((slice) => [slice.branch, slice]));
+  for (const slice of slices) {
+    for (const dep of slice.dependsOn) {
+      if (dep === slice.id) problems.push(`slice ${slice.id}: depends on itself`);
+      else if (!byId.has(dep)) problems.push(`slice ${slice.id}: depends on unknown slice ${dep}`);
+    }
+    const explicitBase = slice.base;
+    if (explicitBase) {
+      const parent = byBranch.get(explicitBase);
+      if (parent && !slice.dependsOn.includes(parent.id))
+        problems.push(
+          `slice ${slice.id}: base ${explicitBase} is slice ${parent.id}'s branch; add "${parent.id}" to its dependsOn`,
+        );
+    } else {
+      const single = slice.dependsOn.length === 1 ? byId.get(slice.dependsOn[0]) : undefined;
+      slice.base = single ? single.branch : trunk;
+    }
+  }
+  const cycle = findCycle(slices);
+  if (cycle) problems.push(`dependency cycle: ${cycle.join(" -> ")}`);
+  if (problems.length) return { ok: false, problems };
+  return {
+    ok: true,
+    plan: {
+      v: FANOUT_VERSION,
+      name: planName,
+      trunk,
+      shared,
+      slices,
+      createdAt: "",
+      updatedAt: "",
+    },
+  };
+}
+
+function findCycle(slices: readonly Slice[]): string[] | null {
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  const state = new Map<string, "open" | "done">();
+  const trail: string[] = [];
+  const visit = (id: string): string[] | null => {
+    if (state.get(id) === "done") return null;
+    if (state.get(id) === "open") return [...trail.slice(trail.indexOf(id)), id];
+    state.set(id, "open");
+    trail.push(id);
+    for (const dep of byId.get(id)?.dependsOn ?? []) {
+      if (!byId.has(dep) || dep === id) continue;
+      const found = visit(dep);
+      if (found) return found;
+    }
+    trail.pop();
+    state.set(id, "done");
+    return null;
+  };
+  for (const slice of slices) {
+    const found = visit(slice.id);
+    if (found) return found;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// ordering
+
+/** Dependencies first; among the ready ones, the order the plan lists them. */
+export function landingOrder(slices: readonly Slice[]): string[] {
+  const order: string[] = [];
+  const placed = new Set<string>();
+  const known = new Set(slices.map((slice) => slice.id));
+  while (order.length < slices.length) {
+    const next = slices.find(
+      (slice) =>
+        !placed.has(slice.id) && slice.dependsOn.every((dep) => placed.has(dep) || !known.has(dep)),
+    );
+    if (!next) break;
+    order.push(next.id);
+    placed.add(next.id);
+  }
+  return order;
+}
+
+/** Slices that can run at the same time: wave n waits only for waves before it. */
+export function waves(slices: readonly Slice[]): string[][] {
+  const level = new Map<string, number>();
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  for (const id of landingOrder(slices)) {
+    const deps = byId.get(id)?.dependsOn ?? [];
+    level.set(id, deps.length ? Math.max(...deps.map((dep) => level.get(dep) ?? 0)) + 1 : 0);
+  }
+  const out: string[][] = [];
+  for (const slice of slices) (out[level.get(slice.id) ?? 0] ??= []).push(slice.id);
+  return out.filter(Boolean);
+}
+
+/** Every slice `id` waits for, directly or through another dependency. */
+function ancestors(slices: readonly Slice[]): Map<string, Set<string>> {
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  const out = new Map<string, Set<string>>();
+  for (const id of landingOrder(slices)) {
+    const set = new Set<string>();
+    for (const dep of byId.get(id)?.dependsOn ?? []) {
+      set.add(dep);
+      for (const deeper of out.get(dep) ?? []) set.add(deeper);
+    }
+    out.set(id, set);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// overlap
+
+export type Overlap = {
+  path: string;
+  slices: string[];
+  resolution: "owner" | "serialized";
+  owner?: string;
+};
+
+type OwnerSuggestion = { kind: "owner"; slice: string; paths: string[]; text: string };
+type Suggestion =
+  | OwnerSuggestion
+  | { kind: "serialize"; edges: Array<{ slice: string; dependsOn: string }>; text: string };
+
+export type OverlapConflict = {
+  slices: string[];
+  paths: string[];
+  /** Every path is a known shared file (lockfile, manifest, barrel, CI config). */
+  shared: boolean;
+  reason: "overlap" | "several_owners";
+  suggestion: Suggestion;
+  alternative?: Suggestion;
+};
+
+const quoteList = (items: readonly string[]): string => items.map((item) => `"${item}"`).join(", ");
+
+const ownerSuggestion = (slice: string, paths: string[]): OwnerSuggestion => ({
+  kind: "owner",
+  slice,
+  paths,
+  text: `add ${quoteList(paths)} to "owns" of slice ${slice}`,
+});
+
+const serializeSuggestion = (ids: readonly string[]): Suggestion => {
+  const edges = ids.slice(1).map((slice, index) => ({ slice, dependsOn: ids[index] }));
+  return {
+    kind: "serialize",
+    edges,
+    text: edges
+      .map((edge) => `add "${edge.dependsOn}" to "dependsOn" of slice ${edge.slice}`)
+      .join("; "),
+  };
+};
+
+/**
+ * Which files more than one slice may write, given the candidate paths.
+ * Resolved overlaps (one owner, or every pair serialized by a dependency)
+ * are listed; the rest are conflicts grouped by the slices involved.
+ */
+export function analyzeOverlap(
+  plan: FanoutFile,
+  candidates: Iterable<string>,
+): { overlaps: Overlap[]; conflicts: OverlapConflict[] } {
+  const shared = [...DEFAULT_SHARED, ...plan.shared];
+  const before = ancestors(plan.slices);
+  const related = (a: string, b: string): boolean =>
+    Boolean(before.get(a)?.has(b) || before.get(b)?.has(a));
+  const overlaps: Overlap[] = [];
+  const groups = new Map<string, OverlapConflict & { members: Slice[] }>();
+  // Paths that differ only in case are one file on case-insensitive checkouts.
+  const byCase = new Map<string, string[]>();
+  for (const file of [...new Set(candidates)].toSorted())
+    (
+      byCase.get(file.toLowerCase()) ?? byCase.set(file.toLowerCase(), []).get(file.toLowerCase())
+    )?.push(file);
+  for (const spellings of byCase.values()) {
+    const file = spellings.join(" ~ ");
+    const any = (patterns: readonly string[]) =>
+      spellings.some((spelling) => matchesAny(patterns, spelling));
+    const matching = plan.slices.filter((slice) => any(slice.scope) || any(slice.owns));
+    if (matching.length < 2) continue;
+    const ids = matching.map((slice) => slice.id);
+    const owners = matching.filter((slice) => any(slice.owns));
+    if (owners.length === 1) {
+      overlaps.push({ path: file, slices: ids, resolution: "owner", owner: owners[0].id });
+      continue;
+    }
+    if (
+      owners.length === 0 &&
+      matching.every((a, i) => matching.slice(i + 1).every((b) => related(a.id, b.id)))
+    ) {
+      overlaps.push({ path: file, slices: ids, resolution: "serialized" });
+      continue;
+    }
+    const members = owners.length > 1 ? owners : matching;
+    const reason = owners.length > 1 ? "several_owners" : "overlap";
+    const isShared = any(shared);
+    const key = `${reason}|${isShared}|${members.map((slice) => slice.id).join(",")}`;
+    const group = groups.get(key);
+    if (group) group.paths.push(file);
+    else
+      groups.set(key, {
+        slices: members.map((slice) => slice.id),
+        paths: [file],
+        shared: isShared,
+        reason,
+        members,
+        suggestion: ownerSuggestion(members[0].id, []),
+      });
+  }
+  const conflicts = [...groups.values()].map(({ members, ...group }) => {
+    // The owner: the first slice (plan order) that names one of the paths
+    // literally, else the first slice. Serializing keeps plan order.
+    const literal = members.find((slice) =>
+      slice.scope.some((pattern) => group.paths.includes(pattern)),
+    );
+    const owner = ownerSuggestion((literal ?? members[0]).id, group.paths);
+    if (group.reason === "several_owners")
+      return {
+        ...group,
+        suggestion: {
+          ...owner,
+          text: `keep ${quoteList(group.paths)} in "owns" of slice ${owner.slice} only`,
+        },
+      };
+    const serialize = serializeSuggestion(group.slices);
+    return group.shared
+      ? { ...group, suggestion: owner, alternative: serialize }
+      : { ...group, suggestion: serialize, alternative: owner };
+  });
+  return { overlaps, conflicts };
+}
+
+// ---------------------------------------------------------------------------
+// git
+
+type GitRun = { ok: boolean; status: number | null; stdout: string; stderr: string };
+
+export const gitRun = (cwd: string, args: string[]): GitRun => {
+  const run = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUTS.local,
+    killSignal: "SIGKILL",
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C", LANGUAGE: "C" },
+  });
+  return {
+    ok: run.status === 0,
+    status: run.status,
+    stdout: run.stdout ?? "",
+    stderr: run.error ? String(run.error.message) : (run.stderr ?? ""),
+  };
+};
+
+export const nulList = (text: string): string[] => text.split("\0").filter(Boolean);
+
+/** The commit a branch name points at: the local branch, else its remote-tracking ref. */
+export function branchRef(cwd: string, branch: string): string | null {
+  if (!branch || branch.startsWith("-")) return null;
+  const local = resolveRef(cwd, `refs/heads/${branch}`);
+  if (local) return local;
+  const remote = pushRemoteName(cwd) ?? "origin";
+  return resolveRef(cwd, `refs/remotes/${remote}/${branch}`);
+}
+
+/** The trunk as the forge sees it (remote-tracking ref) when known, else the local branch. */
+export function trunkRef(cwd: string, trunk: string): string | null {
+  if (!trunk || trunk.startsWith("-")) return null;
+  const remote = pushRemoteName(cwd) ?? "origin";
+  for (const ref of [`refs/remotes/${remote}/${trunk}`, `refs/heads/${trunk}`, trunk])
+    if (resolveRef(cwd, ref)) return ref;
+  return null;
+}
+
+/** The trunk name when the plan does not give one: origin's default branch, else main. */
+export function defaultTrunk(cwd: string): string {
+  const base = defaultBase(cwd);
+  return base ? base.replace(/^origin\//u, "") : "main";
+}
+
+/** `<repo>-wt/` beside the main checkout. */
+export function worktreeRoot(cwd: string): string {
+  const common = gitCommonDir(cwd);
+  const main = common && path.basename(common) === ".git" ? path.dirname(common) : cwd;
+  return path.join(path.dirname(main), `${path.basename(main)}-wt`);
+}
+
+// ---------------------------------------------------------------------------
+// store
+
+export function fanoutsDir(cwd: string): FanoutResult<string> {
+  const root = storeRoot(cwd);
+  if (!root.ok) return fanoutFail(root.code, root.error, root.unblock);
+  return { ok: true, data: path.join(root.value.root, "fanouts") };
+}
+
+/**
+ * Tolerant read (D17) that still re-validates what the checks rely on: every
+ * glob normalizes, every dependency is a known slice, no cycle. A file that
+ * fails is "not a valid plan", never half-trusted.
+ */
+function parseStored(raw: unknown): FanoutFile | null {
+  if (!isRecord(raw) || typeof raw.name !== "string" || typeof raw.trunk !== "string") return null;
+  if (!Array.isArray(raw.slices)) return null;
+  const list = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+  const text = (value: unknown): string => (typeof value === "string" ? value : "");
+  let globsValid = true;
+  const globs = (value: unknown): string[] =>
+    list(value).map((entry) => {
+      const normalized = normalizePattern(entry);
+      if ("error" in normalized) {
+        globsValid = false;
+        return entry;
+      }
+      return normalized.pattern;
+    });
+  const slices: Slice[] = [];
+  for (const item of raw.slices) {
+    if (!isRecord(item) || typeof item.id !== "string" || typeof item.branch !== "string")
+      return null;
+    slices.push({
+      id: item.id,
+      branch: item.branch,
+      base: text(item.base) || raw.trunk,
+      worktree: text(item.worktree),
+      tier: (TIERS as readonly unknown[]).includes(item.tier) ? (item.tier as Tier) : "standard",
+      dependsOn: list(item.dependsOn),
+      scope: globs(item.scope),
+      owns: globs(item.owns),
+      goal: text(item.goal),
+      acceptance: list(item.acceptance),
+      verify: list(item.verify),
+      forbidden: list(item.forbidden),
+      context: typeof item.context === "string" ? item.context : null,
+      timebox: typeof item.timebox === "string" ? item.timebox : null,
+    });
+  }
+  const shared = globs(raw.shared);
+  const ids = new Set(slices.map((slice) => slice.id));
+  if (
+    !globsValid ||
+    ids.size !== slices.length ||
+    slices.some((slice) => slice.dependsOn.some((dep) => dep === slice.id || !ids.has(dep))) ||
+    findCycle(slices)
+  )
+    return null;
+  return {
+    v: typeof raw.v === "number" ? raw.v : FANOUT_VERSION,
+    name: raw.name,
+    trunk: raw.trunk,
+    shared,
+    slices,
+    createdAt: text(raw.createdAt),
+    updatedAt: text(raw.updatedAt),
+  };
+}
+
+export function readFanout(cwd: string, name: string): FanoutResult<FanoutFile | null> {
+  const dir = fanoutsDir(cwd);
+  if (!dir.ok) return dir;
+  const file = path.join(dir.data, stackFileName(name));
+  let parsed: FanoutFile | null = null;
+  try {
+    parsed = parseStored(JSON.parse(fs.readFileSync(file, "utf8")));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { ok: true, data: null };
+    parsed = null;
+  }
+  return parsed
+    ? { ok: true, data: parsed }
+    : fanoutFail(
+        "failed",
+        `fanout file ${file} is not a valid plan`,
+        `workit fanout plan <plan.json> --name ${name}  # rewrite it`,
+      );
+}
+
+function listFanouts(cwd: string): FanoutResult<FanoutFile[]> {
+  const dir = fanoutsDir(cwd);
+  if (!dir.ok) return dir;
+  let names: string[] = [];
+  try {
+    names = fs.readdirSync(dir.data).filter((entry) => entry.endsWith(".json"));
+  } catch {
+    return { ok: true, data: [] };
+  }
+  const out: FanoutFile[] = [];
+  for (const entry of names) {
+    let parsed: FanoutFile | null = null;
+    try {
+      parsed = parseStored(JSON.parse(fs.readFileSync(path.join(dir.data, entry), "utf8")));
+    } catch {
+      parsed = null;
+    }
+    if (parsed && stackFileName(parsed.name) === entry) out.push(parsed);
+  }
+  return { ok: true, data: out.toSorted((a, b) => a.name.localeCompare(b.name)) };
+}
+
+/** The plan `name`, else the one with the current branch as a slice, else the only one. */
+export function selectFanout(
+  cwd: string,
+  name: string | null,
+  current: string | null,
+): FanoutResult<FanoutFile> {
+  if (name) {
+    const read = readFanout(cwd, name);
+    if (!read.ok) return read;
+    return read.data
+      ? { ok: true, data: read.data }
+      : fanoutFail("not_found", `no fanout plan named ${name}`, "workit fanout plan <plan.json>");
+  }
+  const all = listFanouts(cwd);
+  if (!all.ok) return all;
+  const holding = all.data.filter((plan) => plan.slices.some((slice) => slice.branch === current));
+  if (holding.length === 1) return { ok: true, data: holding[0] };
+  if (all.data.length === 1) return { ok: true, data: all.data[0] };
+  return all.data.length === 0
+    ? fanoutFail("not_found", "no fanout plan is recorded here", "workit fanout plan <plan.json>")
+    : fanoutFail(
+        "invalid_input",
+        `several fanout plans match; pick one (${all.data.map((plan) => plan.name).join(", ")})`,
+        "pass --name <plan>",
+      );
+}
+
+function writeFanout(cwd: string, plan: FanoutFile): FanoutResult<string> {
+  const dir = fanoutsDir(cwd);
+  if (!dir.ok) return dir;
+  const file = path.join(dir.data, stackFileName(plan.name));
+  const temp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.mkdirSync(dir.data, { recursive: true });
+    fs.writeFileSync(temp, `${JSON.stringify(plan, null, 2)}\n`);
+    fs.renameSync(temp, file);
+    return { ok: true, data: file };
+  } catch (error) {
+    fs.rmSync(temp, { force: true });
+    return fanoutFail("unavailable", `cannot write ${file}: ${(error as Error).message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// plan
+
+export type PlanOutcome = {
+  name: string;
+  trunk: string;
+  file: string;
+  created: boolean;
+  slices: Array<
+    Pick<Slice, "id" | "branch" | "base" | "worktree" | "tier" | "dependsOn" | "scope" | "owns">
+  >;
+  overlaps: Overlap[];
+  waves: string[][];
+  landingOrder: string[];
+  notes: string[];
+};
+
+/** Above this many slices in one wave, the lead queues the rest (4-6 in flight). */
+export const IN_FLIGHT_CAP = 6;
+
+export function planFanout(
+  cwd: string,
+  input: { raw: unknown; name: string | null; trunk: string | null; actor: LedgerActor },
+  now: Date = new Date(),
+): FanoutResult<PlanOutcome> {
+  const dir = fanoutsDir(cwd);
+  if (!dir.ok) return dir;
+  const parsed = parsePlan(
+    input.trunk && isRecord(input.raw) ? { ...input.raw, trunk: input.trunk } : input.raw,
+    { trunk: input.trunk ?? defaultTrunk(cwd), worktreeRoot: worktreeRoot(cwd) },
+    input.name,
+  );
+  if (!parsed.ok)
+    return fanoutFail(
+      "invalid_input",
+      `the plan is incomplete: ${parsed.problems[0]}${parsed.problems.length > 1 ? ` (+${parsed.problems.length - 1} more)` : ""}`,
+      "fill every listed field, then run workit fanout plan again",
+      { problems: parsed.problems },
+    );
+  const plan = parsed.plan;
+  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`);
+  if (badBranches.length)
+    return fanoutFail("invalid_input", badBranches[0], "rename the branch in the plan", {
+      problems: badBranches,
+    });
+
+  const ref = trunkRef(cwd, plan.trunk);
+  const tracked = ref
+    ? nulList(gitRun(cwd, ["ls-tree", "-r", "-z", "--name-only", ref]).stdout)
+    : [];
+  const samples = plan.slices.flatMap((slice) =>
+    [...slice.scope, ...slice.owns].flatMap(scopeSamples),
+  );
+  const { overlaps, conflicts } = analyzeOverlap(plan, [...tracked, ...samples]);
+  if (conflicts.length)
+    return fanoutFail(
+      "blocked",
+      `${conflicts.length} file-scope overlap${conflicts.length === 1 ? "" : "s"} between slices: ${conflicts[0].slices.join(" and ")} on ${conflicts[0].paths[0]}${conflicts[0].paths.length > 1 ? ` (+${conflicts[0].paths.length - 1})` : ""}`,
+      conflicts[0].suggestion.text,
+      { name: plan.name, conflicts, overlaps },
+    );
+
+  const existing = readFanout(cwd, plan.name);
+  const previous = existing.ok ? existing.data : null;
+  plan.createdAt = previous?.createdAt || now.toISOString();
+  plan.updatedAt = now.toISOString();
+  const written = writeFanout(cwd, plan);
+  if (!written.ok) return written;
+  appendObserved(cwd, {
+    type: "fanout.planned",
+    actor: input.actor,
+    fanout: plan.name,
+    trunk: plan.trunk,
+    slices: plan.slices.length,
+    ids: plan.slices.slice(0, 20).map((slice) => slice.id),
+  });
+
+  const grouped = waves(plan.slices);
+  const notes: string[] = [];
+  if (!ref)
+    notes.push(
+      `trunk ${plan.trunk} does not resolve here; only sample paths of each glob were compared`,
+    );
+  grouped.forEach((wave, index) => {
+    if (wave.length > IN_FLIGHT_CAP)
+      notes.push(
+        `wave ${index + 1} has ${wave.length} slices; keep 4-${IN_FLIGHT_CAP} in flight and queue the rest`,
+      );
+  });
+  for (const slice of plan.slices)
+    if (slice.dependsOn.length > 1 && slice.base === plan.trunk)
+      notes.push(
+        `slice ${slice.id} depends on ${slice.dependsOn.join(", ")}: start it from ${plan.trunk} after they land`,
+      );
+  return {
+    ok: true,
+    data: {
+      name: plan.name,
+      trunk: plan.trunk,
+      file: written.data,
+      created: previous === null,
+      slices: plan.slices.map(({ id, branch, base, worktree, tier, dependsOn, scope, owns }) => ({
+        id,
+        branch,
+        base,
+        worktree,
+        tier,
+        dependsOn,
+        scope,
+        owns,
+      })),
+      overlaps,
+      waves: grouped,
+      landingOrder: landingOrder(plan.slices),
+      notes,
+    },
+  };
+}