@wildorder/nightshift 0.17.0 → 0.18.0

package/dist/worktree.js

@@ -0,0 +1,397 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { mkdir, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { promisify } from "node:util";
+import { lockfileManager } from "./detect-package-manager.js";
+const execFileAsync = promisify(execFile);
+/** The fixed prefix for every runner-created worktree branch. Not a config key. */
+export const WORKTREE_BRANCH_PREFIX = "nightshift/";
+/** `nightshift/<programId>/<workstreamId>` — a branch under refs/heads/. Ids are lowercased so a case-insensitive filesystem can never make two refs collide. */
+export function worktreeBranchName(programId, workstreamId) {
+    return `${WORKTREE_BRANCH_PREFIX}${programId.toLowerCase()}/${workstreamId.toLowerCase()}`;
+}
+/** Every branch this program's worktrees may use, for prefix-matched reaping. */
+export function worktreeBranchPrefix(programId) {
+    return `${WORKTREE_BRANCH_PREFIX}${programId.toLowerCase()}/`;
+}
+/** `refs/nightshift/<programId>/<workstreamId>` — where a verified-but-unintegrated commit is retained. */
+export function retainedRefName(programId, workstreamId) {
+    return `refs/nightshift/${programId.toLowerCase()}/${workstreamId.toLowerCase()}`;
+}
+function hash8(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+/**
+ * The realpath of `repoRoot`, falling back to the resolved path when
+ * `realpath` cannot be taken (a repository whose parent no longer exists —
+ * an edge case, but one this function must not throw on).
+ */
+async function repoRealpath(repoRoot) {
+    try {
+        return await realpath(repoRoot);
+    }
+    catch {
+        return resolve(repoRoot);
+    }
+}
+/**
+ * Where a workstream's worktree lives: `<base>/<programId>-<hash8>/<workstreamId>`,
+ * where `hash8` is derived from the repository's own realpath — see
+ * `resolveWorktreeBase`'s doc comment for why this segment is load-bearing.
+ */
+export function worktreePathFor(base, programId, workstreamId, repoHash) {
+    return join(base, `${programId}-${repoHash}`, workstreamId);
+}
+/**
+ * Resolves the base directory under which this run's worktrees are created,
+ * once per run: `<dirname(realpath(repoRoot))>/.nightshift-worktrees`, or —
+ * when that parent is not writable (a read-only mount, a container) —
+ * `<os tmpdir>/nightshift-worktrees`. Eagerly `mkdir -p`s the chosen base so
+ * the fallback decision is made once, up front, rather than discovered mid-run.
+ *
+ * The `hash8(realpath(repoRoot))` segment (folded into every returned path via
+ * `repoHash`) is load-bearing, not decoration: without it, two checkouts of
+ * the same repository — or two test fixtures sharing an OS temp directory and
+ * the same programId — would resolve to the same worktree path and the
+ * second `git worktree add` would fail with `already exists`.
+ */
+export async function resolveWorktreeBase(repoRoot, override) {
+    const realRepoRoot = await repoRealpath(repoRoot);
+    const repoHash = hash8(realRepoRoot);
+    if (override !== undefined) {
+        const base = resolve(override);
+        await mkdir(base, { recursive: true });
+        return { base, repoHash, usedFallback: false };
+    }
+    const siblingBase = join(dirname(realRepoRoot), ".nightshift-worktrees");
+    if (await insideGitWorkTree(dirname(realRepoRoot))) {
+        // The repository itself sits inside another checkout: a sibling
+        // directory would land in *that* repository's tracked tree.
+        const fallbackBase = join(tmpdir(), "nightshift-worktrees");
+        await mkdir(fallbackBase, { recursive: true });
+        return { base: fallbackBase, repoHash, usedFallback: true };
+    }
+    try {
+        await mkdir(siblingBase, { recursive: true });
+        return { base: siblingBase, repoHash, usedFallback: false };
+    }
+    catch {
+        const fallbackBase = join(tmpdir(), "nightshift-worktrees");
+        await mkdir(fallbackBase, { recursive: true });
+        return { base: fallbackBase, repoHash, usedFallback: true };
+    }
+}
+/** The install command for a worktree, or undefined when there is no lockfile. */
+export function worktreeInstallCommand(worktreeRoot) {
+    const manager = lockfileManager(worktreeRoot);
+    if (manager === undefined)
+        return undefined;
+    return installCommandFor(manager);
+}
+function installCommandFor(manager) {
+    switch (manager) {
+        case "npm":
+            return "npm ci";
+        case "pnpm":
+            return "pnpm install --frozen-lockfile";
+        case "yarn":
+            return "yarn install";
+        case "bun":
+            return "bun install --frozen-lockfile";
+    }
+}
+/**
+ * True for a path the runner owns in the tree being inspected. `git status
+ * --porcelain` paths are relative to that tree's root — the root checkout
+ * during the report commit, the worktree during a build. In a worktree the
+ * runner writes nothing here, so this only ever fires when an agent itself
+ * edited planning artifacts, which is equally not the work it was asked to
+ * do.
+ */
+export function isRunnerOwnedArtifactPath(path) {
+    return path.replaceAll("\\", "/").startsWith("docs/programs/");
+}
+async function run(cwd, args) {
+    return execFileAsync("git", args, { cwd, maxBuffer: 32 * 1024 * 1024 });
+}
+function outputOf(error) {
+    const err = error;
+    const streams = `${err.stdout ?? ""}${err.stderr ?? ""}`;
+    // A spawn-level failure (git never ran: ENAMETOOLONG on an oversized argv,
+    // ENOENT, EPERM) leaves both streams empty. The error's own message is
+    // then the only diagnosis there is, and an empty reason is the one thing
+    // the caller's report must never render.
+    if (streams.trim() !== "")
+        return streams;
+    return err.message ?? String(error);
+}
+/**
+ * `git` with `input` written to stdin — for `--pathspec-from-file=-`, so a
+ * pathspec of any length never rides on argv (Windows caps a command line at
+ * 32K characters; a workstream touching a few hundred files exceeds it).
+ */
+async function runWithStdin(cwd, args, input) {
+    return new Promise((resolvePromise, reject) => {
+        const child = execFile("git", args, { cwd, maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error) {
+                reject(Object.assign(error, { stdout, stderr }));
+                return;
+            }
+            resolvePromise({ stdout, stderr });
+        });
+        child.stdin?.on("error", () => undefined);
+        child.stdin?.end(input);
+    });
+}
+async function insideGitWorkTree(dir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir });
+        return stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+function parseWorktreeList(raw) {
+    const entries = [];
+    let current = {};
+    const flush = () => {
+        if (current.path !== undefined && current.head !== undefined) {
+            entries.push({
+                path: current.path,
+                head: current.head,
+                ...(current.branch === undefined ? {} : { branch: current.branch }),
+                ...(current.prunable === true ? { prunable: true } : {}),
+            });
+        }
+        current = {};
+    };
+    for (const line of raw.split("\n")) {
+        if (line === "") {
+            flush();
+            continue;
+        }
+        if (line.startsWith("worktree ")) {
+            current.path = line.slice("worktree ".length);
+        }
+        else if (line.startsWith("HEAD ")) {
+            current.head = line.slice("HEAD ".length);
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = line.slice("branch ".length);
+        }
+        else if (line.startsWith("prunable")) {
+            current.prunable = true;
+        }
+    }
+    flush();
+    return entries;
+}
+export const defaultWorktreeOps = {
+    async add(root, path, branch, commitish) {
+        await mkdir(dirname(path), { recursive: true });
+        await run(root, ["worktree", "add", "-b", branch, path, commitish]);
+    },
+    async list(root) {
+        const { stdout } = await run(root, ["worktree", "list", "--porcelain"]);
+        return parseWorktreeList(stdout);
+    },
+    async remove(root, path) {
+        try {
+            await run(root, ["worktree", "remove", "--force", path]);
+        }
+        catch {
+            // Already missing, or git's administrative entry disagrees with the
+            // filesystem — either way, there is nothing more to remove.
+        }
+    },
+    async prune(root) {
+        try {
+            await run(root, ["worktree", "prune"]);
+        }
+        catch {
+            // Best-effort housekeeping; never fatal.
+        }
+    },
+    async branchesUnder(root, prefix) {
+        try {
+            const { stdout } = await run(root, [
+                "for-each-ref",
+                "--format=%(refname:short)",
+                `refs/heads/${prefix}`,
+            ]);
+            return stdout
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line !== "");
+        }
+        catch {
+            return [];
+        }
+    },
+    async deleteBranch(root, branch) {
+        try {
+            await run(root, ["branch", "-D", branch]);
+        }
+        catch {
+            // Absent branch — nothing to delete.
+        }
+    },
+    async mergeInto(worktree, commitish, message) {
+        try {
+            const { stdout, stderr } = await run(worktree, ["merge", "--no-edit", "-m", message, commitish]);
+            return { ok: true, conflicts: [], output: `${stdout}${stderr}` };
+        }
+        catch (error) {
+            let conflicts = [];
+            try {
+                const { stdout } = await run(worktree, ["diff", "--name-only", "--diff-filter=U"]);
+                conflicts = stdout.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+            }
+            catch {
+                // Nothing more we can learn.
+            }
+            return { ok: false, conflicts, output: outputOf(error) };
+        }
+    },
+    async abortMerge(worktree) {
+        try {
+            await run(worktree, ["merge", "--abort"]);
+        }
+        catch {
+            // Nothing to abort, or the abort itself failed — the caller's own
+            // recovery path (reset --merge, worktree retention) covers this.
+        }
+    },
+    async squashIntegrate(cwd, commitish, message, paths) {
+        try {
+            await run(cwd, ["merge", "--squash", commitish]);
+        }
+        catch (error) {
+            try {
+                await run(cwd, ["reset", "--merge"]);
+            }
+            catch {
+                // Best-effort recovery; the caller reports the original failure.
+            }
+            return { ok: false, output: outputOf(error) };
+        }
+        if (paths.length === 0) {
+            // Nothing to stage or commit — an identical branch. Treat as a no-op
+            // integration, not a failure: there is no state to recover.
+            return { ok: true, commit: undefined };
+        }
+        try {
+            await runWithStdin(cwd, ["commit", "-m", message, "--pathspec-from-file=-", "--pathspec-file-nul"], paths.join(""));
+        }
+        catch (error) {
+            const output = outputOf(error);
+            // "nothing to commit" for the given pathspec is not a failure — the
+            // squash staged nothing under these paths (can legitimately happen
+            // when every incoming path was itself an exclusion).
+            if (/nothing to commit|nothing added to commit|no changes added to commit/u.test(output)) {
+                return { ok: true, commit: undefined };
+            }
+            try {
+                await run(cwd, ["reset", "--merge"]);
+            }
+            catch {
+                // Best-effort recovery; the caller reports the original failure.
+            }
+            return { ok: false, output };
+        }
+        try {
+            const { stdout } = await run(cwd, ["rev-parse", "HEAD"]);
+            return { ok: true, commit: stdout.trim() };
+        }
+        catch {
+            return { ok: true, commit: undefined };
+        }
+    },
+    async commitEverything(worktree, message) {
+        try {
+            await run(worktree, ["add", "-A"]);
+            try {
+                await run(worktree, ["commit", "-m", message]);
+            }
+            catch (error) {
+                if (!/nothing to commit|nothing added to commit|no changes added to commit/u.test(outputOf(error))) {
+                    throw error;
+                }
+            }
+            const { stdout } = await run(worktree, ["rev-parse", "HEAD"]);
+            return stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
+    async updateRef(root, ref, commit) {
+        await run(root, ["update-ref", ref, commit]);
+    },
+    async isAncestor(root, ancestor, descendant) {
+        try {
+            await run(root, ["merge-base", "--is-ancestor", ancestor, descendant]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async changedPaths(cwd, a, b) {
+        try {
+            const { stdout } = await run(cwd, ["diff", "--name-only", "-z", "--no-renames", a, b]);
+            return stdout.split("\0").filter((path) => path !== "");
+        }
+        catch {
+            return [];
+        }
+    },
+    async resolveCommit(cwd, rev) {
+        try {
+            const { stdout } = await run(cwd, ["rev-parse", "--verify", `${rev}^{commit}`]);
+            return stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
+    async discardRunnerArtifacts(worktree) {
+        let discovered = [];
+        try {
+            const { stdout } = await run(worktree, [
+                "status",
+                "--porcelain",
+                "-z",
+                "--",
+                ":(top)docs/programs",
+            ]);
+            discovered = stdout
+                .split("\0")
+                .filter((token) => token !== "")
+                .map((token) => token.slice(3));
+        }
+        catch {
+            // No tracked or untracked docs/programs paths — nothing to discard.
+        }
+        if (discovered.length === 0)
+            return [];
+        try {
+            await run(worktree, ["checkout", "--", ":(top)docs/programs"]);
+        }
+        catch {
+            // "did not match any file(s) known to git" is an ordinary case — no
+            // tracked file under docs/programs in this worktree.
+        }
+        try {
+            await run(worktree, ["clean", "-fd", "--", ":(top)docs/programs"]);
+        }
+        catch {
+            // Nothing untracked to remove.
+        }
+        return discovered;
+    },
+};
+//# sourceMappingURL=worktree.js.map

package/dist/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"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"}

package/dist/write-queue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A per-program serialized write queue: the single door every access to a
+ * program's manifest and decision ledger goes through. Manifest saves and
+ * ledger appends share one chain keyed by program (not per file) — that
+ * costs a few milliseconds of false serialization and buys a total order
+ * over a program's runner-owned state, which is what makes "the ledger
+ * never describes a manifest state that never existed" true by
+ * construction.
+ *
+ * A queued task may only do filesystem work. It must never spawn an agent,
+ * run a verify command, or call another queued API — this queue is not
+ * re-entrant, and a re-entrant call (a task that itself calls
+ * `enqueueProgramWrite` for the same key and awaits it) self-deadlocks.
+ */
+/** Stable key for one program's runner-owned files. */
+export declare function programWriteKey(root: string, programId: string): string;
+/**
+ * Runs `task` after everything already queued for `key` has settled, and
+ * returns its result. FIFO by call order. A rejected task rejects only its
+ * own caller — the chain is never poisoned for the next task.
+ */
+export declare function enqueueProgramWrite<T>(key: string, task: () => Promise<T>): Promise<T>;
+/** Resolves when everything currently queued for `key` has settled. */
+export declare function drainProgramWrites(key: string): Promise<void>;
+//# sourceMappingURL=write-queue.d.ts.map

package/dist/write-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-queue.d.ts","sourceRoot":"","sources":["../src/write-queue.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvE;AAOD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAED,uEAAuE;AACvE,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAInE"}

package/dist/write-queue.js

@@ -0,0 +1,52 @@
+import { resolve } from "node:path";
+/**
+ * A per-program serialized write queue: the single door every access to a
+ * program's manifest and decision ledger goes through. Manifest saves and
+ * ledger appends share one chain keyed by program (not per file) — that
+ * costs a few milliseconds of false serialization and buys a total order
+ * over a program's runner-owned state, which is what makes "the ledger
+ * never describes a manifest state that never existed" true by
+ * construction.
+ *
+ * A queued task may only do filesystem work. It must never spawn an agent,
+ * run a verify command, or call another queued API — this queue is not
+ * re-entrant, and a re-entrant call (a task that itself calls
+ * `enqueueProgramWrite` for the same key and awaits it) self-deadlocks.
+ */
+/** Stable key for one program's runner-owned files. */
+export function programWriteKey(root, programId) {
+    return `${resolve(root)} ${programId}`;
+}
+// The tail of each key's chain — always a promise that resolves (never
+// rejects), so the next task's `priorTail` is never poisoned by a prior
+// task's failure.
+const tails = new Map();
+/**
+ * Runs `task` after everything already queued for `key` has settled, and
+ * returns its result. FIFO by call order. A rejected task rejects only its
+ * own caller — the chain is never poisoned for the next task.
+ */
+export function enqueueProgramWrite(key, task) {
+    const priorTail = tails.get(key) ?? Promise.resolve();
+    const run = () => task();
+    const started = priorTail.then(run, run);
+    const settledTail = started.then(() => undefined, () => undefined);
+    tails.set(key, settledTail);
+    void settledTail.then(() => {
+        // Delete the entry only when this task's settlement is still the tail
+        // — a long-lived process must not accumulate one entry per program
+        // forever, but a newer task queued behind this one must not have its
+        // tail yanked out from under it.
+        if (tails.get(key) === settledTail)
+            tails.delete(key);
+    });
+    return started;
+}
+/** Resolves when everything currently queued for `key` has settled. */
+export async function drainProgramWrites(key) {
+    const tail = tails.get(key);
+    if (tail === undefined)
+        return;
+    await tail;
+}
+//# sourceMappingURL=write-queue.js.map

package/dist/write-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-queue.js","sourceRoot":"","sources":["../src/write-queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,SAAiB;IAC7D,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACzC,CAAC;AAED,uEAAuE;AACvE,wEAAwE;AACxE,kBAAkB;AAClB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAW,EACX,IAAsB;IAEtB,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IACtD,MAAM,GAAG,GAAG,GAAe,EAAE,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAC9B,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;IAEF,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC5B,KAAK,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE;QACzB,sEAAsE;QACtE,mEAAmE;QACnE,qEAAqE;QACrE,iCAAiC;QACjC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,WAAW;YAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAW;IAClD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,MAAM,IAAI,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildorder/nightshift",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "The crew that builds while you're gone: walk-away, CI-dispatched engineering programs with a decision ledger instead of gates",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,7 +59,7 @@
     "@eslint/js": "^10.0.1",
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^26.1.2",
-    "@wildorder/nightshift": "^0.16.0",
+    "@wildorder/nightshift": "^0.17.0",
     "eslint": "^10.8.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.66.0",

package/skills/plan-program/SKILL.md

@@ -135,12 +135,28 @@ orchestration is necessary.
   shared-contract migration requires expand → migrate consumers →
   contract/delete ordering.
 
+The runner builds independent workstreams concurrently, bounded by
+`--max-parallel`, and starts a workstream's build as soon as its own spec is
+finished and its dependencies have landed. Material parallelism is therefore
+evidence you can bank, not a hope. **Pipelining pays on chains, too** — a
+shape planners have been told not to expect a win from: a chain of *n*
+workstreams overlaps each spec's authoring with the previous workstream's
+build, so the run's length is roughly `author(1) + Σ build` rather than
+`Σ author + Σ build`. A chain is no longer a reason to prefer `atomic`.
+
 Do not choose orchestrated merely because the feature is important, spans
-many files, or has a high estimated token count. State the concrete evidence
-in `program.executionModeReason`. In atomic mode create exactly one
-workstream covering the entire program, with no dependencies and task file
-`tasks/{program-id}/implementation.md`. In orchestrated mode use the
-decomposition and checkpoint rules below.
+many files, or has a high estimated token count. And it is still not a
+licence to over-decompose: every workstream carries a spec, a critique
+cycle, a verify pass, and an integration, and two workstreams that edit the
+same file now collide at integration where serially they would have queued.
+`atomic` remains the default when one agent can hold the change coherently.
+State the concrete evidence in `program.executionModeReason`. In atomic mode
+create exactly one workstream covering the entire program, with no
+dependencies and task file `tasks/{program-id}/implementation.md`. In
+orchestrated mode use the decomposition and checkpoint rules below, and name
+the expected **width** (the widest dependency level, by workstream id) and
+the expected **critical path** (the chain of workstreams expected to
+determine the run's length) — one sentence each, in the program document.
 
 ## 2.5. Create the program's branch
 
@@ -253,6 +269,9 @@ when one exists. Otherwise use:
 ## Execution Mode
 **Mode:** atomic | orchestrated
 **Reason:** [Concrete causal evidence for the choice.]
+**Shape:** [Orchestrated only: the widest dependency level (which workstream
+ids run together) and the chain expected to determine the run's length. Omit
+for atomic.]
 
 ## Strategic Goals
 [Three to five outcome-focused bullets.]
@@ -403,6 +422,14 @@ workstream:
   neighbors might reasonably assume it handles something, say that it does
   not.
 
+Under concurrent builds, `excludes` carries one more job: two workstreams
+that both edit a shared file — a barrel like `src/index.ts`, the README, a
+shared test file, a config schema module — no longer queue behind each
+other; they build against the same base and one of them hits a conflict at
+integration. So **name an owner for each shared file one workstream will
+touch and others might**: the owner's `includes` says it owns the file,
+every other workstream's `excludes` says it does not.
+
 ### Every orchestrated workstream is an independently green checkpoint
 
 Design the roster so that, starting from a green repository containing only
@@ -423,6 +450,11 @@ For a shared contract migration, prefer an explicit sequence:
 The destructive cleanup depends on every migration workstream. Do not place
 foundational deletion first merely because it is conceptually central.
 
+Green now means green against the program-branch tip **including the
+siblings that landed while this workstream was building**, because the
+runner re-verifies after integration — a checkpoint that is green only
+against the tip it started from is a checkpoint that fails integration.
+
 ## 4.5. Absorb backlog items
 
 When any part of this program's scope came from an item captured under

package/dist/worktree-guard.d.ts

@@ -1,40 +0,0 @@
-/**
- * A pre-attempt snapshot of the git worktree. Rejected replanner attempts
- * were "rolled back" by restoring exactly two files, but the replanner is a
- * full agentic CLI that can touch anything — out-of-scope edits and stray
- * temp scripts survived the rollback while the progress line claimed a clean
- * transaction. This guard makes the claim true: capture the whole tracked
- * tree via `git stash create` (which snapshots without touching the
- * worktree) and record which paths were untracked, so a restore can revert
- * every tracked change and delete files the agent created.
- *
- * Limits, stated rather than hidden: modifications to files that were
- * already untracked at capture time cannot be restored (git has no snapshot
- * of them), and gitignored files are invisible to the status listing. In a
- * non-git directory `available` is false and callers fall back to the
- * legacy two-file restore with a warning.
- */
-export interface WorktreeCapture {
-    available: boolean;
-    /** Git repository toplevel; all recorded paths are relative to it. */
-    toplevel?: string;
-    /** Commit whose tree is the captured tracked state. */
-    source?: string;
-    /** Paths untracked at capture; never deleted by a restore. */
-    untracked?: Set<string>;
-}
-export declare function captureWorktree(root: string): Promise<WorktreeCapture>;
-export interface WorktreeRestoreResult {
-    restored: boolean;
-    /** Tracked paths whose state drifted from the capture (before restoring). */
-    drifted: string[];
-    /** Newly created untracked files that were deleted. */
-    removed: string[];
-}
-/**
- * Revert the worktree to `capture`, except `preservePaths` (absolute or
- * root-relative), which keep their current content. Newly created untracked
- * files outside the preserve list are deleted.
- */
-export declare function restoreWorktree(root: string, capture: WorktreeCapture, preservePaths?: string[]): Promise<WorktreeRestoreResult>;
-//# sourceMappingURL=worktree-guard.d.ts.map

package/dist/worktree-guard.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"worktree-guard.d.ts","sourceRoot":"","sources":["../src/worktree-guard.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAyBD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAc5E;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,aAAa,GAAE,MAAM,EAAO,GAC3B,OAAO,CAAC,qBAAqB,CAAC,CAwChC"}