@boyingliu01/xp-gate 0.31.3 → 0.32.0

package/lib/doctor-tui.js

@@ -117,38 +117,128 @@ function compareSemver(a, b) {
   return 0;
 }
 
+/**
+ * Every skills directory `xp-gate init` deploys to, derived from
+ * PLATFORM_PROFILES so the platform-to-directory mapping has one source of
+ * truth. A hardcoded copy here would drift the moment a platform is added
+ * (Delphi R1 MA-01).
+ *
+ * init deploys to all of these at once, so doctor has to verify all of them —
+ * resolving a single "current" platform silently left the others unchecked
+ * (#635). `.dsh` is included because the package ships `plugins/dsh` and
+ * `sync-package-content.js` treats `dsh` as a first-class platform, even
+ * though `detectPlatform()` never returns it.
+ *
+ * Resolved through getSkillsDirs() at call time: the home directory and the
+ * profile list are read lazily, and tests reassign process.env.HOME.
+ *
+ * @returns {Array<{platform: string, dir: string}>}
+ */
+function skillsDeployTargets() {
+  const { PLATFORM_PROFILES, getSkillsDirs } = require('./detect-deps.js');
+  return Object.keys(PLATFORM_PROFILES).map((platform) => ({
+    platform,
+    // skillsDirs[0] is the skills directory; [1] is the broader platform dir.
+    dir: getSkillsDirs(platform)[0],
+  }));
+}
+
+/**
+ * List the skill names actually present in a skills directory.
+ *
+ * A skill counts as installed when `<dir>/<name>/SKILL.md` exists — the same
+ * shape `install-skill` writes. Returns [] when the directory is missing or
+ * unreadable; a missing directory is "not deployed here", not an error.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function listInstalledSkillNames(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+    .map((e) => e.name)
+    .sort();
+}
+
 /**
  * Check 9: Installed skills vs package-bundled skills (#332).
  * Uses semver version comparison on SKILL.md frontmatter when available;
  * falls back to byte-for-byte content comparison for skills without version field.
+ *
+ * The skill list comes from the filesystem, not from `config.installedSkills`:
+ * `xp-gate init` never writes that field, so keying off it made this check
+ * report "No skills installed" on a fully deployed machine and return before
+ * touching disk (#635). An explicit `config.installedSkills` is still honoured
+ * when present, so callers and older tests keep their behaviour.
+ *
  * @param {object} config
  * @param {Array} checks
  * @returns {number} issue count
  */
 function diagnoseInstalledSkills(config, checks) {
-  const installedSkills = config.installedSkills || {};
-  const skillNames = Object.keys(installedSkills);
-  if (skillNames.length === 0) {
-    checks.push({ name: 'Installed skills', status: 'SKIP', detail: 'No skills installed' });
-    return 0;
-  }
-
   const bundledSkillsDir = path.join(PKG_DIR, 'skills');
   if (!fs.existsSync(bundledSkillsDir)) {
     checks.push({ name: 'Installed skills', status: 'SKIP', detail: 'Package skills dir not found' });
     return 0;
   }
 
+  const explicit = config && config.installedSkills ? Object.keys(config.installedSkills) : [];
+  const targets = skillsDeployTargets();
+
+  // An explicit `installedSkills` list is a caller saying "check THIS list, for
+  // THIS platform" — legacy single-target behaviour, kept so existing callers
+  // and their tests retain an unchanged contract (Delphi R1 MA-02).
+  //
+  // The asymmetry with the default path below is deliberate and load-bearing:
+  // the explicit list names no directory, so a platform still has to be
+  // inferred, and silently checking a different platform's directory than the
+  // caller meant would be worse than checking one. `xp-gate init` never writes
+  // this field, so in practice doctor takes the filesystem path below.
   const platform = detectPlatform();
-  let userSkillsDir;
-  if (platform === 'qoder') {
-    userSkillsDir = path.join(HOME_DIR, '.qoder', 'skills');
-  } else if (platform === 'claude-code') {
-    userSkillsDir = path.join(HOME_DIR, '.claude', 'skills');
-  } else {
-    userSkillsDir = path.join(HOME_DIR, '.config', 'opencode', 'skills');
+  if (explicit.length > 0) {
+    const match = targets.find((t) => t.platform === platform) || targets[0];
+    return diagnoseSkillsInDir(explicit, match.dir, bundledSkillsDir, checks, null);
   }
 
+  // No explicit list: verify every directory that actually has skills deployed.
+  const deployed = targets.filter((t) => listInstalledSkillNames(t.dir).length > 0);
+  if (deployed.length === 0) {
+    checks.push({
+      name: 'Installed skills',
+      status: 'SKIP',
+      detail: `No skills deployed in any known location (${targets.map((t) => t.platform).join(', ')})`,
+    });
+    return 0;
+  }
+
+  let issues = 0;
+  for (const target of deployed) {
+    const names = listInstalledSkillNames(target.dir);
+    issues += diagnoseSkillsInDir(names, target.dir, bundledSkillsDir, checks, target.platform);
+  }
+  return issues;
+}
+
+/**
+ * Compare one deployed skills directory against the bundled copy.
+ *
+ * @param {string[]} skillNames
+ * @param {string} userSkillsDir
+ * @param {string} bundledSkillsDir
+ * @param {Array} checks
+ * @param {string|null} platformLabel - prefix for check names, or null for the
+ *   legacy unprefixed names (explicit-installedSkills callers).
+ * @returns {number} issue count
+ */
+function diagnoseSkillsInDir(skillNames, userSkillsDir, bundledSkillsDir, checks, platformLabel) {
+  const label = (name) => (platformLabel ? `Skill [${platformLabel}]: ${name}` : `Skill: ${name}`);
+
   let issues = 0;
   for (const name of skillNames) {
     const bundledSkillMd = path.join(bundledSkillsDir, name, 'SKILL.md');
@@ -156,7 +246,7 @@ function diagnoseInstalledSkills(config, checks) {
 
     if (!fs.existsSync(bundledSkillMd)) continue;
     if (!fs.existsSync(userSkillMd)) {
-      checks.push({ name: `Skill: ${name}`, status: 'FAIL', detail: 'Installed SKILL.md missing' });
+      checks.push({ name: label(name), status: 'FAIL', detail: 'Installed SKILL.md missing' });
       issues++;
       continue;
     }
@@ -174,24 +264,24 @@ function diagnoseInstalledSkills(config, checks) {
         // Version strings not valid semver — fall back to content comparison
         if (!sameContentIgnoringLineEndings(bundledContent, userContent)) {
           checks.push({
-            name: `Skill: ${name}`,
+            name: label(name),
             status: 'WARN',
             detail: `Outdated — run xp-gate update-skill --all (installed: ${userVersion}, bundled: ${bundledVersion})`,
           });
           issues++;
         } else {
-          checks.push({ name: `Skill: ${name}`, status: 'PASS', detail: 'Up to date' });
+          checks.push({ name: label(name), status: 'PASS', detail: 'Up to date' });
         }
       } else if (cmp < 0) {
         checks.push({
-          name: `Skill: ${name}`,
+          name: label(name),
           status: 'WARN',
           detail: `Outdated — run xp-gate update-skill --all (installed: ${userVersion}, bundled: ${bundledVersion})`,
         });
         issues++;
       } else {
         // cmp >= 0: installed version is same or newer than bundled
-        checks.push({ name: `Skill: ${name}`, status: 'PASS', detail: 'Up to date' });
+        checks.push({ name: label(name), status: 'PASS', detail: 'Up to date' });
       }
     } else {
       // No version in at least one file — compare content, but not byte-for-byte:
@@ -206,13 +296,13 @@ function diagnoseInstalledSkills(config, checks) {
         withoutVersionLine(userContent)
       )) {
         checks.push({
-          name: `Skill: ${name}`,
+          name: label(name),
           status: 'WARN',
           detail: 'Content differs and version cannot be determined (missing version frontmatter) — compare manually before running update-skill (it pulls from main, which may be older than the installed copy)',
         });
         issues++;
       } else {
-        checks.push({ name: `Skill: ${name}`, status: 'PASS', detail: 'Up to date' });
+        checks.push({ name: label(name), status: 'PASS', detail: 'Up to date' });
       }
     }
   }

package/lib/gate-runner.js

@@ -129,20 +129,63 @@ function firstExisting(candidates) {
   }
 }
 
