dw-sdlc 0.20.0 → 0.21.1

package/dist/checks/markdown-refs.js

@@ -1,8 +1,9 @@
-// `markdown-refs`: every relative link and image in the markdown resolves, its path to a file or a
-// directory git tracks or would track and its heading anchor to a heading of the file it names, so a
-// link to an ignored file or to another case of a file's name fails here as it fails in CI.
+// `markdown-refs`: every relative link and image, and every URL into origin's default branch even in
+// code, resolves to a file or directory git tracks or would track and its anchor to a heading there, so
+// a link to an ignored file or to another case of a file's name fails here as it fails in CI.
 import { readFileSync } from "node:fs";
 import { join, posix } from "node:path";
+import { asked } from "../git.js";
 import { anchorsOf, links } from "../markdown.js";
 import { directoriesOf, matching, treeFiles } from "./tree.js";
 const REMEDIES = {
@@ -12,6 +13,51 @@ const REMEDIES = {
 };
 /** A target with a scheme, such as `https:` or `mailto:`, or a host: no file of the tree answers it. */
 const EXTERNAL = /^([a-z][a-z\d+.-]*:|\/\/)/i;
+/** `owner/name` in the URL of a GitHub remote, over SSH or HTTPS, with a user, a token or a port, `.git` or not. */
+const GITHUB_REMOTE = /^(?:git@github\.com:|(?:ssh|https?):\/\/(?:[^@/]+@)?github\.com(?::\d+)?\/)([^/]+\/[^/]+?)(?:\.git)?\/?$/i;
+const REMOTE_HEAD = "refs/remotes/origin/HEAD";
+/** The branch a URL is judged at when origin/HEAD names none, as in a CI checkout. */
+const FALLBACK_BRANCH = "main";
+/** A URL into a GitHub repository: a file page, a directory page or a raw file, up to a space, a quote or a bracket. */
+const REPOSITORY_URL = /https:\/\/(?:github\.com\/[^/\s]+\/[^/\s]+\/(?:blob|tree)|raw\.githubusercontent\.com\/[^/\s]+\/[^/\s]+)\/[^\s"'`<>()[\]]+/gi;
+/** Closing punctuation and emphasis markers after a URL, which GitHub leaves out of it. */
+const TRAILING = /[.,;:!?*_~]+$/;
+/** A GitHub anchor to a line or a range of lines, which names no heading. */
+const LINE_ANCHOR = /#L\d+(C\d+)?(-L\d+(C\d+)?)?$/;
+/** The prefixes of URLs into origin's default branch; none when origin is not on GitHub. */
+function prefixesOf(root) {
+    const slug = GITHUB_REMOTE.exec(asked(root, ["remote", "get-url", "origin"]) ?? "")?.[1]?.toLowerCase();
+    if (slug === undefined) {
+        return [];
+    }
+    const head = asked(root, ["symbolic-ref", "-q", REMOTE_HEAD])?.replace(/^refs\/remotes\/origin\//, "");
+    const branch = head === undefined || head === "" ? FALLBACK_BRANCH : head;
+    return [
+        `https://github.com/${slug}/blob/`,
+        `https://github.com/${slug}/tree/`,
+        `https://raw.githubusercontent.com/${slug}/`
+    ].map((repository) => ({ repository, branch }));
+}
+/** The path from the root `url` names under one of `prefixes`, its line anchor dropped; undefined under none. */
+function pathOf(url, prefixes) {
+    const prefix = prefixes.find(({ repository, branch }) => url.toLowerCase().startsWith(repository) && url.slice(repository.length).startsWith(`${branch}/`));
+    return prefix === undefined
+        ? undefined
+        : `/${url.slice(prefix.repository.length + prefix.branch.length + 1).replace(LINE_ANCHOR, "")}`;
+}
+/** Every URL of `text` into the repository's default branch, a fenced line's included, once per line. */
+function repositoryLinks(text, prefixes) {
+    if (prefixes.length === 0) {
+        return [];
+    }
+    return text.split("\n").flatMap((line, index) => {
+        const urls = new Set(Array.from(line.matchAll(REPOSITORY_URL), ([url]) => url.replace(TRAILING, "")));
+        return [...urls].flatMap((url) => {
+            const target = pathOf(url, prefixes);
+            return target === undefined ? [] : [{ target, line: index + 1, shown: url }];
+        });
+    });
+}
 function decode(text) {
     try {
         return decodeURIComponent(text);
@@ -30,13 +76,13 @@ function resolve(file, path) {
     return normal.length > 1 ? normal.replace(/\/$/, "") : normal;
 }
 /** What is wrong with one link of `file`: a path out of the repository or not in it, or an anchor with no heading. */
-function judge(repository, file, { target, line }) {
+function judge(repository, file, { target, line, shown = target }) {
     if (EXTERNAL.test(target)) {
         return [];
     }
     const [beforeAnchor = "", anchor = ""] = target.split("#", 2);
     const resolved = resolve(file, decode(beforeAnchor.split("?", 1)[0] ?? ""));
-    const quoted = JSON.stringify(target);
+    const quoted = JSON.stringify(shown);
     if (resolved === ".." || resolved.startsWith("../")) {
         return [{ file, line, message: `links to ${quoted}, which is outside the repository`, remedy: REMEDIES.outside }];
     }
@@ -53,8 +99,14 @@ function judge(repository, file, { target, line }) {
 function run(root, { files, exempt }) {
     const tree = treeFiles(root);
     const known = new Set(tree);
+    const prefixes = prefixesOf(root);
     const repository = { root, files: known, directories: directoriesOf(known), anchors: new Map() };
-    return matching(root, tree, files, exempt).flatMap((file) => links(readFileSync(join(root, file), "utf8")).flatMap((link) => judge(repository, file, link)));
+    return matching(root, tree, files, exempt).flatMap((file) => {
+        const text = readFileSync(join(root, file), "utf8");
+        return [...links(text), ...repositoryLinks(text, prefixes)]
+            .toSorted((left, right) => left.line - right.line)
+            .flatMap((link) => judge(repository, file, link));
+    });
 }
 export const markdownRefs = {
     name: "markdown-refs",

package/dist/checks/primitives.js

@@ -2,10 +2,10 @@
 // one-line summary, real code and docs paths, no decision record out of force, every file named.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { resolveConfig } from "../agentic-config.js";
+import { CannotRun } from "../cannot-run.js";
 import { CATALOGUE_FILE, primitivesNaming, readCatalogue } from "../catalogue.js";
 import { anchorsOf } from "../markdown.js";
-import { CannotRun, optionsOf } from "./check.js";
+import { optionsOf } from "./check.js";
 import { decisionRecords, OUT_OF_FORCE, recordStatus } from "./decision-records.js";
 import { treeFiles } from "./tree.js";
 const MAX_SUMMARY = 120;
@@ -68,16 +68,16 @@ function judge(root, catalogue, primitive, at, cache, records) {
     }
     return findings;
 }
-function run(root, { file, roots }) {
+function run(root, { file, roots }, gate) {
     const read = readCatalogue(root, file);
     if (read.state === "missing") {
-        throw new CannotRun({ file, message: "the catalogue does not exist", remedy: REMEDIES.missing });
+        throw new CannotRun("the catalogue does not exist", REMEDIES.missing, { file });
     }
     if (read.state === "invalid") {
         return read.problems.map((message) => ({ file, message, remedy: REMEDIES.shape }));
     }
     const { catalogue, text } = read;
-    const records = (optionsOf(decisionRecords, resolveConfig(root).config.gate.checks["decision-records"]) ?? decisionRecords.defaults).dirs;
+    const records = (optionsOf(decisionRecords, gate.checks["decision-records"]) ?? decisionRecords.defaults).dirs;
     const findings = [];
     const seen = new Map();
     const cache = new Map();

package/dist/checks/routed-docs.js

@@ -2,7 +2,6 @@
 // a Task Router row of the agent map, through a path, a directory above it or a glob, or by the docs of
 // a Primitive in the catalogue. It reads the file list, the Task Router and the catalogue, never prose.
 import { matchesGlob, posix } from "node:path";
-import { resolveConfig } from "../agentic-config.js";
 import { readCatalogue } from "../catalogue.js";
 import { mapFile, readMap, routes } from "./agents-map.js";
 import { catalogueFile } from "./primitives.js";
@@ -25,8 +24,7 @@ function catalogueDocs(root, file) {
     const read = readCatalogue(root, file);
     return read.state === "valid" ? read.catalogue.primitives.flatMap(({ docs }) => docs) : [];
 }
-function run(root, { files, exempt }) {
-    const { checks } = resolveConfig(root).config.gate;
+function run(root, { files, exempt }, { checks }) {
     const map = mapFile(checks);
     const rows = routes(readMap(root, map));
     const findings = [];

package/dist/checks/skill-sections.js

@@ -3,10 +3,10 @@
 // docs name. `dw-sdlc check skill-sections --write` writes each part from its section.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, posix } from "node:path";
-import { resolveConfig } from "../agentic-config.js";
+import { CannotRun } from "../cannot-run.js";
 import { readCatalogue } from "../catalogue.js";
 import { headings, openFence, prose } from "../markdown.js";
-import { CannotRun } from "./check.js";
+import {} from "./check.js";
 import { catalogueFile } from "./primitives.js";
 import { matching, treeFiles } from "./tree.js";
 /** Either marker of a part: `/` before `README.md` closes it. */
@@ -111,41 +111,33 @@ function render(root, path, sources) {
     pieces.push(text.slice(copied));
     return { text: pieces.join(""), findings, rewritten };
 }
-/** The docs entries the catalogue names, each read from the root; the catalogue is read on the first call. */
-function listedDocs(root) {
+/** The docs entries of the catalogue `gate` points at, each read from the root; it is read on the first call. */
+function listedDocs(root, gate) {
     let listed;
     return () => {
         if (listed === undefined) {
-            const file = catalogueFile(resolveConfig(root).config.gate.checks);
+            const file = catalogueFile(gate.checks);
             const read = readCatalogue(root, file);
             if (read.state === "missing") {
-                throw new CannotRun({
-                    file,
-                    message: "the catalogue does not exist, and a skill holds a part",
-                    remedy: REMEDIES.missing
-                });
+                throw new CannotRun("the catalogue does not exist, and a skill holds a part", REMEDIES.missing, { file });
             }
             if (read.state === "invalid") {
-                throw new CannotRun({
-                    file,
-                    message: "the catalogue is not valid, and a skill holds a part",
-                    remedy: REMEDIES.invalid
-                });
+                throw new CannotRun("the catalogue is not valid, and a skill holds a part", REMEDIES.invalid, { file });
             }
             listed = new Set(read.catalogue.primitives.flatMap(({ docs }) => docs).map((entry) => posix.join(".", entry)));
         }
         return listed;
     };
 }
-function renderAll(root, { files }) {
-    const sources = { listed: listedDocs(root), readmes: new Map() };
+function renderAll(root, { files }, gate) {
+    const sources = { listed: listedDocs(root, gate), readmes: new Map() };
     return matching(root, treeFiles(root), files).map((path) => ({ path, rendered: render(root, path, sources) }));
 }
 function plural(count, noun) {
     return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
-function write(root, options) {
-    const changed = renderAll(root, options).filter(({ rendered }) => rendered.rewritten > 0);
+function write(root, options, gate) {
+    const changed = renderAll(root, options, gate).filter(({ rendered }) => rendered.rewritten > 0);
     for (const { path, rendered } of changed) {
         writeFileSync(join(root, path), rendered.text);
     }
@@ -158,6 +150,6 @@ function write(root, options) {
 export const skillSections = {
     name: "skill-sections",
     defaults: { files: ["**/skills/**/*.md"] },
-    run: (root, options) => renderAll(root, options).flatMap(({ rendered }) => rendered.findings),
+    run: (root, options, gate) => renderAll(root, options, gate).flatMap(({ rendered }) => rendered.findings),
     write
 };

package/dist/checks/tree.js

@@ -2,18 +2,18 @@
 // pick out of them: what the Checks that judge many files read, so a file git ignores is never judged.
 import { existsSync, lstatSync, realpathSync } from "node:fs";
 import { join, matchesGlob, posix, relative } from "node:path";
-import { exec } from "../exec.js";
-import { CannotRun } from "./check.js";
+import { CannotRun } from "../cannot-run.js";
+import { git } from "../git.js";
 /** Every file under `pathspecs`, the whole tree when there are none, that git tracks or would track and that is on disk; sorted. */
 export function treeFiles(root, pathspecs = []) {
-    const args = ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...pathspecs];
-    const listed = exec("git", args);
-    if (listed.status !== 0) {
+    const args = ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...pathspecs];
+    const listed = git(root, args, { raw: true });
+    if ("error" in listed) {
         const under = pathspecs.length === 0 ? "" : ` under ${pathspecs.join(", ")}`;
         const message = `cannot list the files${under}: not a git repository`;
-        throw new CannotRun({ message, remedy: "run the Gate inside a git repository" });
+        throw new CannotRun(message, "run the Gate inside a git repository");
     }
-    return [...new Set(listed.stdout.split("\0").filter((path) => path !== ""))]
+    return [...new Set(listed.out.split("\0").filter((path) => path !== ""))]
         .filter((path) => existsSync(join(root, path)))
         .toSorted();
 }

package/dist/cli.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+/** `dw-sdlc <argv>`: the command's exit code, or 2 with its line when it throws `CannotRun`. */
+export declare function dispatch(argv: string[]): number | Promise<number>;

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // The `dw-sdlc` bin: one row per subcommand, each a module under `commands/`. A plugin's hook or skill
 // reaches it through the plugin's `dw-sdlc` link.
+import { CannotRun, messageOf } from "./cannot-run.js";
 import * as check from "./commands/check.js";
 import * as config from "./commands/config.js";
 import * as doctor from "./commands/doctor.js";
@@ -40,7 +41,13 @@ function usage() {
     const rows = [...COMMANDS].map(([name, { summary }]) => `  ${name.padEnd(width)}${summary}`);
     return `Usage: dw-sdlc <command> [options]\n\nCommands:\n${rows.join("\n")}\n\nRun dw-sdlc <command> --help for its options.`;
 }
-async function main(argv) {
+/** What the bin prints for `error`, which stopped `command`: the problem, its remedy, the lines after it. */
+function stopText(command, { message, remedy, detail }) {
+    const line = `dw-sdlc ${command}: ${message}${remedy === undefined ? "" : ` — ${remedy}`}\n`;
+    return detail.after === undefined ? line : `${line}${detail.after}\n`;
+}
+/** `dw-sdlc <argv>`: the command's exit code, or 2 with its line when it throws `CannotRun`. */
+export function dispatch(argv) {
     const [first, second] = argv;
     if (first === "--help" || first === "-h") {
         process.stdout.write(`${usage()}\n`);
@@ -48,21 +55,35 @@ async function main(argv) {
     }
     // A two-word name, as `references sync`, before its first word alone.
     const words = second !== undefined && COMMANDS.has(`${first} ${second}`) ? 2 : 1;
-    const command = COMMANDS.get(argv.slice(0, words).join(" "));
+    const name = argv.slice(0, words).join(" ");
+    const command = COMMANDS.get(name);
     if (command === undefined) {
         const problem = first === undefined ? "no command given" : `unknown command ${JSON.stringify(first)}`;
         process.stderr.write(`dw-sdlc: ${problem}\n\n${usage()}\n`);
         return 2;
     }
-    return command.run(argv.slice(words));
+    const stopped = (error) => {
+        if (!(error instanceof CannotRun)) {
+            throw error;
+        }
+        process.stderr.write(stopText(name, error));
+        return 2;
+    };
+    try {
+        const code = command.run(argv.slice(words));
+        return typeof code === "number" ? code : code.catch(stopped);
+    }
+    catch (error) {
+        return stopped(error);
+    }
 }
 if (import.meta.main) {
     try {
-        process.exitCode = await main(process.argv.slice(2));
+        process.exitCode = await dispatch(process.argv.slice(2));
     }
     catch (error) {
         // What no command answered for stopped it before a verdict: exit 1 would read as one.
-        process.stderr.write(`dw-sdlc: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`dw-sdlc: ${messageOf(error)}\n`);
         process.exitCode = 2;
     }
 }

package/dist/commands/check.js

@@ -1,7 +1,6 @@
 // `dw-sdlc check <name>`: one Check of the Gate by its name, without the Steps and the other Checks.
-import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig } from "../agentic-config.js";
-import { CannotRun } from "../checks/check.js";
+import { CannotRun, readArgs, rootDir, usageError } from "../cannot-run.js";
 import { CHECK_NAMES, shippedCheck } from "../checks/index.js";
 import { TAIL_LINES } from "../run-command.js";
 import { printReport, runGate } from "./gate.js";
@@ -23,49 +22,45 @@ skill-sections writes each part of a skill from its README section.
 A Ratchet's baseline is refreshed by dw-sdlc gate --update-baseline, which needs every other Check to
 pass.
 
-Exit 0 when the Check passes, 1 when it fails, 2 when it cannot run: no Check of that name, an
-invalid config layer, a command the shell cannot find or execute, or an input the Check reads
-missing.`;
+Exit 0 when the Check passes, 1 when it fails, 2 when it cannot run: a --root that names no
+directory, no Check of that name, an invalid config layer, a command the shell cannot find or
+execute, or an input the Check reads missing.`;
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: {
-                help: { type: "boolean", short: "h" },
-                json: { type: "boolean" },
-                write: { type: "boolean" },
-                root: { type: "string" }
-            }
-        });
-        if (positionals.length > 1) {
-            return { error: `one Check at a time, not ${positionals.map((name) => JSON.stringify(name)).join(" and ")}` };
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            write: { type: "boolean" },
+            root: { type: "string" }
         }
-        const flags = { help: values.help === true, json: values.json === true, write: values.write === true };
-        return { ...flags, root: values.root, name: positionals[0] };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
+    }, USAGE);
+    if (positionals.length > 1) {
+        const names = positionals.map((name) => JSON.stringify(name)).join(" and ");
+        throw usageError(`one Check at a time, not ${names}`, USAGE);
     }
+    const flags = { help: values.help === true, json: values.json === true, write: values.write === true };
+    return { ...flags, root: values.root, name: positionals[0] };
 }
 /**
  * Writes what the shipped Check `name` derives, on the setting the config gives it, and prints what it
- * wrote; why it cannot when it takes no --write. An invalid config or a missing input writes nothing,
- * and the run after it reports why.
+ * wrote; stops the command when it takes no --write. An invalid config or a missing input writes
+ * nothing, and the run after it reports why.
  */
 function writeDerived(root, name, json) {
     const { config, problems } = resolveConfig(root);
     if (problems.length > 0) {
-        return undefined;
+        return;
     }
-    const shipped = shippedCheck(name, config.gate.checks[name]);
+    const shipped = shippedCheck(name, config.gate);
     if (shipped === undefined && !config.gate.checks.run.some((check) => check.name === name)) {
         // No Check of that name: the run after it says so, with the names there are.
-        return undefined;
+        return;
     }
     const write = shipped?.write;
     if (write === undefined) {
-        return `${JSON.stringify(name)} takes no --write: it derives no file`;
+        throw new CannotRun(`${JSON.stringify(name)} takes no --write: it derives no file`);
     }
     try {
         const out = json ? process.stderr : process.stdout;
@@ -76,30 +71,20 @@ function writeDerived(root, name, json) {
             throw error;
         }
     }
-    return undefined;
 }
 export async function run(argv) {
     const cli = parseCli(argv);
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc check: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
     if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
     if (cli.name === undefined) {
-        process.stderr.write(`dw-sdlc check: name the Check to run\n\n${USAGE}\n`);
-        return 2;
+        throw usageError("name the Check to run", USAGE);
     }
     const { json, name } = cli;
-    const root = repositoryRoot(cli.root ?? process.cwd());
+    const root = repositoryRoot(rootDir(cli.root));
     if (cli.write) {
-        const refused = writeDerived(root, name, json);
-        if (refused !== undefined) {
-            process.stderr.write(`dw-sdlc check: ${refused}\n`);
-            return 2;
-        }
+        writeDerived(root, name, json);
     }
     const report = await runGate(root, { json, only: name });
     return printReport(report, json, `check ${name}`);

package/dist/commands/config.js

@@ -1,37 +1,31 @@
 // `dw-sdlc config`, the config check: resolves a repository's agentic config, or validates one file
 // against the schema, and prints what the guards see.
 import { readFileSync } from "node:fs";
-import { parseArgs } from "node:util";
-import { COMMITTED_FILE, findRepository, LOCAL_FILE, repositoryRoot, resolveConfig, validateDocument } from "../agentic-config.js";
+import { COMMITTED_FILE, findRepository, invalidLayerEffect, LOCAL_FILE, repositoryRoot, resolveConfig, validateDocument } from "../agentic-config.js";
+import { messageOf, readArgs, rootDir, usageError } from "../cannot-run.js";
 export const summary = "resolve the repository's agentic config, or validate one file against the schema";
 const USAGE = `Usage: dw-sdlc config [--root <dir>] [file]
   or:  pnpm agentic:check [--root <dir>] [file], in a checkout of dw-sdlc
 
 Without a file: resolves the agentic config of the repository holding --root (default: the current
 directory) — local over committed over inferred — and prints what the guards see. With a file:
-validates that one document against the schema. Exit 1 on any problem.`;
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function fail(message, code) {
-    console.error(`agentic:check: ${message}`);
-    process.exit(code);
+validates that one document against the schema. Exit 1 on any problem, 2 when --root names no
+directory.`;
+/** A problem the check reports beside the config's own: exit 1, as for an invalid layer. */
+function failed(message) {
+    console.error(`dw-sdlc config: ${message}`);
+    return 1;
 }
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: { help: { type: "boolean", short: "h" }, root: { type: "string" } }
-        });
-        if (positionals.length > 1) {
-            throw new Error("at most one file");
-        }
-        return { help: values.help === true, root: values.root, file: positionals[0] };
-    }
-    catch (error) {
-        fail(`${messageOf(error)}\n\n${USAGE}`, 2);
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { help: { type: "boolean", short: "h" }, root: { type: "string" } }
+    }, USAGE);
+    if (positionals.length > 1) {
+        throw usageError("at most one file", USAGE);
     }
+    return { help: values.help === true, root: values.root, file: positionals[0] };
 }
 function report(problems) {
     for (const { file, path, message } of problems) {
@@ -50,7 +44,7 @@ export function run(argv) {
             text = readFileSync(cli.file, "utf8");
         }
         catch (error) {
-            fail(messageOf(error), 1);
+            return failed(messageOf(error));
         }
         const result = validateDocument(cli.file, text);
         if ("problems" in result) {
@@ -60,9 +54,10 @@ export function run(argv) {
         console.log(`${cli.file}: valid`);
         return 0;
     }
-    const root = cli.root === undefined
-        ? (findRepository(process.cwd()) ?? fail("not inside a git repository; pass --root <dir>", 1))
-        : repositoryRoot(cli.root);
+    const root = cli.root === undefined ? findRepository(process.cwd()) : repositoryRoot(rootDir(cli.root));
+    if (root === undefined) {
+        return failed("not inside a git repository; pass --root <dir>");
+    }
     const { config, problems, layers, sources } = resolveConfig(root);
     const from = (source) => source === undefined || source === root ? "" : `, from ${source}`;
     console.log(`committed  ${COMMITTED_FILE}  ${layers.committed}${from(sources.committed)}`);
@@ -70,7 +65,7 @@ export function run(argv) {
     console.log(JSON.stringify(config, null, 2));
     if (problems.length > 0) {
         report(problems);
-        fail(`${problems.length} problem(s) above; the guards run on the strictest defaults until the file is fixed`, 1);
+        return failed(`${problems.length} problem(s) above; ${invalidLayerEffect(config)} until the file is fixed`);
     }
     return 0;
 }

package/dist/commands/doctor.d.ts

@@ -20,6 +20,8 @@ export type RepositoryConfig = {
     config: {
         commit: {
             convention?: string;
+            pattern?: string;
+            trailer?: string;
         };
     };
     problems: string[];

package/dist/commands/doctor.js

@@ -4,10 +4,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parseArgs } from "node:util";
-import { findRepository, resolveConfig } from "../agentic-config.js";
+import { findRepository, invalidLayerEffect, resolveConfig } from "../agentic-config.js";
+import { readArgs, rootDir } from "../cannot-run.js";
 import { checkPackage, checkPlugin, checkSessions, parseJson, runningPluginRoot, sessionsEnabled, versionBefore } from "../doctor-plugins.js";
-import { exec, TimedOut } from "../exec.js";
+import { exec, firstLine, TimedOut } from "../exec.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) {
@@ -39,7 +39,7 @@ export const realProbe = {
     shell(script) {
         const shell = process.env.SHELL ?? "/bin/sh";
         const result = probed(shell, ["-l", "-c", script]);
-        return (result?.stdout ?? "").trim().split("\n")[0] ?? "";
+        return firstLine(result?.stdout ?? "") ?? "";
     }
 };
 function checkJq(probe) {
@@ -213,7 +213,7 @@ function checkConfig(config, root) {
         return {
             name: "config",
             level: "FAIL",
-            detail: `the guards run on the strictest defaults: ${config.problems.join("; ")}`
+            detail: `${invalidLayerEffect(config.config)}: ${config.problems.join("; ")}`
         };
     }
     // A worktree that lacks a layer reads the main checkout's; say so, since the file is not here.
@@ -250,7 +250,7 @@ const USAGE = `Usage: dw-sdlc doctor [--root <dir>] [--home <dir>]
   or:  pnpm guardrails:doctor [--root <dir>] [--home <dir>], in a checkout of dw-sdlc
 
 One PASS / WARN / FAIL line per machine check the sdlc plugin relies on; read-only. Exit 1 when any
-check fails. Claude Code's settings are read from $CLAUDE_CONFIG_DIR, or ~/.claude without it; a
+check fails, 2 when --root names no directory. Claude Code's settings are read from $CLAUDE_CONFIG_DIR, or ~/.claude without it; a
 --home reads <home>/.claude.`;
 function repositoryConfig(root) {
     const resolution = resolveConfig(root);
@@ -261,22 +261,15 @@ function repositoryConfig(root) {
     };
 }
 export function run(argv) {
-    let values;
-    try {
-        values = parseArgs({
-            args: argv,
-            options: { help: { type: "boolean", short: "h" }, root: { type: "string" }, home: { type: "string" } }
-        }).values;
-    }
-    catch (error) {
-        console.error(`guardrails:doctor: ${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
-        return 2;
-    }
+    const { values } = readArgs({
+        args: argv,
+        options: { help: { type: "boolean", short: "h" }, root: { type: "string" }, home: { type: "string" } }
+    }, USAGE);
     if (values.help === true) {
         console.log(USAGE);
         return 0;
     }
-    const dir = values.root ?? process.cwd();
+    const dir = rootDir(values.root);
     const root = findRepository(dir);
     const checks = diagnose({
         root: root ?? dir,