dw-sdlc 0.15.0 → 0.15.2

package/dist/commands/setup.d.ts

@@ -1,6 +1,6 @@
 import { type CommitConvention, type CommitOnProtected, type ForcePush } from "../agentic-config.ts";
-/** `by hand` is an edit the setup names and leaves to the user. */
-export type Outcome = "wrote" | "unchanged" | "refused" | "by hand";
+/** `by hand` is an edit the setup names and leaves to the user; `skipped` is a file it has no reason to write. */
+export type Outcome = "wrote" | "unchanged" | "skipped" | "refused" | "by hand";
 export type Step = {
     file: string;
     outcome: Outcome;

package/dist/commands/setup.js

@@ -28,7 +28,8 @@ is kept, and --force-push and --commit-on-protected pin those two keys in it, re
 loosen what the committed config sets; --force overwrites a local config that differs in anything
 else; --dry-run reports without writing. Where cswap is on PATH, the local config also gets
 worker.command, the command a Worker starts with: cswap run -- --dangerously-skip-permissions. A
-worker block the file holds is kept as it is, and without cswap nothing is written.
+worker block the file holds is kept as it is, and without cswap nothing is written. A local config
+holding only $schema is not written, and an existing one stays: the run prints "skipped".
 
 Where the repository has a package.json, the setup adopts the Gate. --add-package pins dw-sdlc
 there as a devDependency, at the version running the setup; a new dependency needs the owner's yes,
@@ -251,8 +252,8 @@ export function setup(options) {
     const root = repositoryRoot(options.root);
     const { checkout, gitDir } = mainCheckout(root);
     const claudeDir = options.claudeDir ?? join(options.home, ".claude");
-    // 1. The local config, from inference, the convention (the flag's, else the one the file pins) and
-    // the guardrails block the file holds, with the keys the flags pin.
+    // 1. The local config: inference, the convention (the flag's, else the file's pin), the guardrails block
+    // the file holds with the flags' pins. A layer of `$schema` alone tells the guards nothing: not written.
     const localPath = join(checkout, LOCAL_FILE);
     const localCurrent = existsSync(localPath) ? readFileSync(localPath, "utf8") : undefined;
     const existing = localCurrent === undefined ? undefined : parseObject(localCurrent);
@@ -264,7 +265,10 @@ export function setup(options) {
     else {
         const { worker, detail } = pinnedWorker(keptWorker(existing), options.path ?? process.env.PATH);
         const local = localConfig(checkout, claudeDir, convention, pinned.guardrails, worker);
-        if (localCurrent !== undefined && !sameContent(existing, local) && !options.force) {
+        if (Object.keys(local).length === 1 && (localCurrent === undefined || sameContent(existing, local))) {
+            writer.steps.push({ file: LOCAL_FILE, outcome: "skipped", detail: "the layer would hold only $schema" });
+        }
+        else if (localCurrent !== undefined && !sameContent(existing, local) && !options.force) {
             writer.refuse(LOCAL_FILE, "exists with other content; pass --force to overwrite it");
         }
         else {

package/dist/commands/worker-start.js

@@ -7,6 +7,7 @@ import { parseArgs } from "node:util";
 import { mainCheckout, repositoryRoot, resolveConfig, WORKER_EFFORTS } from "../agentic-config.js";
 import { isObject } from "../json-text.js";
 import { describe, hcObject, isLive, lead, refuse, Refusal, wholeNumber, workersOf } from "../worker/herdr.js";
+import { freshenOrigin } from "../worker/origin.js";
 import { nameTab } from "../worker/tabs.js";
 export const summary = "start a Worker on a Brief in a herdr terminal";
 /** The most seconds the command looks for the Worker's tab in the window, beside the read-back. */
@@ -27,12 +28,17 @@ turns working, blocked or done. It fails when herdr reports the first message as
 ended, the Worker reports an error, or the Worker is still idle or silent when the time is up. It never sends
 the Brief again: read the terminal with hc read first.
 
+Before it starts the Worker it fetches origin's default branch into the clone (the branch origin/HEAD names,
+else baseBranch of the config, else every branch of origin), so the Worker's worktree, which Claude Code
+branches from origin/<default>, begins from origin's tip. A clone with no origin skips the fetch. When the
+fetch fails the command starts no Worker and exits 2.
+
 It refuses outside herdr ($HC_TERMINAL_ID unset) and when the Lead already has --max-workers live
 Workers (default 3). The name is 1-32 of a-z, 0-9, - and _; it names the worktree too.
 
 One line, or one JSON document with --json.
 
-Exit 0 started and delivered, 1 started but not delivered, 2 when it cannot run.`;
+Exit 0 started and delivered, 1 started but not delivered, 2 when it cannot run, a failed fetch included.`;
 const DEFAULT_MAX_WORKERS = 3;
 const DEFAULT_WAIT = 30;
 /** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
@@ -156,7 +162,7 @@ async function start(cli) {
     const checkout = repositoryRoot(process.cwd());
     // The Worker's --worktree makes a worktree of the repository itself, never of a linked one.
     const root = mainCheckout(checkout) ?? checkout;
-    const worker = resolveConfig(checkout).config.worker;
+    const { baseBranch, worker } = resolveConfig(checkout).config;
     const command = worker.command.split(/\s+/).filter(Boolean);
     if (command.length === 0) {
         throw new Refusal("worker.command holds no command", "set it in .ai/agentic.config.local.json, or remove the key");
@@ -167,6 +173,8 @@ async function start(cli) {
     if (live.length >= cli.max) {
         throw new Refusal(`${leadId} already has ${live.length} live Workers (the limit is ${cli.max})`, `carry one through first, or raise the limit with --max-workers ${live.length + 1}`);
     }
+    // Before hc run, so a failed fetch starts no terminal.
+    freshenOrigin(root, baseBranch);
     const space = spaceOf(leadId);
     const { address } = hcObject([
         "run",

package/dist/exec.js

@@ -1,6 +1,6 @@
-// Every short-lived child process the package runs: stopped at a time limit, so a tool that hangs cannot
-// hang the command, and with git's prompts off, since nobody would see one. A Step of the Gate runs
-// through `run-command.ts` instead, and takes as long as it takes.
+// Every short-lived child process the package runs: in a session of its own, so a time limit stops it with
+// every child it started; no terminal, so no prompt, ssh's included; Ctrl-C stops the package, not the
+// tool. A Step of the Gate runs through `run-command.ts`, as long as it takes.
 import { spawnSync } from "node:child_process";
 const LIMIT_MS = 120_000;
 /** For what the network or a repository's size can stretch: a clone, a fetch, a scan of its history. */
@@ -19,20 +19,39 @@ function limitOf(asked) {
 function shown(tool, args) {
     return [tool, ...args].join(" ").replaceAll(/\s+/g, " ").trim().slice(0, SHOWN);
 }
+/** Every process left in the group the tool led; the tool itself is stopped and reaped by now. */
+function stopGroup(pid) {
+    // A pid of 0 would make the kill reach this process's own group.
+    if (pid <= 0) {
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch (error) {
+        // ESRCH: no process is left in the group.
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+}
 /** `tool args` as a child process; a tool's own exit, or its absence, is the caller's. Throws `TimedOut` at the limit. */
 export function exec(tool, args, options = {}) {
     const { cwd, env = process.env, input } = options;
     const limitMs = limitOf(options.limitMs ?? LIMIT_MS);
-    const result = spawnSync(tool, args, {
+    const spawnOptions = {
         ...(cwd === undefined ? {} : { cwd }),
         ...(input === undefined ? {} : { input }),
+        detached: true,
         encoding: "utf8",
         env: { ...env, GIT_TERMINAL_PROMPT: "0" },
         killSignal: "SIGKILL",
         maxBuffer: MAX_BUFFER,
         timeout: limitMs
-    });
+    };
+    const result = spawnSync(tool, args, spawnOptions);
     if (result.error !== undefined && "code" in result.error && result.error.code === "ETIMEDOUT") {
+        stopGroup(result.pid);
         throw new TimedOut(`${shown(tool, args)} did not answer within ${limitMs / 1000} s`);
     }
     return result;

package/dist/pr/decide.js

@@ -157,7 +157,7 @@ const ROWS = [
             action: "done",
             actor: "dev",
             reason: pr.mergeCommit === null ? "merged" : `merged as ${pr.mergeCommit.slice(0, 7)}`,
-            command: shellLine(["git", "push", "origin", "--delete", pr.branch]),
+            ...(pr.branchStands ? { command: shellLine(["git", "push", "origin", "--delete", pr.branch]) } : {}),
             ...(pr.mergeCommit === null ? {} : { details: { mergeCommit: pr.mergeCommit } })
         }),
         alone: true
@@ -249,14 +249,18 @@ const ROWS = [
         }
     },
     {
-        when: (pr) => ciOf(pr).length === 0,
-        answer: (pr, now, policy) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
+        // A head whose every check was skipped has run nothing: a draft's are, until `ready` starts the run.
+        when: (pr) => ciOf(pr).length === 0 || (!pr.draft && ciOf(pr).every((check) => check.bucket === "skipping")),
+        answer: (pr, now, policy) => now - Math.max(Date.parse(pr.headCommittedAt), Date.parse(pr.readyAt ?? pr.headCommittedAt)) <=
+            GRACE_SECONDS * 1000
             ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }
             : {
                 status: "park",
                 action: "unverified",
                 actor: "dev",
-                reason: `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`,
+                reason: ciOf(pr).length === 0
+                    ? `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`
+                    : `every check on ${pr.head.slice(0, 7)} was skipped, ${GRACE_SECONDS} s after its commit or its ready`,
                 command: devCommand(pr, "merge", policy)
             }
     },

package/dist/pr/read.d.ts

@@ -39,6 +39,8 @@ export declare function defaultBranch(): string;
 export declare function now(): number;
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
 export declare function readAgain(pr: PrState, sized: boolean): PrState;
+/** For a test that runs the command in its own process: each case starts with no compare read. */
+export declare function forgetCompares(): void;
 /** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
 export declare function carriesBase(before: PrState, after: PrState): boolean;
 /**

package/dist/pr/read.js

@@ -164,6 +164,10 @@ export function readAgain(pr, sized) {
  * once: a compare of two commits never changes.
  */
 const COMPARES = new Map();
+/** For a test that runs the command in its own process: each case starts with no compare read. */
+export function forgetCompares() {
+    COMPARES.clear();
+}
 /** The reply of the compare from `from` to `commit`, read once per process; `what` names it when gh refuses it. */
 function compared(pr, from, commit, what) {
     const key = `${pr.repo} ${from}...${commit}`;

package/dist/pr/state.d.ts

@@ -10,7 +10,7 @@ export declare const MARK_STATE = "failure";
 export declare const READ_MARK = "read, findings open";
 /** How the description of the success the dev's `--accept` posts reads: the head, taken with its Findings open. */
 export declare const ACCEPTED = "accepted by the dev, findings open";
-export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid\n      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { pageInfo { hasNextPage } nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName headRef { name } baseRefName\n      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }\n      latestReviews(first: 100) { nodes { state author { login } commit { oid } } }\n      reviewThreads(first: 100) { pageInfo { hasNextPage } nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { pageInfo { hasNextPage } nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -51,7 +51,11 @@ export type PrState = {
     viewerDidAuthor: boolean;
     head: string;
     headCommittedAt: string;
+    /** When the pull request last left draft; null when it never was one. */
+    readyAt: string | null;
     branch: string;
+    /** Whether the head branch still stands on the remote: GitHub reports no `headRef` once it is gone. */
+    branchStands: boolean;
     base: string;
     /**
      * The commit the base branch points at, read from the branch itself: GitHub's `baseRefOid` lags a

package/dist/pr/state.js

@@ -18,8 +18,9 @@ const THREADS_READ = 100;
 export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
-      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid
-      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }
+      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName headRef { name } baseRefName
+      baseRefOid baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }
+      ready: timelineItems(last: 1, itemTypes: [READY_FOR_REVIEW_EVENT]) { nodes { ... on ReadyForReviewEvent { createdAt } } }
       latestReviews(first: 100) { nodes { state author { login } commit { oid } } }
       reviewThreads(first: ${THREADS_READ}) { pageInfo { hasNextPage } nodes { id isResolved isOutdated path line
         comments(first: 1) { nodes { author { login } body } }
@@ -302,6 +303,7 @@ export function parsePr(reply, repo) {
     const head = string(pr, "headRefOid");
     const baseRef = childOrNull(pr, "baseRef");
     const history = historyOf(pr);
+    const [ready] = nodes(pr, "ready");
     return {
         url: string(pr, "url"),
         repo,
@@ -314,7 +316,9 @@ export function parsePr(reply, repo) {
         viewerDidAuthor: boolean(pr, "viewerDidAuthor"),
         head,
         headCommittedAt: time(commit, "committedDate"),
+        readyAt: ready === undefined ? null : time(ready, "createdAt"),
         branch: string(pr, "headRefName"),
+        branchStands: childOrNull(pr, "headRef") !== null,
         base: string(pr, "baseRefName"),
         baseOid: baseRef === null ? string(pr, "baseRefOid") : string(child(baseRef, "target"), "oid"),
         mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),

package/dist/worker/origin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fetches origin's default branch, or every branch of origin when no default is known, into the remote-tracking
+ * refs at `root`; a clone with no origin has nothing to fetch and is left alone. Throws a `Refusal` when the
+ * fetch fails, since a Worker started on a stale base is the fault this prevents.
+ */
+export declare function freshenOrigin(root: string, baseBranch: string): void;

package/dist/worker/origin.js

@@ -0,0 +1,42 @@
+// Brings the clone's view of origin's default branch up to date before a Worker starts: Claude Code's
+// `--worktree` branches from the cached `origin/<default>` and fetches it only when the clone has gone a
+// day without a fetch, so a Worker could otherwise begin from a ref that is hours or days behind.
+import { exec, SLOW_LIMIT_MS, TimedOut } from "../exec.js";
+import { repositoryFreeEnv } from "../git-env.js";
+import { asked } from "../working-tree.js";
+import { Refusal } from "./herdr.js";
+const REMOTE_HEAD = "refs/remotes/origin/HEAD";
+const PREFIX = "refs/remotes/origin/";
+/** The branch to fetch: the one origin/HEAD names, else `baseBranch` of the config; undefined when neither names one. */
+function defaultBranch(root, baseBranch) {
+    const ref = asked(root, ["symbolic-ref", "-q", REMOTE_HEAD]);
+    if (ref !== undefined && ref.startsWith(PREFIX) && ref.length > PREFIX.length) {
+        return ref.slice(PREFIX.length);
+    }
+    return baseBranch === "" || baseBranch === "auto" ? undefined : baseBranch;
+}
+/**
+ * Fetches origin's default branch, or every branch of origin when no default is known, into the remote-tracking
+ * refs at `root`; a clone with no origin has nothing to fetch and is left alone. Throws a `Refusal` when the
+ * fetch fails, since a Worker started on a stale base is the fault this prevents.
+ */
+export function freshenOrigin(root, baseBranch) {
+    if (asked(root, ["remote", "get-url", "origin"]) === undefined) {
+        return;
+    }
+    const branch = defaultBranch(root, baseBranch);
+    const args = ["-C", root, "fetch", "--quiet", "origin", ...(branch === undefined ? [] : [branch])];
+    const fetched = `git fetch origin${branch === undefined ? "" : ` ${branch}`}`;
+    const stale = (why) => new Refusal(`${fetched} failed, so the Worker would begin from a stale base: ${why}`, "check the network and the access to origin, then start the Worker again");
+    let result;
+    try {
+        result = exec("git", args, { env: repositoryFreeEnv(), limitMs: SLOW_LIMIT_MS });
+    }
+    catch (error) {
+        throw error instanceof TimedOut ? stale(error.message) : error;
+    }
+    if (result.status !== 0) {
+        const said = result.stderr.split("\n").find((line) => line.trim() !== "");
+        throw stale(said?.trim() ?? `exited ${result.status ?? "on a signal"}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {