@sabaiway/agent-workflow-kit 1.9.1 → 1.11.0

package/tools/inject-methodology.test.mjs

@@ -1,6 +1,6 @@
-import { describe, it } from 'node:test';
+import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +11,7 @@ import {
   extractSlot,
   ensureSlot,
   reconcileSlot,
+  slotNeedsFill,
   METHODOLOGY_ANCHOR,
   EMPTY_SLOT,
   AGENTS_MD_CAP,
@@ -20,7 +21,47 @@ import {
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const SCRIPT = join(HERE, 'inject-methodology.mjs');
-const FRAGMENT = readFileSync(join(HERE, 'methodology-slot.md'), 'utf8');
+
+// The bounded methodology fragment is read LIVE from the installed engine now (the kit mirror is
+// retired in Plan 3D), so this suite no longer reads a bundled methodology-slot.md. Tests use an
+// inline fragment and, for the live-read CLI cases, an on-the-fly engine fixture that ships exactly
+// this fragment — keeping the kit suite decoupled from the sibling engine's on-disk presence.
+// Single-line (like the canonical fragment) so byte-equality holds in both LF and CRLF documents.
+const FRAGMENT =
+  '> **Workflow methodology (test fixture)** — plan → execute → review. Plans are ephemeral, gitignored, never committed; every Plan ends with a mandatory **Phase: Cleanup**.\n';
+
+// Temp dirs created by the fixtures below — cleaned up once after the whole file.
+const tmpDirs = [];
+after(() => tmpDirs.forEach((d) => rmSync(d, { recursive: true, force: true })));
+
+// A minimal but VALID installed-engine fixture: a methodology-engine capability.json + a SKILL.md
+// whose metadata.version matches it (the validator's authoritative version source when there is no
+// package.json) + the live fragment at references/methodology-slot.md. detectEngine accepts it.
+const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0') => {
+  const dir = mkdtempSync(join(tmpdir(), 'engine-fixture-'));
+  tmpDirs.push(dir);
+  const manifest = {
+    family: 'agent-workflow',
+    schema: 1,
+    name: 'agent-workflow-engine',
+    kind: 'methodology-engine',
+    version,
+    available: true,
+    provides: ['plan'],
+    roles: {},
+  };
+  writeFileSync(join(dir, 'capability.json'), JSON.stringify(manifest, null, 2));
+  writeFileSync(join(dir, 'SKILL.md'), `---\nname: agent-workflow-engine\nmetadata:\n  version: '${version}'\n---\n# engine\n`);
+  mkdirSync(join(dir, 'references'), { recursive: true });
+  writeFileSync(join(dir, 'references', 'methodology-slot.md'), fragment);
+  return dir;
+};
+
+const ENGINE = makeEngineFixture();
+// A path that is guaranteed NOT to be a valid engine — proves the no-op / explicit-override paths
+// never consult the engine, and drives the fail-loud STOP.
+const NO_ENGINE = join(tmpdir(), `definitely-no-engine-${process.pid}`);
+const withEngine = (engineDir) => ({ ...process.env, AGENT_WORKFLOW_ENGINE_DIR: engineDir });
 
 const wrap = (inner) =>
   `# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n${START_MARKER}${inner}${END_MARKER}\n\n## Hard Constraints\n\nsuffix bytes\n`;
@@ -309,7 +350,46 @@ describe('reconcileSlot — ensure + inject-if-empty + cap, as one atomic policy
   });
 });
 
