@dougharness/cli 1.0.2 → 1.1.1

package/node_modules/@dougharness/gates/lib/baseline.mjs

@@ -5,7 +5,7 @@
 // SessionStart script (its earlier capture, when the platform fires it).
 
 import { execFileSync } from "node:child_process";
-import { readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync, mkdirSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, resolve, sep } from "node:path";
 import { matchAny } from "./glob.mjs";
@@ -158,3 +158,168 @@ export function captureBaseline(dir, paths) {
 export function sinceBaseline(dir, paths, baseline) {
   return paths.filter((p) => !(p in baseline) || fileIdentity(join(dir, p)) !== baseline[p]);
 }
+
+// The verified-tree fingerprint (card stop-gate-process-storm, goal 2): the HEAD sha plus the content
+// identity of every dirty path and every proposal-path file on disk, at the moment it is computed. Null
+// when `changed` is not the array shape changedFiles returns (no git, or git unavailable) — there is
+// nothing to fingerprint reliably, so the tree can never be judged "unchanged" on this path.
+export function treeFingerprint(dir, cfg, changed) {
+  if (!Array.isArray(changed)) return null;
+  const walked = walkProposalPathFiles(dir, cfg.proposalPaths);
+  const paths = [...new Set([...changed, ...walked])];
+  // `at` (state.mjs's comment for state.verified) is when this fingerprint was taken; sameTree below never
+  // reads it, so recomputing it on the after-wait path (a fresh Date.now()) never affects equality.
+  return { head: headAt(dir), tree: captureBaseline(dir, paths), at: Date.now() };
+}
+
+// Whether two treeFingerprint results describe the same tree: both present, the same HEAD, the same set of
+// paths, and an identical identity for each. Never throws (a hook reader must never throw): a malformed
+// fingerprint — e.g. a hand-edited state.verified — just compares unequal rather than blocking the gate.
+export function sameTree(a, b) {
+  try {
+    if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
+    if (a.head !== b.head) return false;
+    const at = a.tree && typeof a.tree === "object" ? a.tree : null;
+    const bt = b.tree && typeof b.tree === "object" ? b.tree : null;
+    if (!at || !bt) return false;
+    const ak = Object.keys(at).sort();
+    const bk = Object.keys(bt).sort();
+    if (ak.length !== bk.length) return false;
+    for (let i = 0; i < ak.length; i++) if (ak[i] !== bk[i]) return false;
+    return ak.every((k) => at[k] === bt[k]);
+  } catch {
+    return false;
+  }
+}
+
+// card stop-gate-no-test-paths: whether every path changed since the last green verification (`verified`, a
+// treeFingerprint recorded in state.verified) is on preCommit.noTestPaths, read with the pre-commit hook's
+// exact rule (.githooks/pre-commit): an entry matches a path when equal, or, ending in "/", when the path
+// starts with it. Not a glob. "Changed since" is the union of the paths committed since verified.head that are
+// absent from verified.tree or whose current identity differs from the recorded one (a path committed with the
+// verified content is not a change), every path dirty now (read with --no-renames, both sides of a rename) that is absent from verified.tree or whose identity moved, and every verified.tree path
+// whose identity moved (reverted or committed with other content). Fails closed: false when there is no
+// verified fingerprint, its head is unknown to git, git is unavailable, the union is empty, the list is
+// missing, empty, or holds a non-string or empty entry, or any path is off the list. Never throws.
+export function onlyNoTestPathsChanged(dir, cfg, verified, changed) {
+  try {
+    const list = cfg && cfg.preCommit && cfg.preCommit.noTestPaths;
+    if (!Array.isArray(list) || list.length === 0 || !list.every((e) => typeof e === "string" && e !== "")) return false;
+    const moved = movedSinceVerified(dir, verified, changed);
+    if (!moved || moved.size === 0) return false;
+    const hit = (p) => list.some((e) => (e.endsWith("/") ? p.startsWith(e) : p === e));
+    return [...moved].every(hit);
+  } catch {
+    return false;
+  }
+}
+
+// The "changed since the last green" set onlyNoTestPathsChanged judges (card gate-docs-skip-unless-named factors
+// it out so the docs rule reads the same set): a Set of paths, or null when there is no usable verified
+// fingerprint, `changed` is not an array, its head is unknown to git, or anything throws. Never throws.
+export function movedSinceVerified(dir, verified, changed) {
+  try {
+    if (!verified || typeof verified !== "object" || !verified.tree || typeof verified.tree !== "object" || Array.isArray(verified.tree)) return null;
+    if (!Array.isArray(changed)) return null;
+    const committed = committedSince(dir, verified.head);
+    if (!Array.isArray(committed)) return null;
+    const moved = new Set();
+    for (const p of committed) {
+      if (!(p in verified.tree) || fileIdentity(join(dir, p)) !== verified.tree[p]) moved.add(p);
+    }
+    // changedFiles collapses a rename `old -> new` to `new`, hiding a path moved out of a source location, so
+    // the dirty set is collected here with --no-renames (both sides), exactly as pre-commit does.
+    const git = (args) =>
+      execFileSync("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 })
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .filter((p) => !p.startsWith(".claude/worktrees/") && !p.startsWith(".doug/.state/") && p !== ".doug/anchor.md");
+    const dirty = [...git(["diff", "--name-only", "--no-renames", "HEAD", "--"]), ...git(["ls-files", "--others", "--exclude-standard"])];
+    for (const p of new Set([...dirty, ...Object.keys(verified.tree)])) {
+      if (!(p in verified.tree) || fileIdentity(join(dir, p)) !== verified.tree[p]) moved.add(p);
+    }
+    return moved;
+  } catch {
+    return null;
+  }
+}
+
+// card gate-skip-readonly-researchers: the start fingerprint of a subagent, written by the trace hook on
+// SubagentStart and read by the stop gate. One small JSON file per agent under .doug/.state/agent-start/<session>/.
+// Ids are reduced to [A-Za-z0-9_-] so one can never escape the directory. Both functions never throw: a failed
+// write means no record, an unreadable record reads as null (the gate then runs as before).
+function agentStartFile(dir, sessionId, agentId) {
+  const clean = (v) => String(v ?? "").replace(/[^A-Za-z0-9_-]/g, "_") || "_";
+  return join(dir, ".doug/.state/agent-start", clean(sessionId), `${clean(agentId)}.json`);
+}
+
+export function writeAgentStart(dir, cfg, sessionId, agentId) {
+  try {
+    const fp = treeFingerprint(dir, cfg, changedFiles(dir));
+    if (!fp) return;
+    const file = agentStartFile(dir, sessionId, agentId);
+    mkdirSync(join(file, ".."), { recursive: true });
+    writeFileSync(file, JSON.stringify(fp));
+  } catch {
+    // no record
+  }
+}
+
+export function readAgentStart(dir, sessionId, agentId) {
+  try {
+    return JSON.parse(readFileSync(agentStartFile(dir, sessionId, agentId), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// card stop-gate-runs-only-on-code-turns: the turn-start fingerprint, written by scripts/turn-start.mjs on
+// UserPromptSubmit and read by the main Stop gate. One small JSON file per session under
+// .doug/.state/turn-start/<session>.json, same id sanitising as agentStartFile. Both functions never throw: a
+// failed write means no record, an unreadable record reads as null (the gate then verifies as before).
+function turnStartFile(dir, sessionId) {
+  const clean = String(sessionId ?? "").replace(/[^A-Za-z0-9_-]/g, "_") || "_";
+  return join(dir, ".doug/.state/turn-start", `${clean}.json`);
+}
+
+export function writeTurnStart(dir, cfg, sessionId) {
+  try {
+    const fp = treeFingerprint(dir, cfg, changedFiles(dir));
+    if (!fp) return;
+    const file = turnStartFile(dir, sessionId);
+    mkdirSync(join(file, ".."), { recursive: true });
+    writeFileSync(file, JSON.stringify(fp));
+  } catch {
+    // no record
+  }
+}
+
+export function readTurnStart(dir, sessionId) {
+  try {
+    return JSON.parse(readFileSync(turnStartFile(dir, sessionId), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Whether the tree still matches a turn-start record once every path on preCommit.noTestPaths is dropped from
+// both (the pre-commit hook's rule: equal, or a prefix when the entry ends in "/"). Returns null when it cannot
+// tell (no or malformed record, no current fingerprint, any throw) so the caller verifies; otherwise
+// { same, exact, dirty }: `exact` = equal with nothing dropped; `same` = same HEAD, same code paths, same identities; `dirty` = the current tree still holds
+// code paths. Never throws.
+export function turnTreeStatus(cfg, start, current) {
+  try {
+    if (!start || !current || typeof start !== "object" || typeof current !== "object") return null;
+    if (!start.tree || typeof start.tree !== "object" || Array.isArray(start.tree)) return null;
+    if (!current.tree || typeof current.tree !== "object" || Array.isArray(current.tree)) return null;
+    const list = cfg && cfg.preCommit && Array.isArray(cfg.preCommit.noTestPaths) ? cfg.preCommit.noTestPaths.filter((e) => typeof e === "string" && e !== "") : [];
+    const skip = (p) => list.some((e) => (e.endsWith("/") ? p.startsWith(e) : p === e));
+    const strip = (fp) => ({ head: fp.head, tree: Object.fromEntries(Object.entries(fp.tree).filter(([p]) => !skip(p))) });
+    const a = strip(start);
+    const b = strip(current);
+    return { same: sameTree(a, b), exact: sameTree(start, current), dirty: Object.keys(b.tree).length > 0 };
+  } catch {
+    return null;
+  }
+}

package/node_modules/@dougharness/gates/lib/bash-rules.mjs

@@ -726,8 +726,8 @@ function skipPrefixOptions(w, i, argFlags, onArgFlag) {
 // exactly as before. For the separate-token form the value is already its own token, so this returns { next }
 // pointing at it and lets matchesShellWords's loop continue from there. For an attached form (whose value can't
 // be pulled back out as its own token) there is no token to point { next } at, so this returns { splice: value,
-// next } instead: the caller replaces everything up to `next` with the single token `value` and resumes its own
-// loop at index 0 - a rebuild, not a recursive call, so nested attached values (env -Senv -Senv ... sh) cost no
+// next } instead: the caller overwrites the attached token's slot (next - 1) with the single token `value` and resumes its own
+// loop at that slot - a linear overwrite, not a recursive call, so nested attached values (env -Senv -Senv ... sh) cost no
 // call-stack depth no matter how many there are. Otherwise (the value is missing, empty, or itself option-
 // shaped) it isn't the command, so env keeps parsing options from there: for the separate-token form the walk
 // re-examines that same value token as the next option (advancing by 1, not 2, past just the flag), and for an
@@ -892,10 +892,13 @@ function redirWordSpan(tok) {
 // Walks a stage's already-split words from index i, resolving prefixes (env assignments, sudo, env, nice,
 // time, nohup, exec, command, busybox) until it lands on the candidate verb. Split out of matchesShellStage so
 // scanEnvOptions can hand an -S/--split-string value back into this same walk when that value qualifies as
-// env's command. That handoff is a rebuild of `w`, not a recursive call (see the "splice" case below): every
-// handoff replaces one or more consumed tokens with the single value token, so `w` strictly shrinks by at least
-// one token each time, and the loop below runs no deeper than one stack frame no matter how many wrappers are
-// nested (env -Senv -Senv ... sh).
+// env's command. That handoff is an in-place overwrite of one slot of a single copy of `w`, not a recursive call (see the "splice" case below): every
+// handoff replaces one or more consumed tokens with the single value token, so the walk's unread tail strictly
+// shrinks by at least one token each time, and the loop below runs no deeper than one stack frame no matter how
+// many wrappers are nested (env -Senv -Senv ... sh). The handoff is linear (card bash-rules-env-splice-quadratic):
+// the value overwrites the attached token's slot in a single copy of `w` and the walk resumes there, instead of
+// rebuilding the array per handoff (quadratic: 25 s at 80000 nestings). No token cap is applied: a cap would deny
+// commands that are allowed today, and the linear walk removes the timeout risk that a cap would guard.
 // Card bash-rules-prefixed-commands: also shared with commandForms, which needs the resolved word array and
 // verb index (not just a shell/not-shell verdict), so the walk itself no longer decides an outcome - it returns
 // { w, i } once it lands on a candidate verb (i may be w.length when nothing followed the prefixes), or
@@ -920,7 +923,7 @@ function redirWordSpan(tok) {
 //     still reads the RAW token, unchanged - a quoted FLAG is out of this card's scope, and dequoting it too
 //     would risk changing which flag a cluster or an attached form is read as, for no fixture that needs it.
 //     The returned `{w, i}` itself is unaffected by this: `w` is still the array the caller passed in (or
-//     resolveVerb's own env-splice rebuild, unrelated to this round), and `i` is just an index into it - the
+//     resolveVerb's own single copy after an env splice, unrelated to this round), and `i` is just an index into it - the
 //     caller (isShellVerb by way of commandForms/matchesShellWords) dequotes `w[i]` itself before comparing it
 //     against a shell name, the same way this loop now does for a prefix name.
 //
@@ -936,6 +939,7 @@ function redirWordSpan(tok) {
 // ...) reads the prefix/verb token's text again - everything after it operates on the RAW words that follow,
 // unaffected by which reading recognised the name in front of them.
 function resolveVerb(w, i) {
+  const original = w;
   while (i < w.length) {
     const tok = w[i];
     const span = redirWordSpan(tok);
@@ -970,11 +974,14 @@ function resolveVerb(w, i) {
     if (isBase("env")) {
       const result = scanEnvOptions(w, i + 1);
       if ("splice" in result) {
-        // An attached -S/--split-string value qualified as env's command: rebuild the word array with that
-        // value as the new first word, followed by whatever came after it, and resume this same loop at 0 -
-        // no recursive call, so this is safe no matter how many attached values are nested.
-        w = [result.splice, ...w.slice(result.next)];
-        i = 0;
+        // An attached -S/--split-string value qualified as env's command: the value becomes the walk's next word.
+        // It overwrites the slot of the attached token just before result.next (copying w once, on the first
+        // splice, so the caller's array is never mutated) and the walk resumes AT that slot - the same words,
+        // from the same start, the old rebuilt array [value, ...rest] held at its index 0. Each handoff consumes at
+        // least one token and costs O(1), so n nested values cost O(n), and no recursion either.
+        if (w === original) w = original.slice();
+        i = result.next - 1;
+        w[i] = result.splice;
         continue;
       }
       i = result.next; // separate-token -S/--split-string value, or no qualifying value: continue the walk
@@ -1335,8 +1342,8 @@ function dequoteScript(word, reading = "bash") {
 // behind a resolvable prefix (sudo, an env assignment, env, nice, time, nohup, exec, command, busybox) or a
 // shell's -c string. Always includes cmd itself. When resolveVerb's walk consumed or rebuilt anything - i > 0
 // (an ordinary prefix was skipped) or the returned word array isn't the one passed in (an attached env
-// -S/--split-string value spliced in a new array and reset i to 0 on it, so i > 0 alone missed a denied command
-// sitting right behind it, e.g. env -Sgit reset --hard) - also includes the resolved word array from the verb
+// -S/--split-string value was spliced into a single copy of the array, overwriting the attached token's slot;
+// the walk resumes there, so i stays >= 1 after a splice) - also includes the resolved word array from the verb
 // onward. When that verb's basename is a shell, findScriptCandidates (above) locates 0, 1, or 2 candidate -c
 // script words; each candidate is dequoted (dequoteScript) - the ONLY word this function dequotes - twice, once
 // per shell reading (review round 3: bash and zsh decode an unrecognised ANSI-C escape differently, see

package/node_modules/@dougharness/gates/lib/block-ledger.mjs

@@ -18,6 +18,60 @@ function stripLeadingDotSlash(f) {
   return typeof f === "string" && f.startsWith("./") ? f.slice(2) : f;
 }
 
+const TEST_FILE_RE = /\.(?:test|spec)\.[A-Za-z]+$/;
+
+// Every path a tsc error line names (card stop-gate-tsc-red-claim): a path token immediately followed by
+// `(<line>,<col>): error TS<digits>` anywhere on the line, so a `pnpm -r` prefix does not hide it. Same
+// normalisation as failingTestFilesFrom (leading "./", then `dir + "/"`). Never throws: reads as none.
+export function tscErrorPaths(output, dir) {
+  try {
+    const paths = new Set();
+    const MARK = "): error TS";
+    const isDigit = (c) => c >= "0" && c <= "9";
+    const isStop = (c) => /[\s"'`()]/.test(c);
+    for (const line of String(output || "").split("\n")) {
+      // Cheap pre-filter, and no backtracking regex: every step below is a linear walk from a marker.
+      let at = line.indexOf(MARK);
+      while (at !== -1) {
+        const after = at + MARK.length;
+        let i = at - 1;
+        const colEnd = i;
+        while (i >= 0 && isDigit(line[i])) i--;
+        let ok = i < colEnd && line[i] === "," ;
+        if (ok) {
+          i--;
+          const lineEnd = i;
+          while (i >= 0 && isDigit(line[i])) i--;
+          ok = i < lineEnd && line[i] === "(";
+        }
+        if (ok && isDigit(line[after] || "")) {
+          const pathEnd = i;
+          let j = pathEnd;
+          while (j > 0 && !isStop(line[j - 1])) j--;
+          if (j < pathEnd) {
+            let f = stripLeadingDotSlash(line.slice(j, pathEnd));
+            if (typeof dir === "string" && dir && f.startsWith(dir + "/")) f = f.slice(dir.length + 1);
+            paths.add(f);
+          }
+        }
+        at = line.indexOf(MARK, at + 1);
+      }
+    }
+    return [...paths];
+  } catch {
+    return [];
+  }
+}
+
+// The tsc error paths in `output` that are not test files; one of these means the failure is not red by design.
+export function nonTestTscPathsFrom(output, dir) {
+  try {
+    return tscErrorPaths(output, dir).filter((f) => !TEST_FILE_RE.test(f));
+  } catch {
+    return [];
+  }
+}
+
 // Test files a failed verification command's output names: every path token ending in ".test.<ext>" or
 // ".spec.<ext>" (ext = letters) on a line containing "FAIL" or "failed", deduplicated, normalised to a
 // repository-relative path when absolute under `dir`. Moved here from stop-gate.mjs (card
@@ -28,6 +82,7 @@ export function failingTestFilesFrom(output, dir) {
   try {
     const files = new Set();
     const tokenRe = /[^\s"'`]+\.(?:test|spec)\.[A-Za-z]+/g;
+    for (const p of tscErrorPaths(output, dir)) if (TEST_FILE_RE.test(p)) files.add(p);
     for (const line of String(output || "").split("\n")) {
       if (!line.includes("FAIL") && !line.includes("failed")) continue;
       for (const m of line.matchAll(tokenRe)) {
@@ -72,13 +127,15 @@ export function classifyFinalBlock({ preVerificationProblems, evidenceProblemAdd
     const namedByCommand = failures.map((cf) => failingTestFilesFrom(cf.output, dir));
     const allNamed = [...new Set(namedByCommand.flat())];
 
+    const nonTestTsc = failures.some((cf) => nonTestTscPathsFrom(cf.output, dir).length > 0);
+
     const onlyFailedCommands =
       preVerificationProblems === 0 &&
       !evidenceProblemAdded &&
       failures.length > 0 &&
       postCommandProblems - preVerificationProblems === failures.length;
     const everyCommandNamedAFile = failures.length > 0 && namedByCommand.every((files) => files.length > 0);
-    if (onlyFailedCommands && everyCommandNamedAFile && Array.isArray(redByDesignClaimFiles) && redByDesignClaimFiles.length > 0) {
+    if (onlyFailedCommands && !nonTestTsc && everyCommandNamedAFile && Array.isArray(redByDesignClaimFiles) && redByDesignClaimFiles.length > 0) {
       const claimSet = new Set(redByDesignClaimFiles);
       if (allNamed.every((f) => claimSet.has(f))) return "expected-red";
     }

package/node_modules/@dougharness/gates/lib/checkpoint.mjs

@@ -43,7 +43,7 @@ export function refName(at = new Date()) {
 
 export function commitMessage(cfg, gateResults) {
   const head = (cfg.checkpoint && cfg.checkpoint.message) || DEFAULT_MESSAGE;
-  const gate = (gateResults || []).map((r) => `${r.name} ${r.ok ? "ok" : "failed"}`).join(", ");
+  const gate = (gateResults || []).map((r) => `${r.name}${r.targeted ? ` (targeted: ${r.targeted} files)` : ""} ${r.ok ? "ok" : "failed"}`).join(", ");
   return gate ? `${head}\n\ngate: ${gate}` : head;
 }
 

package/node_modules/@dougharness/gates/lib/config.mjs

@@ -83,6 +83,9 @@ export const DEFAULTS = Object.freeze({
   // Per-subagent cap on WebSearch plus WebFetch calls (scripts/research-cap.mjs, card research-fetch-cap): null
   // or 0 turns it off. The main session is never capped.
   research: { maxFetches: 6 },
+  // Card autopilot-unlimited: the context percentage (1..100) at which `/doug-next --auto` ends and hands off; read by
+  // doug-flow's scripts/context.mjs. A value that is not a finite number in that range folds back to 60 (loadConfig).
+  autopilot: { contextThreshold: 60 },
 });
 
 export function projectDir(input) {
@@ -152,6 +155,22 @@ function normaliseArrayShapes(cfg) {
   }
 }
 
+function normaliseAutopilot(cfg) {
+  const a = cfg.autopilot;
+  if (a === null || typeof a !== "object" || Array.isArray(a)) {
+    cfg.autopilot = { ...DEFAULTS.autopilot };
+    return;
+  }
+  const v = a.contextThreshold;
+  if (v === undefined || v === null) {
+    cfg.autopilot = { ...a, contextThreshold: DEFAULTS.autopilot.contextThreshold };
+    return;
+  }
+  if (typeof v === "number" && Number.isFinite(v) && v >= 1 && v <= 100) return;
+  process.stderr.write(`[doug] ${CONFIG_RELPATH} autopilot.contextThreshold must be a number from 1 to 100; using the default\n`);
+  cfg.autopilot = { ...a, contextThreshold: DEFAULTS.autopilot.contextThreshold };
+}
+
 export function loadConfig(dir) {
   const file = join(dir, CONFIG_RELPATH);
   if (!existsSync(file)) return { ...DEFAULTS, _present: false };
@@ -159,6 +178,7 @@ export function loadConfig(dir) {
     const raw = JSON.parse(readFileSync(file, "utf8"));
     const merged = { ...deepMerge(DEFAULTS, raw), _present: true };
     normaliseArrayShapes(merged);
+    normaliseAutopilot(merged);
     return merged;
   } catch (err) {
     // A broken config must never silently disable gates. Fall back to defaults and say so.

package/node_modules/@dougharness/gates/lib/docs-gate.mjs

@@ -0,0 +1,95 @@
+// card gate-docs-skip-unless-named: the docs rule shared by the Stop gate and the pre-commit hook
+// (.githooks/pre-commit). A changed docs/**/*.md file does not by itself run the suite. When every changed path
+// is on preCommit.noTestPaths or is a docs .md (and at least one is a docs .md not on the list), the tracked
+// test files whose text names that doc (its repo-relative path, or its basename, which also covers a
+// join("docs", "decisions", "<basename>") spelling) decide: none -> { kind: "skip" }; some -> { kind:
+// "targeted", files } (repo-relative, sorted). Anything else, or any doubt, returns null: run the full gate.
+// Never throws (a throw would reach runHook, which fails open and would skip the gate).
+// CLI (used by .githooks/pre-commit): staged paths on stdin, the config JSON in DOUG_NO_TEST_CONFIG, cwd =
+// the repo; prints "skip", or "targeted" then one file per line; prints nothing for the full gate.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEST_FILE = /\.test\.(mjs|js|ts|cjs)$/;
+const CODE_FILE = /\.(mjs|js|ts|cjs|sh)$/;
+// Only plainly shell-safe paths are handed to a command line; anything else runs the full gate.
+const SAFE_PATH = /^[A-Za-z0-9_.@+/-]+$/;
+
+export function isDocsMarkdown(p) {
+  return typeof p === "string" && p.startsWith("docs/") && p.endsWith(".md");
+}
+
+function noTestHit(list, p) {
+  return list.some((e) => (e.endsWith("/") ? p.startsWith(e) : p === e));
+}
+
+function validList(cfg) {
+  const list = cfg && cfg.preCommit && cfg.preCommit.noTestPaths;
+  return Array.isArray(list) && list.length > 0 && list.every((e) => typeof e === "string" && e !== "") ? list : null;
+}
+
+// -> sorted test files naming any of `docs`, or null (unreadable tree, or a file that cannot be mapped to test
+// files names a doc).
+function namingTests(dir, docs, tracked) {
+  const needles = [...new Set(docs.flatMap((d) => [d, basename(d)]))];
+  const found = [];
+  for (const f of tracked) {
+    const isTest = TEST_FILE.test(f);
+    const underTests = f.startsWith("tests/") || f.includes("/tests/");
+    const code = CODE_FILE.test(f) && !f.startsWith("docs/");
+    if (!isTest && !underTests && !code) continue;
+    if (f.startsWith("docs/")) continue;
+    const text = readFileSync(join(dir, f), "utf8");
+    if (!needles.some((n) => text.includes(n))) continue;
+    if (!isTest) return null; // a helper or source file reads the doc: cannot be mapped to test files
+    found.push(f);
+  }
+  return found.sort();
+}
+
+// preCommit.docsTests: absent or [] -> []; otherwise the entries, or null when malformed or not a tracked file.
+function docsTestsList(cfg, tracked) {
+  const v = cfg && cfg.preCommit && cfg.preCommit.docsTests;
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || !v.every((e) => typeof e === "string" && e !== "")) return null;
+  const set = new Set(tracked);
+  return v.every((e) => set.has(e)) ? v : null;
+}
+
+// moved: the changed paths (Set or array). Returns { kind: "skip" } | { kind: "targeted", files } | null.
+export function docsGateDecision(dir, cfg, moved) {
+  try {
+    const list = validList(cfg);
+    if (!list) return null;
+    const paths = [...moved];
+    if (paths.length === 0 || !paths.every((p) => typeof p === "string" && p !== "")) return null;
+    const docs = paths.filter((p) => !noTestHit(list, p));
+    if (docs.length === 0 || !docs.every(isDocsMarkdown)) return null;
+    const raw = execFileSync("git", ["ls-files", "-z"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000, maxBuffer: 64 * 1024 * 1024 });
+    const tracked = raw.split("\0").filter(Boolean);
+    const named = namingTests(dir, docs, tracked);
+    const extra = docsTestsList(cfg, tracked);
+    if (!named || !extra) return null;
+    const files = [...new Set([...named, ...extra])].sort();
+    if (files.length === 0) return { kind: "skip" };
+    if (!files.every((f) => SAFE_PATH.test(f))) return null;
+    return { kind: "targeted", files };
+  } catch {
+    return null;
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  try {
+    const cfg = JSON.parse(process.env.DOUG_NO_TEST_CONFIG);
+    const staged = readFileSync(0, "utf8").split("\n").filter((l) => l !== "");
+    const d = docsGateDecision(process.cwd(), cfg, staged);
+    if (d && d.kind === "skip") process.stdout.write("skip\n");
+    else if (d) process.stdout.write(`targeted\n${d.files.join("\n")}\n`);
+  } catch {
+    // no output: the hook runs the full gate
+  }
+}

package/node_modules/@dougharness/gates/lib/evidence.mjs

@@ -20,6 +20,8 @@ export const RUNNER_PATTERNS = [
   /\bgradle\w*\b.*\btest\b/,
   /\bdotnet\s+test\b/,
   /\bmake\s+(test|check)\b/,
+  // card verified-tree-record: the vendored or plugin verify.mjs only; a project's own verify.mjs must not count.
+  /(\.doug\/hooks|doug-gates)\/scripts\/verify\.mjs\b/,
 ];
 
 // The commands the stop gate runs, by name, plus every other configured project command except install.

package/node_modules/@dougharness/gates/lib/gate-lock.mjs

@@ -0,0 +1,94 @@
+// The gate.lock helpers shared by the Stop gate (scripts/stop-gate.mjs) and verify.mjs (card
+// verify-takes-gate-lock). Moved verbatim from stop-gate.mjs; the Stop gate's behaviour is unchanged.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Single-runner lock (card stop-gate-process-storm, goal 3): only one gate runs the verification commands
+// at a time per project, so concurrent SubagentStops share one suite instead of each starting its own (the
+// 2026-09-16 process storm). `.doug/.state/gate.lock` holds `{ pid, session, at }` while a gate's commands
+// run.
+const GATE_LOCK_RELPATH = ".doug/.state/gate.lock";
+export function gateLockPath(dir) {
+  return join(dir, GATE_LOCK_RELPATH);
+}
+
+// Reads gate.lock, tolerating garbage (a hook reader must never throw): a missing file, unreadable file, or
+// content that fails to parse or carries no numeric pid all read as null — the same as "no lock", which the
+// caller treats exactly like a stale one.
+export function readGateLock(dir) {
+  try {
+    const o = JSON.parse(readFileSync(gateLockPath(dir), "utf8"));
+    // A pid only counts when it is a positive integer (reviewer-found gap): 0 means "this process's own
+    // group" and -1 broadcasts to every process the caller may signal, so process.kill(pid, 0) does not
+    // throw for either and a liveness check that hands them straight to it reads a garbage lock as live.
+    return o && typeof o === "object" && Number.isInteger(o.pid) && o.pid > 0 ? o : null;
+  } catch {
+    return null;
+  }
+}
+
+export function pidIsLive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the pid exists but is owned by another user (permission denied, not "no such process") —
+    // that holder is still alive, just not signallable by us. Every other error (ESRCH: no such process, or
+    // anything else) reads as dead.
+    return err && err.code === "EPERM";
+  }
+}
+
+// Creates gate.lock exclusively (throws EEXIST when one is already there, or any other fs error). The
+// caller decides what a failure means.
+export function writeGateLock(dir, sessionId) {
+  mkdirSync(join(dir, ".doug/.state"), { recursive: true });
+  writeFileSync(gateLockPath(dir), JSON.stringify({ pid: process.pid, session: sessionId, at: Date.now() }), { flag: "wx" });
+}
+
+// Overwrites gate.lock with this gate's own pid/session, whether it was stale (a dead pid) or its holder
+// simply never let go inside the wait bound — either way, never lets a lock the gate cannot even write hang
+// it (best-effort; a failure here just leaves lockOwned false to the caller, which never releases a lock it
+// does not hold).
+export function takeOverGateLock(dir, sessionId) {
+  try {
+    mkdirSync(join(dir, ".doug/.state"), { recursive: true });
+    writeFileSync(gateLockPath(dir), JSON.stringify({ pid: process.pid, session: sessionId, at: Date.now() }));
+  } catch {
+    // best-effort takeover only
+  }
+}
+
+// Card stop-gate-budget-under-hook-timeout: cfg.stopGate.hookTimeoutSec must equal the platform's own
+// Stop/SubagentStop hook `timeout` (hooks.json/settings.json), but a hook reader never throws (F6), so a
+// missing, non-number, or non-positive value reads as the platform's own default, 600.
+export function resolveHookTimeoutSec(cfg) {
+  const sec = cfg && cfg.stopGate && cfg.stopGate.hookTimeoutSec;
+  return typeof sec === "number" && Number.isFinite(sec) && sec > 0 ? sec : 600;
+}
+
+// A lock whose numeric `at` is older than the hook-timeout budget is stale regardless of a live pid: no
+// legitimate holder can still be running that long, since the platform itself would have killed its hook
+// by then (F1). A missing or non-numeric `at` changes nothing here; the pid liveness check still decides.
+export function lockStaleByAge(lock, hookTimeoutMs) {
+  return !!lock && typeof lock.at === "number" && Number.isFinite(lock.at) && Date.now() - lock.at > hookTimeoutMs;
+}
+
+// Card stop-gate-timeout-normalise (moved here by card verify-lock-wait-bound so verify.mjs shares it):
+// cfg.stopGate.timeoutMs normalised once, shared by the per-command timeout and the wait bound, so the two
+// never disagree on what a garbage or fractional value means. A finite number above 0 floors to an integer,
+// clamped up to at least 1ms (0.5 must not floor to 0 — spawnSync reads a timeout of 0 as none at all,
+// letting a command run past the budget unclamped; 2.5 must not reach spawnSync un-floored — it throws
+// ERR_OUT_OF_RANGE there, and a hook reader must never throw, F6). Anything else (non-number, NaN, Infinity,
+// 0, negative, null) is "unset" (null), read by each call site as its own default.
+export function normalizedTimeoutMs(cfg) {
+  const t = cfg.stopGate.timeoutMs;
+  return typeof t === "number" && Number.isFinite(t) && t > 0 ? Math.max(1, Math.floor(t)) : null;
+}
+
+// How long a gate waits on a live gate.lock: the per-command timeout times the command count, the longest a
+// holder legitimately runs.
+export function lockWaitBoundMs(perCommandMs, commandCount) {
+  return perCommandMs * Math.max(1, commandCount);
+}

package/node_modules/@dougharness/gates/lib/run.mjs

@@ -6,6 +6,10 @@ import { spawnSync } from "node:child_process";
 export function commandEnv(base = process.env) {
   const env = { ...base, CI: base.CI ?? "1", NO_COLOR: "1" };
   delete env.FORCE_COLOR;
+  // card worktree-gate-mixed-tree-agent: the stop gate's per-tree plumbing never reaches the commands it runs.
+  delete env.DOUG_STOP_GATE_TREE;
+  delete env.DOUG_STOP_GATE_DEADLINE;
+  delete env.DOUG_STOP_GATE_CHILD;
   return env;
 }