pi-aia-asf 0.16.1 → 0.17.1

package/CHANGELOG.md

@@ -7,13 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.16.1] - 2026-11-07
+## [0.17.1] - 2026-11-07
 
 ### Added
 
-- (describe changes for 0.16.1)
+- (describe changes for 0.17.1)
+
+## [0.17.0] - 2026-11-07
+
+### Added — the health gate ships its own toolchain
+
+The gate could not measure. `detectTools()` looked only in the **project's**
+`node_modules`, so on any repo without eslint/jscpd/madge it produced eight
+"tool not installed" skips and reported a level it never examined — and a run
+that changed source could be judged by metrics that were all missing.
+
+- **The tools are now ASF's own dependencies**: `eslint`, `eslint-plugin-sonarjs`,
+  `@typescript-eslint/parser`, `jscpd`, `madge`. Installing pi-aia-asf installs
+  them, so a fresh clone with an empty `node_modules` is still measured.
+- **ASF-first resolution** (`lib/code-health/tools.mjs`): ASF's copy, then the
+  project's, then PATH. The same metric means the same thing in every repo, and a
+  project pinning its own eslint still wins.
+- **No more `npx --no-install`.** Every metric tool is spawned by absolute path
+  from the resolved install; `npx` could silently run a different version or none.
+- **Deterministic eslint.** The gate writes its own flat config to a temp file and
+  runs with `--no-config-lookup`, so a project's eslint config cannot change what
+  is measured. The sonarjs plugin and TS parser are imported by absolute file URL
+  from ASF's install.
+- **Missing tools name the package** ("jscpd is not available — it ships with
+  pi-aia-asf; reinstall the package") instead of a bare "tool not installed".
 
-## [0.16.0] - 2026-11-07
+### Fixed
+
+- **A sonarjs metric counted the wrong rule id** (`cognitive-complexity` instead
+  of `sonarjs/cognitive-complexity`), so it always reported zero violations.
+- **Vendored trees were scanned as project source.** The model level walked
+  `.local`, `site-packages`, `.venv`, `vendor`, `third_party`, `target`, `Pods`
+  and every other dot-directory: from a home directory it produced 958 findings
+  from Python packages belonging to nobody's project. Those trees are skipped now.
+- **A circular dependency in ASF itself** (`code-health/model.mjs` ↔ `run.mjs`,
+  via a dynamic import) — found by madge the moment it could actually run. The
+  file walker moved to `lib/code-health/files.mjs`, imported by both.
+
+## [0.16.1] - 2026-11-07
 
 ### Fixed — the 2026-11-07 endless completion-gate loop
 

package/index.ts

@@ -26,7 +26,7 @@ import { execFileSync } from "node:child_process";
 import { createLedger, deriveSuiteRun, renderLedger } from "./lib/gates/ledger.mjs";
 import { evaluateBlockers, BLOCKERS, RULE_TEXT, refusalStage, __resetRefusals } from "./lib/gates/blockers.mjs";
 import { createAuthority, renderAuthority } from "./lib/gates/authority.mjs";
-import { decideSettlement, renderCompletionGate, MAX_STEERS, MAX_IDENTICAL_STEERS, steerFingerprint } from "./lib/gates/settle.mjs";
+import { decideSettlement, renderCompletionGate, MAX_STEERS, steerFingerprint } from "./lib/gates/settle.mjs";
 import { projectKey as resolveProjectKey, __clearProjectCache } from "./lib/project.mjs";
 import { classifyToolCall, activationDecision, isSourcePath, bashWritesSource } from "./lib/activation.mjs";
 import { renderRunCard, cardSummary, CARD_CEILING_BYTES } from "./lib/run-card.mjs";

package/lib/code-health/files.mjs

@@ -0,0 +1,117 @@
+/**
+ * Source-file discovery for the health gate.
+ *
+ * Its own module so model.mjs can use it without importing run.mjs, which
+ * imports model.mjs — that pair was a real circular dependency the gate found
+ * in ASF itself once madge was actually installed.
+ */
+
+import { readdirSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/** Recursively list source files under root, skipping ignored dirs/files. */
+export function listSourceFiles(root, ignorePatterns) {
+  const ignoreDirs = new Set([
+    "node_modules", ".git", "dist", "build", "coverage", "test", "tests", "__tests__", "fixtures",
+    ".next", ".cache",
+    // vendored / generated trees: measuring a dependency's code says nothing
+    // about this project, and on a home directory it produced 958 findings from
+    // Python site-packages.
+    "site-packages", "dist-packages", "venv", ".venv", "env", ".tox", "__pycache__",
+    "vendor", "third_party", "bower_components", "target", "Pods", ".gradle", ".m2",
+  ]);
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const abs = join(dir, e.name);
+      const rel = relative(root, abs);
+      if (e.isDirectory()) {
+        // Dot-directories (.git, .local, .cache, .venv …) are tool state, not
+        // project source.
+        if (e.name.startsWith(".") && e.name !== ".") continue;
+        if (ignoreDirs.has(e.name) || rel.split(sep).some((part) => ignoreDirs.has(part))) continue;
+        walk(abs);
+      } else if (e.isFile()) {
+        if (/\.(test|spec)\.[^.]+$/.test(e.name)) continue;
+        if (ignorePatterns && ignorePatterns.some((p) => p.includes(e.name))) continue;
+        out.push(rel);
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * Detect which metric tools are available. Resolution is ASF-first (see
+ * tools.mjs): the gate ships its own toolchain, so a project without eslint is
+ * still measured rather than skipped.
+ */
+export function detectTools(root) {
+  const tools = resolveTools(root);
+  return {
+    eslint: tools.eslint,
+    eslintSonarjs: tools.eslintSonarjs,
+    jscpd: tools.jscpd,
+    madge: tools.madge,
+    dependencyCruiser: tools.dependencyCruiser,
+    typescriptParser: tools.typescriptParser,
+    bins: tools.bins,
+    pkgs: tools.pkgs,
+    sources: tools.sources,
+    missing: missingTools(tools),
+  };
+}
+
+/**
+ * Build a flat-config eslint config for the requested rules and write it to a
+ * temp file. Deterministic on purpose: `--no-config-lookup` means the project's
+ * own config cannot change what the gate measures, and the plugin/parser are
+ * imported by absolute file URL so they resolve from ASF's install.
+ */
+function writeEslintConfig(rules, tools, root) {
+  const imports = [];
+  // flat config wants plugin OBJECTS, not names
+  let pluginsSrc = "{}";
+  const langOpts = ['ecmaVersion: "latest"', 'sourceType: "module"'];
+  // Resolve each package's real entry point instead of guessing a path: the
+  // plugin's main file moves between major versions (lib/index.js → cjs/plugin.js).
+  const entry = (name) => {
+    for (const base of [ASF_ROOT, root]) {
+      try {
+        return pathToFileURL(createRequire(join(base, "package.json")).resolve(name)).href;
+      } catch { /* try the next base */ }
+    }
+    return null;
+  };
+  const sonarjsEntry = tools.pkgs.sonarjs && entry("eslint-plugin-sonarjs");
+  if (sonarjsEntry) {
+    // CJS plugin with __esModule: the real object is a nested default.
+    imports.push(`import sonarjsMod from ${JSON.stringify(sonarjsEntry)};\nconst sonarjs = sonarjsMod.default || sonarjsMod;`);
+    pluginsSrc = "{ sonarjs }";
+  }
+  const tsParserEntry = tools.pkgs.tsParser && entry("@typescript-eslint/parser");
+  if (tsParserEntry) {
+    imports.push(`import tsParserMod from ${JSON.stringify(tsParserEntry)};\nconst tsParser = tsParserMod.default || tsParserMod;`);
+    langOpts.push("parser: tsParser");
+    langOpts.push('parserOptions: { ecmaVersion: "latest", sourceType: "module", ecmaFeatures: { jsx: true } }');
+  }
+  const body = `${imports.join("\n")}
+export default [{
+  files: ["**/*.js", "**/*.mjs", "**/*.cjs", "**/*.jsx", "**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+  languageOptions: { ${langOpts.join(", ")} },
+  plugins: ${pluginsSrc},
+  rules: ${JSON.stringify(rules, null, 2)},
+}];
+`;
+  const file = join(tmpdir(), `asf-eslint-${process.pid}-${Math.random().toString(36).slice(2, 8)}.mjs`);
+  writeFileSync(file, body, "utf-8");
+  return file;
+}
+

package/lib/code-health/model.mjs

@@ -25,6 +25,10 @@
  * exception stays visible instead of becoming a silent pass.
  */
 
+// The walker lives in files.mjs: importing it from run.mjs made the pair circular.
+import { listSourceFiles } from "./files.mjs";
+
+
 /**
  * Declarations whose documented meaning is "deleting the parent takes the
  * children". Relational, ORM-mapped and object-store alike — the *concept* is
@@ -371,7 +375,7 @@ export function hasPersistenceFiles(files) {
  */
 export async function scanModel(root, { files, readFile, config } = {}) {
   const fs = readFile || (await import("node:fs/promises")).readFile;
-  const list = files || (await import("./run.mjs")).listSourceFiles(root, null);
+  const list = files || listSourceFiles(root, null);
   const findings = [];
   const errors = [];
   let scanned = 0;

package/lib/code-health/run.mjs

@@ -8,7 +8,15 @@
 import { readdirSync, statSync, existsSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { spawn } from "node:child_process";
+import { writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
 import { scanModel } from "./model.mjs";
+import { resolveTools, missingTools, ASF_ROOT } from "./tools.mjs";
+import { listSourceFiles } from "./files.mjs";
+
+export { listSourceFiles };
 
 /** Run a command with a hard timeout; resolve on exit. */
 export function exec(cmd, args, { cwd, timeoutMs = 120_000, env } = {}) {
@@ -34,45 +42,70 @@ export function exec(cmd, args, { cwd, timeoutMs = 120_000, env } = {}) {
   });
 }
 
-/** Recursively list source files under root, skipping ignored dirs/files. */
-export function listSourceFiles(root, ignorePatterns) {
-  const ignoreDirs = new Set(["node_modules", ".git", "dist", "build", "coverage", "test", "tests", "__tests__", "fixtures", ".next", ".cache"]);
-  const out = [];
-  const walk = (dir) => {
-    let entries;
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const e of entries) {
-      const abs = join(dir, e.name);
-      const rel = relative(root, abs);
-      if (e.isDirectory()) {
-        if (ignoreDirs.has(e.name) || rel.split(sep).some((part) => ignoreDirs.has(part))) continue;
-        walk(abs);
-      } else if (e.isFile()) {
-        if (/\.(test|spec)\.[^.]+$/.test(e.name)) continue;
-        if (ignorePatterns && ignorePatterns.some((p) => p.includes(e.name))) continue;
-        out.push(rel);
-      }
-    }
+/**
+ * Detect which metric tools are available. Resolution is ASF-first (see
+ * tools.mjs): the gate ships its own toolchain, so a project without eslint is
+ * still measured rather than skipped.
+ */
+export function detectTools(root) {
+  const tools = resolveTools(root);
+  return {
+    eslint: tools.eslint,
+    eslintSonarjs: tools.eslintSonarjs,
+    jscpd: tools.jscpd,
+    madge: tools.madge,
+    dependencyCruiser: tools.dependencyCruiser,
+    typescriptParser: tools.typescriptParser,
+    bins: tools.bins,
+    pkgs: tools.pkgs,
+    sources: tools.sources,
+    missing: missingTools(tools),
   };
-  walk(root);
-  return out;
 }
 
-/** Detect which metric tools are available in the project. */
-export function detectTools(root, { execFn = exec, timeoutMs = 30_000 } = {}) {
-  const bin = (name) => existsSync(join(root, "node_modules", ".bin", name));
-  const pkg = (name) => existsSync(join(root, "node_modules", name));
-  const eslint = bin("eslint");
-  const eslintSonarjs = eslint && pkg("eslint-plugin-sonarjs");
-  const jscpd = bin("jscpd") || pkg("jscpd");
-  const madge = bin("madge") || pkg("madge");
-  const dependencyCruiser = bin("depcruise") || pkg("dependency-cruiser");
-  const typescriptParser = pkg("@typescript-eslint/parser");
-  return { eslint, eslintSonarjs, jscpd, madge, dependencyCruiser, typescriptParser };
+/**
+ * Build a flat-config eslint config for the requested rules and write it to a
+ * temp file. Deterministic on purpose: `--no-config-lookup` means the project's
+ * own config cannot change what the gate measures, and the plugin/parser are
+ * imported by absolute file URL so they resolve from ASF's install.
+ */
+function writeEslintConfig(rules, tools, root) {
+  const imports = [];
+  let pluginsSrc = "{}";
+  const langOpts = ['ecmaVersion: "latest"', 'sourceType: "module"'];
+  // Resolve each package's real entry point instead of guessing a path: the
+  // plugin's main file moves between major versions (lib/index.js → cjs/plugin.js).
+  const entry = (name) => {
+    for (const base of [ASF_ROOT, root]) {
+      try {
+        return pathToFileURL(createRequire(join(base, "package.json")).resolve(name)).href;
+      } catch { /* try the next base */ }
+    }
+    return null;
+  };
+  const sonarjsEntry = tools.pkgs.sonarjs && entry("eslint-plugin-sonarjs");
+  if (sonarjsEntry) {
+    // CJS plugin with __esModule: the real plugin object is a nested default.
+    imports.push(`import sonarjsMod from ${JSON.stringify(sonarjsEntry)};\nconst sonarjs = sonarjsMod.default || sonarjsMod;`);
+    pluginsSrc = "{ sonarjs }";
+  }
+  const tsParserEntry = tools.pkgs.tsParser && entry("@typescript-eslint/parser");
+  if (tsParserEntry) {
+    imports.push(`import tsParserMod from ${JSON.stringify(tsParserEntry)};\nconst tsParser = tsParserMod.default || tsParserMod;`);
+    langOpts.push("parser: tsParser");
+    langOpts.push('parserOptions: { ecmaVersion: "latest", sourceType: "module", ecmaFeatures: { jsx: true } }');
+  }
+  const body = `${imports.join("\n")}
+export default [{
+  files: ["**/*.js", "**/*.mjs", "**/*.cjs", "**/*.jsx", "**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+  languageOptions: { ${langOpts.join(", ")} },
+  plugins: ${pluginsSrc},
+  rules: ${JSON.stringify(rules, null, 2)},
+}];
+`;
+  const file = join(tmpdir(), `asf-eslint-${process.pid}-${Math.random().toString(36).slice(2, 8)}.mjs`);
+  writeFileSync(file, body, "utf-8");
+  return file;
 }
 
 const ESLINT_RULES = {
@@ -99,22 +132,30 @@ export async function runEslint(plans, root, { execFn = exec, timeoutMs = 120_00
   if (eslintPlans.length === 0) return {};
   const files = listSourceFiles(root, null).filter((f) => /\.(js|jsx|mjs|cjs|ts|tsx|mts|cts)$/.test(f));
   if (files.length === 0) return {};
+  const tools = resolveTools(root);
+  if (!tools.bins.eslint) {
+    return { __error: "eslint is not available — it ships with pi-aia-asf; reinstall the package" };
+  }
   const hasTs = files.some((f) => /\.tsx?$/.test(f));
-  const args = ["--no-eslintrc", "--format", "json"];
-  if (hasTs) {
-    if (!detectTools(root).typescriptParser) {
-      return { __error: "TypeScript parser (@typescript-eslint/parser) not installed — cannot lint .ts files" };
-    }
-    args.push("--parser", "@typescript-eslint/parser");
+  if (hasTs && !tools.typescriptParser) {
+    return { __error: "@typescript-eslint/parser is not available — it ships with pi-aia-asf; reinstall the package" };
   }
+  const rules = {};
   for (const p of eslintPlans) {
     const ruleId = ESLINT_RULE_IDS[p.key];
     if (!ruleId) continue;
-    const rule = ESLINT_RULES[p.key](p.threshold);
-    args.push("--rule", JSON.stringify({ [ruleId]: rule }));
+    // eslint 9 flat config uses the bare rule name; the plugin namespace is
+    // only for sonarjs.
+    rules[p.tool === "eslint-sonarjs" ? `sonarjs/${ruleId}` : ruleId] = ESLINT_RULES[p.key](p.threshold);
+  }
+  const configFile = writeEslintConfig(rules, tools, root);
+  const args = ["--no-config-lookup", "--config", configFile, "--format", "json", ...files];
+  let res;
+  try {
+    res = await execFn(tools.bins.eslint, args, { cwd: root, timeoutMs });
+  } finally {
+    try { rmSync(configFile, { force: true }); } catch { /* best effort */ }
   }
-  args.push(...files);
-  const res = await execFn("npx", ["--no-install", "eslint", ...args], { cwd: root, timeoutMs });
   if (res.timedOut) return { __error: `eslint timed out after ${timeoutMs / 1000}s` };
   if (res.code !== 0 && !res.stdout) return { __error: `eslint failed: ${(res.stderr || "").slice(0, 300)}` };
   let data;
@@ -135,7 +176,10 @@ export async function runEslint(plans, root, { execFn = exec, timeoutMs = 120_00
   }
   const out = {};
   for (const p of eslintPlans) {
-    const ruleId = ESLINT_RULE_IDS[p.key];
+    // The reported id carries the plugin namespace for sonarjs rules; counting
+    // the bare name silently reported 0 violations for every sonarjs metric.
+    const bare = ESLINT_RULE_IDS[p.key];
+    const ruleId = p.tool === "eslint-sonarjs" ? `sonarjs/${bare}` : bare;
     if (unavailable.has(ruleId)) {
       out[p.key] = { value: 0, unavailable: true };
     } else {
@@ -158,7 +202,9 @@ export async function runJscpd(plan, root, { execFn = exec, timeoutMs = 120_000,
     "--ignore", "**/node_modules/**,**/dist/**,**/build/**,**/coverage/**,**/test/**,**/tests/**,**/__tests__/**,**/fixtures/**,**/*.test.*,**/*.spec.*",
     root,
   ];
-  const res = await execFn("npx", ["--no-install", "jscpd", ...args], { cwd: root, timeoutMs });
+  const bin = resolveTools(root).bins.jscpd;
+  if (!bin) return { error: "jscpd is not available — it ships with pi-aia-asf; reinstall the package" };
+  const res = await execFn(bin, args, { cwd: root, timeoutMs });
   if (res.timedOut) return { error: `jscpd timed out after ${timeoutMs / 1000}s` };
   const reportPath = join(outDir, "jscpd-report.json");
   try {
@@ -174,7 +220,9 @@ export async function runJscpd(plan, root, { execFn = exec, timeoutMs = 120_000,
 
 /** Run madge --circular; return { value: cycle count } or { error }. */
 export async function runMadge(plan, root, { execFn = exec, timeoutMs = 120_000 } = {}) {
-  const res = await execFn("npx", ["--no-install", "madge", "--circular", "--extensions", "js,jsx,ts,tsx,mjs,cjs", root], { cwd: root, timeoutMs });
+  const bin = resolveTools(root).bins.madge;
+  if (!bin) return { error: "madge is not available — it ships with pi-aia-asf; reinstall the package" };
+  const res = await execFn(bin, ["--circular", "--extensions", "js,jsx,ts,tsx,mjs,cjs", root], { cwd: root, timeoutMs });
   if (res.timedOut) return { error: `madge timed out after ${timeoutMs / 1000}s` };
   const text = res.stdout + res.stderr;
   if (res.code === 0) return { value: 0 };
@@ -187,7 +235,9 @@ export async function runDepcruise(plan, root, { execFn = exec, timeoutMs = 120_
   const cfg = plan.args.config;
   const files = listSourceFiles(root, null).filter((f) => /\.(js|jsx|mjs|cjs|ts|tsx|mts|cts)$/.test(f));
   if (files.length === 0) return { value: 0 };
-  const res = await execFn("npx", ["--no-install", "depcruise", "--config", cfg, "--output-type", "err", "--fail-on", "error", ...files], { cwd: root, timeoutMs });
+  const bin = resolveTools(root).bins.depcruise;
+  if (!bin) return { error: "dependency-cruiser is not available — install it in the project to use this metric" };
+  const res = await execFn(bin, ["--config", cfg, "--output-type", "err", "--fail-on", "error", ...files], { cwd: root, timeoutMs });
   if (res.timedOut) return { error: `dependency-cruiser timed out after ${timeoutMs / 1000}s` };
   return { value: res.code === 0 ? 0 : 1 };
 }

package/lib/code-health/tools.mjs

@@ -0,0 +1,140 @@
+/**
+ * Code Health Gate — tool resolution.
+ *
+ * The gate measures nothing without its tools, and a project that happens not to
+ * ship eslint/jscpd/madge is not a project without complexity problems. So the
+ * tools are ASF's OWN dependencies (package.json) and are resolved from ASF
+ * first: the same metric means the same thing in every repo, and a fresh clone
+ * with an empty node_modules still gets a real measurement instead of eight
+ * "tool not installed" skips.
+ *
+ * Resolution order, per tool:
+ *   1. ASF's own node_modules  — deterministic, ships with the package
+ *   2. the project's node_modules — a project may pin its own version
+ *   3. PATH — a global install
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** ASF's package root (this file is <root>/lib/code-health/tools.mjs). */
+export const ASF_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const TOOLS = {
+  eslint: { bin: "eslint", pkg: "eslint" },
+  sonarjs: { pkg: "eslint-plugin-sonarjs" },
+  tsParser: { pkg: "@typescript-eslint/parser" },
+  jscpd: { bin: "jscpd", pkg: "jscpd" },
+  madge: { bin: "madge", pkg: "madge" },
+  depcruise: { bin: "depcruise", pkg: "dependency-cruiser" },
+};
+
+function isExecutable(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function findBin(base, name) {
+  const p = join(base, "node_modules", ".bin", name);
+  return isExecutable(p) ? p : null;
+}
+
+function findPkg(base, name) {
+  const p = join(base, "node_modules", name);
+  return existsSync(p) ? p : null;
+}
+
+function findOnPath(name) {
+  for (const dir of String(process.env.PATH || "").split(":")) {
+    if (!dir) continue;
+    const p = join(dir, name);
+    if (isExecutable(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Resolve every tool. `bins` holds absolute paths to spawn (never `npx`, which
+ * silently installs a different version or nothing at all).
+ *
+ * @param {string} projectRoot
+ * @returns {{eslint:boolean, eslintSonarjs:boolean, jscpd:boolean, madge:boolean,
+ *            dependencyCruiser:boolean, typescriptParser:boolean,
+ *            bins:Record<string,string|null>, pkgs:Record<string,string|null>,
+ *            sources:Record<string,string>}}
+ */
+export function resolveTools(projectRoot) {
+  const bases = [
+    { dir: ASF_ROOT, source: "asf" },
+    { dir: projectRoot, source: "project" },
+  ];
+  const bins = {};
+  const pkgs = {};
+  const sources = {};
+
+  for (const [key, spec] of Object.entries(TOOLS)) {
+    if (spec.bin) {
+      bins[key] = null;
+      for (const b of bases) {
+        const found = findBin(b.dir, spec.bin);
+        if (found) {
+          bins[key] = found;
+          sources[key] = b.source;
+          break;
+        }
+      }
+      if (!bins[key]) {
+        const onPath = findOnPath(spec.bin);
+        if (onPath) {
+          bins[key] = onPath;
+          sources[key] = "path";
+        }
+      }
+    }
+    if (spec.pkg) {
+      pkgs[key] = null;
+      for (const b of bases) {
+        const found = findPkg(b.dir, spec.pkg);
+        if (found) {
+          pkgs[key] = found;
+          if (!sources[key]) sources[key] = b.source;
+          break;
+        }
+      }
+    }
+  }
+
+  // eslint is usable when its binary exists; the sonarjs rules only when the
+  // plugin package is there too. A missing plugin must not disable the six
+  // eslint metrics that do not need it.
+  const eslint = !!bins.eslint;
+  return {
+    eslint,
+    eslintSonarjs: eslint && !!pkgs.sonarjs,
+    jscpd: !!bins.jscpd,
+    madge: !!bins.madge,
+    dependencyCruiser: !!bins.depcruise,
+    typescriptParser: !!pkgs.tsParser,
+    bins,
+    pkgs,
+    sources,
+  };
+}
+
+/**
+ * Human-readable list of what is missing, for the "make them requirements"
+ * contract: the gate names the package, not just "tool not installed".
+ */
+export function missingTools(tools) {
+  const out = [];
+  if (!tools.eslint) out.push("eslint");
+  if (!tools.eslintSonarjs) out.push("eslint-plugin-sonarjs");
+  if (!tools.jscpd) out.push("jscpd");
+  if (!tools.madge) out.push("madge");
+  if (!tools.typescriptParser) out.push("@typescript-eslint/parser");
+  return out;
+}

package/lib/gates/settle.mjs

@@ -28,16 +28,10 @@
 
 import { sessionFacts } from "./ledger.mjs";
 
-/** An identical steer is never issued twice. */
-export const MAX_IDENTICAL_STEERS = 1;
 /**
- * Absolute ceiling on distinct steers per session. Beyond it the gaps are
- * reported and the run is allowed to settle — this is a reporting boundary, not
- * a stop: the work is never halted, only the asking.
- */
-/**
- * A REPORTING number only — never a stop. It exists so the steer text can say
- * "steer N" without inventing a bound; there is no cap on warranted work.
+ * A REPORTING number only — never a stop, and no longer referenced by any
+ * decision. It is kept so tooling that prints "steer N" has a number to name;
+ * there is no cap on warranted work, and a real gap is re-raised forever.
  */
 export const MAX_STEERS = 12;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",
@@ -72,5 +72,12 @@
     "jiti": "^2.7.0",
     "typebox": "1.3.27",
     "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@typescript-eslint/parser": "^8.72.1",
+    "eslint": "^9.39.5",
+    "eslint-plugin-sonarjs": "^4.2.2",
+    "jscpd": "^5.4.2",
+    "madge": "^8.0.0"
   }
 }