@brainervirus/workit-core 7.4.0 → 7.5.0

package/package.json

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

@@ -14,30 +14,30 @@ ceremony; do it yourself.
    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.
+   brief fields. `workit fanout plan <plan.json>` refuses an empty or
+   placeholder (`<goal>`, `TBD`) 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.
+   (exact commands), TIER, TIMEBOX, SCRATCH, FORBIDDEN, REPORT, STANDING.
+   STANDING is every standing order and user directive so far, pasted
+   verbatim into each spawn and respawn: 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>`.
-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` (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.
+   worktree: Claude Code's `implementer` agent (first command `workit git
+   branch <branch> --base <base>`); elsewhere `workit fanout worktree create
+   <slice>`, which prints the SCRATCH dir. Refill from `fanout status`.
+4. **Judge liveness by side effects only:** `workit fanout status` (head age,
+   PR, CI, verdict, landed; STUCK past the TIMEBOX, default 30 min). Stop a
+   stuck worker and observe that it exited (a timeout is not proof). Removing
+   a worktree drops its uncommitted changes: `workit fanout worktree release
+   <slice>` records `git status` in the ledger first and refuses them without
+   `--force` (native worktrees: record `git -C <wt> status --short` first).
+   Respawn in `MODE: resume` (brief, directives, last report), same branch.
+   Never two live workers on one branch. Replace at most twice, then re-slice
+   or report the gap. Never chain resumes.
 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
@@ -47,12 +47,12 @@ ceremony; do it yourself.
 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.
+   out-of-scope edit becomes a follow-up slice) until it exits 0. A slice
+   whose PR merged reads as landed; its dependents stop waiting. Then
+   `workit ledger check --branch <b>` per slice, land in `fanout status` order
+   and release the worktrees you made. Stacks: `workit stack plan <bottom> …
+   <top>` once, then `stack sync` and `land`. Only you touch topology: workers
+   never rebase, retarget or merge. Then workit-ship.
 
 ## Example
 

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

@@ -14,6 +14,7 @@ ACCEPTANCE:
 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>
+SCRATCH: <your own temp dir: the one `fanout worktree create` printed, else `mktemp -d`; never a shared path>
 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,
   each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
@@ -37,6 +38,7 @@ ACCEPTANCE:
 VERIFY: `workit check test`; verify-api feature "usage"
 TIER: standard
 TIMEBOX: 45 minutes
+SCRATCH: ../app-wt/usage-endpoint/.workit-scratch
 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
@@ -50,7 +52,9 @@ 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"`.
+through a sample path. Use `/` as the separator; a backslash only escapes
+literal brackets: `"app/\\[id\\]/page.tsx"`. A `timebox` such as `45 minutes`
+is the slice's STUCK threshold in `workit fanout status`.
 
 ```json
 {

package/src/duration.ts

@@ -0,0 +1,27 @@
+// One duration parser for CLI flags (`--timeout 20m`, `--stuck-after 1h30m`)
+// and plan fields (a slice TIMEBOX such as `45 minutes`).
+
+const UNITS: ReadonlyArray<[RegExp, number]> = [
+  [/^(?:ms|milliseconds?)$/u, 1],
+  [/^(?:s|secs?|seconds?)$/u, 1000],
+  [/^(?:m|mins?|minutes?)$/u, 60_000],
+  [/^(?:h|hrs?|hours?)$/u, 3_600_000],
+];
+
+/**
+ * `20m`, `30s`, `1500ms`, `1h`, `1h30m`, `45 minutes`, `2 hours`, or bare
+ * seconds, in ms; null when it does not read as a duration.
+ */
+export function parseDuration(value: string): number | null {
+  const text = value.trim().toLowerCase();
+  if (/^\d+(?:\.\d+)?$/u.test(text)) return Math.round(Number(text) * 1000);
+  const parts = [...text.matchAll(/(\d+(?:\.\d+)?)\s*([a-z]+)\s*/gu)];
+  if (parts.length === 0 || parts.map((part) => part[0]).join("") !== text) return null;
+  let total = 0;
+  for (const [, amount, unit] of parts) {
+    const factor = UNITS.find(([pattern]) => pattern.test(unit))?.[1];
+    if (factor === undefined) return null;
+    total += Number(amount) * factor;
+  }
+  return Math.round(total);
+}

package/src/fanout-check.ts

@@ -9,14 +9,22 @@
 //   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.
+// - case: a file or directory it adds that the trunk spells differently only
+//   in case (one path on macOS and Windows checkouts).
+// A slice that already landed (fanout-landed.ts: its PR merged, squash
+// merges included, or git shows its change on the trunk) is done: it is not
+// checked, and slices that depend on it no longer wait for it.
 // 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
+// ready or landed. Verdicts are reported (`workit ledger check`) but gated by
 // `workit pr merge`, not here. Refs are read as they are locally: fetch first.
+import type { ResolvedForge } from "./forge/resolve";
 import { checkVerdicts, readLedger, type ReadRow } from "./ledger";
 import {
   FANOUT_VERSION,
   branchRef,
+  caseClash,
+  caseIndex,
   fanoutFail,
   gitRun,
   inScope,
@@ -27,8 +35,15 @@ import {
   type FanoutResult,
   type Slice,
 } from "./fanout";
+import {
+  detectLanding,
+  forgeBreaker,
+  sliceStart,
+  type LandingContext,
+  type SliceLanding,
+} from "./fanout-landed";
 
-export type SliceStatus = "ready" | "blocked";
+export type SliceStatus = "ready" | "blocked" | "landed";
 
 export type SliceCheck = {
   id: string;
@@ -38,10 +53,14 @@ export type SliceCheck = {
   status: SliceStatus;
   changed: number;
   outOfScope: string[];
+  /** Paths it adds that the trunk spells differently only in case: `ours ~ trunk's`. */
+  caseCollisions: string[];
   trunkConflicts: string[];
   siblingConflicts: Array<{ with: string; paths: string[] }>;
   waitsFor: string[];
   verdict: { accepted: boolean; basis: string };
+  /** How it landed, when it did (then nothing else was checked). */
+  landed: { how: string; pr: number | null } | null;
   reasons: string[];
 };
 
