dw-sdlc 0.10.0 → 0.12.0

package/README.md

@@ -86,6 +86,7 @@ script posts that status itself, its description saying why, and goes on.
 | `references setup` | the Router, its table and the ignore rules a repository needs to declare References |
 | `pr ship [<n>]`    | the Action one pull request needs next, performing the script's own                 |
 | `pr reviewed <n>`  | a clean review pinned to the head it read, as a commit status                       |
+| `recap`            | the facts a Recap rests on and whether the session can be closed                    |
 
 `dw-sdlc <command> --help` gives each one's options.
 

package/dist/agentic-config.d.ts

@@ -36,7 +36,7 @@ export type PrConfig = {
     reviewCommand: string;
 };
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
-declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
 export type WorkerEffort = (typeof WORKER_EFFORTS)[number];
 /** How a Worker's Claude Code session starts: the words that start it, its model and its effort. */
 export type WorkerConfig = {

package/dist/agentic-config.js

@@ -14,7 +14,7 @@ export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
 /** The Review depths, strictest first: what the dev's `--review` names. */
 export const REVIEW_DEPTHS = ["full", "light", "off"];
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
-const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+export const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],

package/dist/cli.js

@@ -8,9 +8,13 @@ import * as gate from "./commands/gate.js";
 import * as prReviewed from "./commands/pr-reviewed.js";
 import * as prShip from "./commands/pr-ship.js";
 import * as primitives from "./commands/primitives.js";
+import * as recap from "./commands/recap.js";
 import * as referencesSetup from "./commands/references-setup.js";
 import * as referencesSync from "./commands/references-sync.js";
 import * as setup from "./commands/setup.js";