+/**
+ * Write the `--all` file list to a temporary file and return its path.
+ *
+ * The list is one line per tracked file (thousands on a real repository), so it
+ * cannot travel as a `bash -c` argument: on Windows the whole script is a single
+ * command-line string capped at 32,767 characters, and exceeding it surfaced as
+ * `spawnSync bash ENAMETOOLONG` — Gate 3 could not run at all under `--all`.
+ *
+ * Inlining was also semantically broken: `JSON.stringify` escapes the separators
+ * to a literal `\n`, and bash does not interpret escape sequences inside double
+ * quotes, so the gates received one long non-existent path instead of a list.
+ *
+ * @param {string} contents newline-separated file list
+ * @returns {string} path to the temp file
+ */
+function writeAllModeFileList(contents) {
+  const listFile = path.join(os.tmpdir(), `xp-gate-all-files-${process.pid}-${Date.now()}.txt`);
+  try {
+    fs.writeFileSync(listFile, contents, 'utf8');
+  } catch (err) {
+    throw new Error(`xp-gate: cannot write the --all file list to ${listFile}: ${err.message}`);
+  }
+  return listFile;
+}
+
+/**
+ * Remove the temporary file list, if one was written.
+ *
+ * Best effort: a leftover file in the temp directory is not worth failing a gate
+ * over, but a failure other than ENOENT is named so it does not go unnoticed.
+ *
+ * @param {string} listFile path to remove, or the empty string
+ */
+function removeFileList(listFile) {
+  if (!listFile) return;
+  try {
+    fs.unlinkSync(listFile);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.error(`[xp-gate] could not remove ${listFile}: ${err.message}`);
+    }
+  }
+}
+
 /**
  * The shell lines that populate CHANGED_FILES, chosen by scan scope.
  *
  * Extracted so `runGateAdapter` stays readable: the diff form is three lines of
- * git plumbing and the tree form is a single assignment, and mixing them inline
- * made the wrapper harder to follow than the thing it wraps.
+ * git plumbing and the tree form is a single read, and mixing them inline made
+ * the wrapper harder to follow than the thing it wraps.
  *
  * @param {boolean} allMode true for `--all` (whole tree)
- * @param {string} allModeFiles pre-resolved file list for all mode
  * @returns {string[]} shell lines
  */