@@ -68,6 +87,13 @@ export type CheckOutcome = {
   notes: string[];
 };
 
+export type CheckOptions = {
+  only?: readonly string[];
+  trunkRef?: string | null;
+  /** Asks the forge whether a slice's PR merged; null checks with git alone. */
+  forge?: ResolvedForge | null;
+};
+
 const SAFE = (value: string | null): value is string => Boolean(value) && !value?.startsWith("-");
 
 /** Paths both sides change incompatibly, [] when clean, or an error. */
@@ -97,7 +123,7 @@ const isAncestor = (cwd: string, a: string, b: string): boolean =>
 export function checkFanout(
   cwd: string,
   plan: FanoutFile,
-  options: { only?: readonly string[]; trunkRef?: string | null } = {},
+  options: CheckOptions = {},
 ): FanoutResult<CheckOutcome> {
   const unknown = (options.only ?? []).filter((id) => !plan.slices.some((s) => s.id === id));
   if (unknown.length)
@@ -119,10 +145,22 @@ export function checkFanout(
   const ledger = readLedger(cwd);
   const rows: readonly ReadRow[] = ledger.ok ? ledger.value.rows : [];
 
+  const breaker = forgeBreaker(options.forge ?? null);
+  const landings = sliceLandings(cwd, plan, trunk, tips, rows, breaker.forge);
+  const trunkCase = caseIndex(
+    nulList(gitRun(cwd, ["ls-tree", "-r", "-z", "--name-only", trunk]).stdout),
+  );
   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));
+  for (const slice of plan.slices) {
+    const landing = landings.get(slice.id) as SliceLanding;
+    checks.set(
+      slice.id,
+      landing.landed
+        ? landedCheck(slice, tips.get(slice.id) ?? null, landing)
+        : inspect(cwd, plan, slice, { trunk, trunkCase, tips, landings, rows }, changedBy),
+    );
+  }
 
   // Pairwise siblings: skip a pair where one contains the other (a stacked child).
   const conflicts: SiblingConflict[] = [];
