@dougharness/cli 1.0.1

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

@@ -0,0 +1,268 @@
+// Pure rule functions for the secret-scan guard so they can be unit-tested without spawning.
+// Only new text (Write content, Edit/MultiEdit new_string, NotebookEdit new_source, Bash command)
+// is ever scanned; old_string is never included, so removing a secret is never blocked.
+
+// AWS access key ids: of the IAM unique-ID prefixes, only AKIA (long-term) and ASIA (temporary STS)
+// denote access key ids (docs.aws.amazon.com .../reference_identifiers.html). The documented example
+// id is the prefix plus 16 [A-Z0-9] characters; the AccessKeyId API contract allows 16-128 `\w`
+// characters, so the suffix is widened to 16 or more (docs.aws.amazon.com .../API_AccessKey.html).
+const AWS_KEY_ID_SRC = "(?<![A-Za-z0-9])(?:AKIA|ASIA)[A-Z0-9]{16,}(?![A-Za-z0-9])";
+
+// PEM private-key headers: RFC 7468's ABNF (`preeb = "-----BEGIN " label "-----"`; a label is one or
+// more labelchars joined by a single SP or "-") applied to the PRIVATE KEY (section 10) and ENCRYPTED
+// PRIVATE KEY (section 11) labels; RSA/DSA/EC/SM2/OPENSSH are OpenSSL/OpenSSH label words preceding
+// it (rfc-editor.org/rfc/rfc7468.txt). The label-word count and length are capped (round 2, M1) so the
+// group is a single bounded repeat, not an unbounded quantifier nested inside another.
+const PEM_PRIVATE_KEY_SRC = "-----BEGIN (?:[A-Z0-9]{1,20} ){0,3}PRIVATE KEY-----";
+
+// GitHub tokens: the classic prefixes ghp_/gho_/ghu_/ghs_/ghr_ (docs.github.com, "about authentication
+// to GitHub") each followed by 36-255 characters (github.blog's "up to 255 characters" integrator
+// guidance; "30 random plus a 6-character checksum" is stated there for OAuth (gho_) tokens only —
+// the other prefixes' 36-char shape is an inference from the same page, not separately documented),
+// the github_pat_ fine-grained form (internal shape undocumented; 22 is Doug's own floor, 255 the
+// same integrator ceiling), and the 2026 stateless installation-token form ghs_<appid>_<JWT>
+// (docs.github.com, same page). Every repeat is bounded (round 2, M1) so no run is rescanned from
+// every start position, and the trailing check is (?![A-Za-z0-9]), not \b, so a token glued to a
+// following "_" still hits (round 2, m1).
+const GITHUB_TOKEN_SRC =
+  "\\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,255}(?![A-Za-z0-9])" +
+  "|\\bgithub_pat_[A-Za-z0-9_]{22,255}(?![A-Za-z0-9])" +
+  "|\\bghs_[0-9]{1,10}_[A-Za-z0-9_-]{8,2048}\\.[A-Za-z0-9_-]{8,2048}\\.[A-Za-z0-9_-]{8,2048}(?![A-Za-z0-9])";
+
+// Slack tokens: bot/user/workflow/app-level strings begin xoxb-/xoxp-/xwfp-/xapp-, each divided into
+// dash-separated sections whose final section is the secret (docs.slack.dev/authentication/tokens);
+// rotation gives refresh tokens a bare "xoxe-" prefix (docs.slack.dev/authentication/using-token-
+// rotation) — a rotated *access* token's "xoxe." prefix needs no separate alternative, since the
+// xoxp-/xoxb- token it wraps already matches on its own (round 2, m2: the old xoxe\. alternative was
+// dead code). The prefix match below is a single bounded literal (no nested quantifier, round 2, M1);
+// scanSlackToken then reads the run of dash-joined sections and checks the final section's length in
+// plain code, never with a `(?:[A-Za-z0-9]+-)*` group, so nothing is rescanned from every start
+// position. The final section must be at least 6 characters (the documented pre-2016 legacy minimum);
+// xoxa-/xoxr-/xoxs- have no Slack source and are dropped.
+const SLACK_PREFIX_SRC = "\\b(?:xoxb|xoxp|xwfp|xapp|xoxe)-";
+const SLACK_RUN_CHARS = /[A-Za-z0-9-]/;
+const SLACK_RUN_WINDOW = 512; // generous vs. any real Slack token; keeps the scan bounded per match
+
+function scanSlackToken(text) {
+  const re = new RegExp(SLACK_PREFIX_SRC, "g");
+  let m;
+  while ((m = re.exec(text))) {
+    const start = m.index + m[0].length;
+    const end = Math.min(text.length, start + SLACK_RUN_WINDOW);
+    let i = start;
+    while (i < end && SLACK_RUN_CHARS.test(text[i])) i++;
+    const run = text.slice(start, i);
+    const sections = run.split("-");
+    const last = sections[sections.length - 1];
+    if (last.length >= 6) return true;
+    re.lastIndex = Math.max(re.lastIndex, i);
+  }
+  return false;
+}
+
+// Inline credential assignment: Doug's own rule (round 2 redesign, no external source), written
+// independently of the prior rule. The regex finds a credential key name — captured in group 1, so
+// its left boundary can be judged in code, not the regex — (password, passwd, pwd, secret, client
+// secret, api key, access token, auth token, private key, access key — words joined by `_`, `-`, or
+// nothing, case-insensitive) followed by `=`/`:` and an optional opening quote (captured in group 2).
+// Left boundary (round 4, since round 3's letter/digit exclusion also killed camelCase and glued
+// keys like dbPassword/jwtSecret/dbpassword — see isValidKeyBoundary): the long names may be
+// preceded by anything at all, including `$` (round 5 correction: PHP/Perl spell a variable with a
+// leading `$`, e.g. `$password = "..."`, and that is a real assignment, not shell interpolation);
+// only the bare `pwd` alternative keeps round 3's strict rule (not preceded by a letter, digit, or
+// `$`), with one exception — a lower-to-upper case step right before it (dbPwd hits; XPWD, preceded
+// by an upper-case letter, does not; nor does $PWD/$pwd, the shell-variable case that rule exists
+// for). The VALUE itself is read
+// by plain code, not by a regex quantifier, from a single bounded slice taken up front (round 3,
+// R3-2: that one slice backs both the end-of-line check and the closing-quote search below, so
+// neither is an unbounded scan over the rest of the text — see readInlineValue). A quoted value ends
+// at the next quote character of the SAME kind that opened it, within that slice and never past its
+// first newline (round 3, R3-3: an embedded apostrophe inside a double-quoted value no longer ends
+// it early; no matching quote on the line disqualifies the match rather than swallowing the rest of
+// the slice). A bare value ends at the next whitespace/`;`/`,`/`)`/`}`/`]`. It is flagged when the
+// value is 12+ characters, has at least one letter and at least one digit or one of `/+=`, is not a
+// reference (starts with `$`, `{`, `<`, `%`, `process.env`, or `os.environ`), is not a filesystem
+// path or network address whether quoted or bare (round 3 R3-1, widened round 4: see
+// isInlinePathOrUrl), and is not a configured placeholder prefix.
+const INLINE_KEY_SRC =
+  "(password|passwd|pwd|secret|client[_-]?secret|api[_-]?key|access[_-]?token|auth[_-]?token|private[_-]?key|access[_-]?key)" +
+  "\\s*[:=]\\s*([\"'`])?";
+const INLINE_BARE_STOP = /^[^\s;,)}\]]*/;
+const INLINE_WINDOW = 4096; // shared bound for the quoted branch's end-of-line and closing-quote search
+const INLINE_BARE_WINDOW = 512;
+const INLINE_REFERENCE_MARKERS = /^[${<%]/;
+const INLINE_PATH_START = /^(?:\/|\.\/|\.\.\/|~)/;
+const INLINE_ANY_QUOTE = /["'`]/;
+const INLINE_LETTER_OR_DIGIT = /[A-Za-z0-9]/;
+const INLINE_LOWER = /[a-z]/;
+const INLINE_UPPER = /[A-Z]/;
+
+// Judges a matched key name's left boundary in plain code (round 4), since the exception for `pwd`
+// (a camelCase step is allowed; any other letter/digit is not) needs the matched key's own casing,
+// which a single case-insensitive regex can't branch on. `left` is the character immediately before
+// the key, or undefined at the start of the text. The long names may be preceded by anything at all
+// (dbPassword, jwtSecret, dbpassword, ADMIN_API_KEY, and a PHP/Perl `$password = "..."` or
+// `$secret = '...'` all still hit — round 5 correction: a leading `$` is how those languages spell
+// a variable, not shell/template interpolation, so it is not excluded there). Only bare `pwd` is
+// pickier: `left` must be absent, not a letter or digit, or — the camelCase exception — a lower-case
+// letter immediately followed by an upper-case first letter of the match (dbPwd hits; XPWD and
+// $PWD/$pwd, the shell-variable false positive round 3 introduced this rule for, do not).
+function isValidKeyBoundary(left, keyText) {
+  if (left === undefined) return true;
+  if (keyText.toLowerCase() !== "pwd") return true;
+  if (left === "$") return false;
+  if (!INLINE_LETTER_OR_DIGIT.test(left)) return true;
+  return INLINE_LOWER.test(left) && INLINE_UPPER.test(keyText.charAt(0));
+}
+
+// Reads the value following a matched key+separator. Quoted: slice at most INLINE_WINDOW characters
+// once (bounding both checks below to that one slice, round 3, R3-2), cut the slice at its first
+// newline if any (a value never spans lines), then find the next occurrence of the SAME quote
+// character within what's left; no such quote means no value (null), never "keep scanning" or "keep
+// the rest of the slice" (round 3, R3-3). Bare: up to the next whitespace/`;`/`,`/`)`/`}`/`]`, itself
+// a single bounded slice.
+function readInlineValue(text, pos, quote) {
+  if (quote) {
+    const window = text.slice(pos, Math.min(text.length, pos + INLINE_WINDOW));
+    const newline = window.indexOf("\n");
+    const line = newline === -1 ? window : window.slice(0, newline);
+    const rel = line.indexOf(quote);
+    if (rel === -1) return null;
+    const value = line.slice(0, rel);
+    // A real value never itself starts with a quote character of any kind (that first character
+    // would immediately close an empty value) or with whitespace (round 4: a wider left-boundary
+    // means the "opening" quote is now sometimes the tail of an unrelated string a few characters
+    // earlier — e.g. a key matched inside a JS string literal whose own closing quote sits right
+    // where a value would start, with the match then running on to the next quote later in the
+    // source line); either shape means the match crossed into unrelated text, so there is no value.
+    if (INLINE_ANY_QUOTE.test(value.charAt(0)) || /\s/.test(value.charAt(0))) return null;
+    return value;
+  }
+  const window = text.slice(pos, Math.min(text.length, pos + INLINE_BARE_WINDOW));
+  return INLINE_BARE_STOP.exec(window)[0];
+}
+
+function isInlineReference(value) {
+  const lower = value.toLowerCase();
+  return INLINE_REFERENCE_MARKERS.test(value) || lower.startsWith("process.env") || lower.startsWith("os.environ");
+}
+
+// A value naming a filesystem location or a network address is not a credential literal (round 3,
+// R3-1, widened to quoted values in round 4): it starts with a slash, a `./` or `../` relative
+// prefix, or a `~` home shorthand, or it carries a scheme separator (colon, two slashes) further in.
+function isInlinePathOrUrl(value) {
+  return INLINE_PATH_START.test(value) || value.includes(":" + "//");
+}
+
+export const RULES = [
+  {
+    id: "awsKeyId",
+    what: "an AWS access key id",
+    source: [
+      "https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html",
+      "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html",
+      "https://docs.aws.amazon.com/IAM/latest/APIReference/API_AccessKey.html",
+    ],
+    test: (text) => new RegExp(AWS_KEY_ID_SRC).test(text),
+  },
+  {
+    id: "pemPrivateKey",
+    what: "a PEM private-key header",
+    source: "https://www.rfc-editor.org/rfc/rfc7468.txt",
+    test: (text) => new RegExp(PEM_PRIVATE_KEY_SRC).test(text),
+  },
+  {
+    id: "githubToken",
+    what: "a GitHub token",
+    source: [
+      "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github",
+      "https://github.blog/engineering/platform-security/behind-githubs-new-authentication-token-formats/",
+    ],
+    test: (text) => new RegExp(GITHUB_TOKEN_SRC).test(text),
+  },
+  {
+    id: "slackToken",
+    what: "a Slack token",
+    source: ["https://docs.slack.dev/authentication/tokens", "https://docs.slack.dev/authentication/using-token-rotation"],
+    test: (text) => scanSlackToken(text),
+  },
+  {
+    id: "inlineAssignment",
+    what: "an inline credential assignment (password, secret, api_key, or token with a literal value)",
+    source: "Doug's own design (no external source)",
+    test: (text, secrets) => {
+      const placeholders = ((secrets && secrets.placeholders) || []).map((p) => String(p).toLowerCase());
+      const re = new RegExp(INLINE_KEY_SRC, "gi");
+      let m;
+      while ((m = re.exec(text))) {
+        const left = m.index > 0 ? text.charAt(m.index - 1) : undefined;
+        if (!isValidKeyBoundary(left, m[1])) continue;
+        const pos = m.index + m[0].length;
+        const quote = m[2];
+        const value = readInlineValue(text, pos, quote);
+        if (value === null || value.length < 12) continue;
+        if (!/[A-Za-z]/.test(value)) continue;
+        if (!/[0-9/+=]/.test(value)) continue;
+        if (isInlineReference(value)) continue;
+        if (isInlinePathOrUrl(value)) continue;
+        const lower = value.toLowerCase();
+        if (placeholders.some((p) => lower.startsWith(p))) continue;
+        return true;
+      }
+      return false;
+    },
+  },
+];
+
+// Returns { rule, what } for the first enabled rule that hits, else null.
+export function scanText(text, secrets) {
+  if (typeof text !== "string") return null;
+  for (const rule of RULES) {
+    if (secrets && secrets.rules && secrets.rules[rule.id] === false) continue;
+    if (rule.test(text, secrets)) return { rule: rule.id, what: rule.what };
+  }
+  return null;
+}
+
+// Extracts the candidate texts to scan (and their labels/paths) from a tool_input.
+export function candidateTexts(toolInput) {
+  if (!toolInput || typeof toolInput !== "object") return [];
+  const out = [];
+  const pathOf = (v) => (typeof v === "string" ? v : null);
+  if (typeof toolInput.command === "string") {
+    out.push({ label: "this command", path: null, text: toolInput.command });
+  }
+  if (typeof toolInput.content === "string") {
+    const path = pathOf(toolInput.file_path);
+    out.push({ label: path ?? "this edit", path, text: toolInput.content });
+  }
+  if (typeof toolInput.new_string === "string") {
+    const path = pathOf(toolInput.file_path);
+    out.push({ label: path ?? "this edit", path, text: toolInput.new_string });
+  }
+  if (typeof toolInput.new_source === "string") {
+    const path = pathOf(toolInput.notebook_path);
+    out.push({ label: path ?? "this edit", path, text: toolInput.new_source });
+  }
+  if (Array.isArray(toolInput.edits)) {
+    for (const e of toolInput.edits) {
+      if (e && typeof e === "object" && typeof e.new_string === "string") {
+        const raw = toolInput.file_path ?? e.file_path ?? null;
+        const path = pathOf(raw);
+        out.push({ label: path ?? "this edit", path, text: e.new_string });
+      }
+    }
+  }
+  return out;
+}
+
+export function denyReason(hit, label) {
+  const lead =
+    label === "this command"
+      ? `Refusing to run this command: it contains what looks like ${hit.what} (rule ${hit.rule}).`
+      : `Refusing to write ${label}: it contains what looks like ${hit.what} (rule ${hit.rule}).`;
+  return (
+    lead +
+    ` Reference credentials through an environment variable or a secret manager instead of writing them into files or commands. If this is a placeholder, add its prefix to secrets.placeholders in .doug/config.json; to exempt a path, add it to secrets.ignorePaths; secrets.rules.${hit.rule}: false turns the rule off.`
+  );
+}

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

@@ -0,0 +1,114 @@
+// Per-session state for hooks, stored under <project>/.doug/.state/<session_id>.json.
+// Written atomically (tmp + rename). Never shared between sessions.
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const STATE_DIR_RELPATH = ".doug/.state";
+
+function safeId(id) {
+  return String(id || "no-session")
+    .replace(/[^A-Za-z0-9_.-]/g, "_")
+    .replace(/\.{2,}/g, "_")
+    .slice(0, 120);
+}
+
+export function statePath(dir, sessionId) {
+  return join(dir, STATE_DIR_RELPATH, safeId(sessionId) + ".json");
+}
+
+export function loadState(dir, sessionId) {
+  const file = statePath(dir, sessionId);
+  if (!existsSync(file)) return emptyState();
+  try {
+    return { ...emptyState(), ...JSON.parse(readFileSync(file, "utf8")) };
+  } catch {
+    return emptyState();
+  }
+}
+
+export function saveState(dir, sessionId, state) {
+  const file = statePath(dir, sessionId);
+  mkdirSync(join(dir, STATE_DIR_RELPATH), { recursive: true });
+  const tmp = file + "." + process.pid + ".tmp";
+  writeFileSync(tmp, JSON.stringify(state));
+  renameSync(tmp, file);
+}
+
+export function emptyState() {
+  return {
+    edits: {}, // relpath -> [timestamps]
+    editedFiles: [], // relpaths edited this session (deduped)
+    turns: 0,
+    stopBlocks: 0,
+    // Consecutive deferred main Stops (card stop-gate-deferral-cap): reset to 0 by a SubagentStop of this
+    // session, or by a main Stop that reaches the deferral check point and does not defer (stop-gate.mjs).
+    // Absent from an old state file reads as 0 via the emptyState spread below.
+    deferrals: 0,
+    agentBlocks: {}, // agent_id -> blocks of that subagent's SubagentStop, capped like stopBlocks but apart from it
+    // agent_id -> { context: { pct, tokens, window, model, at, maxPct, notifiedAt } }: a worker's measured context
+    // (card worker-context-handoff, lib/agent-context.mjs), read from its own transcript by scripts/trace.mjs on
+    // PostToolUse and checked by scripts/stop-gate.mjs's SubagentStop gate before accepting a partial claim.
+    // Absent from an old state file loads as {} (the spread of emptyState() above supplies it).
+    agents: {},
+    lastGate: null, // { ok, at, results }
+    commands: [], // Bash commands the guard let through this session, newest last, clipped; the stop gate reads them as verification evidence
+    baseline: null, // relpath -> content identity, captured on SessionStart or (fallback) the stop gate's first run this session; null until captured
+    baselineSource: null, // "session-start" | "stop" | null (not yet captured) — where state.baseline came from
+    // git HEAD sha recorded in the same write as `baseline` (card stop-scan-committed-changes), or null when
+    // there was no git repo or no HEAD yet at capture time. Never overwritten once non-null. Lets a later Stop
+    // scan `git diff --name-only <this>..HEAD` (baseline.mjs's committedSince) for paths the session committed
+    // instead of leaving dirty, which a working-tree-only scan can never see. Absent from an old state file
+    // predating this key loads as null via the emptyState spread above, which degrades to today's behavior.
+    baselineHead: null,
+    // True once `baseline` can be trusted to hold identities for every current proposalPaths file on disk
+    // (card stop-scan-committed-changes): both capture sites set this in the same write as `baseline`, since
+    // they always perform that walk. Absent from a state file whose baseline was captured before this key
+    // existed loads as false via the emptyState spread above: a pre-existing, untouched proposalPaths file
+    // (e.g. an old ADR) that was never walked into that baseline would otherwise read as "new" the first time
+    // a later stop-gate.mjs walks the filesystem and compares against it. Rather than sitting out the
+    // walk-based check for the rest of such a session, stop-gate.mjs's one-time repair (Minor 4) backfills
+    // the missing identities into `baseline` on the very first Stop that finds this false, sets it true right
+    // there, and only that one Stop still skips the walk-based check (it just backfilled from whatever the
+    // tree looks like now, not from true session start) - the walk is live again from the next Stop on.
+    baselineWalked: false,
+    // Recorded by a green gate (card stop-gate-process-storm): { head, tree, at } where `head` is headAt(dir)
+    // and `tree` is captureBaseline(dir, [...changed, ...walkProposalPathFiles(dir, cfg.proposalPaths)]) — the
+    // fingerprint of the tree the commands were about to run against, taken BEFORE they ran, not after. A
+    // command that itself changes a file this fingerprint covers (e.g. a formatter) is therefore never matched
+    // by a later Stop/SubagentStop's sameTree comparison even though that same gate just passed — deliberate:
+    // `tree` promises "this is what was verified", and a command's own edit was never actually verified against.
+    // When it does match, the later Stop/SubagentStop skips re-running the verification commands entirely
+    // instead of every concurrent SubagentStop starting its own full suite (the 2026-09-16 process storm). A
+    // red gate never sets this; absent from an old state file loads as null via the emptyState spread above,
+    // which degrades to today's behavior (always verify).
+    verified: null,
+    // The standing tests_red_by_design claim (card stop-gate-block-ledger, d183db5's honoured-claim path):
+    // { files, at, agent } — `files` is the coverage's claimed file list, `at` an ISO timestamp, `agent` the
+    // subagent's id (not its type). Written only in stop-gate.mjs's honoured-claim branch, alongside (never
+    // instead of) the existing state.lastGate.redByDesign write; state.lastGate itself is replaced wholesale
+    // on every later gate run (line ~942), so that record alone would not stand for a later block to read.
+    // This key does: the block-ledger classifier reads redByDesignClaim.files to label a later block
+    // 'expected-red' when it covers it. No expiry and no say in whether a stop is let through — that stays
+    // the Decide card stop-gate-honours-tester-claim's to add. Absent from an old state file loads as null
+    // via the emptyState spread above.
+    redByDesignClaim: null,
+    // context (card context-window-handoff): { pct, at, notifiedAt? } — absent until the status line first
+    // records a reading (statusline.mjs), so not a default key here. pct and at are written by the status line
+    // on every rounded-pct change; notifiedAt is written by the Stop gate (stop-gate.mjs) when it notices, and
+    // is preserved across later pct updates so repeat logic tracks growth since the last notice, not since the
+    // last render. Cleared by reanchor.mjs on PostCompact.
+  };
+}
+
+export const MAX_COMMANDS = 100;
+
+// Remember an allowed Bash command (clipped to 200 characters, the last MAX_COMMANDS kept).
+export function recordCommand(dir, sessionId, command) {
+  if (typeof command !== "string" || !command.trim()) return;
+  const state = loadState(dir, sessionId);
+  const commands = Array.isArray(state.commands) ? state.commands : [];
+  commands.push(command.replace(/\s+/g, " ").trim().slice(0, 200));
+  state.commands = commands.slice(-MAX_COMMANDS);
+  saveState(dir, sessionId, state);
+}

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

@@ -0,0 +1,196 @@
+// Run trace (decision 0002, card run-trace): the trace hook appends one JSON line per SubagentStart, SubagentStop,
+// PreToolUse, and PostToolUse event to <project>/.doug/.state/trace/<session>.jsonl. The readers here (replay,
+// per-agent attribution) are what `doug trace` prints. Tokens are recorded only where Claude Code reports them:
+// a SubagentStop carries the agent's transcript path, whose assistant lines carry per-message usage. Everything
+// else records null; nothing is ever estimated. `context` (card worker-context-handoff) is the worker's own
+// measured context pct on a PostToolUse inside a subagent, from lib/agent-context.mjs; null everywhere else.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const TRACE_DIR_RELPATH = ".doug/.state/trace";
+
+function safeId(id) {
+  return String(id || "no-session")
+    .replace(/[^A-Za-z0-9_.-]/g, "_")
+    .replace(/\.{2,}/g, "_")
+    .slice(0, 120);
+}
+
+export function tracePath(dir, sessionId) {
+  return join(dir, TRACE_DIR_RELPATH, safeId(sessionId) + ".jsonl");
+}
+
+function clip(s, n = 120) {
+  const t = String(s).replace(/\s+/g, " ").trim();
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+
+// A one-line summary of a tool's input: the command, the file, the pattern, or the description. Never the whole input.
+// "skill" (card learn-signals) records a Skill tool call's skill name, so trace-derived signals can count
+// which skills actually get invoked.
+export function detailOf(toolInput) {
+  if (!toolInput || typeof toolInput !== "object") return null;
+  for (const key of ["command", "file_path", "notebook_path", "pattern", "description", "prompt", "url", "skill"]) {
+    if (typeof toolInput[key] === "string" && toolInput[key].trim()) return clip(toolInput[key]);
+  }
+  return null;
+}
+
+// Token usage summed from a Claude Code transcript (one line per content block, each repeating its message's
+// usage, so the largest value per message id counts once). null when the file is missing or has no usage lines.
+export function usageFromTranscript(file) {
+  if (!file || !existsSync(file)) return null;
+  const perMessage = new Map();
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let o;
+    try {
+      o = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const m = o && o.message;
+    if (o.type !== "assistant" || !m || !m.usage) continue;
+    const id = m.id || o.requestId || o.uuid;
+    const u = m.usage;
+    const cur = perMessage.get(id) || { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, model: m.model || null };
+    cur.input = Math.max(cur.input, u.input_tokens || 0);
+    cur.output = Math.max(cur.output, u.output_tokens || 0);
+    cur.cacheRead = Math.max(cur.cacheRead, u.cache_read_input_tokens || 0);
+    cur.cacheWrite = Math.max(cur.cacheWrite, u.cache_creation_input_tokens || 0);
+    if (m.model) cur.model = m.model;
+    perMessage.set(id, cur);
+  }
+  if (perMessage.size === 0) return null;
+  const out = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, messages: perMessage.size, model: null };
+  const models = new Map();
+  for (const v of perMessage.values()) {
+    out.input += v.input;
+    out.output += v.output;
+    out.cacheRead += v.cacheRead;
+    out.cacheWrite += v.cacheWrite;
+    if (v.model) models.set(v.model, (models.get(v.model) || 0) + 1);
+  }
+  out.model = [...models.entries()].sort((a, b) => b[1] - a[1]).map(([m]) => m)[0] || null;
+  return out;
+}
+
+// The line for one hook input. `now` is injectable for tests. `context` (card worker-context-handoff) is the
+// caller's already-computed reading pct for a PostToolUse inside a subagent (scripts/trace.mjs); null when there
+// is none, which is every other event and every caller that doesn't pass it.
+//
+// InstructionsLoaded and PermissionDenied (card learn-signals) record path-only, never-block observation, the
+// same as every other event here: InstructionsLoaded's `detail` is the loaded file's path and its `reason` the
+// matcher's load_reason ("session_start", "path_glob_match", ...) - `file_content` is never read off the input,
+// so it can never end up on the line even by accident. PermissionDenied's `detail` is the denied tool's input
+// (via detailOf, same as a Pre/PostToolUse line), `ok` is forced false, and `reason` is the clipped denial_reason.
+// Every other event's `reason` is null.
+export function traceLine(input, { now = new Date(), context = null } = {}) {
+  const event = input.hook_event_name || null;
+  const response = input.tool_response ?? input.tool_output ?? null;
+  let ok = null;
+  if (event === "PostToolUse") {
+    ok = response === null ? null : !(typeof response === "object" && (response.is_error === true || typeof response.error === "string"));
+  } else if (event === "PermissionDenied") {
+    ok = false;
+  }
+  const tokens = event === "SubagentStop" ? usageFromTranscript(input.agent_transcript_path) : null;
+  let detail = null;
+  let reason = null;
+  if (event === "PreToolUse" || event === "PostToolUse" || event === "PermissionDenied") {
+    detail = detailOf(input.tool_input);
+  }
+  if (event === "PermissionDenied") {
+    reason = typeof input.denial_reason === "string" && input.denial_reason.trim() ? clip(input.denial_reason, 120) : null;
+  } else if (event === "InstructionsLoaded") {
+    detail = typeof input.file_path === "string" && input.file_path ? input.file_path : null;
+    reason = typeof input.load_reason === "string" && input.load_reason ? input.load_reason : null;
+  }
+  return {
+    t: now.toISOString(),
+    event,
+    session: input.session_id || null,
+    agent: input.agent_id || null,
+    agentType: input.agent_type || null,
+    tool: input.tool_name || null,
+    toolUseId: input.tool_use_id || null,
+    detail,
+    ok,
+    tokens,
+    context,
+    reason,
+  };
+}
+
+export function appendTrace(dir, line) {
+  mkdirSync(join(dir, TRACE_DIR_RELPATH), { recursive: true });
+  appendFileSync(tracePath(dir, line.session), JSON.stringify(line) + "\n");
+}
+
+// Every well-formed line of a trace file, in order.
+export function readTrace(file) {
+  const out = [];
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      if (o && typeof o === "object" && o.event) out.push(o);
+    } catch {
+      // a torn line from a crashed hook is skipped, never fatal
+    }
+  }
+  return out;
+}
+
+export function agentLabel(line) {
+  return line.agent ? `${line.agentType || "agent"}:${String(line.agent).slice(0, 8)}` : "main";
+}
+
+// One text line per event: time, who, what.
+export function replay(lines) {
+  return lines.map((l) => {
+    const time = /T(\d\d:\d\d:\d\d)/.exec(l.t || "")?.[1] || "??:??:??";
+    const parts = [time, agentLabel(l).padEnd(22), (l.event || "").padEnd(13)];
+    if (l.tool) parts.push(l.tool);
+    if (l.detail) parts.push(l.detail);
+    if (l.ok === false) parts.push("FAILED");
+    if ((l.event === "InstructionsLoaded" || l.event === "PermissionDenied") && l.reason) parts.push(l.reason);
+    if (l.event === "SubagentStop") parts.push(l.tokens ? `tokens in ${l.tokens.input} out ${l.tokens.output}` : "tokens null");
+    return parts.join("  ").trimEnd();
+  });
+}
+
+// Per agent: events, tool calls by name, failed calls, wall time, and tokens (null unless a SubagentStop reported them).
+export function attribution(lines) {
+  const byAgent = new Map();
+  for (const l of lines) {
+    const key = l.agent || "main";
+    const a = byAgent.get(key) || { agent: key, agentType: l.agent ? l.agentType || null : "main", events: 0, toolCalls: {}, failedCalls: 0, startedAt: l.t || null, endedAt: l.t || null, wallMs: null, tokens: null };
+    a.events += 1;
+    if (l.agentType && l.agent) a.agentType = l.agentType;
+    if (l.event === "PreToolUse" && l.tool) a.toolCalls[l.tool] = (a.toolCalls[l.tool] || 0) + 1;
+    if (l.event === "PostToolUse" && l.ok === false) a.failedCalls += 1;
+    if (l.event === "SubagentStart") a.startedAt = l.t || a.startedAt;
+    if (l.event === "SubagentStop") {
+      a.endedAt = l.t || a.endedAt;
+      a.tokens = l.tokens || null;
+    } else if (l.t && (!a.endedAt || l.t > a.endedAt)) a.endedAt = l.t;
+    if (l.t && (!a.startedAt || l.t < a.startedAt) && l.event !== "SubagentStart") a.startedAt = a.startedAt || l.t;
+    byAgent.set(key, a);
+  }
+  const out = [...byAgent.values()];
+  for (const a of out) {
+    const s = Date.parse(a.startedAt || "");
+    const e = Date.parse(a.endedAt || "");
+    a.wallMs = Number.isFinite(s) && Number.isFinite(e) && e >= s ? e - s : null;
+  }
+  out.sort((x, y) => (x.agent === "main" ? -1 : y.agent === "main" ? 1 : String(x.startedAt).localeCompare(String(y.startedAt))));
+  return out;
+}

