@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/lint_framework_leakage.ts

@@ -148,19 +148,19 @@ const CROSS_STACK_HINTS: Record<string, string[]> = {
     ruby: ['\\bRails\\b', '\\bbin/rails\\b', '\\bGemfile\\b', '\\bbundle exec\\b'],
     python: ['\\bDjango\\b', '\\bFastAPI\\b', '\\bFlask\\b', '\\bpoetry\\b',
         '\\buv (add|sync|run|pip)\\b', '\\bvenv\\b', '\\bPydantic\\b', '\\bJinja\\b',
-        'docs\\.python\\.org'],
+        'docs\\.python\\.org', '\\bPython\\b'],
     node: ['\\bExpress\\b', '\\bNext\\.?js\\b', '\\bNode\\.?js\\b', '\\bnpx\\b',
         '\\bvitest\\b', '\\bjest\\b', '\\beslint\\b', '\\bprettier\\b',
         '\\bReact\\b', '\\bVue\\b', '\\bNestJS\\b', '\\bTypeScript\\b',
         '\\btsc\\b', '\\bzod\\b', '\\bPrisma\\b', '\\bTailwind\\b',
         '\\bTurborepo\\b', '\\bclass-validator\\b', '\\bInertia\\b',
         '\\bJSX\\b', '\\bNx\\b',
-        '\\.tsx?\\b', 'typescriptlang\\.org'],
+        '\\.tsx?\\b', 'typescriptlang\\.org', '\\bTS\\b', '\\bJS\\b'],
     go: ['\\bgo (test|build|run|mod)\\b', '\\bgolangci-lint\\b', '\\bGoLand\\b',
         '\\bGolang\\b', '\\bgo\\.dev\\b'],
     rust: ['\\bcargo (test|build|run|check|fmt|clippy|add|update)\\b',
         '\\bClippy\\b', '\\brustfmt\\b', '\\bCargo\\.toml\\b',
-        'rust-lang\\.org'],
+        'rust-lang\\.org', '\\bRust\\b'],
     dotnet: ['\\bdotnet (test|build|run|add|restore)\\b', '\\b\\.NET\\b'],
     java: ['\\bSpring\\b', '\\bmvn (test|clean|install|package)\\b',
         '\\bgradle\\b', '\\bMaven\\b'],
@@ -168,6 +168,20 @@ const CROSS_STACK_HINTS: Record<string, string[]> = {
     // are hit patterns; these are window-only hints so a JS/Python hit next
     // to plain-language PHP mentions self-suppresses as cross-stack docs.
     php: ['\\bvendor/', '\\bPHP\\b'],
+    // Bare LANGUAGE names (Python / Rust / TS / JS above) are the same class of
+    // window-only hint the `php` family already had, and their absence was an
+    // asymmetry, not a policy: a checklist row naming "PHP typed properties +
+    // declare(strict_types=1), TS strict, Python type hints, Go / Rust" — five
+    // ecosystems on ONE line, the rule's textbook "multi-stack peers" case —
+    // matched the PHP hit pattern and found no cross-stack hint, because only
+    // PHP had a plain-language entry. So the linter flagged the exact shape
+    // framework-neutrality documents as allowed.
+    //
+    // `\bGo\b` is deliberately NOT added. These hints SUPPRESS, so an
+    // over-broad one hides real leakage — and "go to" / "go ahead" would fire
+    // constantly in prose. Golang / `go test|build|run|mod` / go.dev stay the
+    // Go signals; a Go-only line with none of those is not self-evidently
+    // cross-stack anyway.
     // Polyglot-runner pseudo-family: a Taskfile/Makefile mention marks the
     // window as multi-stack tooling documentation (runner files are
     // ecosystem-neutral by definition).

package/src/scripts/lint_framework_leakage_allowlist.json

@@ -116,6 +116,38 @@
         185
       ],
       "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "lines": [
+        228,
+        231,
+        239,
+        243
+      ],
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/image-editing/SKILL.md",
+      "lines": [
+        48
+      ],
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
+    },
+    {
+      "file": "src/skills/image-generation/SKILL.md",
+      "lines": [
+        45
+      ],
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
+    },
+    {
+      "file": "src/skills/prompt-engineering-image/SKILL.md",
+      "lines": [
+        74,
+        115
+      ],
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     }
   ]
 }