+import * as workerLs from "./commands/worker-ls.js";
+import * as workerReport from "./commands/worker-report.js";
+import * as workerStart from "./commands/worker-start.js";
 const COMMANDS = new Map([
     ["gate", gate],
     ["check", check],
@@ -21,7 +25,11 @@ const COMMANDS = new Map([
     ["references sync", referencesSync],
     ["references setup", referencesSetup],
     ["pr ship", prShip],
-    ["pr reviewed", prReviewed]
+    ["pr reviewed", prReviewed],
+    ["recap", recap],
+    ["worker start", workerStart],
+    ["worker ls", workerLs],
+    ["worker report", workerReport]
 ]);
 function usage() {
     const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;

package/dist/commands/doctor.d.ts

@@ -40,11 +40,6 @@ export type Inputs = {
 };
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export declare function claudeConfigDir(env: Record<string, string | undefined>, home: string): string;
-/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
-export declare const MARKETPLACE = "dw-sdlc";
-export declare const PLUGIN = "sdlc";
-export declare const PLUGIN_ID = "sdlc@dw-sdlc";
-export declare const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export declare const RTK_FIND_EXEC_FIXED = "0.46.0";
 export declare const PNPM_MINIMUM_RELEASE_AGE = 10080;

package/dist/commands/doctor.js

@@ -7,16 +7,12 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { findRepository, resolveConfig } from "../agentic-config.js";
-import { EXACT_VERSION, parseCatalog, parsePins } from "../pins.js";
+import { checkPackage, checkPlugin, checkSessions, parseJson, runningPluginRoot, versionBefore } from "../doctor-plugins.js";
+import { isObject } from "../json-text.js";
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export function claudeConfigDir(env, home) {
     return env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
 }
-/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
-export const MARKETPLACE = "dw-sdlc";
-export const PLUGIN = "sdlc";
-export const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
-export const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export const RTK_FIND_EXEC_FIXED = "0.46.0";
 export const PNPM_MINIMUM_RELEASE_AGE = 10080;
@@ -34,20 +30,6 @@ export const realProbe = {
         return (result.stdout ?? "").trim().split("\n")[0] ?? "";
     }
 };
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function parseJson(text) {
-    if (text === undefined) {
-        return undefined;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-}
 function checkJq(probe) {
     const { status, stdout } = probe.run("jq", ["--version"]);
     if (status === 0) {
@@ -55,116 +37,6 @@ function checkJq(probe) {
     }
     return { name: "jq", level: "FAIL", detail: "missing: every guard is silent without it. brew install jq" };
 }
-/** Where the plugin's hooks run: live from the checkout for a marketplace added from a directory, a
- *  cached snapshot for one added from git. A marker placed in only one of the two settled it. */
-/** The checkout a directory marketplace runs the plugin from, or undefined for a snapshot. */
-function liveCheckout(probe, claude) {
-    const known = parseJson(probe.read(join(claude, "plugins", "known_marketplaces.json")));
-    const entry = isObject(known) && isObject(known[MARKETPLACE]) ? known[MARKETPLACE] : undefined;
-    const source = entry !== undefined && isObject(entry.source) ? entry.source : undefined;
-    return source?.source === "directory" && typeof source.path === "string" ? source.path : undefined;
-}
-function pluginOrigin(probe, claude, installPath) {
-    const checkout = liveCheckout(probe, claude);
-    if (checkout !== undefined) {
-        return `runs live from ${checkout}/plugins/${PLUGIN}; a change there is in the next session`;
-    }
-    return `installed at ${installPath}; a change reaches it through claude plugin update`;
-}
-/** The directory whose hooks run on this machine: the checkout of a directory marketplace, else the installed snapshot. */
-function runningPluginRoot(probe, claude) {
-    const checkout = liveCheckout(probe, claude);
-    if (checkout !== undefined) {
-        return join(checkout, "plugins", PLUGIN);
-    }
-    const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
-    const list = status === 0 ? parseJson(stdout) : undefined;
-    if (!Array.isArray(list)) {
-        return undefined;
-    }
-    const entry = list.find((item) => isObject(item) && item.id === PLUGIN_ID);
-    return entry !== undefined && typeof entry.installPath === "string" ? entry.installPath : undefined;
-}
-function checkPlugin(probe, claude) {
-    const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
-    const list = status === 0 ? parseJson(stdout) : undefined;
-    if (!Array.isArray(list)) {
-        return { name: "plugin", level: "FAIL", detail: "claude plugin list did not answer; is Claude Code installed?" };
-    }
-    const entry = list.find((item) => isObject(item) && item.id === PLUGIN_ID);
-    if (entry === undefined) {
-        return {
-            name: "plugin",
-            level: "FAIL",
-            detail: `${PLUGIN_ID} is not installed. claude plugin marketplace add dominikwozniak/dw-sdlc --sparse .claude-plugin plugins packages && claude plugin install ${PLUGIN_ID} --scope user`
-        };
-    }
-    const version = typeof entry.version === "string" ? entry.version : "?";
-    const installPath = typeof entry.installPath === "string" ? entry.installPath : "?";
-    if (entry.enabled !== true) {
-        return {
-            name: "plugin",
-            level: "FAIL",
-            detail: `${version} installed but disabled, so no guard runs. claude plugin enable ${PLUGIN_ID}`
-        };
-    }
-    return {
-        name: "plugin",
-        level: "PASS",
-        detail: `${version} enabled; ${pluginOrigin(probe, claude, installPath)}`
-    };
-}
-/** The `version` of the package.json in `dir`, or undefined when there is none. */
-function manifestVersion(probe, dir) {
-    const manifest = parseJson(probe.read(join(dir, "package.json")));
-    return isObject(manifest) && typeof manifest.version === "string" ? manifest.version : undefined;
-}
-/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
-function checkPackage(probe, claude, root) {
-    const name = "package";
-    const manifest = root === undefined ? undefined : probe.read(join(root, "package.json"));
-    if (root === undefined || manifest === undefined) {
-        return { name, level: "INFO", detail: `no package.json here to pin ${PACKAGE}` };
-    }
-    let spec;
-    try {
-        spec = parsePins(manifest, parseCatalog(probe.read(join(root, "pnpm-workspace.yaml")) ?? ""))[PACKAGE];
-    }
-    catch {
-        return { name, level: "INFO", detail: `${join(root, "package.json")} is not JSON` };
-    }
-    if (spec === undefined) {
-        return { name, level: "INFO", detail: `the repository does not pin ${PACKAGE}` };
-    }
-    // `workspace:` or a range names no one version: the copy installed under node_modules is the one that runs.
-    const pinned = EXACT_VERSION.test(spec) ? spec : manifestVersion(probe, join(root, "node_modules", PACKAGE));
-    if (pinned === undefined) {
-        return { name, level: "WARN", detail: `the repository pins ${PACKAGE} ${spec}, not installed: pnpm install` };
-    }
-    const plugin = runningPluginRoot(probe, claude);
-    if (plugin === undefined) {
-        return { name, level: "INFO", detail: `no ${PLUGIN_ID} runs here to compare with the pinned ${pinned}` };
-    }
-    const linked = manifestVersion(probe, join(plugin, PACKAGE));
-    if (linked === undefined) {
-        return {
-            name,
-            level: "WARN",
-            detail: `the plugin at ${plugin} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
-        };
-    }
-    if (linked !== pinned) {
-        const remedy = versionBefore(linked, pinned)
-            ? `claude plugin update ${PLUGIN_ID}`
-            : `pnpm add --save-dev --save-exact ${PACKAGE}@${linked}`;
-        return {
-            name,
-            level: "WARN",
-            detail: `drift: the plugin runs ${PACKAGE} ${linked} and the repository pins ${pinned}, so its hooks and skills run other code than the Gate. ${remedy}`
-        };
-    }
-    return { name, level: "PASS", detail: `${PACKAGE} ${linked} in the plugin and in the repository` };
-}
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {
     if (!isObject(settings) || !isObject(settings.hooks)) {
@@ -203,18 +75,6 @@ export function rtkExcludes(toml) {
     }
     return [...(match[1] ?? "").matchAll(/"([^"]*)"/g)].map((entry) => entry[1] ?? "");
 }
-function versionBefore(version, threshold) {
-    const a = version.split(".").map((part) => Number.parseInt(part, 10));
-    const b = threshold.split(".").map((part) => Number.parseInt(part, 10));
-    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
-        const x = a[i] ?? 0;
-        const y = b[i] ?? 0;
-        if (x !== y) {
-            return x < y;
-        }
-    }
-    return false;
-}
 // The plugin's rtk-rewrite.sh is the one wiring of `rtk hook claude`; a second one in the user
 // settings rewrites again, and in a linked worktree that copy is what the isolation check refuses.
 function checkRtk(probe, home, claude) {
@@ -261,6 +121,14 @@ function checkRtk(probe, home, claude) {
         detail: `rtk ${version} behind the plugin's rewrite hook; exclude_commands: ${excludes.join(", ") || "none"}`
     };
 }
+/** herdr's `hc` in the agent's shell, which a Lead starts its Workers through; a machine may go without it. */
+function checkHc(probe) {
+    const hc = probe.shell("command -v hc");
+    if (hc === "") {
+        return { name: "hc", level: "INFO", detail: "no hc on PATH, so no /sdlc-delegate: install herdr to run Workers" };
+    }
+    return { name: "hc", level: "PASS", detail: `${hc}, so a Lead can start Workers` };
+}
 function checkSafeChain(probe) {
     const binary = probe.shell("command -v safe-chain");
     if (binary === "") {
@@ -342,6 +210,8 @@ export function diagnose(inputs) {
         checkJq(probe),
         checkPlugin(probe, claude),
         checkPackage(probe, claude, inputs.config === undefined ? undefined : inputs.root),
+        checkSessions(probe, claude),
+        checkHc(probe),
         checkRtk(probe, home, claude),
         checkSafeChain(probe),
         checkPnpmReleaseAge(probe, home),

package/dist/commands/pr-ship.js

@@ -3,8 +3,8 @@
 // is not, as a line or one JSON document, with an exit code that names whose turn it is.
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig, REVIEW_DEPTHS } from "../agentic-config.js";
-import { decide, devCommand, hostArgs, isScriptAction, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
-import { CannotRun, carriesBase, gh, namedProblem, read, readAgain, said } from "../pr/read.js";
+import { decide, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
+import { CannotRun, carriesBase, gh, namedProblem, now, read, readAgain, said, withBehind } from "../pr/read.js";
 export const summary = "decide the Action one pull request needs next, as a line or JSON";
 const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--review full|light|off] [--dry-run] [--json] [--verbose]
 
@@ -13,7 +13,9 @@ is omitted, and answers the Action it needs next: the status, the action, whose
 The script performs its own Actions, each at most once and then reads again: it updates a branch
 behind its base, marks a draft ready once nothing else holds it back, and squash merges a pull
 request ready to merge under pr.merge auto in .ai/agentic.config.json or with --merge for this call;
-under ask, the default, it parks with the merge command. A head without a ${REVIEW} success
+under ask, the default, it parks with the merge command. A branch is behind when the compare of
+the base with the head shows the head lacks a commit of the base, or GitHub reports BEHIND, which
+it does only under a rule that a branch be up to date. A head without a ${REVIEW} success
 gets the Review depth --review names for this call, else pr.review: under full the agent reviews it
 with the command pr.reviewCommand names, /code-review by default; under light one sdlc-reviewer
 subagent reads the diff; under off the script posts the success itself, its description saying
@@ -38,7 +40,6 @@ Exit 0 done, 10 the agent's turn, 20 wait, 30 the dev's turn, 2 when it cannot r
 /** The depths --review takes, strictest first, as a sentence lists them. */
 const DEPTHS_SENTENCE = `${REVIEW_DEPTHS.slice(0, -1).join(", ")} or ${REVIEW_DEPTHS.at(-1)}`;
 const EXIT = { done: 0, act: 10, wait: 20, park: 30 };
-const REMEDIES = { clock: "unset it: it stands in for the clock in tests" };
 /** A call that stopped after it ran Actions: what it ran stands in `performed`, `ok` null where no read followed. */
 class Interrupted extends CannotRun {
     performed;
@@ -92,18 +93,6 @@ function parseCli(argv) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
 }
-/** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
-function now() {
-    const given = process.env.DW_SDLC_NOW?.trim();
-    if (given === undefined || given === "") {
-        return Date.now();
-    }
-    const time = Date.parse(given);
-    if (Number.isNaN(time)) {
-        throw new CannotRun(`DW_SDLC_NOW is ${JSON.stringify(given)}, not an ISO 8601 time`, REMEDIES.clock);
-    }
-    return time;
-}
 /** How a reason names each script Action: what the script would do, the act, and the state it acts on. */
 const NAMED = {
     "update-branch": { would: "update the branch", act: "the update", still: "the branch still reads behind its base" },
@@ -156,7 +145,7 @@ function handedOver(pr, policy, answer, action, reason) {
 function ship(cli, policy) {
     // Only pr.review auto routes the depth from the changes, so only it reads them.
     const sized = policy.review.depth === "auto";
-    let pr = read(cli, "pr ship", sized);
+    let pr = withBehind(read(cli, "pr ship", sized));
     const performed = [];
     // The head each Action ran on.
     const postedOn = new Map();
@@ -190,7 +179,7 @@ function ship(cli, policy) {
         const record = { action, command, exit: status, ...(message === "" ? {} : { stderr: message }) };
         postedOn.set(action, before.head);
         try {
-            pr = readAgain(pr, sized);
+            pr = withBehind(readAgain(pr, sized));
             performed.push({ ...record, ok: TOOK[action](before, pr) });
         }
         catch (error) {
@@ -202,12 +191,6 @@ function ship(cli, policy) {
         }
     }
 }
-/** `<status> <action>: <reason>`, the action dropped when it repeats the status, then the recheck and the command. */
-function lineOf({ status, action, reason, command, recheckAfter }) {
-    const label = status === action ? status : `${status} ${action}`;
-    const recheck = recheckAfter === undefined ? "" : `, recheck in ${recheckAfter} s`;
-    return `${label}: ${reason}${recheck}${command === undefined ? "" : ` — ${command}`}`;
-}
 function documentOf(pr, answer, performed, verbose) {
     const facts = verbose ? { facts: pr } : {};
     return { pr: pr.url, head: pr.head, base: pr.base, ...answer, performed, ...facts };
@@ -225,9 +208,9 @@ export function run(argv) {
     // An invalid config layer resolves to ask and full, like every other strictest setting.
     const declared = resolveConfig(repositoryRoot(process.cwd())).config.pr;
     const policy = {
-        merge: cli.merge ? "auto" : declared.merge,
-        review: cli.review === undefined ? { depth: declared.review, source: "config" } : { depth: cli.review, source: "flag" },
-        reviewCommand: declared.reviewCommand
+        ...declaredPolicy(declared),
+        ...(cli.merge ? { merge: "auto" } : {}),
+        ...(cli.review === undefined ? {} : { review: { depth: cli.review, source: "flag" } })
     };
     let shipped;
     try {

package/dist/commands/recap.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "the facts a Recap rests on and whether the session can be closed";
+export declare function run(argv: string[]): number;