package/node_modules/@dougharness/gates/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@dougharness/gates",
+  "version": "1.0.1",
+  "private": true,
+  "description": "Deterministic Claude Code hooks: protected paths, bash guard, secret scan on edits and commands, format on edit, edit-loop detection, stop gate, re-anchor after compaction.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "scripts",
+    "lib",
+    "hooks",
+    ".claude-plugin"
+  ],
+  "engines": {
+    "node": ">=22.16"
+  }
+}

package/node_modules/@dougharness/gates/scripts/edit-loop.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// PostToolUse (Edit|Write|MultiEdit): record edits per file for this session and nudge
+// when the same file is edited `threshold` times inside `windowMinutes`. Also records the
+// set of edited files so the stop gate knows whether anything changed.
+
+import { runHook, allow, addContext } from "../lib/io.mjs";
+import { loadConfig, projectDir } from "../lib/config.mjs";
+import { loadState, saveState } from "../lib/state.mjs";
+import { toProjectRelative, filePathsFromToolInput } from "../lib/paths.mjs";
+
+runHook("edit-loop", async (input) => {
+  const dir = projectDir(input);
+  const cfg = loadConfig(dir);
+  const paths = filePathsFromToolInput(input.tool_input).map((p) => toProjectRelative(dir, p)).filter(Boolean);
+  if (paths.length === 0) return allow();
+
+  const now = Date.now();
+  const windowMs = (cfg.editLoop.windowMinutes || 30) * 60000;
+  const threshold = cfg.editLoop.threshold || 6;
+  const state = loadState(dir, input.session_id);
+  const looping = [];
+
+  for (const rel of paths) {
+    const stamps = (state.edits[rel] || []).filter((t) => now - t < windowMs);
+    stamps.push(now);
+    state.edits[rel] = stamps;
+    if (!state.editedFiles.includes(rel)) state.editedFiles.push(rel);
+    if (stamps.length >= threshold && (stamps.length - threshold) % 3 === 0) looping.push({ rel, n: stamps.length });
+  }
+  saveState(dir, input.session_id, state);
+
+  if (looping.length === 0) return allow();
+  const lines = looping.map(({ rel, n }) => `${rel} has been edited ${n} times in the last ${cfg.editLoop.windowMinutes || 30} minutes.`);
+  return addContext(
+    "PostToolUse",
+    `[doug] Possible edit loop. ${lines.join(" ")} Before editing it again: re-read the whole file, run the relevant test once, ` +
+      `and state in one sentence what is actually wrong. If the approach is not working, say so and propose a different one.`,
+  );
+});