@@ -132,6 +170,7 @@ export function checkFanout(
       const second = order[j];
       const a = tips.get(first);
       const b = tips.get(second);
+      if (landings.get(first)?.landed || landings.get(second)?.landed) continue;
       if (!a || !b || isAncestor(cwd, a, b) || isAncestor(cwd, b, a)) continue;
       const check = checks.get(second) as SliceCheck;
       const theirs = new Map(
@@ -173,8 +212,9 @@ export function checkFanout(
 
   for (const id of order) {
     const check = checks.get(id) as SliceCheck;
+    if (check.status === "landed") continue;
     check.waitsFor = (byId.get(id)?.dependsOn ?? []).filter(
-      (dep) => checks.get(dep)?.status !== "ready",
+      (dep) => checks.get(dep)?.status !== "ready" && checks.get(dep)?.status !== "landed",
     );
     if (check.waitsFor.length) check.reasons.push(`waits for ${check.waitsFor.join(", ")}`);
     check.status = check.reasons.length ? "blocked" : "ready";
@@ -184,7 +224,7 @@ export function checkFanout(
   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 ready = slices.every((check) => check.status !== "blocked");
   const blocked = slices.find((check) => check.status === "blocked");
   const notes =
     plan.v === FANOUT_VERSION
@@ -192,9 +232,21 @@ export function checkFanout(
       : [
           `plan file version ${plan.v} is not ${FANOUT_VERSION}; read leniently (re-plan to rewrite it)`,
         ];
+  const forgeErrors = [...landings.values()].flatMap((landing) =>
+    landing.forgeError ? [landing.forgeError] : [],
+  );
+  if (!options.forge)
+    notes.push("landed slices detected with git only (no forge): a squash merge may be missed");
+  else if (breaker.down())
+    notes.push(`forge went down (${breaker.down()}); git alone decided the remaining slices`);
+  else if (forgeErrors.length)
+    notes.push(`forge lookups failed (${forgeErrors[0]}); git alone decided those slices`);
+  const toLand = slices.filter((check) => check.status === "ready").map((check) => check.id);
   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)`;
+    : toLand.length
+      ? `land in this order: ${toLand.join(", ")} (workit pr merge each once verified; stacked slices with workit stack land)`
+      : "every slice has landed";
   return {
     ok: true,
     data: {
@@ -216,40 +268,132 @@ export function checkFanout(
 const resolves = (cwd: string, ref: string): boolean =>
   gitRun(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).ok;
 
-function inspect(
+/** Landed state per slice, dependencies first (a child's base is its parent's merged head). */
+export function sliceLandings(
   cwd: string,
   plan: FanoutFile,
-  slice: Slice,
   trunk: string,
   tips: ReadonlyMap<string, string | null>,
   rows: readonly ReadRow[],
+  forge: ResolvedForge | null,
+): Map<string, SliceLanding> {
+  const ctx: LandingContext = { cwd, trunk, forge };
+  const out = new Map<string, SliceLanding>();
+  const byId = new Map(plan.slices.map((slice) => [slice.id, slice]));
+  for (const id of landingOrder(plan.slices)) {
+    const slice = byId.get(id) as Slice;
+    const parent = plan.slices.find((other) => other.branch === slice.base);
+    const parentHead = parent
+      ? (tips.get(parent.id) ?? out.get(parent.id)?.landedHead ?? null)
+      : null;
+    out.set(
+      id,
+      detectLanding(ctx, slice, {
+        head: tips.get(id) ?? null,
+        createdFrom: sliceStart(cwd, rows, plan.name, slice),
+        parentHead,
+        fanout: plan.name,
+        since: plan.createdAt || null,
+        rows,
+      }),
+    );
+  }
+  return out;
+}
+
+const blank = (slice: Slice, head: string | null): SliceCheck => ({
+  id: slice.id,
+  branch: slice.branch,
+  head,
+  base: slice.base,
+  status: "blocked",
+  changed: 0,
+  outOfScope: [],
+  caseCollisions: [],
+  trunkConflicts: [],
+  siblingConflicts: [],
+  waitsFor: [],
+  verdict: { accepted: false, basis: "missing" },
+  landed: null,
+  reasons: [],
+});
+
+function landedCheck(slice: Slice, head: string | null, landing: SliceLanding): SliceCheck {
+  return {
+    ...blank(slice, head),
+    status: "landed",
+    landed: { how: landing.how ?? "pr_merged", pr: landing.pr?.number ?? null },
+  };
+}
+
+type InspectContext = {
+  trunk: string;
+  trunkCase: ReadonlyMap<string, ReadonlySet<string>>;
+  tips: ReadonlyMap<string, string | null>;
+  landings: ReadonlyMap<string, SliceLanding>;
+  rows: readonly ReadRow[];
+};
+
+/** Files at `rev`, or null when it cannot be listed. */
+const treeFiles = (cwd: string, rev: string | null): Set<string> | null => {
+  if (!rev) return null;
+  const run = gitRun(cwd, ["ls-tree", "-r", "-z", "--name-only", rev]);
+  return run.ok ? new Set(nulList(run.stdout)) : null;
+};
+
+/**
+ * Paths the slice adds or changes that the trunk spells differently only in
+ * case, unless the slice removed the trunk's spelling (a case rename).
+ */
+function trunkCaseCollisions(
+  cwd: string,
+  ctx: InspectContext,
+  head: string,
+  changed: readonly string[],
+): string[] {
+  const headFiles = treeFiles(cwd, head);
+  const forkFiles = treeFiles(
+    cwd,
+    gitRun(cwd, ["merge-base", head, ctx.trunk]).stdout.trim() || null,
+  );
+  if (!headFiles) return [];
+  const present = (files: ReadonlySet<string> | null, prefix: string): boolean =>
+    Boolean(
+      files && (files.has(prefix) || [...files].some((file) => file.startsWith(`${prefix}/`))),
+    );
+  const out = new Set<string>();
+  for (const file of changed) {
+    if (!headFiles.has(file)) continue;
+    const clash = caseClash(ctx.trunkCase, file);
+    if (!clash) continue;
+    // The slice deleted the trunk's spelling it had: a deliberate case rename.
+    if (present(forkFiles, clash.trunk) && !present(headFiles, clash.trunk)) continue;
+    out.add(`${clash.path} ~ ${clash.trunk}`);
+  }
+  return [...out].toSorted();
+}
+
+function inspect(
+  cwd: string,
+  plan: FanoutFile,
+  slice: Slice,
+  ctx: InspectContext,
   changedBy: Map<string, string[]>,
 ): SliceCheck {
+  const { trunk, tips, rows } = ctx;
   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: [],
-  };
+  const check = blank(slice, head);
   if (!head) {
-    check.reasons.push(`branch ${slice.branch} not found (not started, landed, or not fetched)`);
+    check.reasons.push(`branch ${slice.branch} not found (not started, or not fetched)`);
     return check;
   }
   const parent = plan.slices.find((other) => other.branch === slice.base);
+  // A landed parent whose branch is gone: diff against the head that merged.
   const baseRef =
     slice.base === plan.trunk
       ? trunk
       : parent
-        ? (tips.get(parent.id) ?? null)
+        ? (tips.get(parent.id) ?? ctx.landings.get(parent.id)?.landedHead ?? null)
         : branchRef(cwd, slice.base);
   if (!SAFE(baseRef)) {
     check.reasons.push(`base ${slice.base} not found`);
@@ -267,6 +411,11 @@ function inspect(
   check.outOfScope = changed.filter((file) => !inScope(plan, slice, file)).toSorted();
   if (check.outOfScope.length)
     check.reasons.push(`edits outside its scope: ${check.outOfScope.join(", ")}`);
+  check.caseCollisions = trunkCaseCollisions(cwd, ctx, head, changed);
+  if (check.caseCollisions.length)
+    check.reasons.push(
+      `differs only in case from ${plan.trunk}: ${check.caseCollisions.join(", ")}`,
+    );
   const trunkResult = mergeConflicts(cwd, trunk, head);
   if (Array.isArray(trunkResult)) {
     check.trunkConflicts = trunkResult;
@@ -280,9 +429,11 @@ function inspect(
 
 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}`;
+    return `start or fetch ${check.branch}, then workit fanout check (a landed slice is detected through its merged PR when the forge is reachable)`;
   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.caseCollisions.length)
+    return `rename to ${plan.trunk}'s spelling on ${check.branch} (git mv), 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) {