-function buildFileSourceLines(allMode, allModeFiles) {
+function buildFileSourceLines(allMode) {
   if (allMode) {
-    return ['#589: --all scans the tracked tree, not the diff', `CHANGED_FILES=${JSON.stringify(allModeFiles)}`];
+    return ['#589: --all scans the tracked tree, not the diff ($5 = file list)', 'CHANGED_FILES="$(cat "$5" 2>/dev/null || true)"'];
   }
   // The historical diff form, unchanged: staged first, then anything vs HEAD.
   // Interpolating the literal `${CHANGED_FILES}` brace-by-brace would be torn apart
@@ -200,16 +243,20 @@ function runGateAdapter(scriptPath, cwd = process.cwd(), opts = {}) {
   // CHANGED_FILES must see the whole tree, not the diff — otherwise a full check
   // scans less than an ordinary commit and reads like a pass.
   const allMode = opts.scope === 'all';
-  const fileSourceLines = buildFileSourceLines(allMode, allMode ? resolveAllModeChangedFiles(cwd) : '');
-  const wrap = buildPreamble(allMode, fileSourceLines);
-
-  // execFileSync avoids an extra /bin/sh layer, so bash receives the script as a
-  // single argv arg (no shell-metacharacter injection through the path).
-  execFileSync(
-    bashCommand,
-    ['--noprofile', '--norc', '-c', wrap, 'xp-gate', commonScript, nowMsScript, scriptPath, process.execPath],
-    { stdio: 'inherit', cwd }
-  );
+  const listFile = allMode ? writeAllModeFileList(resolveAllModeChangedFiles(cwd)) : '';
+  try {
+    const wrap = buildPreamble(allMode, buildFileSourceLines(allMode));
+
+    // execFileSync avoids an extra /bin/sh layer, so bash receives the script as a
+    // single argv arg (no shell-metacharacter injection through the path).
+    execFileSync(
+      bashCommand,
+      ['--noprofile', '--norc', '-c', wrap, 'xp-gate', commonScript, nowMsScript, scriptPath, process.execPath, listFile],
+      { stdio: 'inherit', cwd }
+    );
+  } finally {
+    removeFileList(listFile);
+  }
 }
 
 /**
@@ -253,6 +300,16 @@ function buildPreamble(allMode, fileSourceLines) {
  */
 const TS_GATE_TIMEOUT_MS = 120000;
 
+/**
+ * #618: sentinel for "this gate ran nothing at all" -- no TypeScript module and
+ * no bash fallback. It must never be conflated with 0 ("ran, found nothing").
+ * Returned up through runGate() so the --all summary counts it as skipped
+ * rather than passed: three advertised gates were analysing nothing and sitting
+ * inside the passed count, which is the same defect class as a vacuous pass
+ * elsewhere -- a dimension nobody measured, scored as if measured.
+ */
+const GATE_NOT_RUN = 'NOT_RUN';
+
 /**
  * Run a TypeScript gate module via npx tsx.
  * Finds the .ts entry point, spawns tsx with --run flag.
@@ -266,11 +323,13 @@ function runTsGate(gateModule, targetPath, opts = {}) {
     const gateNum = gateModule.replace('gate-', '');
     const script = resolveGateScript(gateNum, targetCwd);
     if (script) {
-      runGateAdapter(script, targetCwd, opts);
-    } else {
-      console.log(`Gate ${gateModule}: TypeScript module not found and no bash fallback available.`);
+      return runGateAdapter(script, targetCwd, opts);
     }
-    return 0;
+    // #618: nothing ran. Before this, the function fell through to `return 0`
+    // and the --all summary counted the gate as passed.
+    console.log(`Gate ${gateModule}: TypeScript module not found and no bash fallback available.`);
+    console.log(`⏭️  SKIPPED - Gate ${gateModule} did not run (no module, no bash fallback)`);
+    return GATE_NOT_RUN;
   }
 
   const args = ['-y', 'tsx', entry, '--run'];
@@ -484,9 +543,8 @@ function findConfig(basePath, fileName) {
 /**
  * The basename of the first `gate-<num>-*.sh` in a directory, or null.
  *
- * A missing directory is the normal case (most projects have no `githooks/gates/`),
- * so it returns null rather than throwing; a read error is also treated as "no
- * match" because the caller falls through to the next candidate either way.
+ * A missing directory is the normal case -- most projects have no
+ * `githooks/gates/` -- so it returns null rather than throwing.
  *
  * @param {string} dir directory to list
  * @param {string} gateNum gate number as a string
@@ -501,22 +559,37 @@ function matchGateFileIn(dir, gateNum) {
   }
 }
 
+/**
+ * Locate the bash script that implements a gate, for the TS-less fallback path.
+ *
+ * Candidate order:
+ *   1. `<cwd>/githooks/gates/gate-<n>-*.sh` -- a consumer's OWN gate scripts. The
+ *      hyphenated name is what lets a project keep several variants of one gate
+ *      (`gate-9-public-fallback.sh`), which the flat `gate-<n>.sh` name cannot
+ *      express. `xp-gate init` does not create this directory and the npm package
+ *      does not ship it, so in a stock project it simply never matches. It is
+ *      still a supported extension point, pinned by the REQ-standalone-gates-05
+ *      and -06 tests in lib/__tests__/gate-runner.test.js.
+ *   2. `<cwd>/githooks/gate-<n>.sh` -- the flat copy `xp-gate init` installs.
+ *   3. `~/.config/xp-gate/adapters/gate-<n>.sh` -- the global install.
+ *
+ * NOTE: this repository's own `githooks/gates/` was a different thing entirely --
+ * five drifted copies of the canonical gates that only ever matched inside this
+ * checkout, shadowing `githooks/gate-N.sh` (36 lines apart for gate-9, still
+ * carrying the GATE_10_STATUS artifact from #532). Those were deleted; the
+ * lookup path above was not, because consumer projects legitimately use it.
+ *
+ * @param {string} gateNum gate number as a string
+ * @param {string} cwd project root to search
+ * @returns {string|null}
+ */
 function resolveGateScript(gateNum, cwd = process.cwd()) {
-  const candidates = [
-    path.join(cwd, 'githooks', 'gates', `gate-${gateNum}-*.sh`),
-    path.join(cwd, 'githooks', `gate-${gateNum}.sh`),
-  ];
+  const gatesDir = path.join(cwd, 'githooks', 'gates');
+  const flexible = matchGateFileIn(gatesDir, gateNum);
+  if (flexible) return path.join(gatesDir, flexible);
 
-  // Try glob patterns
-  for (const pattern of candidates) {
-    if (pattern.includes('*')) {
-      const dir = path.dirname(pattern);
-      const match = matchGateFileIn(dir, gateNum);
-      if (match) return path.join(dir, match);
-    } else if (fs.existsSync(pattern)) {
-      return pattern;
-    }
-  }
+  const projectScript = path.join(cwd, 'githooks', `gate-${gateNum}.sh`);
+  if (fs.existsSync(projectScript)) return projectScript;
 
   // Check global install
   const globalDir = path.join(os.homedir(), '.config', 'xp-gate', 'adapters');
@@ -573,6 +646,7 @@ async function runGate(gateId, targetPath, opts = {}) {
       // failing gate from a passing one. Handlers that return nothing at all
       // (gate 2, whose execFileSync throws on a non-zero exit instead) are
       // still treated as pass, because their failure signal is the throw below.
+      if (result === GATE_NOT_RUN) return GATE_NOT_RUN;
       return typeof result === 'number' ? result : 0;
     } catch (err) {
       // Covers a synchronous throw AND a rejection from the awaited handler.
@@ -585,4 +659,4 @@ async function runGate(gateId, targetPath, opts = {}) {
   return 1;
 }
 
-module.exports = { GATE_REGISTRY, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript, SOURCE_FILE_EXTENSIONS, resolveAllModeChangedFiles, describeEmptyChangedFiles, describeChangedFilesScope };
+module.exports = { GATE_REGISTRY, GATE_NOT_RUN, getGateInfo, getAllGates, runGate, resolveAlias, getAliases, runGateAdapter, findTsGateEntry, resolveGateScript, SOURCE_FILE_EXTENSIONS, resolveAllModeChangedFiles, describeEmptyChangedFiles, describeChangedFilesScope };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-26T05:44:50.695Z",
+  "checked_at": "2026-10-28T17:43:58.740Z",
   "source": "network"
 }

package/lib/principles.js

@@ -44,21 +44,41 @@ function buildPrinciplesInvocation(files, format) {
   const tsxCli = [findLocalTsxCli(), path.resolve(__dirname, '..', 'node_modules', 'tsx', 'dist', 'cli.mjs')].find(
     (candidate) => candidate && fs.existsSync(candidate)
   );
+  // Second-best shape: run npm's own npx entry with node.exe. A bare `npx` cannot be
+  // spawned without a shell on Windows (CreateProcess only resolves `.exe`, and the
+  // installed shim is `npx.cmd`), which surfaced as spawnSync ENOENT (#<new>).
+  const npxCli = tsxCli ? null : findNpxCli();
 
-  const command = tsxCli ? process.execPath : 'npx';
-  const prefix = tsxCli ? [tsxCli, entry] : ['-y', 'tsx', entry];
+  let command;
+  let prefix;
+  let useShell;
+  if (tsxCli) {
+    command = process.execPath;
+    prefix = [tsxCli, entry];
+    useShell = false;
+  } else if (npxCli) {
+    command = process.execPath;
+    prefix = [npxCli, '-y', 'tsx', entry];
+    useShell = false;
+  } else {
+    // Last resort: a bare npx on PATH. Only a shell can resolve it on Windows, so the
+    // flag has to travel with the plan instead of being hard-coded false.
+    command = 'npx';
+    prefix = ['-y', 'tsx', entry];
+    useShell = process.platform === 'win32';
+  }
 
   if (listChars <= ARGV_CHAR_BUDGET) {
     return {
       command,
       args: [...prefix, '--files', files.join(' '), '--format', format],
-      useShell: false,
+      useShell,
       cleanup: null,
     };
   }
 
   // By reference: one short argument instead of thousands of characters.
-  return buildByReferenceInvocation(prefix, files, format, command);
+  return buildByReferenceInvocation(prefix, files, format, command, useShell);
 }
 
 /**
@@ -73,9 +93,10 @@ function buildPrinciplesInvocation(files, format) {
  * @param {string[]} files source files to analyse
  * @param {string} format 'json' or 'text'
  * @param {string} command executable to run
+ * @param {boolean} useShell whether the spawn needs a shell to resolve the command
  * @returns {{command: string, args: string[], useShell: boolean, cleanup: string|null}}
  */
-function buildByReferenceInvocation(prefix, files, format, command) {
+function buildByReferenceInvocation(prefix, files, format, command, useShell) {
   const listFile = path.join(os.tmpdir(), `xp-gate-principles-${process.pid}-${Date.now()}.txt`);
   try {
     fs.writeFileSync(listFile, files.join('\n'));
@@ -88,7 +109,7 @@ function buildByReferenceInvocation(prefix, files, format, command) {
     command,
     // The @ prefix is the engine's own "read the list from this file" form.
     args: [...prefix, '--files', `@${listFile}`, '--format', format],
-    useShell: false,
+    useShell,
     cleanup: listFile,
   };
 }
@@ -120,6 +141,27 @@ function findLocalTsxCli() {
   return null;
 }
 
+/**
+ * Path to npm's own npx CLI entry (`npx-cli.js`), or null.
+ *
+ * `spawnSync('npx', ...)` without a shell works on POSIX (npx is a symlinked JS
+ * script) but fails on Windows with ENOENT: CreateProcess resolves only `.exe`
+ * names, and the installed entry point is `npx.cmd`. Running npm's JS entry with
+ * the current node binary is equivalent and platform-independent.
+ *
+ * @returns {string|null}
+ */
+function findNpxCli() {
+  const execDir = path.dirname(process.execPath);
+  const candidates = [
+    // Windows/self-contained Node: <nodeDir>/node_modules/npm/bin/npx-cli.js
+    path.join(execDir, 'node_modules', 'npm', 'bin', 'npx-cli.js'),
+    // POSIX layout: <prefix>/bin/node → <prefix>/lib/node_modules/npm/bin/npx-cli.js
+    path.resolve(execDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npx-cli.js'),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
 /**
  * Was this failure the tool not running, or the code having problems?
  *

package/lib/shared-utils.js

@@ -57,6 +57,14 @@ function copyAdapters(srcDir, destDir) {
   if (fs.existsSync(adapterCommon)) {
     fs.copyFileSync(adapterCommon, path.join(destDir, 'adapter-common.sh'));
   }
+  // Shared shell helpers the fragments `source` at runtime (ccn-ratchet.sh and
+  // friends). Without this, gate-3.sh resolves $GATE_DIR/lib/ccn-ratchet.sh to a
+  // path that no installer ever created, and `.` failing there silently disabled
+  // the complexity ratchet: a CCN regression was graded PASS.
+  const libSrc = path.join(srcDir, 'hooks', 'lib');
+  if (fs.existsSync(libSrc)) {
+    copyDirRecursive(libSrc, path.join(destDir, 'lib'));
+  }
   if (fs.existsSync(adaptersDir)) {
     fs.readdirSync(adaptersDir).forEach(f => {
       if (f.endsWith('.sh')) {

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-26
-**Commit:** 7a6d9971
+**Generated:** 2026-10-28
+**Commit:** 0f58c300
 **Branch:** main
-**Version:** 0.31.3.0
+**Version:** 0.32.0.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mock-policy/gate-m3.ts

@@ -86,10 +86,28 @@ interface ValidateImportInput {
   engine: MockDecisionEngine;
   layer: ReturnType<typeof detectTestLayer>;
   severity: 'warning' | 'error';
+  lenientUnit: boolean;
+}
+
+/**
+ * Is this file exempt from the strategy check?
+ *
+ * A lenient unit layer only RECOMMENDS mocking every dependency. Reporting a test
+ * that injects a hand-written fake instead would flag tests that are already
+ * isolated, which is how a gate teaches people to ignore it.
+ */
+function isLenientUnitFile(
+  lenientUnit: boolean,
+  layer: ReturnType<typeof detectTestLayer>,
+): boolean {
+  if (!lenientUnit) return false;
+  return layer === 'unit' || layer === 'unknown';
 }
 
 function validateImport(input: ValidateImportInput): MockPolicyViolation[] {
-  const { testFile, content, importPath, engine, layer, severity } = input;
+  const { testFile, content, importPath, engine, layer, severity, lenientUnit } = input;
+  if (isLenientUnitFile(lenientUnit, layer)) return [];
+
   const decision = engine.decide(importPath, layer);
   const actualStrategy = detectMockUsage(content, importPath);
   const violations: MockPolicyViolation[] = [];
@@ -117,9 +135,22 @@ async function validateFile(
   engine: MockDecisionEngine,
   projectRoot: string,
   severity: 'warning' | 'error',
+  lenientUnit: boolean,
 ): Promise<MockPolicyViolation[]> {
   const fullPath = isAbsolute(testFile) ? testFile : join(projectRoot, testFile);
-  const content = await readFile(fullPath, 'utf-8');
+  // A changed-file list naming a file that cannot be read is broken input, and
+  // gate-m3.test.ts pins the rejection. Reporting "no violations" for a file nobody
+  // could read is the one failure a gate must never have, so the error is caught
+  // only to add the path and then rethrown.
+  let content: string;
+  try {
+    content = await readFile(fullPath, 'utf-8');
+  } catch (error) {
+    // String(error) rather than (error as Error).message: a thrower is free to
+    // reject with a non-Error, and that cast would render the cause as
+    // "undefined" — losing the only diagnostic this rethrow exists to add.
+    throw new Error(`cannot read test file ${testFile}: ${String(error)}`);
+  }
   const layer = detectTestLayer(testFile);
   const imports = collectImports(content);
 
@@ -130,9 +161,25 @@ async function validateFile(
     engine,
     layer,
     severity,
+    lenientUnit,
   }));
 }
 
+/** Every import mentioned across the given test files, deduplicated. */
+async function collectAllImports(testFiles: string[], projectRoot: string): Promise<string[]> {
+  const all: string[] = [];
+  for (const testFile of testFiles) {
+    try {
+      const fullPath = isAbsolute(testFile) ? testFile : join(projectRoot, testFile);
+      const content = await readFile(fullPath, 'utf-8');
+      all.push(...collectImports(content));
+    } catch {
+      // Unreadable file — the per-file pass reports nothing for it either.
+    }
+  }
+  return [...new Set(all)];
+}
+
 export async function runGateM3(
   changedFiles: string[],
   projectRoot: string = process.cwd(),
@@ -151,38 +198,25 @@ export async function runGateM3(
   const config = await loadMockPolicyConfig(projectRoot);
   const severity: 'warning' | 'error' = config.severity;
 
-  // Collect all imports from all test files
-  const allImports: string[] = [];
-  for (const testFile of testFiles) {
-    try {
-      const fullPath = isAbsolute(testFile) ? testFile : join(projectRoot, testFile);
-      const content = await readFile(fullPath, 'utf-8');
-      allImports.push(...collectImports(content));
-    } catch {
-      // File not readable — skip
-    }
-  }
-
   const scope = await scanProjectScope({
     projectRoot,
-    imports: [...new Set(allImports)],
+    imports: await collectAllImports(testFiles, projectRoot),
     boundary: config.projectBoundary,
   });
 
   const engine = new MockDecisionEngine(scope, config, projectRoot);
-  const allViolations: MockPolicyViolation[] = [];
+  // Resolved once from config: a lenient unit layer is advisory, so its files skip
+  // strategy comparison entirely.
+  const lenientUnit = config.layers.unit.mockPolicy === 'lenient';
 
+  const allViolations: MockPolicyViolation[] = [];
   let integrationCount = 0;
   for (const testFile of testFiles) {
-    const layer = detectTestLayer(testFile);
-    if (layer === 'integration') integrationCount++;
-
-    const violations = await validateFile(testFile, engine, projectRoot, severity);
-    allViolations.push(...violations);
+    if (detectTestLayer(testFile) === 'integration') integrationCount++;
+    allViolations.push(...await validateFile(testFile, engine, projectRoot, severity, lenientUnit));
   }
 
-  const hasBlockableViolations = allViolations.some(v => v.severity === 'error');
-  const blocked = severity === 'error' && hasBlockableViolations;
+  const blocked = severity === 'error' && allViolations.some(v => v.severity === 'error');
 
   return {
     exitCode: blocked ? 1 : 0,