dw-sdlc 0.16.1 → 0.17.0

package/README.md

@@ -35,6 +35,10 @@ lines, exit codes and document.
 }
 ```
 
+A Step is a command string, or `{ "command": "…", "hint": "…" }`; a `gate.checks.run` entry takes a
+`hint` beside `name` and `command`. When the Step or script fails, the Gate prints `hint: <text>` under
+its failure line, and `--json` carries `hint` on every Step and Check, `null` where there is none.
+
 ```json
 { "scripts": { "check": "dw-sdlc gate" } }
 ```
@@ -42,6 +46,9 @@ lines, exit codes and document.
 Under `gate.checks`, a Check the package ships is `true` for its defaults or an object of its options.
 `comment-budget` holds each comment block in the JavaScript, TypeScript and shell (`.sh`) files under
 its `roots` to `maxProseLines` lines of prose, 3 by default.
+`disable-directives` fails every Disable directive in a comment that gives no reason: `oxlint-disable*`,
+`eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `rubocop:disable` and `noqa`. A reason follows `--`
+on the directive's line, follows an `@ts-` directive, or is a comment on the line above.
 
 ## The Ship script
 

package/config/agentic.config.schema.json

@@ -42,6 +42,11 @@
           "description": "`deny` refuses a `git commit`, `merge`, `cherry-pick` or `revert` on a branch listed in `protectedBranches`, so every change starts on a branch of its own. `allow` lets it through, for a repository that commits small fixes on its protected branch and pushes them from a person's terminal. Default `allow`. Strictest first: deny, allow.",
           "enum": ["deny", "allow"]
         },