package/src/scripts/lint_governed_writes.ts

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+/**
+ * lint_governed_writes — flag direct filesystem writes to protected
+ * ledger/governance surfaces that bypass the sanctioned write path.
+ *
+ * Scans: src/scripts/**\/*.ts (excluding *.test.ts and the atomic-write
+ * primitive itself, _lib/fs_atomic.ts, which is the sanctioned layer this
+ * lint measures bypasses of).
+ *
+ * Protected surfaces (each carries its own write policy):
+ *   - docs/CLAIMS.md (claims ledger) — `always-forbidden`: ANY direct
+ *     fs write/append call referencing this path is a violation; the
+ *     ledger is only ever mutated via `write_atomic` from
+ *     `src/scripts/_lib/fs_atomic.ts` (which this lint does not scan, and
+ *     whose call name — `write_atomic` — never matches the banned-call
+ *     patterns below, so a compliant writer is naturally clean).
+ *   - agents/memory/intake/ (append-only signal JSONL) — `append-only`:
+ *     an APPEND call (appendFileSync / fs.promises.appendFile /
+ *     createWriteStream with an `'a'` flag) is the sanctioned operation;
+ *     only a REWRITE call is a violation.
+ *   - agents/runtime/state/audit/ (append-only audit-log-v1 JSONL) —
+ *     `append-only`, same split as above.
+ *
+ * Banned call shapes (rewrite family): fs.writeFileSync(),
+ * fs.promises.writeFile(), fs.createWriteStream() without an append flag —
+ * each also matched via a bare destructured import (writeFileSync(...)).
+ * Banned call shapes (append family, sanctioned on append-only surfaces,
+ * always a violation on always-forbidden surfaces): fs.appendFileSync(),
+ * fs.promises.appendFile(), fs.createWriteStream() with `{ flags: 'a' }`.
+ *
+ * A call only counts against a surface when the surface's path fragment
+ * appears as a string/template literal INSIDE that call's own argument
+ * list (matched by balanced-paren scanning, so multi-line call arguments
+ * are captured) — a path built up through an unrelated variable (no
+ * literal in the call's own arguments) is not flagged; that is a known,
+ * deliberate scope limit of a static, zero-runtime-cost lint.
+ *
+ * Inline-ignore: add a comment on the same or previous line:
+ *   lint-governed-writes-disable-next-line [-- reason]
+ *   lint-governed-writes-disable-line [-- reason]
+ *   lint-governed-writes-disable-file [-- reason]  (top of file)
+ *
+ * Exit codes: 0 = clean, 2 = findings present, 1 = internal error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(_HERE, "..", "..");
+export const SCRIPTS_DIR = path.join(REPO_ROOT, "src", "scripts");
+
+// ---------------------------------------------------------------------------
+// Protected surfaces
+// ---------------------------------------------------------------------------
+type SurfacePolicy = "always-forbidden" | "append-only";
+
+interface ProtectedSurface {
+  id: string;
+  fragment: string;
+  policy: SurfacePolicy;
+}
+
+// No canonical bench-report index file was found under src/scripts at
+// authoring time (no writer builds a single "bench index" registry path) —
+// see the lint's own docstring history / task report. If one is added
+// later, append it here with the matching policy.
+const PROTECTED_SURFACES: ProtectedSurface[] = [
+  { id: "claims-ledger", fragment: "docs/CLAIMS.md", policy: "always-forbidden" },
+  { id: "memory-intake", fragment: "agents/memory/intake/", policy: "append-only" },
+  { id: "audit-log", fragment: "agents/runtime/state/audit/", policy: "append-only" },
+];
+
+// ---------------------------------------------------------------------------
+// Banned call-shape patterns
+// ---------------------------------------------------------------------------
+type CallFamily = "rewrite" | "append" | "stream";
+
+interface CallPattern {
+  name: string;
+  family: CallFamily;
+  source: string; // regex source, compiled fresh per exec loop (stateful lastIndex)
+}
+
+const CALL_PATTERNS: CallPattern[] = [
+  { name: "fs.writeFileSync", family: "rewrite", source: "\\b(?:fs\\.)?writeFileSync\\s*\\(" },
+  { name: "fs.promises.writeFile", family: "rewrite", source: "\\bfs\\.promises\\.writeFile\\s*\\(" },
+  { name: "fs.appendFileSync", family: "append", source: "\\b(?:fs\\.)?appendFileSync\\s*\\(" },
+  { name: "fs.promises.appendFile", family: "append", source: "\\bfs\\.promises\\.appendFile\\s*\\(" },
+  { name: "fs.createWriteStream", family: "stream", source: "\\b(?:fs\\.)?createWriteStream\\s*\\(" },
+];
+
+const APPEND_FLAG_RE = /flags\s*:\s*['"]a['"]/;
+
+interface Finding {
+  file: string;
+  line: number;
+  surface: string;
+  call: string;
+  policy: SurfacePolicy;
+  snippet: string;
+}
+
+// ---------------------------------------------------------------------------
+// Balanced-paren call-argument extraction
+// ---------------------------------------------------------------------------
+/**
+ * Given the index of the opening `(` of a call, return the substring from
+ * that `(` through its matching `)` (inclusive) — the call's full argument
+ * list, spanning multiple lines when the call is formatted that way.
+ * String/template literals are tracked so a stray paren inside a quoted
+ * value never desyncs the depth count.
+ */
+function extractCallArgsRegion(content: string, openParenIdx: number): string {
+  let depth = 0;
+  let inString: string | null = null;
+  let escaped = false;
+  for (let i = openParenIdx; i < content.length; i++) {
+    const ch = content[i] as string;
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === inString) {
+        inString = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      inString = ch;
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+    } else if (ch === ")") {
+      depth--;
+      if (depth === 0) {
+        return content.slice(openParenIdx, i + 1);
+      }
+    }
+  }
+  return content.slice(openParenIdx);
+}
+
+function lineOfIndex(content: string, idx: number): number {
+  let line = 1;
+  for (let i = 0; i < idx; i++) {
+    if (content[i] === "\n") line++;
+  }
+  return line;
+}
+
+// ---------------------------------------------------------------------------
+// Inline-ignore parsing (mirrors lint_output_slop's convention)
+// ---------------------------------------------------------------------------
+type IgnoreScope = "file" | "line" | "next-line";
+interface Ignore {
+  scope: IgnoreScope;
+  lineNum?: number;
+}
+
+function parseIgnores(lines: string[]): Ignore[] {
+  const ignores: Ignore[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (/lint-governed-writes-disable-file/i.test(line)) {
+      ignores.push({ scope: "file" });
+    }
+    if (/lint-governed-writes-disable-line/i.test(line)) {
+      ignores.push({ scope: "line", lineNum: i + 1 });
+    }
+    if (/lint-governed-writes-disable-next-line/i.test(line)) {
+      ignores.push({ scope: "next-line", lineNum: i + 2 });
+    }
+  }
+  return ignores;
+}
+
+function isIgnored(ignores: Ignore[], lineNum: number): boolean {
+  for (const ig of ignores) {
+    if (ig.scope === "file") return true;
+    if (ig.scope === "line" && ig.lineNum === lineNum) return true;
+    if (ig.scope === "next-line" && ig.lineNum === lineNum) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Per-file scanning
+// ---------------------------------------------------------------------------
+export function scanContent(content: string, relFile: string): Finding[] {
+  const findings: Finding[] = [];
+  const lines = content.split("\n");
+  const ignores = parseIgnores(lines);
+
+  for (const pat of CALL_PATTERNS) {
+    const re = new RegExp(pat.source, "g");
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(content)) !== null) {
+      const openParenIdx = m.index + m[0].length - 1;
+      const region = extractCallArgsRegion(content, openParenIdx);
+
+      let kind: "rewrite" | "append";
+      if (pat.family === "stream") {
+        kind = APPEND_FLAG_RE.test(region) ? "append" : "rewrite";
+      } else {
+        kind = pat.family;
+      }
+
+      const lineNum = lineOfIndex(content, m.index);
+      if (isIgnored(ignores, lineNum)) continue;
+
+      for (const surface of PROTECTED_SURFACES) {
+        if (!region.includes(surface.fragment)) continue;
+        const isViolation =
+          surface.policy === "always-forbidden" ||
+          (surface.policy === "append-only" && kind === "rewrite");
+        if (!isViolation) continue;
+
+        findings.push({
+          file: relFile,
+          line: lineNum,
+          surface: surface.id,
+          call: pat.name,
+          policy: surface.policy,
+          snippet: (lines[lineNum - 1] ?? "").trim().slice(0, 160),
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// File discovery
+// ---------------------------------------------------------------------------
+const EXCLUDED_RELATIVE_FILES = new Set<string>(["_lib/fs_atomic.ts"]);
+
+function* walkTsFiles(dir: string, root: string): Generator<string> {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === "dist") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkTsFiles(full, root);
+      continue;
+    }
+    if (!entry.name.endsWith(".ts")) continue;
+    if (entry.name.endsWith(".test.ts")) continue;
+    const rel = path.relative(root, full).split(path.sep).join("/");
+    if (EXCLUDED_RELATIVE_FILES.has(rel)) continue;
+    yield full;
+  }
+}
+
+/** Scan every eligible `.ts` file under `scriptsDir`. */
+export function scanScriptsDir(scriptsDir: string): Finding[] {
+  const findings: Finding[] = [];
+  for (const file of walkTsFiles(scriptsDir, scriptsDir)) {
+    let content: string;
+    try {
+      content = fs.readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    const rel = path.relative(scriptsDir, file).split(path.sep).join("/");
+    findings.push(...scanContent(content, rel));
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    process.stdout.write(
+      "usage: lint_governed_writes [--json] [--quiet]\n" +
+        "  Flags direct fs write/append calls to protected ledger/governance\n" +
+        "  surfaces (docs/CLAIMS.md, agents/memory/intake/, agents/runtime/state/audit/)\n" +
+        "  that bypass the sanctioned atomic-write layer or the append-only contract.\n" +
+        "  Exit 2 on any finding, 0 clean.\n",
+    );
+    return 0;
+  }
+
+  const jsonMode = argv.includes("--json");
+  const quiet = argv.includes("--quiet");
+
+  const findings = scanScriptsDir(SCRIPTS_DIR);
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(findings, null, 2) + "\n");
+    return findings.length > 0 ? 2 : 0;
+  }
+
+  if (findings.length === 0) {
+    if (!quiet) {
+      process.stdout.write(
+        "✅  lint_governed_writes: clean — no direct writes to protected surfaces found.\n",
+      );
+    }
+    return 0;
+  }
+
+  for (const f of findings) {
+    process.stdout.write(
+      `❌  ${f.file}:${f.line} [${f.surface}/${f.policy}] ${f.call} — ${f.snippet}\n`,
+    );
+  }
+  process.stdout.write(
+    `\nlint_governed_writes: ${findings.length} finding(s). Route the write through ` +
+      "write_atomic (src/scripts/_lib/fs_atomic.ts) or the surface's sanctioned append " +
+      "call, or use lint-governed-writes-disable-next-line -- reason.\n",
+  );
+  return 2;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention — importing this
+// module for its exports, e.g. from a test, never triggers a CLI run).
+if (process.argv[1] !== undefined) {
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+    if (here === argv1) {
+      process.exit(main());
+    }
+  } catch {
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+      process.exit(main());
+    }
+  }
+}

package/src/scripts/lint_hidden_unicode.ts

@@ -342,7 +342,13 @@ export function main(argv: readonly string[] | null = null): number {
     return sl.report(findings, { check_label: 'hidden-unicode' });
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/lint_mcp_registry_manifest.ts

@@ -33,6 +33,8 @@ const SCHEMA = path.join(ROOT, 'docs', 'contracts', 'mcp-registry-manifest.schem
 const MANIFEST = path.join(ROOT, 'dist', 'mcp', 'registry-manifest.json');
 const ROW_MD = path.join(ROOT, 'dist', 'mcp', 'awesome-mcp-servers.row.md');
 const CF_JSON = path.join(ROOT, 'dist', 'mcp', 'mcp-cloudflare-catalogue.json');
+const SERVER_JSON = path.join(ROOT, 'dist', 'mcp', 'server.json');
+const PKG_FILE = path.join(ROOT, 'package.json');
 
 function _relToRoot(p: string): string {
     return path.relative(ROOT, p);
@@ -293,7 +295,7 @@ function main(argv: readonly string[]): number {
         throw e;
     }
 
-    for (const p of [SCHEMA, MANIFEST, ROW_MD, CF_JSON]) {
+    for (const p of [SCHEMA, MANIFEST, ROW_MD, CF_JSON, SERVER_JSON]) {
         if (!fs.existsSync(p)) {
             return _fail(`missing: ${_relToRoot(p)}`);
         }
@@ -324,6 +326,29 @@ function main(argv: readonly string[]): number {
         return _fail(`mcp-cloudflare-catalogue.json: ${(e as Error).message}`);
     }
 
+    // Official-registry payload (road-to-credible-install Phase 3): valid
+    // JSON, reverse-DNS name matching package.json `mcpName`, and version
+    // equal to package.json.version (the CI version-equality gate).
+    let server_payload: JsonObject;
+    try {
+        server_payload = JSON.parse(fs.readFileSync(SERVER_JSON, 'utf-8')) as JsonObject;
+    } catch (e) {
+        return _fail(`server.json: ${(e as Error).message}`);
+    }
+    const pkg_for_gate = JSON.parse(fs.readFileSync(PKG_FILE, 'utf-8')) as JsonObject;
+    if (server_payload['version'] !== pkg_for_gate['version']) {
+        return _fail(
+            `server.json version (${String(server_payload['version'])}) != package.json version ` +
+                `(${String(pkg_for_gate['version'])}) — re-run build:mcp-manifest`,
+        );
+    }
+    if (server_payload['name'] !== pkg_for_gate['mcpName']) {
+        return _fail(
+            `server.json name (${String(server_payload['name'])}) != package.json mcpName ` +
+                `(${String(pkg_for_gate['mcpName'])})`,
+        );
+    }
+
     if (!args.quiet) {
         const registries = (manifest as JsonObject)['registries'];
         const count = Array.isArray(registries) ? registries.length : 0;

package/src/scripts/lint_memory_tripwire.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Personal-context tripwire over TRACKED memory files — invariant 3 of
+ * ADR-130 (`subject` axis, road-to-reachable-code-memory Phase 8).
+ *
+ * Hand-authored first-person / preference vocabulary (DE+EN) that indicates
+ * a `subject: user` record leaked into a tracked project artifact. On a hit
+ * it HALTS (exit 1) and NEVER rewrites — a human decides.
+ *
+ * ── Honest-null verdict (pre-registered in the roadmap, applied 2026-07-27):
+ * `--history` scanned the FULL git history of agents/memory/** at cut time —
+ * see the run record in agents/evidence/reports/spike-reachable-code-memory-s0.md.
+ * Per the pre-registration, ZERO fires across the full history means
+ * invariant 3 is UNFOUNDED: this script is retained as evidence + an
+ * on-demand tool, but it is deliberately NOT wired into CI; invariants 1–2
+ * (structural: lint_store_boundary + the memory_signal provenance gate)
+ * carry the boundary. A non-zero history result at cut time would have
+ * wired it as a vitest gate instead.
+ *
+ * Exit codes: 0 clean · 1 hits · 2 usage · 3 internal.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Tracked memory surfaces the tripwire watches. */
+export const TRACKED_GLOB_ROOT = 'agents/memory';
+
+/**
+ * Hand-authored personal-context vocabulary, DE+EN. Deliberately narrow:
+ * first-person preference/identity statements — not every "I" (change-log
+ * prose like "I/O" or quoted user feedback in an incident record must not
+ * trip). Word-boundary anchored; case-insensitive.
+ */
+export const TRIPWIRE_PATTERNS: readonly RegExp[] = [
+    // EN — first-person preference / identity
+    /\bI (?:prefer|like|dislike|hate|want|always use|never use)\b/i,
+    /\bmy (?:name|email|address|phone|password|birthday|salary)\b/i,
+    /\bcall me\b/i,
+    // DE — first-person preference / identity (Du-form package: user prose)
+    /\bich (?:bevorzuge|mag|hasse|will|möchte|nutze immer|nutze nie)\b/i,
+    /\bmein[e]? (?:name|e-?mail|adresse|telefonnummer|passwort|geburtstag|gehalt)\b/i,
+    /\bnenn mich\b/i,
+];
+
+export interface Hit {
+    file: string;
+    line: number;
+    pattern: string;
+    /** commit sha for --history hits; 'worktree' otherwise. */
+    ref: string;
+}
+
+export function scanText(text: string, file: string, ref: string): Hit[] {
+    const hits: Hit[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        for (const re of TRIPWIRE_PATTERNS) {
+            if (re.test(lines[i]!)) {
+                hits.push({ file, line: i + 1, pattern: re.source, ref });
+                break;
+            }
+        }
+    }
+    return hits;
+}
+
+function _git(root: string, args: string[]): string {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+
+/** Scan the current worktree's tracked memory files. */
+export function scanWorktree(root: string): Hit[] {
+    const out: Hit[] = [];
+    let files: string[];
+    try {
+        files = _git(root, ['ls-files', TRACKED_GLOB_ROOT]).split('\n').filter(Boolean);
+    } catch {
+        return out;
+    }
+    for (const f of files) {
+        const p = path.join(root, f);
+        if (!fs.existsSync(p)) continue;
+        out.push(...scanText(fs.readFileSync(p, 'utf8'), f, 'worktree'));
+    }
+    return out;
+}
+
+/** Scan EVERY historical version of every tracked memory file (all commits). */
+export function scanHistory(root: string): { hits: Hit[]; commits: number; blobs: number } {
+    const shas = _git(root, ['log', '--all', '--pretty=%H', '--', TRACKED_GLOB_ROOT])
+        .split('\n')
+        .filter(Boolean);
+    const hits: Hit[] = [];
+    const seenBlobs = new Set<string>();
+    let blobs = 0;
+    for (const sha of shas) {
+        let listing: string;
+        try {
+            listing = _git(root, ['ls-tree', '-r', sha, '--', TRACKED_GLOB_ROOT]);
+        } catch {
+            continue;
+        }
+        for (const row of listing.split('\n').filter(Boolean)) {
+            // <mode> blob <hash>\t<path>
+            const m = /^\d+ blob ([0-9a-f]+)\t(.+)$/.exec(row);
+            if (!m) continue;
+            const [, blob, file] = m;
+            if (seenBlobs.has(blob!)) continue;
+            seenBlobs.add(blob!);
+            blobs++;
+            let content: string;
+            try {
+                content = _git(root, ['cat-file', 'blob', blob!]);
+            } catch {
+                continue;
+            }
+            hits.push(...scanText(content, file!, sha.slice(0, 10)));
+        }
+    }
+    return { hits, commits: shas.length, blobs };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    let root = REPO_ROOT;
+    let history = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i]!;
+        if (a === '--root') root = argv[++i] ?? root;
+        else if (a.startsWith('--root=')) root = a.slice('--root='.length);
+        else if (a === '--history') history = true;
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_memory_tripwire [--root ROOT] [--history]\n');
+            return 0;
+        } else {
+            process.stderr.write(`lint_memory_tripwire: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+    try {
+        if (history) {
+            const { hits, commits, blobs } = scanHistory(root);
+            process.stdout.write(
+                `scanned ${commits} commit(s), ${blobs} unique blob(s) under ${TRACKED_GLOB_ROOT}\n`,
+            );
+            if (hits.length === 0) {
+                process.stdout.write('✅  zero tripwire fires across the full history.\n');
+                return 0;
+            }
+            for (const h of hits) {
+                process.stdout.write(`  🔴 ${h.ref} ${h.file}:${h.line}  (pattern: ${h.pattern})\n`);
+            }
+            process.stdout.write(`❌  ${hits.length} fire(s). HALT — never rewrite; a human decides.\n`);
+            return 1;
+        }
+        const hits = scanWorktree(root);
+        if (hits.length === 0) {
+            process.stdout.write('✅  tripwire clean on tracked memory files.\n');
+            return 0;
+        }
+        for (const h of hits) {
+            process.stdout.write(`  🔴 ${h.file}:${h.line}  (pattern: ${h.pattern})\n`);
+        }
+        process.stdout.write(`❌  ${hits.length} fire(s). HALT — never rewrite; a human decides.\n`);
+        return 1;
+    } catch (exc) {
+        process.stderr.write(`lint_memory_tripwire: internal error: ${String(exc)}\n`);
+        return 3;
+    }
+}
+
+const _isMain = (() => {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return pathToFileURL(fs.realpathSync(path.resolve(process.argv[1]))).href === import.meta.url;
+    } catch {
+        return pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+    }
+})();
+if (_isMain) {
+    process.exit(main());
+}