@dougharness/cli 1.0.1

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

@@ -0,0 +1,101 @@
+import { isAbsolute, relative, resolve, sep, parse, dirname, basename } from "node:path";
+import { homedir } from "node:os";
+import { realpathSync } from "node:fs";
+
+// Returns the path relative to the project dir with forward slashes,
+// or null if the path escapes the project.
+export function toProjectRelative(dir, p) {
+  if (!p) return null;
+  const abs = isAbsolute(p) ? p : resolve(dir, p);
+  const rel = relative(dir, abs);
+  if (rel.startsWith("..") || isAbsolute(rel)) return null;
+  return rel.split(sep).join("/");
+}
+
+// Expands a leading "~" or "~/..." against HOME. "~" alone, or "~/" followed by any number of extra leading
+// slashes, resolves under homedir() (the extra slashes are stripped so "~//etc" means "$HOME/etc", never
+// "/etc" — resolve() would otherwise discard the home prefix when the second argument is absolute). Anything
+// else starting with "~" (e.g. "~x", "~root/x") is not tilde-home syntax and is returned unchanged.
+function expandTilde(entry) {
+  if (entry === "~") return homedir();
+  if (entry.startsWith("~/")) return resolve(homedir(), entry.slice(2).replace(/^[/\\]+/, ""));
+  return entry;
+}
+
+// True when a resolved path is exactly a filesystem root (e.g. "/" or "C:\").
+function isFilesystemRoot(p) {
+  return parse(p).root === p;
+}
+
+// Resolves the real path of p by realpath-ing its deepest existing ancestor and re-appending any path
+// segments that do not exist yet (e.g. a Write creating a new file), so containment checks are resistant to
+// symlinks and filesystem case-aliases. Uses realpathSync.native (the OS's own realpath) rather than plain
+// realpathSync: on a case-insensitive, case-preserving volume (APFS's default on macOS) plain
+// realpathSync only resolves symlinks and echoes back whatever case the input used, so it does NOT canonicalize
+// a case-variant alias to the same string — verified directly (fs.realpathSync of a same-directory alias with
+// swapped case returns the swapped-case string unchanged, while fs.realpathSync.native returns the one true
+// on-disk casing for both). Falls back to the lexical, resolved path if realpath cannot be determined for any
+// reason (a missing/inaccessible ancestor all the way to the root) — never throws.
+export function realpathDeepestExisting(p) {
+  const resolved = resolve(p);
+  const pending = [];
+  let current = resolved;
+  for (;;) {
+    try {
+      const real = realpathSync.native(current);
+      return pending.length ? resolve(real, ...pending.reverse()) : real;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return resolved;
+      pending.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+// True when absPath is equal to, or really contained inside, one of allowedOutsidePaths (each entry an
+// absolute or ~-prefixed path naming a file or directory). Used by protect-paths.mjs to let a write outside
+// the project directory through when it is explicitly allowlisted in .doug/config.json's allowedOutsidePaths.
+// Entries that are empty or not strings are ignored rather than thrown on, as is any entry whose REAL path is a
+// filesystem root — never a legitimate allowlist entry, and catastrophic if honored, since "/" as the prefix
+// matches every absolute path and would disable this guard globally. The root check runs after realpath
+// resolution as well as before it, because an entry that is a symlink to "/" resolves lexically to something
+// harmless-looking and only becomes the root once followed. No globs: directory containment on resolved,
+// `..`-free paths is the right primitive for an escape hatch, and is safer than glob matching here. Containment
+// requires a real path-segment boundary (the resolved entry plus a trailing separator, or an exact match) so
+// that an entry "/a/allowed" does not also match a sibling "/a/allowed-other". Both sides are resolved through
+// realpathDeepestExisting so a symlink or filesystem-case alias cannot be used to make a path look contained
+// (or not) when its real target says otherwise.
+export function isAllowedOutside(absPath, allowedOutsidePaths) {
+  if (!absPath || !Array.isArray(allowedOutsidePaths)) return false;
+  const target = realpathDeepestExisting(absPath);
+  for (const entry of allowedOutsidePaths) {
+    if (!entry || typeof entry !== "string") continue;
+    const resolvedEntry = resolve(expandTilde(entry));
+    if (isFilesystemRoot(resolvedEntry)) {
+      process.stderr.write(`[doug] allowedOutsidePaths entry ${JSON.stringify(entry)} resolves to the filesystem root; ignoring it.\n`);
+      continue;
+    }
+    const realEntry = realpathDeepestExisting(resolvedEntry);
+    // The entry's real path is the root: a symlink (or chain of them) pointing at "/". Same treatment.
+    if (isFilesystemRoot(realEntry)) {
+      process.stderr.write(`[doug] allowedOutsidePaths entry ${JSON.stringify(entry)} resolves to the filesystem root; ignoring it.\n`);
+      continue;
+    }
+    if (target === realEntry) return true;
+    if (target.startsWith(realEntry.endsWith(sep) ? realEntry : realEntry + sep)) return true;
+  }
+  return false;
+}
+
+// Extracts file paths from a tool_input for Edit/Write/MultiEdit/NotebookEdit.
+export function filePathsFromToolInput(toolInput) {
+  if (!toolInput || typeof toolInput !== "object") return [];
+  const out = [];
+  if (typeof toolInput.file_path === "string") out.push(toolInput.file_path);
+  if (typeof toolInput.notebook_path === "string") out.push(toolInput.notebook_path);
+  if (Array.isArray(toolInput.edits)) {
+    for (const e of toolInput.edits) if (e && typeof e.file_path === "string") out.push(e.file_path);
+  }
+  return out;
+}

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

@@ -0,0 +1,201 @@
+// Reader for the applied-proposal ledger, .doug/.state/proposals/applied.jsonl (cards memory-decisions,
+// proposal-ledger-forgeable): one JSON line per successful `learn.mjs apply` to a proposal-only path
+// (docs/decisions/**, .claude/rules/** by default - proposalPaths in .doug/config.json), written by
+// plugins/doug-flow/lib/learn.mjs's applyProposal. Duplicated here rather than imported across the plugin
+// boundary - no workspace dependency exists between doug-gates and doug-flow (lib/learn.mjs's own header
+// comment states the same precedent for its local glob matcher). The line shape is a contract shared with the
+// writer: { target, sha256, diffSha256, at, proposal }, where `proposal` is the diff file's path relative to
+// `dir` (forward slashes) and `diffSha256` is the sha256 of that diff file's bytes. A row's sha256 alone is not
+// enough to trust (card proposal-ledger-forgeable: a hand-written line can carry any sha256 it likes) - see
+// isAppliedContent below for the re-derivation this module runs instead. A row is untrusted, agent-writable
+// data read at Stop time: every field is treated as adversarial input (wrong type, wrong shape, a path that
+// escapes containment), and no exception from checking one row may ever escape isAppliedContent - runHook
+// (plugins/doug-gates/lib/io.mjs) fails a hook open on an uncaught exception, which would skip the whole Stop
+// gate, not just this check (review BLOCKER 1).
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+
+export const PROPOSAL_LEDGER_RELPATH = ".doug/.state/proposals/applied.jsonl";
+
+// Duplicated from plugins/doug-flow/lib/learn.mjs's own export of the same constant - no cross-plugin import
+// (see this file's header comment). A genuine ledger line's `proposal` must resolve under here.
+const LEARN_STATE_RELPATH = ".doug/.state/learn";
+
+// review MINOR 7 / MINOR 10: each candidate row costs a `git show` and a `git apply` (~30ms); a ledger padded
+// with many matching-but-bogus rows could push a single Stop check past the hook timeout. Only rows whose
+// target and sha256 already match are ever verified (cheap, in-memory), deduped by `proposal` (below) so a
+// pile of rows that all name the same diff costs one verification, not one per row, then capped to the most
+// recently appended this many DISTINCT proposals. This does not close every way to exhaust the cap: an
+// adversary who appends 20 or more rows naming 20 or more genuinely distinct bogus proposal paths can still
+// push a real row out of the window - but that fails closed (a block), never open, so it costs availability,
+// never lets a forgery through.
+const MAX_VERIFIED_ROWS = 20;
+
+// Every spawned git call gets a hard ceiling (ms) so a hung or adversarially slow git invocation cannot itself
+// become the way to blow the Stop-gate timeout (review MINOR 7).
+const GIT_TIMEOUT_MS = 5000;
+
+// Every well-formed line, tolerant of a missing file or a torn line (a crashed process mid-write) - never fatal.
+export function readAppliedLedger(dir) {
+  const file = join(dir, PROPOSAL_LEDGER_RELPATH);
+  if (!existsSync(file)) return [];
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      if (o && typeof o === "object" && o.target) out.push(o);
+    } catch {
+      // a torn line is skipped, never fatal
+    }
+  }
+  return out;
+}
+
+function sha256OfBytes(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+// sha256 of relPath's current bytes under dir, or the sha of empty content when it cannot be read (a deleted or
+// never-created target) - matches applyProposal's own convention for a deleted target.
+function currentSha256(dir, relPath) {
+  try {
+    return sha256OfBytes(readFileSync(join(dir, relPath)));
+  } catch {
+    return sha256OfBytes(Buffer.alloc(0));
+  }
+}
+
+// review MINOR 8: the writer (applyProposal) refuses a diff that touches more than one file, or whose one
+// target differs from what the caller expected - a ledger row must not trust a diff that the writer itself
+// would have refused. Every "+++ b/" AND "--- a/" header is parsed (the union of both sides' file names,
+// mirroring learn.mjs's own parseDiffTargets - duplicated locally, not imported, for the same reason as
+// everything else in this file's header comment); "/dev/null" never matches either pattern, so a creation or
+// deletion diff's placeholder side is naturally excluded. True only when the diff names exactly one path and
+// that path is relPath.
+function diffNamesOnly(diffText, relPath) {
+  const targets = new Set();
+  for (const m of diffText.matchAll(/^\+\+\+ b\/(.+)$/gm)) targets.add(m[1]);
+  for (const m of diffText.matchAll(/^--- a\/(.+)$/gm)) targets.add(m[1]);
+  return targets.size === 1 && targets.has(relPath);
+}
+
+// The committed base of relPath at `ref` (default HEAD) in dir, as a Buffer, or null when the path is not at
+// that ref (a new file), the ref does not exist at all (a repo with no commits yet, or a base sha git no
+// longer knows), or the git call times out (GIT_TIMEOUT_MS) or fails.
+function readCommittedBase(dir, relPath, ref) {
+  const target = typeof ref === "string" && ref ? ref : "HEAD";
+  const result = spawnSync("git", ["show", `${target}:${relPath}`], { cwd: dir, timeout: GIT_TIMEOUT_MS });
+  if (result.status !== 0) return null;
+  return result.stdout;
+}
+
+// Re-derivation at one ref (card proposal-ledger-forgeable): write the committed base of `relPath` at
+// `relPath`, read at `ref`, inside a fresh temp dir (omitted entirely when there is no base at that ref, so a
+// `--- /dev/null` new-file diff can still create it - git apply refuses to create a file that already
+// exists), `git apply` the diff there (git apply works as a plain patch tool outside a git repository; cwd is
+// the temp dir, never `dir` itself, so nothing real is ever touched), and compare the resulting bytes (empty
+// if the diff deleted the file) against `currentSha`. Any failure - a `git apply` that does not succeed or
+// times out (GIT_TIMEOUT_MS), or an unexpected exception - means the diff does not reproduce what is on disk
+// now from this particular ref, so this attempt does not satisfy the check. The temp dir is always removed.
+function diffAppliesAtRef(dir, relPath, diffAbsPath, currentSha, ref) {
+  let tmp;
+  try {
+    tmp = mkdtempSync(join(tmpdir(), "doug-ledger-verify-"));
+    const committedBase = readCommittedBase(dir, relPath, ref);
+    const targetInTmp = join(tmp, relPath);
+    if (committedBase !== null) {
+      mkdirSync(dirname(targetInTmp), { recursive: true });
+      writeFileSync(targetInTmp, committedBase);
+    }
+    const applied = spawnSync("git", ["apply", diffAbsPath], { cwd: tmp, timeout: GIT_TIMEOUT_MS });
+    if (applied.status !== 0) return false;
+    let resultBytes;
+    try {
+      resultBytes = readFileSync(targetInTmp);
+    } catch {
+      resultBytes = Buffer.alloc(0);
+    }
+    return sha256OfBytes(resultBytes) === currentSha;
+  } catch {
+    return false;
+  } finally {
+    if (tmp) {
+      try {
+        rmSync(tmp, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup; a leftover temp dir is harmless
+      }
+    }
+  }
+}
+
+// `base` (card stop-scan-committed-changes) is the session's baseline HEAD when known, tried first: a diff
+// that created `relPath` after that baseline still applies onto "absent" even once the session has since
+// committed `relPath` itself (HEAD would otherwise already equal the current bytes, and git apply refuses to
+// create a file that already exists there). M1 fix: when the base attempt fails, HEAD is also tried before
+// giving up, not only when `base` is null/omitted - a second approved apply on the same target, committed
+// in-session after the first (so its preimage is the first version, not the pre-session base), re-derives
+// correctly onto HEAD even though it cannot re-derive onto the pre-session base at all. Every other check
+// (row shape, containment, diffSha256, diffNamesOnly) is unchanged; this only widens which ref the content
+// re-derivation itself is allowed to succeed against.
+function diffReproducesCurrentContent(dir, relPath, diffAbsPath, currentSha, base) {
+  const refs = typeof base === "string" && base && base !== "HEAD" ? [base, "HEAD"] : ["HEAD"];
+  return refs.some((ref) => diffAppliesAtRef(dir, relPath, diffAbsPath, currentSha, ref));
+}
+
+// One row's full verification, wrapped so that no exception - a malformed field of any type, an unreadable
+// path, a git call throwing - can ever escape (review BLOCKER 1: an uncaught exception here would fail the
+// whole Stop hook open, not just this row). Returns false, never throws.
+function rowIsGenuine(dir, relPath, sha, learnDirAbs, row, base) {
+  try {
+    if (typeof row.diffSha256 !== "string" || typeof row.proposal !== "string") return false;
+    const diffAbsPath = resolve(dir, row.proposal);
+    if (diffAbsPath !== learnDirAbs && !diffAbsPath.startsWith(`${learnDirAbs}${sep}`)) return false;
+    const diffBuf = readFileSync(diffAbsPath);
+    if (sha256OfBytes(diffBuf) !== row.diffSha256) return false;
+    if (!diffNamesOnly(diffBuf.toString("utf8"), relPath)) return false;
+    return diffReproducesCurrentContent(dir, relPath, diffAbsPath, sha, base);
+  } catch {
+    return false;
+  }
+}
+
+// True when relPath's current content sha256 matches an applied-ledger line for that same target AND that
+// line's diff (a) is a real file under dir/.doug/.state/learn/, (b) has the sha256 the row claims for it, (c)
+// names relPath and no other file, and (d) applied onto the committed base of relPath, reproduces exactly the
+// bytes on disk now (card proposal-ledger-forgeable). Any row missing `diffSha256` or `proposal`, or carrying
+// either as anything but a string - the old, pre-hardening line shape, or a forged/malformed one - never
+// satisfies this: a hand-written sha256 alone is not proof of an approved `learn.mjs apply` any more, it is
+// only what the ledger claims happened. `base` (card stop-scan-committed-changes) is the ref re-derivation
+// tries first, forwarded to diffReproducesCurrentContent - the caller's session baseline HEAD when it has
+// one, so a target the session itself committed since that baseline is still checked against what existed
+// before the session started, not only against HEAD (which, once the target is committed, already equals the
+// current bytes and would make a new-file diff fail to apply there). HEAD is always tried too (M1 review
+// fix) - a second approved apply on the same target, committed in-session after the first, has the first
+// version as its preimage and can only re-derive onto HEAD, not onto the pre-session base. With `base` null
+// or omitted, only HEAD is tried, exactly as before this card.
+export function isAppliedContent(dir, relPath, { base = null } = {}) {
+  const sha = currentSha256(dir, relPath);
+  const learnDirAbs = resolve(dir, LEARN_STATE_RELPATH);
+  const matching = readAppliedLedger(dir).filter((row) => row && row.target === relPath && row.sha256 === sha);
+  // review MINOR 10: dedupe by `proposal` before capping to MAX_VERIFIED_ROWS - many rows naming the very same
+  // diff (repeated or near-repeated bogus lines) must cost one verification slot, not one per row, or a large
+  // enough pile of them could push a genuine row for this same target/sha256 out of the last-N window even
+  // though every one of those rows resolves to a single distinct diff file. A Map naturally keeps only the
+  // last-seen entry per key, and the ledger is append-only (later == newer), so the newest occurrence of each
+  // distinct `proposal` wins.
+  const byProposal = new Map();
+  for (const row of matching) byProposal.set(row.proposal, row);
+  const candidates = [...byProposal.values()].slice(-MAX_VERIFIED_ROWS).reverse(); // newest distinct proposal first
+  return candidates.some((row) => rowIsGenuine(dir, relPath, sha, learnDirAbs, row, base));
+}

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

@@ -0,0 +1,147 @@
+import { spawnSync } from "node:child_process";
+
+// card gates-runner-no-color: NO_COLOR, not FORCE_COLOR — vitest's colour library (picocolors/tinyrainbow)
+// treats any FORCE_COLOR key as colour on, even "0", which broke the stop gate's captured output and the
+// block ledger's failing-file parse (same fact as land.mjs's commandEnv, card land-force-color-enables-color).
+export function commandEnv(base = process.env) {
+  const env = { ...base, CI: base.CI ?? "1", NO_COLOR: "1" };
+  delete env.FORCE_COLOR;
+  return env;
+}
+
+// Runs a shell command in the project dir with a timeout. Never throws.
+export function runCommand(command, { cwd, timeoutMs = 300000, env = process.env } = {}) {
+  const started = Date.now();
+  const res = spawnSync(command, {
+    cwd,
+    shell: true,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    maxBuffer: 16 * 1024 * 1024,
+    env: commandEnv(env),
+    // 2026-09-16 process storm (card stop-gate-process-storm): detached makes the spawned shell the leader
+    // of its own process group, so a timeout can kill that whole group below, not just the direct child.
+    detached: true,
+  });
+  const timedOut = res.error && res.error.code === "ETIMEDOUT";
+  // spawnSync's own `timeout` (ETIMEDOUT) and `maxBuffer` (ENOBUFS) both signal only the direct child (the
+  // shell); anything that child spawned (e.g. a background test worker) is left running under pid 1 — four
+  // concurrent SubagentStops each doing this orphaned ten vitest workers apiece and downed the watchdog three
+  // times on 2026-09-16. Killed on ANY res.error with a pid (not just ETIMEDOUT; reviewer-found gap), since a
+  // maxBuffer overflow leaves the same orphaned-descendants shape as a timeout does. With `detached: true`
+  // above, res.pid is the process-group leader, so signalling the negative pid reaches every descendant still
+  // in that group. `timedOut` itself still reports only the ETIMEDOUT case, unchanged.
+  if (res.error && res.pid) {
+    try {
+      process.kill(-res.pid, "SIGKILL");
+    } catch {
+      // group already gone
+    }
+  }
+  return {
+    command,
+    ok: !timedOut && res.status === 0,
+    status: res.status,
+    timedOut: !!timedOut,
+    durationMs: Date.now() - started,
+    stdout: res.stdout || "",
+    stderr: res.stderr || (res.error ? String(res.error.message) : ""),
+  };
+}
+
+// Keeps the last N lines of output so a block reason stays readable.
+export function tail(text, lines = 30) {
+  const arr = String(text).trimEnd().split("\n");
+  return arr.slice(-lines).join("\n");
+}
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+const stripAnsi = (s) => s.replace(ANSI_RE, "");
+
+// card gate-output-names-failures: `tail` alone buries a real vitest failure under dozens of passing lines,
+// leaving no failing test name in a block reason (brief F1/F2). Leads with the failure-naming lines (`FAIL`,
+// `×`, `✗`; a `×` line's `→` message right after it) and the final `Test Files`/`Tests` totals, in output
+// order and each kept once, then fills the rest of `maxLines` with the plain tail of whatever wasn't already
+// shown - skipping any OTHER totals-shaped line too (review H10: a `pnpm -r --stream` run prints one
+// `Test Files`/`Tests` pair per package, so without this the tail filler pulls the earlier, per-package
+// pairs back in and the totals show up more than once). No vitest-shaped lines at all -> identical to
+// `tail(text, maxLines)`. When the failure-naming lines alone would overflow `maxLines`, keeps the first
+// `maxLines - 3` of them plus the two totals lines plus one `… <n> more failing tests not shown` line (40
+// total at the default cap) rather than growing past the cap. ANSI escapes are stripped from every kept
+// line. `maxLines < 4` (too small to fit totals plus the overflow line at all) falls back to a plain tail
+// (review m2). Never throws.
+export function failureSummary(output, maxLines = 40) {
+  let raw;
+  try {
+    raw = String(output ?? "").trimEnd();
+  } catch {
+    // review m1: `output`'s own toString threw; there is nothing safe left to summarise or tail.
+    return "";
+  }
+  if (raw === "") return "";
+  if (maxLines < 4) return tail(raw, maxLines);
+  try {
+    const rawLines = raw.split("\n");
+    const cleanLines = rawLines.map(stripAnsi);
+    const used = new Set();
+    const headIdx = [];
+    for (let i = 0; i < cleanLines.length; i++) {
+      if (used.has(i)) continue;
+      if (!/^\s*(FAIL|×|✗)\s/.test(cleanLines[i])) continue;
+      headIdx.push(i);
+      used.add(i);
+      // a `×` line's `→` message belongs with it, kept whole right after.
+      if (/^\s*×\s/.test(cleanLines[i]) && i + 1 < cleanLines.length && !used.has(i + 1) && /^\s*→/.test(cleanLines[i + 1])) {
+        headIdx.push(i + 1);
+        used.add(i + 1);
+      }
+    }
+    if (headIdx.length === 0) return tail(raw, maxLines);
+
+    // review MAJOR M-A: a `pnpm -r` run prints one `Test Files`/`Tests` pair per package, so scanning for
+    // every line matching the pattern (as before) could add thousands of totals lines and blow the cap wide
+    // open. Only the LAST `Test Files` line and the LAST `Tests` line are the overall run's own totals; kept
+    // (at most one of each, at most 2 lines total) instead, which also keeps the head budget non-negative
+    // for any input size.
+    let lastTestFilesIdx = -1;
+    let lastTestsIdx = -1;
+    for (let i = 0; i < cleanLines.length; i++) {
+      if (used.has(i)) continue;
+      if (/^\s*Test Files\s/.test(cleanLines[i])) lastTestFilesIdx = i;
+      else if (/^\s*Tests\s/.test(cleanLines[i])) lastTestsIdx = i;
+    }
+    const totalsIdx = [lastTestFilesIdx, lastTestsIdx].filter((i) => i !== -1).sort((a, b) => a - b);
+    for (const i of totalsIdx) used.add(i);
+
+    const headLines = headIdx.map((i) => cleanLines[i]);
+    const totalsLines = totalsIdx.map((i) => cleanLines[i]);
+
+    if (headLines.length + totalsLines.length > maxLines) {
+      const keepHeadCount = Math.max(0, maxLines - totalsLines.length - 1);
+      const kept = headLines.slice(0, keepHeadCount);
+      const dropped = headLines.slice(keepHeadCount);
+      const droppedNamed = dropped.filter((l) => /^\s*(FAIL|×|✗)\s/.test(l)).length;
+      return [...kept, ...totalsLines, `… ${droppedNamed} more failing tests not shown`].join("\n");
+    }
+
+    const resultLines = [...headLines, ...totalsLines];
+    const remaining = maxLines - resultLines.length;
+    if (remaining > 0) {
+      // review H10: an earlier per-package Test Files/Tests pair is not in `used` (only the LAST pair is
+      // kept as the real totals above), but it must still be skipped here, or the tail filler pulls it back
+      // in and the totals end up shown more than once.
+      const filler = [];
+      for (let i = cleanLines.length - 1; i >= 0 && filler.length < remaining; i--) {
+        if (used.has(i)) continue;
+        if (/^\s*(Test Files|Tests)\s/.test(cleanLines[i])) continue;
+        filler.push(cleanLines[i]);
+      }
+      filler.reverse();
+      resultLines.push(...filler);
+    }
+    return resultLines.join("\n");
+  } catch {
+    // review m1: `raw` is already a plain, safely-coerced string, so this fallback cannot itself throw.
+    return tail(raw, maxLines);
+  }
+}

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

@@ -0,0 +1,117 @@
+// Plan-versus-diff scope: when .doug/plan.json is approved (or done and not yet landed), the union of
+// the files its tasks own is the only thing a session may change.
+// Pure functions plus one reader; the stop gate decides, this file only computes.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { globToRegExp, matchAny, normalizePath } from "./glob.mjs";
+
+export const PLAN_RELPATH = ".doug/plan.json";
+export const ENFORCED_STATUSES = ["approved", "done"];
+// The flow's own files change during a run and are never out of scope. Per-session hook state too.
+// board.json moves uncommitted with the live board server; it lands in the card's landing commit.
+export const ALWAYS_ALLOWED = [".doug/plan.json", ".doug/anchor.md", ".doug/.state/**", ".doug/board.json"];
+
+// Returns { plan, reason }. plan is set only when the file exists, parses, has tasks, and is in an
+// enforced status; reason says why not otherwise ("no-plan", "unreadable", "status:draft", "invalid").
+export function loadScopePlan(dir) {
+  const file = join(dir, PLAN_RELPATH);
+  if (!existsSync(file)) return { plan: null, reason: "no-plan" };
+  let plan;
+  try {
+    plan = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    return { plan: null, reason: "unreadable", error: String(err.message) };
+  }
+  if (!plan || typeof plan !== "object" || !Array.isArray(plan.tasks)) return { plan: null, reason: "invalid" };
+  if (!ENFORCED_STATUSES.includes(plan.status)) return { plan: null, reason: `status:${plan.status}` };
+  // plan.mjs land records `landed`; a landed plan has been merged and no longer holds scope.
+  if (plan.landed) return { plan: null, reason: "landed" };
+  return { plan, reason: null };
+}
+
+const GLOB_CHARS = /[*?{]/;
+
+// Does a plan ownership entry cover this path? Exact file, a directory (with or without a trailing
+// slash), or a glob matched against the whole relative path. No basename matching: a task that owns
+// "README.md" does not own "docs/README.md".
+export function ownsPath(owned, file) {
+  if (typeof owned !== "string" || typeof file !== "string") return false;
+  const o = normalizePath(owned).replace(/\/+$/, "");
+  const f = normalizePath(file);
+  if (!o) return false;
+  if (GLOB_CHARS.test(o)) return globToRegExp(o).test(f);
+  return f === o || f.startsWith(o + "/");
+}
+
+// Sorted union of every path the plan's tasks own.
+export function planScope(plan) {
+  const out = new Set();
+  for (const t of plan.tasks || []) for (const f of t.files || []) if (typeof f === "string") out.add(normalizePath(f));
+  return [...out].sort();
+}
+
+function segments(p) {
+  return normalizePath(p).split("/").filter(Boolean);
+}
+
+function sharedDepth(a, b) {
+  const x = segments(a).slice(0, -1); // directories only; the basename never counts
+  const y = segments(b).slice(0, -1);
+  let n = 0;
+  while (n < x.length && n < y.length && x[n] === y[n]) n++;
+  return n;
+}
+
+// Tasks whose owned files sit closest to this file in the tree: longest shared directory prefix,
+// ties kept in plan order. Empty when no task owns anything in a directory the file shares.
+export function nearestTasks(plan, file) {
+  let best = 0;
+  const hits = [];
+  for (const t of plan.tasks || []) {
+    let depth = 0;
+    let via = null;
+    for (const f of t.files || []) {
+      const d = sharedDepth(f, file);
+      if (d > depth || via === null) {
+        depth = d;
+        via = f;
+      }
+    }
+    if (via === null || depth === 0) continue;
+    if (depth > best) {
+      best = depth;
+      hits.length = 0;
+    }
+    if (depth === best) hits.push({ id: t.id, via });
+  }
+  return hits;
+}
+
+// Changed files the plan does not cover, after the ignore list and the flow's own files.
+// Each entry: { file, nearest: [{ id, via }] }.
+export function scopeViolations(changed, plan, { ignore = [] } = {}) {
+  const owned = planScope(plan);
+  const out = [];
+  for (const raw of changed) {
+    const file = normalizePath(raw);
+    if (matchAny(ALWAYS_ALLOWED, file)) continue;
+    if (ignore.length && matchAny(ignore, file)) continue;
+    if (owned.some((o) => ownsPath(o, file))) continue;
+    out.push({ file, nearest: nearestTasks(plan, file) });
+  }
+  return out;
+}
+
+export function describeViolations(violations, plan) {
+  const lines = [`Files changed outside the ${plan.status} plan "${plan.title}" (${PLAN_RELPATH}):`];
+  for (const v of violations) {
+    const near = v.nearest.length ? `nearest task${v.nearest.length > 1 ? "s" : ""}: ${v.nearest.map((n) => `${n.id} (owns ${n.via})`).join(", ")}` : "no task owns anything near it";
+    lines.push(`  ${v.file}  ${near}`);
+  }
+  lines.push(
+    "The plan is the contract. Revert these files, or add them to the owning task's files and have the user re-approve the plan. " +
+      "Paths that legitimately change outside any task (lockfiles, generated files) belong in stopGate.ignoreChangedPaths in .doug/config.json.",
+  );
+  return lines.join("\n");
+}