+        "filteredOutput": {
+          "description": "`deny` refuses a check command whose output a pipe feeds to `head`, `tail`, `grep`, `egrep`, `fgrep`, `rg`, `sed`, `awk`, `less` or `more`: the pipe hides the failure and, with `pipefail` off, the exit code. A check command is the `gate.command`, a Step, a `gate.checks.run` command, `dw-sdlc gate`, `dw-sdlc check`, or a common runner such as `vitest`, `tsc` or `rspec`. `tee` and a redirect pass. `allow` turns the guard off, for a repository whose workflow pipes check output. Default `deny`.",
+          "enum": ["deny", "allow"],
+          "default": "deny"
+        },
         "envFiles": {
           "description": "Which env files (`.env`, `.env.*`, `.envrc`) an agent may read, edit or write. A candidate is judged in this order: listed in `deny` → refused; listed in `allow` → readable; `policy` `deny` → refused; `policy` `git` → readable when git tracks it, refused when git ignores it or does not know it. Entries are globs against the path relative to the repository root: `*` and `?` as in a shell pattern (`*` crosses `/`), a leading `**/` means at any depth, so `.env` is the one in the root and `**/.env.example` every file of that name. No brace groups. A path outside the repository root, or outside any repository, is judged by its basename against the `**/` entries alone. Defaults: policy `git`, allow the `.env.example`, `.env.sample` and `.env.template` names anywhere, deny nothing. The local override may drop `allow` entries and add `deny` entries, never the reverse.",
           "type": "object",
@@ -114,11 +119,25 @@
           "minLength": 1
         },
         "steps": {
-          "description": "The Steps: toolchain commands run in order from the repository root through `sh -c`; the first that does not pass ends the Gate and no Check runs. Each one's output is captured, and its last 50 lines are printed when it does not pass; `--verbose` passes the output through instead. A command the shell cannot find (exit 127) or execute (126) means the Gate cannot run.",
+          "description": "The Steps: toolchain commands run in order from the repository root through `sh -c`; the first that does not pass ends the Gate and no Check runs. A Step is a command string, or an object with its `command` and a `hint`. Each one's output is captured, and its last 50 lines are printed when it does not pass, with the `hint` under them; `--verbose` passes the output through instead. A command the shell cannot find (exit 127) or execute (126) means the Gate cannot run.",
           "type": "array",
           "items": {
-            "type": "string",
-            "minLength": 1
+            "type": ["string", "object"],
+            "minLength": 1,
+            "properties": {
+              "command": {
+                "description": "The command the Step runs.",
+                "type": "string",
+                "minLength": 1
+              },
+              "hint": {
+                "description": "What to try when the Step fails: one line the Gate prints as `hint: <text>` under the failure. A passing Step prints nothing.",
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": ["command"],
+            "additionalProperties": false
           }
         },
         "drift": {
@@ -144,6 +163,11 @@
                   "command": {
                     "type": "string",
                     "minLength": 1
+                  },
+                  "hint": {
+                    "description": "What to try when the script fails: one line the Gate prints as `hint: <text>` under the failure. A passing script prints nothing.",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "required": ["name", "command"],
@@ -379,6 +403,31 @@
                 }
               },
               "additionalProperties": false
+            },
+            "disable-directives": {
+              "description": "Every Disable directive in a comment gives a reason: `oxlint-disable*` and `eslint-disable*` in every form, `@ts-expect-error` and `@ts-ignore` in JavaScript and TypeScript, `rubocop:disable` in Ruby and `noqa` in Python. A reason is text after `--` on the directive's line; for `@ts-expect-error` and `@ts-ignore`, text after the directive, with or without `:`; or a comment on the line directly above. A directive inside a string or a template is none, and a rule set to `off` in a lint config is not judged. A hard fail, with no Ratchet; the Gate runs it, never a session hook.",
+              "type": ["boolean", "object"],
+              "properties": {
+                "files": {
+                  "description": "Globs of the files to read, against the files git tracks or would track; `*` and `**` skip a name that starts with a dot. Default every JavaScript, TypeScript, Ruby (`.rb`, `.rake`, `.gemspec`, `.ru`, `Rakefile`, `Gemfile`) and Python file.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                },
+                "exempt": {
+                  "description": "Globs of the files left out. Default `references/**`, `**/vendor/**` and `**/node_modules/**`; a list replaces the default.",
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "uniqueItems": true
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false

package/dist/agentic-config.d.ts

@@ -54,11 +54,21 @@ export type Guardrails = {
 export type GuardrailsLayer = Partial<Omit<Guardrails, "envFiles">> & {
     envFiles?: Partial<EnvFiles>;
 };
-/** A repository's own script under `gate.checks.run`, reported as a Check under `name`. */
+/** A repository's own script under `gate.checks.run`, reported as a Check under `name`; `hint` is what to try when it fails. */
 export type RunCheck = {
     name: string;
     command: string;
+    hint?: string;
 };
+/** A Step of `gate.steps`: its command, or the command with a `hint` on what to try when it fails. */
+export type Step = string | {
+    command: string;
+    hint?: string;
+};
+/** The command a Step runs. */
+export declare function stepCommand(step: Step): string;
+/** The Hint a Step carries, null where it has none. */
+export declare function stepHint(step: Step): string | null;
 /**
  * `run`, and under each other key a Check the package ships, as the schema takes it: `true`, `false` or
  * its options. `src/checks/` reads the setting of each.
@@ -72,14 +82,14 @@ export type DriftSetting = "fail" | "allow";
 /** The Gate: its command, the steps run in order, whether they may write the tree, the Checks run after them. */
 export type Gate = {
     command?: string;
-    steps: string[];
+    steps: Step[];
     drift: DriftSetting;
     checks: GateChecks;
 };
 /** `gate` as one layer writes it: every key optional, `checks` Check by Check. */
 export type GateLayer = {
     command?: string;
-    steps?: string[];
+    steps?: Step[];
     drift?: DriftSetting;
     checks?: Partial<GateChecks>;
 };

package/dist/agentic-config.js

@@ -15,6 +15,14 @@ export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
 export const REVIEW_DEPTHS = ["full", "light", "off"];
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
 export const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+/** The command a Step runs. */
+export function stepCommand(step) {
+    return typeof step === "string" ? step : step.command;
+}
+/** The Hint a Step carries, null where it has none. */
+export function stepHint(step) {
+    return typeof step === "string" ? null : (step.hint ?? null);
+}
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],

package/dist/checks/comment-budget.js

@@ -2,262 +2,11 @@
 // of `//` or shell `#` lines alone on theirs, carries at most `maxProseLines` lines with a letter or a digit.
 import { readFileSync } from "node:fs";
 import { join, matchesGlob } from "node:path";
+import { commentsOf, shellCommentsOf } from "./comments.js";
 import { matching, treeFiles } from "./tree.js";
 const SOURCE = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"];
 const SHELL = "**/*.sh";
 const REMEDY = "cut it to what the code cannot say, or move the reasoning into a doc and point at it";
-/** The characters after which a `/` opens a regular expression, not a division. */
-const BEFORE_REGEX = new Set("(,=:[!&|?{};+-*%<>~^");
-const KEYWORD_BEFORE_REGEX = /(^|[^\w$])(return|typeof|instanceof|in|of|new|delete|void|throw|case|do|else|yield|await)$/;
-/** Where the regular expression whose `/` is at `start` ends, or undefined when the line ends first. */
-function regexEnd(text, start) {
-    let inClass = false;
-    for (let index = start + 1; index < text.length; index += 1) {
-        const char = text[index];
-        if (char === "\\") {
-            index += 1;
-        }
-        else if (char === "\n") {
-            return undefined;
-        }
-        else if (char === "[" || char === "]") {
-            inClass = char === "[";
-        }
-        else if (char === "/" && !inClass) {
-            return index + 1;
-        }
-    }
-    return undefined;
-}
-/** Whether the `/` at `index` opens a regular expression: the code before it ends where a value starts. */
-function opensRegex(text, index) {
-    const before = text.slice(0, index).trimEnd();
-    const last = before.at(-1);
-    return last === undefined || BEFORE_REGEX.has(last) || KEYWORD_BEFORE_REGEX.test(before);
-}
-/** Every comment in JavaScript or TypeScript `text`, skipping strings, template literals and regular expressions. */
-function commentsOf(text) {
-    const comments = [];
-    // The open quotes, and a `{` for each brace opened inside a template literal's `${…}`.
-    const stack = [];
-    let line = 1;
-    let index = 0;
-    while (index < text.length) {
-        const char = text[index];
-        const next = text[index + 1];
-        const top = stack.at(-1);
-        if (top === "'" || top === '"' || top === "`") {
-            if (char === "\\") {
-                line += next === "\n" ? 1 : 0;
-                index += 2;
-                continue;
-            }
-            if (top === "`" && char === "$" && next === "{") {
-                stack.push("{");
-                index += 2;
-                continue;
-            }
-            if (char === top) {
-                stack.pop();
-            }
-            line += char === "\n" ? 1 : 0;
-            index += 1;
-            continue;
-        }
-        if (char === "'" || char === '"' || char === "`" || (char === "{" && top === "{")) {
-            stack.push(char);
-        }
-        else if (char === "}" && top === "{") {
-            stack.pop();
-        }
-        else if (char === "/" && next === "/") {
-            const stop = text.indexOf("\n", index) === -1 ? text.length : text.indexOf("\n", index);
-            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
-            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, stop) });
-            index = stop;
-            continue;
-        }
-        else if (char === "/" && next === "*") {
-            const close = text.indexOf("*/", index + 2);
-            const body = text.slice(index, close === -1 ? text.length : close + 2);
-            const start = line;
-            line += body.split("\n").length - 1;
-            comments.push({ kind: "block", start, end: line, text: body });
-            index += body.length;
-            continue;
-        }
-        else if (char === "/" && opensRegex(text, index)) {
-            index = regexEnd(text, index) ?? index + 1;
-            continue;
-        }
-        line += char === "\n" ? 1 : 0;
-        index += 1;
-    }
-    return comments;
-}
-/** The characters that end a shell word, so a `#` after one opens a comment. */
-const WORD_BREAK = new Set(" \t\n;&|()<>");
-/** Where the line that holds `index` ends: at its newline, or at the end of `text`. */
-function lineEnd(text, index) {
-    const newline = text.indexOf("\n", index);
-    return newline === -1 ? text.length : newline;
-}
-/** Where a span that `closer` ends, read from `start`, stops, past the closer; `\` escapes a character when `escapes`. */
-function spanEnd(text, start, closer, escapes) {
-    for (let index = start; index < text.length; index += 1) {
-        if (escapes && text.charAt(index) === "\\") {
-            index += 1;
-        }
-        else if (text.charAt(index) === closer) {
-            return index + 1;
-        }
-    }
-    return text.length;
-}
-/** The heredoc whose `<<` is at `start`, its delimiter's quotes off, and where the delimiter's word ends. */
-function heredocAt(text, start) {
-    const strip = text.charAt(start + 2) === "-";
-    let index = start + (strip ? 3 : 2);
-    while (text.charAt(index) === " " || text.charAt(index) === "\t") {
-        index += 1;
-    }
-    let end = index;
-    while (end < text.length && !WORD_BREAK.has(text.charAt(end))) {
-        const char = text.charAt(end);
-        end = char === "'" || char === '"' ? spanEnd(text, end + 1, char, false) : end + (char === "\\" ? 2 : 1);
-    }
-    return { delimiter: text.slice(index, end).replace(/["'\\]/g, ""), strip, end };
-}
-/** Where the heredoc body that starts at `start` ends: past the line that is its delimiter. */
-function heredocEnd(text, start, { delimiter, strip }) {
-    for (let index = start; index < text.length;) {
-        const end = lineEnd(text, index);
-        const line = text.slice(index, end);
-        index = end + 1;
-        if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) {
-            return index;
-        }
-    }
-    return text.length;
-}
-/** The character that opens a nesting inside each frame and the one that closes it; a double quote has none. */
-const NESTING = {
-    code: ["(", ")"],
-    arithmetic: ["(", ")"],
-    expansion: ["{", "}"],
-    double: []
-};
-/**
- * Every `#` comment in shell `text`: a `#` that starts a word of code, never one in a quote, an
- * expansion, an arithmetic `((…))` or a heredoc body, nor the shebang on line 1.
- */
-function shellCommentsOf(text) {
-    const comments = [];
-    const newlines = [...text.matchAll(/\n/g)].map((match) => match.index);
-    const outer = [];
-    let frame = { kind: "code", depth: 0 };
-    const heredocs = [];
-    let wordStart = true;
-    let index = text.startsWith("#!") ? lineEnd(text, 0) : 0;
-    const open = (kind, length) => {
-        outer.push(frame);
-        frame = { kind, depth: 0 };
-        index += length;
-        wordStart = true;
-    };
-    const close = (length) => {
-        frame = outer.pop() ?? frame;
-        index += length;
-        wordStart = false;
-    };
-    const skipTo = (end) => {
-        index = end;
-        wordStart = false;
-    };
-    while (index < text.length) {
-        const char = text.charAt(index);
-        const next = text.charAt(index + 1);
-        const { kind } = frame;
-        const [opener, closer] = NESTING[kind];
-        if (char === "\\" && next === "\n") {
-            index += 2;
-        }
-        else if (char === "\\") {
-            skipTo(index + 2);
-        }
-        else if (kind === "double" && char === '"') {
-            close(1);
-        }
-        else if (char === "$" && text.startsWith("((", index + 1)) {
-            open("arithmetic", 3);
-        }
-        else if (char === "$" && next === "(") {
-            open("code", 2);
-        }
-        else if (char === "$" && next === "{") {
-            open("expansion", 2);
-        }
-        else if (char === "`") {
-            skipTo(spanEnd(text, index + 1, "`", true));
-        }
-        else if (kind === "double") {
-            index += 1;
-        }
-        else if (char === "$" && next === "'") {
-            skipTo(spanEnd(text, index + 2, "'", true));
-        }
-        else if (char === "'") {
-            skipTo(spanEnd(text, index + 1, "'", false));
-        }
-        else if (char === '"') {
-            open("double", 1);
-        }
-        else if (kind === "code" && char === "#" && wordStart) {
-            const end = lineEnd(text, index);
-            const line = newlines.filter((newline) => newline < index).length + 1;
-            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
-            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, end) });
-            index = end;
-        }
-        else if (kind === "code" && char === "\n") {
-            index += 1;
-            for (const heredoc of heredocs.splice(0)) {
-                index = heredocEnd(text, index, heredoc);
-            }
-            wordStart = true;
-        }
-        else if (kind === "code" && text.startsWith("<<<", index)) {
-            index += 3;
-            wordStart = true;
-        }
-        else if (kind === "code" && text.startsWith("<<", index)) {
-            const { end, ...heredoc } = heredocAt(text, index);
-            heredocs.push(heredoc);
-            skipTo(end);
-        }
-        else if (kind === "code" && text.startsWith("((", index)) {
-            open("arithmetic", 2);
-        }
-        else if (char === opener) {
-            frame.depth += 1;
-            index += 1;
-            wordStart = true;
-        }
-        else if (char === closer && frame.depth > 0) {
-            frame.depth -= 1;
-            index += 1;
-            wordStart = true;
-        }
-        else if (char === closer && outer.length > 0) {
-            close(kind === "arithmetic" && next === ")" ? 2 : 1);
-        }
-        else {
-            wordStart = WORD_BREAK.has(char);
-            index += 1;
-        }
-    }
-    return comments;
-}
 /** The comments as blocks: a run of `//` or `#` lines alone on consecutive lines is one; a comment after code is none. */
 function blocksOf(comments) {
     const blocks = [];

package/dist/checks/comments.d.ts

@@ -0,0 +1,29 @@
+/** A `//` or `#` comment alone on its line, one after code, or a block comment, by its lines and text. */
+export type Comment = {
+    kind: "line" | "trailing" | "block";
+    start: number;
+    end: number;
+    text: string;
+};
+/** Every comment in JavaScript or TypeScript `text`, skipping strings, template literals and regular expressions. */
+export declare function commentsOf(text: string): Comment[];
+/** Where the line that holds `index` ends: at its newline, or at the end of `text`. */
+export declare function lineEnd(text: string, index: number): number;
+/** Where a span that `closer` ends, read from `start`, stops, past the closer; `\` escapes a character when `escapes`. */
+export declare function spanEnd(text: string, start: number, closer: string, escapes: boolean): number;
+/** A heredoc whose body starts on the next line: its delimiter, and whether `<<-` strips the body's leading tabs. */
+export type Heredoc = {
+    delimiter: string;
+    strip: boolean;
+};
+/** The heredoc whose `<<` is at `start`, its delimiter's quotes off, and where the delimiter's word ends. */
+export declare function heredocAt(text: string, start: number): Heredoc & {
+    end: number;
+};
+/** Where the heredoc body that starts at `start` ends: past the line that is its delimiter. */
+export declare function heredocEnd(text: string, start: number, { delimiter, strip }: Heredoc): number;
+/**
+ * Every `#` comment in shell `text`: a `#` that starts a word of code, never one in a quote, an
+ * expansion, an arithmetic `((…))` or a heredoc body, nor the shebang on line 1.
+ */
+export declare function shellCommentsOf(text: string): Comment[];

package/dist/checks/comments.js

@@ -0,0 +1,255 @@
+// The comments of a source file: every comment in JavaScript, TypeScript or shell `text` with its lines,
+// its text and whether it stands alone on its line, never one inside a string, a template literal, a
+// regular expression, an expansion or a heredoc. `comment-budget` and `disable-directives` read them.
+/** The characters after which a `/` opens a regular expression, not a division. */
+const BEFORE_REGEX = new Set("(,=:[!&|?{};+-*%<>~^");
+const KEYWORD_BEFORE_REGEX = /(^|[^\w$])(return|typeof|instanceof|in|of|new|delete|void|throw|case|do|else|yield|await)$/;
+/** Where the regular expression whose `/` is at `start` ends, or undefined when the line ends first. */
+function regexEnd(text, start) {
+    let inClass = false;
+    for (let index = start + 1; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === "\\") {
+            index += 1;
+        }
+        else if (char === "\n") {
+            return undefined;
+        }
+        else if (char === "[" || char === "]") {
+            inClass = char === "[";
+        }
+        else if (char === "/" && !inClass) {
+            return index + 1;
+        }
+    }
+    return undefined;
+}
+/** Whether the `/` at `index` opens a regular expression: the code before it ends where a value starts. */
+function opensRegex(text, index) {
+    const before = text.slice(0, index).trimEnd();
+    const last = before.at(-1);
+    return last === undefined || BEFORE_REGEX.has(last) || KEYWORD_BEFORE_REGEX.test(before);
+}
+/** Every comment in JavaScript or TypeScript `text`, skipping strings, template literals and regular expressions. */
+export function commentsOf(text) {
+    const comments = [];
+    // The open quotes, and a `{` for each brace opened inside a template literal's `${…}`.
+    const stack = [];
+    let line = 1;
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        const next = text[index + 1];
+        const top = stack.at(-1);
+        if (top === "'" || top === '"' || top === "`") {
+            if (char === "\\") {
+                line += next === "\n" ? 1 : 0;
+                index += 2;
+                continue;
+            }
+            if (top === "`" && char === "$" && next === "{") {
+                stack.push("{");
+                index += 2;
+                continue;
+            }
+            if (char === top) {
+                stack.pop();
+            }
+            line += char === "\n" ? 1 : 0;
+            index += 1;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`" || (char === "{" && top === "{")) {
+            stack.push(char);
+        }
+        else if (char === "}" && top === "{") {
+            stack.pop();
+        }
+        else if (char === "/" && next === "/") {
+            const stop = text.indexOf("\n", index) === -1 ? text.length : text.indexOf("\n", index);
+            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
+            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, stop) });
+            index = stop;
+            continue;
+        }
+        else if (char === "/" && next === "*") {
+            const close = text.indexOf("*/", index + 2);
+            const body = text.slice(index, close === -1 ? text.length : close + 2);
+            const start = line;
+            line += body.split("\n").length - 1;
+            comments.push({ kind: "block", start, end: line, text: body });
+            index += body.length;
+            continue;
+        }
+        else if (char === "/" && opensRegex(text, index)) {
+            index = regexEnd(text, index) ?? index + 1;
+            continue;
+        }
+        line += char === "\n" ? 1 : 0;
+        index += 1;
+    }
+    return comments;
+}
+/** The characters that end a shell word, so a `#` after one opens a comment. */
+const WORD_BREAK = new Set(" \t\n;&|()<>");
+/** Where the line that holds `index` ends: at its newline, or at the end of `text`. */
+export function lineEnd(text, index) {
+    const newline = text.indexOf("\n", index);
+    return newline === -1 ? text.length : newline;
+}
+/** Where a span that `closer` ends, read from `start`, stops, past the closer; `\` escapes a character when `escapes`. */
+export function spanEnd(text, start, closer, escapes) {
+    for (let index = start; index < text.length; index += 1) {
+        if (escapes && text.charAt(index) === "\\") {
+            index += 1;
+        }
+        else if (text.charAt(index) === closer) {
+            return index + 1;
+        }
+    }
+    return text.length;
+}
+/** The heredoc whose `<<` is at `start`, its delimiter's quotes off, and where the delimiter's word ends. */
+export function heredocAt(text, start) {
+    const strip = text.charAt(start + 2) === "-";
+    let index = start + (strip ? 3 : 2);
+    while (text.charAt(index) === " " || text.charAt(index) === "\t") {
+        index += 1;
+    }
+    let end = index;
+    while (end < text.length && !WORD_BREAK.has(text.charAt(end))) {
+        const char = text.charAt(end);
+        end = char === "'" || char === '"' ? spanEnd(text, end + 1, char, false) : end + (char === "\\" ? 2 : 1);
+    }
+    return { delimiter: text.slice(index, end).replace(/["'\\]/g, ""), strip, end };
+}
+/** Where the heredoc body that starts at `start` ends: past the line that is its delimiter. */
+export function heredocEnd(text, start, { delimiter, strip }) {
+    for (let index = start; index < text.length;) {
+        const end = lineEnd(text, index);
+        const line = text.slice(index, end);
+        index = end + 1;
+        if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) {
+            return index;
+        }
+    }
+    return text.length;
+}
+/** The character that opens a nesting inside each frame and the one that closes it; a double quote has none. */
+const NESTING = {
+    code: ["(", ")"],
+    arithmetic: ["(", ")"],
+    expansion: ["{", "}"],
+    double: []
+};
+/**
+ * Every `#` comment in shell `text`: a `#` that starts a word of code, never one in a quote, an
+ * expansion, an arithmetic `((…))` or a heredoc body, nor the shebang on line 1.
+ */
+export function shellCommentsOf(text) {
+    const comments = [];
+    const newlines = [...text.matchAll(/\n/g)].map((match) => match.index);
+    const outer = [];
+    let frame = { kind: "code", depth: 0 };
+    const heredocs = [];
+    let wordStart = true;
+    let index = text.startsWith("#!") ? lineEnd(text, 0) : 0;
+    const open = (kind, length) => {
+        outer.push(frame);
+        frame = { kind, depth: 0 };
+        index += length;
+        wordStart = true;
+    };
+    const close = (length) => {
+        frame = outer.pop() ?? frame;
+        index += length;
+        wordStart = false;
+    };
+    const skipTo = (end) => {
+        index = end;
+        wordStart = false;
+    };
+    while (index < text.length) {
+        const char = text.charAt(index);
+        const next = text.charAt(index + 1);
+        const { kind } = frame;
+        const [opener, closer] = NESTING[kind];
+        if (char === "\\" && next === "\n") {
+            index += 2;
+        }
+        else if (char === "\\") {
+            skipTo(index + 2);
+        }
+        else if (kind === "double" && char === '"') {
+            close(1);
+        }
+        else if (char === "$" && text.startsWith("((", index + 1)) {
+            open("arithmetic", 3);
+        }
+        else if (char === "$" && next === "(") {
+            open("code", 2);
+        }
+        else if (char === "$" && next === "{") {
+            open("expansion", 2);
+        }
+        else if (char === "`") {
+            skipTo(spanEnd(text, index + 1, "`", true));
+        }
+        else if (kind === "double") {
+            index += 1;
+        }
+        else if (char === "$" && next === "'") {
+            skipTo(spanEnd(text, index + 2, "'", true));
+        }
+        else if (char === "'") {
+            skipTo(spanEnd(text, index + 1, "'", false));
+        }
+        else if (char === '"') {
+            open("double", 1);
+        }
+        else if (kind === "code" && char === "#" && wordStart) {
+            const end = lineEnd(text, index);
+            const line = newlines.filter((newline) => newline < index).length + 1;
+            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
+            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, end) });
+            index = end;
+        }
+        else if (kind === "code" && char === "\n") {
+            index += 1;
+            for (const heredoc of heredocs.splice(0)) {
+                index = heredocEnd(text, index, heredoc);
+            }
+            wordStart = true;
+        }
+        else if (kind === "code" && text.startsWith("<<<", index)) {
+            index += 3;
+            wordStart = true;
+        }
+        else if (kind === "code" && text.startsWith("<<", index)) {
+            const { end, ...heredoc } = heredocAt(text, index);
+            heredocs.push(heredoc);
+            skipTo(end);
+        }
+        else if (kind === "code" && text.startsWith("((", index)) {
+            open("arithmetic", 2);
+        }
+        else if (char === opener) {
+            frame.depth += 1;
+            index += 1;
+            wordStart = true;
+        }
+        else if (char === closer && frame.depth > 0) {
+            frame.depth -= 1;
+            index += 1;
+            wordStart = true;
+        }
+        else if (char === closer && outer.length > 0) {
+            close(kind === "arithmetic" && next === ")" ? 2 : 1);
+        }
+        else {
+            wordStart = WORD_BREAK.has(char);
+            index += 1;
+        }
+    }
+    return comments;
+}

package/dist/checks/disable-directives.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from "./check.ts";
+export type DisableDirectivesOptions = {
+    files: string[];
+    exempt: string[];
+};
+export declare const disableDirectives: Check<DisableDirectivesOptions>;

package/dist/checks/disable-directives.js

@@ -0,0 +1,91 @@
+// `disable-directives`: a lint rule or a type check switched off says why. A Disable directive in a comment
+// fails unless a reason follows `--` on its line, follows an `@ts-` directive or is a comment above it.
+// The language of a file picks the comments read and the directives looked for.
+import { readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { commentsOf } from "./comments.js";
+import { hashCommentsOf } from "./hash-comments.js";
+import { matching, treeFiles } from "./tree.js";
+const REMEDY = "add one after `--` on its line, or in a comment on the line above";
+const SCRIPT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+const RUBY_EXTENSIONS = [".rb", ".rake", ".gemspec", ".ru"];
+const RUBY_NAMES = ["Rakefile", "Gemfile"];
+const PYTHON_EXTENSIONS = [".py", ".pyi"];
+function languageOf(file) {
+    const extension = extname(file);
+    if (SCRIPT_EXTENSIONS.includes(extension)) {
+        return "script";
+    }
+    if (RUBY_EXTENSIONS.includes(extension) || RUBY_NAMES.includes(basename(file))) {
+        return "ruby";
+    }
+    return PYTHON_EXTENSIONS.includes(extension) ? "python" : undefined;
+}
+/**
+ * The pattern that finds a directive at the start of a comment's line, its name in group 1. A Python
+ * `noqa` may follow other words of its comment, after a `#` of its own: `# type: ignore  # noqa`.
+ */
+const DIRECTIVES = {
+    script: /^((?:oxlint|eslint)-disable(?:-next-line|-line)?|@ts-expect-error|@ts-ignore)(?![\w-])/,
+    ruby: /^(rubocop:disable)(?![\w-])/,
+    python: /(?:^|#\s*)(noqa)(?![\w-])/i
+};
+/** The reason `--` gives: text after it, set off from what comes before by space. */
+const DASH_REASON = /(?:^|\s)--+\s*\S/;
+/** A comment's lines, each as text starting after its markers and indent, with the line it sits on. */
+function linesOf({ start, text }, language) {
+    return text.split("\n").map((raw, offset) => {
+        const body = language === "script" ? raw.replace(/^\s*(?:\/\/+|\/\*+|\*+(?!\/))?\s*/, "") : raw.replace(/^\s*#+\s*/, "");
+        return { line: start + offset, text: body.replace(/\s*\*\/\s*$/, "").trimEnd() };
+    });
+}
+/** Whether `rest`, the text of a directive's line after its name, gives a reason. */
+function givesReason(directive, rest) {
+    if (directive.startsWith("@ts-")) {
+        return /[^\s-]/.test(rest.replace(/^\s*:/, ""));
+    }
+    return DASH_REASON.test(rest);
+}
+/** The directive that starts a line of a comment, and the text after it, or undefined. */
+function directiveIn(text, language) {
+    const match = DIRECTIVES[language].exec(text);
+    return match === null ? undefined : { directive: match[1] ?? "", rest: text.slice(match.index + match[0].length) };
+}
+function run(root, { files, exempt }) {
+    const findings = [];
+    for (const file of matching(root, treeFiles(root), files, exempt)) {
+        const language = languageOf(file);
+        if (language === undefined) {
+            continue;
+        }
+        const text = readFileSync(join(root, file), "utf8");
+        const comments = language === "script" ? commentsOf(text) : hashCommentsOf(text, language);
+        const found = comments.flatMap((comment) => linesOf(comment, language).flatMap(({ line, text: body }) => {
+            const directive = directiveIn(body, language);
+            return directive === undefined ? [] : [{ line, ...directive }];
+        }));
+        const directiveLines = new Set(found.map(({ line }) => line));
+        // The line above a directive gives a reason when a comment alone on its line ends on it and no directive does.
+        const commentEnds = new Set(comments.filter(({ kind }) => kind !== "trailing").map(({ end }) => end));
+        for (const { line, directive, rest } of found) {
+            const above = commentEnds.has(line - 1) && !directiveLines.has(line - 1);
+            if (!givesReason(directive, rest) && !above) {
+                findings.push({ file, line, directive, message: `${directive} gives no reason`, remedy: REMEDY });
+            }
+        }
+    }
+    return findings;
+}
+export const disableDirectives = {
+    name: "disable-directives",
+    defaults: {
+        files: [
+            "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+            "**/*.{rb,rake,gemspec,ru}",
+            "**/{Rakefile,Gemfile}",
+            "**/*.{py,pyi}"
+        ],
+        exempt: ["references/**", "**/vendor/**", "**/node_modules/**"]
+    },
+    run
+};

package/dist/checks/hash-comments.d.ts

@@ -0,0 +1,4 @@
+import type { Comment } from "./comments.ts";
+export type HashLanguage = "ruby" | "python";
+/** Every `#` comment in Ruby or Python `text`, skipping strings, Ruby heredocs, `=begin` blocks and Python triple quotes. */
+export declare function hashCommentsOf(text: string, language: HashLanguage): Comment[];

package/dist/checks/hash-comments.js

@@ -0,0 +1,121 @@
+// The `#` comments of a Ruby or Python file: every `#` that is not inside a string, as the comments of
+// `comments.ts` are, so a directive in a string literal or a heredoc is none.
+const HEREDOC = /^<<([~-]?)(["'`]?)([A-Za-z_]\w*)\2/;
+/** The heredoc that opens at `index`, or undefined: a bare `<<NAME` counts only in capitals, as `list <<NAME` is an append. */
+function heredocAt(text, index) {
+    const match = HEREDOC.exec(text.slice(index, index + 80));
+    if (match === null || (match[1] === "" && !/^[A-Z_]/.test(match[3] ?? ""))) {
+        return undefined;
+    }
+    return { terminator: match[3] ?? "", indented: match[1] !== "", length: match[0].length };
+}
+/** Where a heredoc body that starts at `start` ends: past the line that is its terminator. */
+function heredocEnd(text, start, { terminator, indented }) {
+    for (let index = start; index < text.length;) {
+        const stop = text.indexOf("\n", index);
+        const end = stop === -1 ? text.length : stop;
+        const line = text.slice(index, end);
+        index = end + 1;
+        if ((indented ? line.trim() : line) === terminator) {
+            return Math.min(index, text.length);
+        }
+    }
+    return text.length;
+}
+/** Where the block that runs from `index` to the next line that starts with `until` ends; the end of `text` if none. */
+function blockEnd(text, index, until) {
+    const stop = text.indexOf(`\n${until}`, index);
+    if (stop === -1) {
+        return text.length;
+    }
+    const end = text.indexOf("\n", stop + 1);
+    return end === -1 ? text.length : end;
+}
+/** Every `#` comment in Ruby or Python `text`, skipping strings, Ruby heredocs, `=begin` blocks and Python triple quotes. */
+export function hashCommentsOf(text, language) {
+    const comments = [];
+    // The open quotes, a triple quote as its three characters, and a `{` for each brace opened in a Ruby `#{…}`.
+    const stack = [];
+    const heredocs = [];
+    let line = 1;
+    let index = 0;
+    const skipTo = (end) => {
+        line += text.slice(index, end).split("\n").length - 1;
+        index = end;
+    };
+    if (language === "ruby" && text.startsWith("=begin")) {
+        skipTo(blockEnd(text, 0, "=end"));
+    }
+    while (index < text.length) {
+        const char = text.charAt(index);
+        const next = text.charAt(index + 1);
+        const top = stack.at(-1);
+        if (top !== undefined && top !== "{") {
+            if (char === "\\") {
+                skipTo(Math.min(index + 2, text.length));
+            }
+            else if (language === "ruby" && char === "#" && next === "{" && top !== "'") {
+                stack.push("{");
+                index += 2;
+            }
+            else if (text.startsWith(top, index)) {
+                stack.pop();
+                index += top.length;
+            }
+            else {
+                line += char === "\n" ? 1 : 0;
+                index += 1;
+            }
+        }
+        else if (char === "'" || char === '"' || (language === "ruby" && char === "`")) {
+            const triple = language === "python" && text.startsWith(char.repeat(3), index);
+            stack.push(triple ? char.repeat(3) : char);
+            index += triple ? 3 : 1;
+        }
+        else if (char === "{" && top === "{") {
+            stack.push("{");
+            index += 1;
+        }
+        else if (char === "}" && top === "{") {
+            stack.pop();
+            index += 1;
+        }
+        else if (char === "#" && language === "ruby" && next === "{") {
+            index += 1;
+        }
+        else if (char === "#") {
+            const stop = text.indexOf("\n", index);
+            const end = stop === -1 ? text.length : stop;
+            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
+            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, end) });
+            index = end;
+        }
+        else if (char === "\n") {
+            line += 1;
+            index += 1;
+            for (const heredoc of heredocs.splice(0)) {
+                skipTo(heredocEnd(text, index, heredoc));
+            }
+            if (language === "ruby" && text.startsWith("=begin", index)) {
+                skipTo(blockEnd(text, index, "=end"));
+            }
+            else if (language === "ruby" && text.startsWith("__END__", index)) {
+                skipTo(text.length);
+            }
+        }
+        else if (language === "ruby" && char === "<" && next === "<") {
+            const heredoc = heredocAt(text, index);
+            if (heredoc === undefined) {
+                index += 2;
+            }
+            else {
+                heredocs.push(heredoc);
+                index += heredoc.length;
+            }
+        }
+        else {
+            index += 1;
+        }
+    }
+    return comments;
+}

package/dist/checks/index.js

@@ -4,6 +4,7 @@ import { agentsMap } from "./agents-map.js";
 import { optionsOf } from "./check.js";
 import { commentBudget } from "./comment-budget.js";
 import { decisionRecords } from "./decision-records.js";
+import { disableDirectives } from "./disable-directives.js";
 import { fileSizeRatchet } from "./file-size-ratchet.js";
 import { markdownBudget } from "./markdown-budget.js";
 import { markdownRefs } from "./markdown-refs.js";
@@ -36,7 +37,8 @@ const SHIPPED = [
     ship(temporalLanguage),
     ship(decisionRecords),
     ship(fileSizeRatchet),
-    ship(commentBudget)
+    ship(commentBudget),
+    ship(disableDirectives)
 ];
 /** The name of every Check the package ships, in the order the Gate runs them. */
 export const CHECK_NAMES = SHIPPED.map(({ name }) => name);

package/dist/commands/gate.d.ts

@@ -6,13 +6,16 @@ type Outcome = {
     exitCode: number | null;
     tail: string[] | null;
 };
+/** `hint` is what the Step carries to try when it fails, null where it has none. */
 type StepReport = Outcome & {
     command: string;
+    hint: string | null;
 };
-/** A Check the package ships runs in this process: it has no command. */
+/** A Check the package ships runs in this process: it has no command and no hint. */
 type CheckReport = Outcome & {
     name: string;
     command: string | null;
+    hint: string | null;
 };
 type GateReport = {
     status: Status;

package/dist/commands/gate.js

@@ -1,12 +1,12 @@
 // `dw-sdlc gate`: the Gate of a repository, from the `gate` key of its resolved agentic config. The
 // run and the report serve `dw-sdlc check` too, which judges one Check of it.
 import { parseArgs } from "node:util";
-import { repositoryRoot, resolveConfig } from "../agentic-config.js";
+import { repositoryRoot, resolveConfig, stepCommand, stepHint } from "../agentic-config.js";
 import { CannotRun } from "../checks/check.js";
 import { CHECK_NAMES, enabledChecks, shippedCheck } from "../checks/index.js";
 import { watchDrift } from "../drift.js";
 import { fingerprint, isGreen, stampGreen } from "../gate-cache.js";
-import { annotation, failureJson, failureLine } from "../report.js";
+import { annotation, failureJson, failureLine, hintLines } from "../report.js";
 import { holdingSignals, runCommand, stoppedBy, TAIL_LINES } from "../run-command.js";
 export const summary = "run the Gate: the Steps of gate.steps in order, then every Check under gate.checks";
 const USAGE = `Usage: dw-sdlc gate [--json] [--verbose] [--root <dir>] [--update-baseline | --cache]
@@ -21,6 +21,9 @@ Actions it is also a workflow annotation. A Step or run script prints nothing of
 does not pass: then its last ${TAIL_LINES} lines, both streams in the order written, under its own
 line. In a terminal a Step's line shows when it starts and takes its result when it ends.
 
+A Step written as { "command", "hint" }, and a run script with a hint, prints "hint: <text>" under its
+failure line when it does not pass; a passing one prints nothing more.
+
 Each Step runs between two records of every file git tracks or would track: a file the Step created,
 changed or deleted is Drift, one failure per file, and the Steps after it still run. Ignored files
 and edits made before the run never drift, and a Step a signal stopped is not compared. gate.drift
@@ -33,7 +36,7 @@ second signal, or one sent while the Checks the package ships run, ends the Gate
 
 --verbose passes each command's output through as it runs instead, under a line naming the command,
 and keeps no tail. --json prints the document alone; each Step and Check in it carries tail, the last
-${TAIL_LINES} lines of a command that did not pass, null otherwise. With --verbose, under --json, the
+${TAIL_LINES} lines of a command that did not pass, null otherwise, and hint, null where there is none. With --verbose, under --json, the
 commands' output goes to stderr and every tail is null.
 
 --update-baseline then rewrites the baseline of each Ratchet, only when every Step and every other
@@ -268,7 +271,7 @@ export async function runGate(root, options) {
     const failures = [];
     const watch = watchDrift(root, config.gate);
     /** Runs one Step or Check, prints its progress and records its failure under `rule`, if it has one. */
-    const runOne = async (kind, subject, command) => {
+    const runOne = async (kind, subject, command, hint) => {
         progress.start(kind, subject);
         const ran = await runCommand(command, root, output);
         progress.end(kind, subject, ran);
@@ -277,7 +280,8 @@ export async function runGate(root, options) {
             failures.push({
                 rule: kind === "step" ? "step" : subject,
                 message: `${JSON.stringify(command)} ${ran.detail}`,
-                remedy
+                remedy,
+                ...(hint === null ? {} : { hint })
             });
         }
         return { status: ran.status, exitCode: ran.exitCode, tail: ran.tail };
@@ -289,15 +293,19 @@ export async function runGate(root, options) {
         const halted = () => failedStep || stoppedBy() !== undefined;
         const steps = [];
         for (const step of selected.steps) {
-            const watched = halted() ? undefined : await watch.step(step, () => runOne("step", step, step));
+            const command = stepCommand(step);
+            const hint = stepHint(step);
+            const watched = halted() ? undefined : await watch.step(command, () => runOne("step", command, command, hint));
             failures.push(...(watched?.failures ?? []));
             const outcome = watched?.result ?? SKIPPED;
-            steps.push({ command: step, ...outcome });
+            steps.push({ command, hint, ...outcome });
             failedStep ||= outcome.status !== "pass";
         }
         const checks = [];
         for (const check of selected.run) {
-            checks.push({ ...check, ...(halted() ? SKIPPED : await runOne("check", check.name, check.command)) });
+            const hint = check.hint ?? null;
+            const outcome = halted() ? SKIPPED : await runOne("check", check.name, check.command, hint);
+            checks.push({ name: check.name, command: check.command, hint, ...outcome });
         }
         return { steps, checks, halted: halted() };
     });
@@ -323,7 +331,7 @@ export async function runGate(root, options) {
             progress.end("check", check.name, outcome);
         }
         failures.push(...found);
-        checks.push({ name: check.name, command: null, ...outcome });
+        checks.push({ name: check.name, command: null, hint: null, ...outcome });
     }
     for (const note of notes) {
         log.write(`${note}\n`);
@@ -361,7 +369,11 @@ export function printReport(report, json, label) {
         }
     }
     else {
-        const lines = report.failures.flatMap((failure) => actions ? [failureLine(failure), annotation(failure)] : [failureLine(failure)]);
+        const lines = report.failures.flatMap((failure) => [
+            failureLine(failure),
+            ...(actions ? [annotation(failure)] : []),
+            ...hintLines(failure)
+        ]);
         process.stdout.write(`${[...lines, verdict(label, report)].join("\n")}\n`);
     }
     return EXIT_CODES[report.status];

package/dist/report.d.ts

@@ -4,10 +4,16 @@ export type Failure = {
     rule: string;
     message: string;
     remedy: string;
+    /** What the repository owner wrote to try, printed as `hint: <text>` under the failure line. */
+    hint?: string;
+    /** The Disable directive a `disable-directives` failure names, as written. */
+    directive?: string;
 };
+/** `hint: <text>` where the failure carries a Hint, nothing otherwise. */
+export declare function hintLines({ hint }: Failure): string[];
 /** `file:line: rule: message — remedy`, without the location where the failure has none. */
 export declare function failureLine({ file, line, rule, message, remedy }: Failure): string;
 /** `::error file=…,line=…,title=<rule>::<message> — <remedy>`, an annotation on the file where there is one. */
 export declare function annotation({ file, line, rule, message, remedy }: Failure): string;
-/** The failure as JSON: every key present, null where it has no file or line. */
-export declare function failureJson({ file, line, rule, message, remedy }: Failure): Record<string, unknown>;
+/** The failure as JSON: every key present, null where it has no file or line, and `directive` where it names one. */
+export declare function failureJson({ file, line, rule, message, remedy, directive }: Failure): Record<string, unknown>;

package/dist/report.js

@@ -1,6 +1,10 @@
 // A failure of the Gate as every consumer reads it: one line naming the file and line where there is
 // one, the rule, what is wrong and the remedy; the same as a GitHub Actions workflow annotation; the
 // same as JSON.
+/** `hint: <text>` where the failure carries a Hint, nothing otherwise. */
+export function hintLines({ hint }) {
+    return hint === undefined ? [] : [`hint: ${hint}`];
+}
 /** `file:line: rule: message — remedy`, without the location where the failure has none. */
 export function failureLine({ file, line, rule, message, remedy }) {
     const where = file === undefined ? "" : `${file}${line === undefined ? "" : `:${line}`}: `;
@@ -23,7 +27,8 @@ export function annotation({ file, line, rule, message, remedy }) {
     ];
     return `::error ${properties.join(",")}::${escapeData(`${message} — ${remedy}`)}`;
 }
-/** The failure as JSON: every key present, null where it has no file or line. */
-export function failureJson({ file, line, rule, message, remedy }) {
-    return { file: file ?? null, line: line ?? null, rule, message, remedy };
+/** The failure as JSON: every key present, null where it has no file or line, and `directive` where it names one. */
+export function failureJson({ file, line, rule, message, remedy, directive }) {
+    const json = { file: file ?? null, line: line ?? null, rule, message, remedy };
+    return directive === undefined ? json : { ...json, directive };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "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": {