-describe('reconcile CLI — atomic ensure+inject-if-empty+cap on the real filesystem', () => {
+describe('slotNeedsFill — lazy-read predicate (matches reconcileSlot fill decision)', () => {
+  it('present empty slot → true', () => {
+    assert.equal(slotNeedsFill(wrap('\n')), true);
+  });
+  it('markerless legacy with one anchor (insertable empty slot) → true', () => {
+    assert.equal(slotNeedsFill(legacyWithAnchor()), true);
+  });
+  it('present filled/customized slot → false (fragment not needed)', () => {
+    assert.equal(slotNeedsFill(wrap('\nuser notes\n')), false);
+  });
+  it('malformed slot → false (reconcileSlot error path fires, not a fill)', () => {
+    assert.equal(slotNeedsFill(`${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`), false);
+  });
+  it('markerless with no anchor → false (cannot insert; reconcile errors without the engine)', () => {
+    assert.equal(slotNeedsFill('# AGENTS.md\n\nno anchor here\n'), false);
+  });
+
+  // slotNeedsFill and reconcileSlot share the SAME emptiness primitives (ensureSlot + extractSlot), so
+  // the lazy "read the engine only when needed" guard cannot disagree with reconcileSlot's actual fill
+  // decision. Pin that equivalence across representative inputs: needsFill === true  IFF reconcile fills
+  // (reconciled-filled / reconciled-inserted); needsFill === false IFF reconcile does NOT fill
+  // (present-filled / error). This forecloses any future divergence that could silently drop a slot.
+  it('agrees with reconcileSlot across every slot state (no divergence → no silent drop)', () => {
+    const cases = [
+      wrap('\n'), // present empty slot → fill
+      legacyWithAnchor(), // markerless + anchor → insert + fill
+      wrap('\nuser notes\n'), // filled slot → no fill
+      `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`, // malformed → no fill (error)
+      '# AGENTS.md\n\nno anchor here\n', // no anchor → no fill (error)
+    ];
+    for (const text of cases) {
+      const needs = slotNeedsFill(text);
+      const result = reconcileSlot(text, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+      const filled = result.status === 'reconciled-filled' || result.status === 'reconciled-inserted';
+      assert.equal(needs, filled, `slotNeedsFill (${needs}) must match whether reconcile fills (${result.status})`);
+    }
+  });
+});
+
+describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragment LIVE from the engine', () => {
   const withTempAgents = (contents, run) => {
     const dir = mkdtempSync(join(tmpdir(), 'reconcile-cli-'));
     const agents = join(dir, 'AGENTS.md');
@@ -321,35 +401,100 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap on the real filesy
     }
   };
 
-  it('markerless legacy (with anchor) → slot inserted and filled (exit 0)', () => {
+  it('markerless legacy (with anchor) → slot inserted + filled from the live engine fragment (exit 0)', () => {
     withTempAgents(legacyWithAnchor(), (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
       const out = readFileSync(agents, 'utf8');
       assert.equal(findSlot(out).state, 'ok');
       assert.equal(extractSlot(out).trim(), FRAGMENT.trim());
     });
   });
 
-  it('present empty slot → slot filled (exit 0)', () => {
+  it('present empty slot → filled from the live engine fragment (exit 0)', () => {
     withTempAgents(wrap('\n'), (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
       assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), FRAGMENT.trim());
     });
   });
 
-  it('filled/customized slot → file left byte-for-byte untouched', () => {
+  it('filled/customized slot → zero-diff no-op WITHOUT consulting the engine (engine absent, exit 0)', () => {
     const custom = wrap('\nuser notes\n');
     withTempAgents(custom, (agents) => {
-      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      // Engine pointed at a path that does not exist — a filled slot must NOT require it.
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
       assert.equal(readFileSync(agents, 'utf8'), custom);
     });
   });
 
-  it('malformed slot → STOP with non-zero exit, file byte-unchanged', () => {
+  it('present empty slot + engine ABSENT → hard STOP (nonzero) printing the install command, file unchanged', () => {
+    withTempAgents(wrap('\n'), (agents) => {
+      const err = (() => {
+        try {
+          execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+          return null;
+        } catch (e) {
+          return e;
+        }
+      })();
+      assert.ok(err, 'expected a non-zero exit when a fill is needed but the engine is absent');
+      const stderr = String(err.stderr);
+      assert.match(stderr, /methodology engine not found\/invalid/);
+      assert.match(stderr, /npx @sabaiway\/agent-workflow-engine@latest init/);
+      assert.equal(readFileSync(agents, 'utf8'), wrap('\n'), 'no partial write on STOP');
+    });
+  });
+
+  it('explicit [fragment.md] override fills from that file and skips engine resolution (engine absent)', () => {
+    const override = '> custom override fragment line\n';
+    const fdir = mkdtempSync(join(tmpdir(), 'frag-'));
+    tmpDirs.push(fdir);
+    const fpath = join(fdir, 'frag.md');
+    writeFileSync(fpath, override);
+    withTempAgents(wrap('\n'), (agents) => {
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents, fpath], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+      assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), override.trim());
+    });
+  });
+
+  it('malformed slot → STOP with non-zero exit, file byte-unchanged (engine never consulted)', () => {
     const malformed = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
     withTempAgents(malformed, (agents) => {
-      assert.throws(() => execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' }));
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
       assert.equal(readFileSync(agents, 'utf8'), malformed);
     });
   });
+
+  it('legacy inject mode: markerless AGENTS.md → no-op WITHOUT the engine (exit 0)', () => {
+    const markerless = '# AGENTS.md\n\nlegacy, no slot\n';
+    withTempAgents(markerless, (agents) => {
+      execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
+      assert.equal(readFileSync(agents, 'utf8'), markerless);
+    });
+  });
+
+  // Legacy `inject` mode FORCE-OVERWRITES any present (ok) slot — filled or empty — unlike `reconcile`,
+  // which preserves a filled slot. So for an ok slot it genuinely NEEDS the fragment and reads the
+  // engine; the read-on-`state==='ok'` guard is correct (reading only an EMPTY ok slot would inject ''
+  // and WIPE a filled slot). These two tests pin that contract.
+  it('legacy inject mode: a FILLED slot is OVERWRITTEN from the live engine (engine present, exit 0)', () => {
+    const filled = wrap('\nstale user content\n');
+    withTempAgents(filled, (agents) => {
+      execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(ENGINE) });
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim(), 'slot overwritten with the live fragment');
+      assert.ok(!out.includes('stale user content'), 'prior slot content replaced');
+    });
+  });
+
+  it('legacy inject mode: a present (ok) slot + engine ABSENT → hard STOP, file unchanged', () => {
+    const filled = wrap('\nstale user content\n');
+    withTempAgents(filled, (agents) => {
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
+      assert.equal(readFileSync(agents, 'utf8'), filled, 'no partial write on STOP');
+    });
+  });
 });

package/tools/known-footprint.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// known-footprint.mjs — the kit-owned registry of what "hidden mode" must keep out of a repo.
+//
+// Two registries, both holding ANCHORED gitignore patterns (repo-root-relative, leading "/"):
+//   KIT_OWN_PATHS   — the kit's OWN deployed artifacts (AGENTS.md, docs/ai/, the added scripts, the
+//                     attribution settings). Always candidates in hidden mode.
+//   KNOWN_FOOTPRINT — every OTHER AI/agent tool's footprint (Claude skills, Cursor, Windsurf, Gemini,
+//                     Copilot, Aider, Continue, …) that would otherwise leak into a commit. Only the
+//                     ones PRESENT on disk become candidates (no pre-emptive hiding of absent paths).
+//
+// Source of truth is here, not an on-disk manifest (the AD-008 `KNOWN_BACKENDS` pattern): a foreign
+// tool's footprint has no file in the kit tarball to read, so the per-tool facts must live in-tool.
+// The drift-guard test (known-footprint.test.mjs) keeps the registry honest — a frozen snapshot +
+// count sentinel + intrinsic invariants (anchoring, uniqueness, disjointness, no subsumption) — and
+// references/contracts.md carries the human-readable mirror table, kept in sync by review.
+//
+// Pure, dependency-free, Node >= 18. The only fs touch is expandGlob (readdir/stat of a glob parent),
+// injected so the registry stays unit-testable without the real filesystem.
+
+import { readdirSync, statSync } from 'node:fs';
+
+// A typed STOP — a deliberate refusal we surface (never a silent skip, never a fail-open). Shared by
+// the writer tool (hide-footprint.mjs imports it) so both speak one error vocabulary. The codebase's
+// typed-error idiom: Object.assign(new Error(), { code }) — no classes (agent_rules §2.3).
+export const FOOTPRINT_STOP = 'FOOTPRINT_STOP';
+export const stop = (message, fields = {}) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'FootprintStop', code: FOOTPRINT_STOP, ...fields });
+
+// ── registries ────────────────────────────────────────────────────────────────
+
+// The kit's OWN footprint — canonical anchored patterns. `/docs/ai/` subsumes the deployment stamp
+// (`.workflow-version`); the 8 enforcement scripts are enumerated (no bare `/scripts/` — a host repo
+// may have unrelated scripts). `/.claude/settings.json` is carried HIDDEN-ONLY: in hidden mode the
+// kit's own attribution file is a footprint; in visible mode the kit commits it and never runs this
+// tool. It passes the same tracked→ASK classifier, so a project that already commits it gets an ASK,
+// never a silent un-track. `/docs/plans/` + both `.claude/settings*.json` are listed because a pure
+// hidden deploy has no tracked `.gitignore`; the classifier drops any candidate a tracked `.gitignore`
+// already covers, so in a repo that DOES track those ignores they are never re-written.
+export const KIT_OWN_PATHS = [
+  '/AGENTS.md',
+  '/CLAUDE.md',
+  '/docs/ai/',
+  '/scripts/_expect-shim.mjs',
+  '/scripts/archive-changelog.mjs',
+  '/scripts/archive-changelog.test.mjs',
+  '/scripts/archive-issues.mjs',
+  '/scripts/archive-issues.test.mjs',
+  '/scripts/check-docs-size.mjs',
+  '/scripts/check-docs-size.test.mjs',
+  '/scripts/install-git-hooks.mjs',
+  '/docs/plans/',
+  '/.claude/settings.local.json',
+  '/.claude/settings.json',
+];
+
+// Every OTHER tool's footprint. `falsePositiveRisk` flags a name generic/ambiguous enough that a
+// present-but-untracked instance should be ASKed about rather than hidden by default (D-policy A).
+// `glob:true` marks the ONE reviewed wildcard (`/.github/copilot-*`) — it is expanded against the
+// filesystem (expandGlob) to concrete present files before any git probe; never fed to ls-files.
+export const KNOWN_FOOTPRINT = [
+  { pattern: '/.claude/skills/', owner: 'Claude Code', type: 'dir', falsePositiveRisk: false, note: 'local-dev skills; absorbs the AD-013 one-off' },
+  { pattern: '/.cursor/rules/', owner: 'Cursor', type: 'dir', falsePositiveRisk: false, note: 'project rule files' },
+  { pattern: '/.cursorrules', owner: 'Cursor (legacy)', type: 'file', falsePositiveRisk: true, note: 'legacy single-file rules' },
+  { pattern: '/.codeium/', owner: 'Codeium/Windsurf', type: 'dir', falsePositiveRisk: false, note: 'home-scoped launchers live under ~/, out of scope' },
+  { pattern: '/.windsurf/', owner: 'Windsurf (Devin)', type: 'dir', falsePositiveRisk: false, note: 'project config dir' },
+  { pattern: '/.windsurfrules', owner: 'Windsurf', type: 'file', falsePositiveRisk: true, note: 'legacy single-file rules' },
+  { pattern: '/GEMINI.md', owner: 'Gemini/Antigravity', type: 'file', falsePositiveRisk: true, note: 'context file; generic name' },
+  { pattern: '/.antigravity.md', owner: 'Antigravity', type: 'file', falsePositiveRisk: true, note: 'context file' },
+  { pattern: '/.github/copilot-*', owner: 'GitHub Copilot', type: 'file', falsePositiveRisk: true, glob: true, note: 'covers copilot-instructions.md; the one reviewed glob' },
+  { pattern: '/.aider.conf.yml', owner: 'Aider', type: 'file', falsePositiveRisk: false, note: 'config' },
+  { pattern: '/.aider.chat.history.md', owner: 'Aider', type: 'file', falsePositiveRisk: false, note: 'chat history' },
+  { pattern: '/.aider.input.history', owner: 'Aider', type: 'file', falsePositiveRisk: false, note: 'input history' },
+  { pattern: '/.continue/', owner: 'Continue', type: 'dir', falsePositiveRisk: false, note: 'project config dir' },
+];
+
+// ── pure pattern helpers ────────────────────────────────────────────────────────
+
+// Forward-slash normalize (Windows `\` → `/`) — every fs/git path is compared in this canonical form.
+export const normalizeSlashes = (p) => p.replace(/\\/g, '/');
+
+// A pattern naming a directory ends with a trailing "/". Used to derive the type of a bare KIT_OWN
+// pattern (KNOWN_FOOTPRINT entries carry an explicit `type`).
+export const isDirPattern = (pattern) => normalizeSlashes(pattern).endsWith('/');
+
+// Is this an unexpanded glob pattern? (Only `/.github/copilot-*` today — `glob:true` in the registry.)
+export const isGlobPattern = (pattern) => normalizeSlashes(pattern).includes('*');
+
+// Convert an ANCHORED gitignore pattern to a repo-relative probe path for `git ls-files` /
+// `git check-ignore` (both run with cwd = the project dir, so the probe must be repo-relative, NOT
+// the leading-"/" gitignore form which git reads as an absolute path → "outside repository", exit 128).
+// Strips the leading "/", preserves a trailing "/" (dir), rejects traversal, and REFUSES a glob — a
+// glob must be expandGlob'd to concrete files first (never handed to git verbatim).
+export const patternToProbe = (pattern) => {
+  const p = normalizeSlashes(pattern);
+  if (p.includes('*')) throw stop(`refusing to probe an unexpanded glob: ${pattern} (expandGlob it first)`);
+  if (p.split('/').includes('..')) throw stop(`refusing a traversal pattern: ${pattern}`);
+  if (!p.startsWith('/')) throw stop(`pattern is not anchored (must start with "/"): ${pattern}`);
+  return p.slice(1); // keeps a trailing "/" for dir patterns
+};
+
+// Turn a basename glob (`copilot-*`) into an anchored regex. Only a single-level `*` is supported
+// (no `**`, no `/`): split on `*`, regex-escape each literal segment, then join with `.*`.
+const basenameGlobToRegExp = (glob) => {
+  const parts = glob.split('*').map((seg) => seg.replace(/[.+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`^${parts.join('.*')}$`);
+};
+
+// Expand a `glob:true` registry pattern against the filesystem → the anchored canonical patterns of
+// the concrete present FILES it matches (each is then probed/classified on its own). One directory
+// level only: readdir the glob's parent, match basenames, keep regular files. An absent parent →
+// no candidates (empty array); any OTHER fs error → typed STOP (fail-closed, never a silent drop).
+// Is a CONCRETE anchored path (e.g. `/.github/copilot-instructions.md`) a child that a `glob:true`
+// registry entry would match? Recognizes an already-written/consented glob expansion (the concrete
+// file, not the glob pattern) as a pre-existing hide rule — so consent survives a re-run.
+export const matchesKnownGlob = (pattern) => {
+  const p = normalizeSlashes(pattern);
+  return KNOWN_FOOTPRINT.some((e) => {
+    if (!e.glob) return false;
+    const probe = normalizeSlashes(e.pattern).slice(1); // ".github/copilot-*"
+    const slash = probe.lastIndexOf('/');
+    if (slash === -1) return false;
+    const parent = `/${probe.slice(0, slash)}`; // "/.github"
+    const base = probe.slice(slash + 1); // "copilot-*"
+    if (!p.startsWith(`${parent}/`)) return false;
+    const tail = p.slice(parent.length + 1);
+    return !tail.includes('/') && basenameGlobToRegExp(base).test(tail);
+  });
+};
+
+export const expandGlob = (pattern, { dir, readdir = readdirSync, stat = statSync } = {}) => {
+  const p = normalizeSlashes(pattern);
+  if (!p.includes('*')) throw stop(`expandGlob called on a non-glob pattern: ${pattern}`);
+  const probe = p.slice(1); // strip leading "/" → e.g. ".github/copilot-*"
+  const slash = probe.lastIndexOf('/');
+  if (slash === -1) throw stop(`glob must live under a directory (no bare top-level glob): ${pattern}`);
+  const parentRel = probe.slice(0, slash);
+  const baseGlob = probe.slice(slash + 1);
+  if (baseGlob.includes('*') === false) throw stop(`glob has no wildcard in its basename: ${pattern}`);
+  const re = basenameGlobToRegExp(baseGlob);
+  const parentAbs = `${dir}/${parentRel}`;
+  let names;
+  try {
+    names = readdir(parentAbs);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    throw stop(`cannot read glob parent (${err.code ?? 'fs error'}): ${parentAbs}`);
+  }
+  const out = [];
+  for (const name of names) {
+    if (!re.test(name)) continue;
+    let st;
+    try {
+      st = stat(`${parentAbs}/${name}`);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') continue; // raced away — not a present footprint
+      throw stop(`cannot stat glob match (${err.code ?? 'fs error'}): ${parentAbs}/${name}`);
+    }
+    if (st.isFile()) out.push(`/${parentRel}/${name}`);
+  }
+  return out.sort();
+};

package/tools/known-footprint.test.mjs

@@ -0,0 +1,271 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  KIT_OWN_PATHS,
+  KNOWN_FOOTPRINT,
+  FOOTPRINT_STOP,
+  normalizeSlashes,
+  isDirPattern,
+  isGlobPattern,
+  patternToProbe,
+  expandGlob,
+  matchesKnownGlob,
+} from './known-footprint.mjs';
+
+// An ENOENT-typed error, matching the shape Node's fs throws.
+const enoent = () => Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+const eacces = () => Object.assign(new Error('EACCES'), { code: 'EACCES' });
+const fileStat = { isFile: () => true };
+const dirStat = { isFile: () => false };
+
+// The probe form of an anchored pattern, for subsumption/coverage reasoning (strip leading "/").
+const probeOf = (pattern) => normalizeSlashes(pattern).replace(/^\//, '');
+// A pattern's "scope" — the path-prefix it ignores. A glob's scope is its parent directory.
+const scopeOf = (pattern) => {
+  const probe = probeOf(pattern);
+  if (isGlobPattern(pattern)) return `${probe.slice(0, probe.lastIndexOf('/') + 1)}`; // e.g. ".github/"
+  return probe;
+};
+// Does `pattern` (as a gitignore rule) cover the concrete repo-relative `path`?
+const covers = (pattern, path) => {
+  const scope = scopeOf(pattern);
+  return scope.endsWith('/') ? path === scope.slice(0, -1) || path.startsWith(scope) : path === scope;
+};
+
+// ── (a) shape + type enum ───────────────────────────────────────────────────────
+
+describe('KNOWN_FOOTPRINT shape', () => {
+  it('every entry is well-shaped with type ∈ {dir,file}', () => {
+    for (const e of KNOWN_FOOTPRINT) {
+      assert.equal(typeof e.pattern, 'string', `pattern is a string`);
+      assert.equal(typeof e.owner, 'string', `${e.pattern}: owner is a string`);
+      assert.ok(e.type === 'dir' || e.type === 'file', `${e.pattern}: type is dir|file`);
+      assert.equal(typeof e.falsePositiveRisk, 'boolean', `${e.pattern}: falsePositiveRisk is boolean`);
+      assert.equal(typeof e.note, 'string', `${e.pattern}: note is a string`);
+      if ('glob' in e) assert.equal(e.glob, true, `${e.pattern}: glob, when present, is true`);
+    }
+  });
+
+  it('a dir entry ends with "/", a file entry does not (glob excepted)', () => {
+    for (const e of KNOWN_FOOTPRINT) {
+      if (isGlobPattern(e.pattern)) continue;
+      assert.equal(isDirPattern(e.pattern), e.type === 'dir', `${e.pattern}: trailing slash matches type`);
+    }
+  });
+});
+
+// ── (b) uniqueness ────────────────────────────────────────────────────────────────
+
+describe('uniqueness', () => {
+  it('KIT_OWN_PATHS has no duplicate patterns', () => {
+    assert.equal(new Set(KIT_OWN_PATHS).size, KIT_OWN_PATHS.length);
+  });
+  it('KNOWN_FOOTPRINT has no duplicate patterns', () => {
+    const pats = KNOWN_FOOTPRINT.map((e) => e.pattern);
+    assert.equal(new Set(pats).size, pats.length);
+  });
+});
+
+// ── (c) anchoring ─────────────────────────────────────────────────────────────────
+
+describe('anchoring', () => {
+  const allPatterns = [...KIT_OWN_PATHS, ...KNOWN_FOOTPRINT.map((e) => e.pattern)];
+  it('every pattern is anchored (starts with "/") and has no traversal', () => {
+    for (const p of allPatterns) {
+      assert.ok(p.startsWith('/'), `${p}: anchored`);
+      assert.ok(!normalizeSlashes(p).split('/').includes('..'), `${p}: no ".."`);
+    }
+  });
+  it('a bare trailing "*" appears ONLY on a glob:true entry', () => {
+    for (const p of KIT_OWN_PATHS) assert.ok(!p.includes('*'), `KIT_OWN ${p}: no wildcard`);
+    for (const e of KNOWN_FOOTPRINT) {
+      if (e.pattern.includes('*')) assert.equal(e.glob, true, `${e.pattern}: wildcard ⇒ glob:true`);
+    }
+    const globs = KNOWN_FOOTPRINT.filter((e) => e.glob);
+    assert.deepEqual(globs.map((e) => e.pattern), ['/.github/copilot-*'], 'exactly one reviewed glob');
+  });
+});
+
+// ── (d) disjoint registries ───────────────────────────────────────────────────────
+
+describe('disjointness', () => {
+  it('KIT_OWN_PATHS ∩ KNOWN_FOOTPRINT == ∅', () => {
+    const own = new Set(KIT_OWN_PATHS);
+    for (const e of KNOWN_FOOTPRINT) assert.ok(!own.has(e.pattern), `${e.pattern}: not in both`);
+  });
+});
+
+// ── (e) no prefix/subsumption between non-glob patterns (glob exempt) ──────────────
+
+describe('no subsumption', () => {
+  it('no non-glob pattern is an ancestor of another across both arrays', () => {
+    const all = [...KIT_OWN_PATHS, ...KNOWN_FOOTPRINT.map((e) => e.pattern)].filter((p) => !isGlobPattern(p));
+    for (const a of all) {
+      for (const b of all) {
+        if (a === b) continue;
+        // a subsumes b iff a is a directory pattern and b sits under it.
+        if (isDirPattern(a)) {
+          assert.ok(!probeOf(b).startsWith(probeOf(a)), `${a} subsumes ${b} — remove the redundant child`);
+        }
+      }
+    }
+  });
+});
+
+// ── (f) external set must NOT reach the kit's own .claude/settings.json ────────────
+
+describe('external set excludes .claude/settings.json', () => {
+  it('no KNOWN_FOOTPRINT pattern covers .claude/settings.json (KIT_OWN carries it, hidden-only)', () => {
+    for (const e of KNOWN_FOOTPRINT) {
+      assert.ok(!covers(e.pattern, '.claude/settings.json'), `${e.pattern}: must not cover .claude/settings.json`);
+    }
+    // sanity: KIT_OWN intentionally DOES carry it.
+    assert.ok(KIT_OWN_PATHS.includes('/.claude/settings.json'));
+  });
+});
+
+// ── (g) frozen snapshot + count sentinel ──────────────────────────────────────────
+
+describe('frozen snapshot', () => {
+  it('KIT_OWN_PATHS matches the frozen expected set + count', () => {
+    const expected = [
+      '/AGENTS.md',
+      '/CLAUDE.md',
+      '/docs/ai/',
+      '/scripts/_expect-shim.mjs',
+      '/scripts/archive-changelog.mjs',
+      '/scripts/archive-changelog.test.mjs',
+      '/scripts/archive-issues.mjs',
+      '/scripts/archive-issues.test.mjs',
+      '/scripts/check-docs-size.mjs',
+      '/scripts/check-docs-size.test.mjs',
+      '/scripts/install-git-hooks.mjs',
+      '/docs/plans/',
+      '/.claude/settings.local.json',
+      '/.claude/settings.json',
+    ];
+    assert.equal(KIT_OWN_PATHS.length, 14, 'KIT_OWN_PATHS count sentinel — edit deliberately');
+    assert.deepEqual(KIT_OWN_PATHS, expected);
+  });
+
+  it('KNOWN_FOOTPRINT matches the frozen expected pattern set + count', () => {
+    const expected = [
+      '/.claude/skills/',
+      '/.cursor/rules/',
+      '/.cursorrules',
+      '/.codeium/',
+      '/.windsurf/',
+      '/.windsurfrules',
+      '/GEMINI.md',
+      '/.antigravity.md',
+      '/.github/copilot-*',
+      '/.aider.conf.yml',
+      '/.aider.chat.history.md',
+      '/.aider.input.history',
+      '/.continue/',
+    ];
+    assert.equal(KNOWN_FOOTPRINT.length, 13, 'KNOWN_FOOTPRINT count sentinel — edit deliberately');
+    assert.deepEqual(KNOWN_FOOTPRINT.map((e) => e.pattern), expected);
+  });
+});
+
+// ── (h) patternToProbe + expandGlob ───────────────────────────────────────────────
+
+describe('patternToProbe', () => {
+  it('strips the leading "/" and round-trips a file', () => {
+    assert.equal(patternToProbe('/AGENTS.md'), 'AGENTS.md');
+    assert.equal(patternToProbe('/.cursorrules'), '.cursorrules');
+  });
+  it('preserves a trailing "/" for a dir', () => {
+    assert.equal(patternToProbe('/docs/ai/'), 'docs/ai/');
+    assert.equal(patternToProbe('/.claude/skills/'), '.claude/skills/');
+  });
+  it('normalizes Windows back-slashes', () => {
+    assert.equal(patternToProbe('\\docs\\ai\\'), 'docs/ai/');
+  });
+  it('STOPs on a glob pattern (must expandGlob first)', () => {
+    assert.throws(() => patternToProbe('/.github/copilot-*'), (e) => e.code === FOOTPRINT_STOP);
+  });
+  it('STOPs on traversal', () => {
+    assert.throws(() => patternToProbe('/x/../y'), (e) => e.code === FOOTPRINT_STOP);
+  });
+  it('STOPs on an unanchored pattern', () => {
+    assert.throws(() => patternToProbe('AGENTS.md'), (e) => e.code === FOOTPRINT_STOP);
+  });
+});
+
+describe('expandGlob', () => {
+  const dir = '/repo';
+  const entries = {
+    '/repo/.github': ['copilot-instructions.md', 'copilot-setup-steps.yml', 'copilot-agents', 'workflows', 'README.md'],
+  };
+  const kinds = {
+    '/repo/.github/copilot-instructions.md': fileStat,
+    '/repo/.github/copilot-setup-steps.yml': fileStat,
+    '/repo/.github/copilot-agents': dirStat, // matches the glob but is a directory → excluded
+    '/repo/.github/workflows': dirStat,
+    '/repo/.github/README.md': fileStat,
+  };
+  const readdir = (p) => {
+    if (p in entries) return entries[p];
+    throw enoent();
+  };
+  const stat = (p) => {
+    if (p in kinds) return kinds[p];
+    throw enoent();
+  };
+
+  it('matches only the concrete present FILES under the parent (dirs + non-matches excluded)', () => {
+    assert.deepEqual(expandGlob('/.github/copilot-*', { dir, readdir, stat }), [
+      '/.github/copilot-instructions.md',
+      '/.github/copilot-setup-steps.yml',
+    ]);
+  });
+  it('an absent parent dir → no candidates', () => {
+    assert.deepEqual(expandGlob('/.github/copilot-*', { dir: '/empty', readdir, stat }), []);
+  });
+  it('a non-ENOENT readdir error → STOP (never a silent drop)', () => {
+    const boom = () => { throw eacces(); };
+    assert.throws(() => expandGlob('/.github/copilot-*', { dir, readdir: boom, stat }), (e) => e.code === FOOTPRINT_STOP);
+  });
+  it('STOPs when called on a non-glob pattern', () => {
+    assert.throws(() => expandGlob('/AGENTS.md', { dir, readdir, stat }), (e) => e.code === FOOTPRINT_STOP);
+  });
+});
+
+// ── small pure helpers ────────────────────────────────────────────────────────────
+
+describe('source hygiene', () => {
+  it('the shipped hidden-mode tools contain no NUL bytes (text-safe; never classified binary)', () => {
+    for (const f of ['known-footprint.mjs', 'hide-footprint.mjs']) {
+      const src = readFileSync(fileURLToPath(new URL(`./${f}`, import.meta.url)), 'utf8');
+      assert.ok(!src.includes('\u0000'), `${f} must not contain a NUL byte`);
+    }
+  });
+});
+
+describe('matchesKnownGlob', () => {
+  it('recognizes a concrete child of a glob:true entry', () => {
+    assert.equal(matchesKnownGlob('/.github/copilot-instructions.md'), true);
+    assert.equal(matchesKnownGlob('/.github/copilot-setup-steps.yml'), true);
+  });
+  it('rejects a non-matching sibling, a nested path, and a non-glob registry pattern', () => {
+    assert.equal(matchesKnownGlob('/.github/dependabot.yml'), false, 'sibling not matching the glob');
+    assert.equal(matchesKnownGlob('/.github/copilot/extra.md'), false, 'one directory level only');
+    assert.equal(matchesKnownGlob('/AGENTS.md'), false, 'a registry pattern is not a glob child');
+  });
+});
+
+describe('pure helpers', () => {
+  it('normalizeSlashes converts back-slashes', () => assert.equal(normalizeSlashes('a\\b\\c'), 'a/b/c'));
+  it('isDirPattern keys on a trailing slash', () => {
+    assert.equal(isDirPattern('/docs/ai/'), true);
+    assert.equal(isDirPattern('/AGENTS.md'), false);
+  });
+  it('isGlobPattern detects a wildcard', () => {
+    assert.equal(isGlobPattern('/.github/copilot-*'), true);
+    assert.equal(isGlobPattern('/AGENTS.md'), false);
+  });
+});