pi-aia-asf 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-09-25
+
+### Added
+
+- (describe changes for 0.8.1)
+
+
+## [0.8.0] - 2026-09-12
+
+### Added
+
+- **Code Health Gate** — objective, configurable measurement of code
+  convolution at three levels, replacing pure judgment with measurable
+  thresholds (references/06e-code-health.md):
+  - **function** — cyclomatic complexity (20), cognitive complexity (15),
+    lines per function (50), nesting depth (4), parameters (3) via eslint
+    (`--rule` flags, not the project's own config);
+  - **module** — lines per file (300) via eslint, duplication (5% / min 5
+    lines / 50 tokens) via jscpd, circular imports (any cycle = fail) via
+    madge;
+  - **architecture** — optional dependency-cruiser rules (off by default).
+- **`/asf health`** — runs the gate and prints a `metric | value | threshold |
+  status` table with a verdict; exit 1 when the gate fails. Flags: `--diff`
+  (regression trend vs the committed baseline), `--update-baseline`, `--json`.
+- **Gate 8 in `/asf verify`** — large work runs the code health gate after the
+  M1 traceability matrix; block mode fails the gate, warn mode reports only.
+- **`.asf-code-health.json`** — optional project config, merged over defaults
+  (defaults ← project ← CLI). On/off at every level: master `enabled`,
+  per-level, per-metric. `gate.mode` block|warn, `gate.scope` large|all|off,
+  `missingTool` warn|fail, `toolTimeoutSeconds` (default 120s, Rule 15).
+- **Committed baseline** — `.asf-code-health-baseline.json` is committed so the
+  trend survives across machines/CI; `--diff` flags any regression.
+- **Test suites** — `test/test-code-health.mjs` (73 checks: pure modules,
+  pipeline triggers + non-triggers with fake tools, real-exec timeout,
+  real-eslint integration) and `test/test-code-health-ext.mjs` (12 checks
+  through the real `/asf health` + `/asf verify` command handlers with a real
+  eslint).
+
 ## [0.7.0] - 2026-09-11
 
 ### Added

package/README.md

@@ -29,6 +29,7 @@ You can also force/start a session explicitly:
 /asf bugfix       — major bugfix
 /asf refactor     — architectural refactor
 /asf status       — show current phase + state
+/asf health       — run the code health gate (function/module/architecture)
 /asf approve      — mark PLAN.md as approved (Gate 5)
 /asf abort        — end the session
 ```
@@ -60,6 +61,31 @@ Then `/reload`.
 - **Extension** (`index.ts`) — `/asf` commands, per-project phase state (`~/.pi/agent/skills/aia-asf/projects/<project>/state.json`), dependency checks.
 - **Specs shared with pi-vigilant** — ASF drives `capture_spec` during intake; pi-vigilant re-verifies every spec at task end and blocks "done" while MUST specs are open. One spec file, two systems.
 
+## Code Health Gate
+
+`/asf health` measures convolution **objectively** at three levels — function
+(complexity, cognitive complexity, lines, depth, params), module (file lines,
+duplication, circular imports) and architecture (optional dependency rules) —
+and fails the gate when a threshold is crossed. It is **on by default** with
+conservative thresholds; configure via `.asf-code-health.json` at the project
+root (every level/metric can be disabled independently). For large work it is
+**Gate 8** in `/asf verify`. See `skills/aia-asf/references/06e-code-health.md`.
+
+```json
+{
+  "enabled": true,
+  "gate": { "mode": "block", "scope": "large" },
+  "missingTool": "warn",
+  "function": { "complexity": { "max": 20 }, "maxDepth": { "max": 4 } },
+  "module": { "duplication": { "thresholdPercent": 5 } }
+}
+```
+
+Flags: `--diff` (compare vs committed `.asf-code-health-baseline.json`),
+`--update-baseline`, `--json`. Tools are invoked via `npx --no-install` — they
+must be project devDependencies (eslint, eslint-plugin-sonarjs, jscpd, madge,
+dependency-cruiser); the gate never installs anything.
+
 ## Hygiene rules enforced
 
 - Test-first; only green commits

package/index.ts

@@ -52,6 +52,7 @@ const QA_CHECKLIST: Array<{ key: string; label: string }> = [
   { key: "browser", label: "Web surfaces exercised through a real browser (n/a if none)" },
   { key: "specs", label: "Every MUST spec 'met' with concrete evidence" },
   { key: "trace", label: "Spec-to-code traceability: every met spec has outcome → codePath → test" },
+  { key: "code-health", label: "Code Health Gate passed (or enabled:false / gate.mode:warn with the report shown)" },
   { key: "surface", label: "Every delivered feature is consumed by a surface (UI or API) — nothing dead" },
   { key: "e2e", label: "Feature specs have an end-to-end behavioral test through the real entry point" },
   { key: "honest", label: "Skipped/inconclusive checks reported explicitly" },
@@ -355,6 +356,21 @@ export default function register(pi: ExtensionAPI): void {
           }
         }
 
+        if (scale === "large") {
+          // Gate 8: Code Health — objective convolution measurement.
+          const { runHealth } = await import("./lib/code-health/index.mjs");
+          const health = await runHealth(process.cwd(), []);
+          lines.push("\nCODE HEALTH (Gate 8 — large work):");
+          lines.push(health.text);
+          if (health.exitCode === 1) {
+            lines.push("\n  ✗ GATE NOT PASSED — resolve code-health violations before delivery.");
+          } else if (!health.healthy && health.config?.gate?.mode === "warn") {
+            lines.push("\n  ⚠ warn mode: violations reported but not blocking.");
+          } else {
+            lines.push("\n  ✓ Code health gate passed.");
+          }
+        }
+
         lines.push(
           "\nDefinition of Done checklist (references/06b-testing-qa.md Rule 10):",
         );
@@ -374,6 +390,19 @@ export default function register(pi: ExtensionAPI): void {
         );
         return lines.join("\n");
       }
+      case "health": {
+        // Code Health Gate: objective measurement of convolution at function /
+        // module / architecture level (references/06e-code-health.md).
+        const { runHealth } = await import("./lib/code-health/index.mjs");
+        const res = await runHealth(process.cwd(), args.slice(1));
+        const tail =
+          res.exitCode === 1
+            ? "\n\n✗ GATE FAILED — resolve the violations before delivery."
+            : res.config?.gate?.mode === "warn" && !res.healthy
+              ? "\n\n(warn mode: violations reported, gate not blocking)"
+              : "";
+        return res.text + tail;
+      }
       case "abort":
         return await setPhase(ctx, "none");
       default:
@@ -385,6 +414,7 @@ export default function register(pi: ExtensionAPI): void {
           "  /asf refactor   — architectural refactor (large, gated)\n" +
           "  /asf small      — small change, automatic (no gates)\n" +
           "  /asf status     — show current phase\n" +
+          "  /asf health     — run the code health gate (function/module/architecture)\n" +
           "  /asf verify     — run the definition-of-done QA gate\n" +
           "  /asf abort      — end the current session\n\n" +
           dependencySummary()

package/lib/code-health/config.mjs

@@ -0,0 +1,176 @@
+/**
+ * Code Health Gate — configuration.
+ *
+ * Pure module: defaults + merge + normalization. No IO beyond reading the
+ * config file it is handed. SSOT for every threshold (06c Rule 2).
+ */
+
+/** Built-in defaults — the gate is ON with conservative values. */
+export const DEFAULT_CONFIG = {
+  enabled: true,
+
+  gate: {
+    mode: "block", // "block" | "warn"
+    scope: "large", // "large" | "all" | "off"
+  },
+
+  missingTool: "warn", // "warn" | "fail"
+
+  // Per-tool spawn bound (06b Rule 15: every wait carries its own timeout).
+  toolTimeoutSeconds: 120,
+
+  function: {
+    enabled: true,
+    complexity: { enabled: true, max: 20 },
+    cognitiveComplexity: { enabled: true, max: 15 },
+    maxLinesPerFunction: { enabled: true, max: 50 },
+    maxDepth: { enabled: true, max: 4 },
+    maxParams: { enabled: true, max: 3 },
+  },
+
+  module: {
+    enabled: true,
+    maxFileLines: { enabled: true, max: 300 },
+    duplication: { enabled: true, thresholdPercent: 5, minLines: 5, minTokens: 50 },
+    circularDependencies: { enabled: true },
+  },
+
+  architecture: {
+    enabled: true,
+    dependencyRules: { enabled: false, config: ".asf-code-health.rules.mjs" },
+  },
+
+  ignore: [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/test/**",
+    "**/tests/**",
+    "**/__tests__/**",
+    "**/fixtures/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+  ],
+};
+
+/** Deep-merge `overrides` onto `base`, returning a new object. */
+export function mergeConfig(base, overrides) {
+  if (overrides === undefined || overrides === null) return structuredClone(base);
+  if (typeof overrides !== "object" || Array.isArray(overrides)) return structuredClone(base);
+  const out = structuredClone(base);
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) continue;
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      typeof out[key] === "object" &&
+      out[key] !== null &&
+      !Array.isArray(out[key])
+    ) {
+      out[key] = mergeConfig(out[key], value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Coerce a value to a positive finite number, falling back to `fallback`. */
+function num(value, fallback) {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function bool(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function oneOf(value, allowed, fallback) {
+  return allowed.includes(value) ? value : fallback;
+}
+
+/**
+ * Normalize a raw config object (from .asf-code-health.json) into a complete
+ * config with every field typed. Unknown keys are dropped; wrong types fall
+ * back to the default for that field.
+ */
+export function normalizeConfig(raw) {
+  const d = DEFAULT_CONFIG;
+  if (!isPlainObject(raw)) return structuredClone(d);
+  const g = isPlainObject(raw.gate) ? raw.gate : {};
+  const f = isPlainObject(raw.function) ? raw.function : {};
+  const m = isPlainObject(raw.module) ? raw.module : {};
+  const a = isPlainObject(raw.architecture) ? raw.architecture : {};
+  const metric = (obj, name) => (isPlainObject(obj[name]) ? obj[name] : {});
+
+  const complexity = metric(f, "complexity");
+  const cognitive = metric(f, "cognitiveComplexity");
+  const linesFn = metric(f, "maxLinesPerFunction");
+  const depth = metric(f, "maxDepth");
+  const params = metric(f, "maxParams");
+  const fileLines = metric(m, "maxFileLines");
+  const dup = metric(m, "duplication");
+  const circ = metric(m, "circularDependencies");
+  const depRules = metric(a, "dependencyRules");
+
+  return {
+    enabled: bool(raw.enabled, d.enabled),
+    gate: {
+      mode: oneOf(g.mode, ["block", "warn"], d.gate.mode),
+      scope: oneOf(g.scope, ["large", "all", "off"], d.gate.scope),
+    },
+    missingTool: oneOf(raw.missingTool, ["warn", "fail"], d.missingTool),
+    toolTimeoutSeconds: num(raw.toolTimeoutSeconds, d.toolTimeoutSeconds),
+    function: {
+      enabled: bool(f.enabled, d.function.enabled),
+      complexity: { enabled: bool(complexity.enabled, true), max: num(complexity.max, d.function.complexity.max) },
+      cognitiveComplexity: { enabled: bool(cognitive.enabled, true), max: num(cognitive.max, d.function.cognitiveComplexity.max) },
+      maxLinesPerFunction: { enabled: bool(linesFn.enabled, true), max: num(linesFn.max, d.function.maxLinesPerFunction.max) },
+      maxDepth: { enabled: bool(depth.enabled, true), max: num(depth.max, d.function.maxDepth.max) },
+      maxParams: { enabled: bool(params.enabled, true), max: num(params.max, d.function.maxParams.max) },
+    },
+    module: {
+      enabled: bool(m.enabled, d.module.enabled),
+      maxFileLines: { enabled: bool(fileLines.enabled, true), max: num(fileLines.max, d.module.maxFileLines.max) },
+      duplication: {
+        enabled: bool(dup.enabled, true),
+        thresholdPercent: num(dup.thresholdPercent, d.module.duplication.thresholdPercent),
+        minLines: num(dup.minLines, d.module.duplication.minLines),
+        minTokens: num(dup.minTokens, d.module.duplication.minTokens),
+      },
+      circularDependencies: { enabled: bool(circ.enabled, true) },
+    },
+    architecture: {
+      enabled: bool(a.enabled, d.architecture.enabled),
+      dependencyRules: {
+        enabled: bool(depRules.enabled, false),
+        config: typeof depRules.config === "string" && depRules.config ? depRules.config : d.architecture.dependencyRules.config,
+      },
+    },
+    ignore: Array.isArray(raw.ignore) && raw.ignore.every((x) => typeof x === "string") && raw.ignore.length > 0
+      ? raw.ignore
+      : [...d.ignore],
+  };
+}
+
+/**
+ * Load the project config: read `.asf-code-health.json` if present, normalize.
+ * `readFile` is injectable for tests.
+ */
+export async function loadConfig(projectRoot, readFile = null) {
+  const fs = readFile || (await import("node:fs/promises")).readFile;
+  let raw = null;
+  try {
+    const text = await fs(`${projectRoot}/.asf-code-health.json`, "utf-8");
+    raw = JSON.parse(text);
+  } catch {
+    raw = null; // no file, or unreadable/invalid → defaults
+  }
+  return normalizeConfig(raw);
+}

package/lib/code-health/detect.mjs

@@ -0,0 +1,128 @@
+/**
+ * Code Health Gate — detection & metric planning.
+ *
+ * Pure module: given the project's file list, tool availability and config,
+ * decide which metrics run, are skipped (language absent / tool missing) or
+ * are disabled. No IO.
+ */
+
+/** Languages the gate's metrics understand. */
+export const LANGUAGES = {
+  javascript: { name: "JavaScript", exts: [".js", ".jsx", ".mjs", ".cjs"] },
+  typescript: { name: "TypeScript", exts: [".ts", ".tsx", ".mts", ".cts"] },
+  python: { name: "Python", exts: [".py"] },
+};
+
+/**
+ * Detect which languages are present in a file list.
+ * Returns a Set of language keys ("javascript", "typescript", "python", …).
+ */
+export function detectLanguages(filePaths) {
+  const present = new Set();
+  for (const p of filePaths) {
+    for (const [key, lang] of Object.entries(LANGUAGES)) {
+      if (lang.exts.some((ext) => p.endsWith(ext))) present.add(key);
+    }
+  }
+  return present;
+}
+
+/** A metric that the gate can run. */
+export function planMetrics(config, languages, tools) {
+  const plans = [];
+  const hasJs = languages.has("javascript") || languages.has("typescript");
+  const hasTs = languages.has("typescript");
+  const hasPython = languages.has("python");
+  // eslint/madge/dependency-cruiser are JS/TS-only; jscpd is language-agnostic.
+  const anySource = languages.size > 0;
+
+  const push = (plan) => plans.push(plan);
+
+  if (!config.enabled) return plans;
+
+  const f = config.function;
+  if (hasJs) {
+    push(metric("complexity", "function", "eslint", f.enabled && f.complexity.enabled, f.complexity.max, "max cyclomatic complexity", tools.eslint, "eslint"));
+    push(metric("cognitiveComplexity", "function", "eslint-sonarjs", f.enabled && f.cognitiveComplexity.enabled, f.cognitiveComplexity.max, "max cognitive complexity", tools.eslintSonarjs, "eslint-plugin-sonarjs"));
+    push(metric("maxLinesPerFunction", "function", "eslint", f.enabled && f.maxLinesPerFunction.enabled, f.maxLinesPerFunction.max, "max lines per function", tools.eslint, "eslint"));
+    push(metric("maxDepth", "function", "eslint", f.enabled && f.maxDepth.enabled, f.maxDepth.max, "max nesting depth", tools.eslint, "eslint"));
+    push(metric("maxParams", "function", "eslint", f.enabled && f.maxParams.enabled, f.maxParams.max, "max parameters", tools.eslint, "eslint"));
+  }
+
+  const m = config.module;
+  if (hasJs) {
+    push(metric("maxFileLines", "module", "eslint", m.enabled && m.maxFileLines.enabled, m.maxFileLines.max, "max lines per file", tools.eslint, "eslint"));
+  }
+  if (anySource) {
+    push({
+      key: "duplication",
+      level: "module",
+      tool: "jscpd",
+      enabled: m.enabled && m.duplication.enabled,
+      threshold: m.duplication.thresholdPercent,
+      thresholdLabel: `max ${m.duplication.thresholdPercent}% duplicated`,
+      toolAvailable: tools.jscpd,
+      toolName: "jscpd",
+      compare: "value",
+      args: { thresholdPercent: m.duplication.thresholdPercent, minLines: m.duplication.minLines, minTokens: m.duplication.minTokens },
+    });
+  }
+  if (hasJs) {
+    push(metric("circularDependencies", "module", "madge", m.enabled && m.circularDependencies.enabled, 0, "no circular imports", tools.madge, "madge"));
+  }
+
+  const a = config.architecture;
+  if (hasJs && a.dependencyRules.enabled) {
+    push({
+      key: "dependencyRules",
+      level: "architecture",
+      tool: "dependency-cruiser",
+      enabled: a.enabled && true,
+      threshold: 0,
+      thresholdLabel: "no rule violations",
+      toolAvailable: tools.dependencyCruiser,
+      toolName: "dependency-cruiser",
+      compare: "violations",
+      args: { config: a.dependencyRules.config },
+    });
+  }
+
+  return plans;
+}
+
+function metric(key, level, tool, enabled, threshold, thresholdLabel, toolAvailable, toolName) {
+  return {
+    key,
+    level,
+    tool,
+    enabled,
+    threshold,
+    thresholdLabel,
+    toolAvailable,
+    toolName,
+    // eslint/madge/depcruise report VIOLATION COUNTS: any violation fails.
+    // jscpd reports a measured percentage: value > threshold fails.
+    compare: tool === "jscpd" ? "value" : "violations",
+    args: {},
+  };
+}
+
+/**
+ * Tool availability check (pure): given a map of tool → boolean, mark each
+ * plan as runnable / missing-tool / language-skipped / disabled.
+ */
+export function resolvePlans(plans, languages) {
+  const hasJs = languages.has("javascript") || languages.has("typescript");
+  const anySource = languages.size > 0;
+  return plans.map((p) => {
+    if (!p.enabled) return { ...p, status: "disabled", reason: "disabled in config" };
+    if (p.tool === "eslint" || p.tool === "eslint-sonarjs" || p.tool === "madge") {
+      if (!hasJs) return { ...p, status: "skip-lang", reason: "no JS/TS sources" };
+    }
+    if (p.tool === "jscpd" && !anySource) {
+      return { ...p, status: "skip-lang", reason: "no source files" };
+    }
+    if (!p.toolAvailable) return { ...p, status: "skip-tool", reason: `tool not installed: ${p.toolName}` };
+    return { ...p, status: "run" };
+  });
+}

package/lib/code-health/index.mjs

@@ -0,0 +1,78 @@
+/**
+ * Code Health Gate — CLI orchestration.
+ *
+ * Thin entry point used by `/asf health` and `/asf verify` (Gate 8):
+ * load config → detect languages/tools → plan → run → evaluate → report.
+ * `deps` is injectable for tests.
+ */
+
+import { loadConfig } from "./config.mjs";
+import { detectLanguages, planMetrics, resolvePlans } from "./detect.mjs";
+import { listSourceFiles, detectTools, runAll } from "./run.mjs";
+import { evaluateRow, verdict, formatReport, jsonReport, diffRows, formatDiff, baselinePayload } from "./report.mjs";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const BASELINE_FILE = ".asf-code-health-baseline.json";
+
+/** Parse CLI args: --diff, --json, --update-baseline, --verbose. */
+export function parseArgs(args) {
+  const flags = { diff: false, json: false, updateBaseline: false, verbose: false };
+  for (const a of args || []) {
+    if (a === "--diff") flags.diff = true;
+    else if (a === "--json") flags.json = true;
+    else if (a === "--update-baseline") flags.updateBaseline = true;
+    else if (a === "--verbose") flags.verbose = true;
+  }
+  return flags;
+}
+
+/**
+ * Run the gate. Returns { text, json, exitCode, healthy, rows, config }.
+ */
+export async function runHealth(projectRoot, args = [], deps = {}) {
+  const flags = parseArgs(args);
+  const config = await loadConfig(projectRoot, deps.readFile);
+  if (!config.enabled) {
+    const text = "Code Health Gate: disabled (enabled: false).";
+    return { text, json: { enabled: false }, exitCode: 0, healthy: true, rows: [], config };
+  }
+
+  const files = listSourceFiles(projectRoot, config.ignore);
+  const languages = detectLanguages(files);
+  const tools = deps.tools || detectTools(projectRoot, deps);
+  const plans = resolvePlans(planMetrics(config, languages, tools), languages);
+  const results = await runAll(plans, projectRoot, { ...deps, timeoutMs: config.toolTimeoutSeconds * 1000 });
+  const rows = plans.map((p) => evaluateRow(p, results[p.key]));
+  const v = verdict(rows, config);
+
+  // Gate semantics: block only when configured to, and only for the scope.
+  const gateBlocks = config.gate.mode === "block" && config.gate.scope !== "off";
+  const exitCode = gateBlocks && !v.healthy ? 1 : 0;
+
+  let text = formatReport(rows, config);
+
+  if (flags.updateBaseline) {
+    const payload = baselinePayload(rows);
+    writeFileSync(join(projectRoot, BASELINE_FILE), JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    text += `\n\nBaseline updated: ${BASELINE_FILE}`;
+  } else if (flags.diff) {
+    const baselinePath = join(projectRoot, BASELINE_FILE);
+    let baselineRows = [];
+    if (existsSync(baselinePath)) {
+      try {
+        const base = JSON.parse(readFileSync(baselinePath, "utf-8"));
+        baselineRows = Object.entries(base.metrics || {}).map(([key, m]) => ({ key, value: m.value, status: m.status }));
+      } catch {
+        /* unreadable baseline → no diff */
+      }
+    }
+    const changes = diffRows(rows, baselineRows);
+    text += "\n\n" + formatDiff(changes);
+  }
+
+  const json = flags.json ? jsonReport(rows, config) : null;
+  return { text, json, exitCode, healthy: v.healthy, rows, config };
+}
+
+export { BASELINE_FILE };

package/lib/code-health/report.mjs

@@ -0,0 +1,169 @@
+/**
+ * Code Health Gate — evaluation & reporting.
+ *
+ * Pure module: results + plans → rows + verdict; text formatting; diff against
+ * a baseline. No IO.
+ */
+
+/** Evaluate a metric result against its plan. */
+export function evaluateRow(plan, result) {
+  if (plan.status === "disabled") {
+    return { key: plan.key, level: plan.level, value: "—", threshold: plan.thresholdLabel, status: "disabled", reason: plan.reason };
+  }
+  if (plan.status === "skip-lang") {
+    return { key: plan.key, level: plan.level, value: "—", threshold: plan.thresholdLabel, status: "skipped", reason: plan.reason };
+  }
+  if (plan.status === "skip-tool") {
+    return { key: plan.key, level: plan.level, value: "—", threshold: plan.thresholdLabel, status: "skipped", reason: plan.reason };
+  }
+  if (result && result.error) {
+    return { key: plan.key, level: plan.level, value: "error", threshold: plan.thresholdLabel, status: "error", reason: result.error };
+  }
+  if (result && result.unavailable) {
+    return { key: plan.key, level: plan.level, value: "—", threshold: plan.thresholdLabel, status: "skipped", reason: "rule not available in installed eslint" };
+  }
+  const value = result ? result.value : null;
+  const compare = plan.compare || "value";
+  const failed = value === null || value === undefined
+    ? true
+    : compare === "violations"
+      ? value > 0
+      : value > plan.threshold;
+  return {
+    key: plan.key,
+    level: plan.level,
+    value: formatValue(plan.key, value),
+    threshold: plan.thresholdLabel,
+    status: failed ? "fail" : "pass",
+    reason: failed ? `value ${value} exceeds ${plan.thresholdLabel}` : "",
+  };
+}
+
+function formatValue(key, value) {
+  if (value === null || value === undefined) return "?";
+  if (key === "duplication") return `${value}%`;
+  if (key === "circularDependencies") return `${value} cycle(s)`;
+  return String(value);
+}
+
+/** Aggregate rows into a verdict. */
+export function verdict(rows, config) {
+  const failures = rows.filter((r) => r.status === "fail");
+  const errors = rows.filter((r) => r.status === "error");
+  const skipped = rows.filter((r) => r.status === "skipped");
+  const ran = rows.filter((r) => r.status === "pass" || r.status === "fail");
+  // missingTool: "fail" — a skipped tool is a gate failure (can't verify).
+  const missingIsFailure = config?.missingTool === "fail" && skipped.length > 0;
+  // With missingTool "warn" (default), skipped metrics never fail the gate —
+  // a fresh project without devDeps must not fail. ran === 0 + skipped === 0
+  // means nothing to measure (no source files) → healthy.
+  const healthy = failures.length === 0 && errors.length === 0 && !missingIsFailure;
+  return { healthy, failures: failures.length, errors: errors.length, skipped: skipped.length, ran: ran.length };
+}
+
+/** Human-readable report. */
+export function formatReport(rows, config) {
+  if (!config.enabled) {
+    return "Code Health Gate: disabled (enabled: false).";
+  }
+  const lines = [];
+  lines.push("Code Health Gate report");
+  lines.push("──────────────────────");
+  if (rows.length === 0) {
+    lines.push("(no metrics to run — no source files, or all levels disabled)");
+  }
+  for (const row of rows) {
+    const mark =
+      row.status === "fail" ? "✗" :
+      row.status === "pass" ? "✓" :
+      row.status === "error" ? "!" :
+      row.status === "skipped" ? "–" : "·";
+    lines.push(`${mark} ${row.level.padEnd(12)} ${row.key.padEnd(22)} ${String(row.value).padEnd(10)} ${row.threshold}${row.reason ? "  (" + row.reason + ")" : ""}`);
+  }
+  const v = verdict(rows, config);
+  lines.push("──────────────────────");
+  if (v.healthy && v.ran === 0 && v.skipped > 0) {
+    lines.push(`UNVERIFIED — no metric could run (${v.skipped} skipped: tools missing). Set missingTool: "fail" to enforce.`);
+  } else if (v.healthy) {
+    lines.push(`HEALTHY — ${v.ran} metric(s) checked${v.skipped ? `, ${v.skipped} skipped` : ""}`);
+  } else if (v.failures === 0 && v.errors === 0 && v.skipped > 0) {
+    lines.push(`NOT healthy — ${v.skipped} metric(s) skipped (missingTool: "fail"). Install the tools or lower the bar.`);
+  } else {
+    lines.push(`${v.failures} violation(s), ${v.errors} error(s)${v.skipped ? `, ${v.skipped} skipped` : ""} — NOT healthy`);
+  }
+  return lines.join("\n");
+}
+
+/** Machine-readable report. */
+export function jsonReport(rows, config) {
+  return {
+    enabled: config.enabled,
+    generatedAt: new Date().toISOString(),
+    rows: rows.map((r) => ({
+      key: r.key,
+      level: r.level,
+      value: r.value,
+      threshold: r.threshold,
+      status: r.status,
+      reason: r.reason || "",
+    })),
+    verdict: config.enabled ? verdict(rows, config) : { healthy: true, failures: 0, errors: 0, skipped: 0, ran: 0 },
+  };
+}
+
+/**
+ * Diff the current rows against a baseline (previous report's rows).
+ * Flags metrics that got WORSE: value increased (for max-threshold metrics),
+ * or a metric that was pass and is now fail.
+ */
+export function diffRows(currentRows, baselineRows) {
+  const byKey = new Map(baselineRows.map((r) => [r.key, r]));
+  const changes = [];
+  for (const row of currentRows) {
+    if (row.status !== "pass" && row.status !== "fail") continue;
+    const prev = byKey.get(row.key);
+    if (!prev) {
+      changes.push({ key: row.key, change: "new", detail: `new metric: ${row.value}` });
+      continue;
+    }
+    const prevNum = numeric(prev.value);
+    const curNum = numeric(row.value);
+    if (prevNum !== null && curNum !== null) {
+      if (curNum > prevNum) {
+        changes.push({ key: row.key, change: "worse", detail: `${prev.value} → ${row.value}` });
+      }
+    } else if (prev.status === "pass" && row.status === "fail") {
+      changes.push({ key: row.key, change: "worse", detail: `${prev.value} → ${row.value}` });
+    }
+  }
+  return changes;
+}
+
+function numeric(value) {
+  if (typeof value === "number") return value;
+  if (typeof value !== "string") return null;
+  const n = Number.parseFloat(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Baseline payload (committed .asf-code-health-baseline.json). */
+export function baselinePayload(rows) {
+  return {
+    generatedAt: new Date().toISOString(),
+    metrics: Object.fromEntries(
+      rows
+        .filter((r) => r.status === "pass" || r.status === "fail")
+        .map((r) => [r.key, { value: r.value, status: r.status }]),
+    ),
+  };
+}
+
+/** Format a diff for display. */
+export function formatDiff(changes) {
+  if (changes.length === 0) return "No metric regressed since the baseline.";
+  const lines = ["Metric regressions vs baseline:"];
+  for (const c of changes) {
+    lines.push(`  ✗ ${c.key}: ${c.change} (${c.detail})`);
+  }
+  return lines.join("\n");
+}

package/lib/code-health/run.mjs

@@ -0,0 +1,213 @@
+/**
+ * Code Health Gate — execution.
+ *
+ * IO layer: list source files, spawn the metric tools with bounded timeouts
+ * (06b Rule 15), collect results. `exec` is injectable for tests (fake tools).
+ */
+
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { spawn } from "node:child_process";
+
+/** Run a command with a hard timeout; resolve on exit. */
+export function exec(cmd, args, { cwd, timeoutMs = 120_000, env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd, env: { ...process.env, ...env }, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr, timedOut, error: err.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? -1, stdout, stderr, timedOut });
+    });
+  });
+}
+
+/** 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);
+      }
+    }
+  };
+  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 };
+}
+
+const ESLINT_RULES = {
+  complexity: (max) => ["error", max],
+  cognitiveComplexity: (max) => ["error", max],
+  maxLinesPerFunction: (max) => ["error", { max }],
+  maxDepth: (max) => ["error", max],
+  maxParams: (max) => ["error", max],
+  maxFileLines: (max) => ["error", { max }],
+};
+
+const ESLINT_RULE_IDS = {
+  complexity: "complexity",
+  cognitiveComplexity: "cognitive-complexity",
+  maxLinesPerFunction: "max-lines-per-function",
+  maxDepth: "max-depth",
+  maxParams: "max-params",
+  maxFileLines: "max-lines",
+};
+
+/** Run eslint once for all eslint-backed plans; return key → violation count. */
+export async function runEslint(plans, root, { execFn = exec, timeoutMs = 120_000 } = {}) {
+  const eslintPlans = plans.filter((p) => (p.tool === "eslint" || p.tool === "eslint-sonarjs") && p.status === "run");
+  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 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");
+  }
+  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 }));
+  }
+  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;
+  try {
+    data = JSON.parse(res.stdout);
+  } catch {
+    return { __error: `eslint produced no JSON: ${(res.stderr || res.stdout || "").slice(0, 200)}` };
+  }
+  const counts = {};
+  const unavailable = new Set();
+  for (const file of data) {
+    for (const msg of file.messages || []) {
+      if (msg.ruleId) counts[msg.ruleId] = (counts[msg.ruleId] || 0) + 1;
+      // A rule the installed eslint does not know (e.g. sonarjs plugin absent)
+      // is reported as a message, not a config error — treat as unavailable.
+      if (msg.ruleId && /was not found/.test(msg.message || "")) unavailable.add(msg.ruleId);
+    }
+  }
+  const out = {};
+  for (const p of eslintPlans) {
+    const ruleId = ESLINT_RULE_IDS[p.key];
+    if (unavailable.has(ruleId)) {
+      out[p.key] = { value: 0, unavailable: true };
+    } else {
+      out[p.key] = { value: counts[ruleId] || 0 };
+    }
+  }
+  return out;
+}
+
+/** Run jscpd; return { value: duplication percentage } or { error }. */
+export async function runJscpd(plan, root, { execFn = exec, timeoutMs = 120_000, tmpDir = null } = {}) {
+  const { thresholdPercent, minLines, minTokens } = plan.args;
+  const outDir = tmpDir || join(root, ".asf-code-health-tmp");
+  const args = [
+    "--threshold", String(thresholdPercent),
+    "--min-lines", String(minLines),
+    "--min-tokens", String(minTokens),
+    "--reporters", "json",
+    "--output", outDir,
+    "--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 });
+  if (res.timedOut) return { error: `jscpd timed out after ${timeoutMs / 1000}s` };
+  const reportPath = join(outDir, "jscpd-report.json");
+  try {
+    const text = await (await import("node:fs/promises")).readFile(reportPath, "utf-8");
+    const report = JSON.parse(text);
+    const pct = report?.statistics?.total?.percentage;
+    if (typeof pct !== "number") return { error: "jscpd report missing statistics.total.percentage" };
+    return { value: Math.round(pct * 10) / 10 };
+  } catch (err) {
+    return { error: `jscpd report unreadable: ${err.message}` };
+  }
+}
+
+/** 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 });
+  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 };
+  const match = text.match(/(\d+)\s+circular dependenc/i);
+  return { value: match ? Number(match[1]) : 1 };
+}
+
+/** Run dependency-cruiser; return { value: 0|1 } or { error }. */
+export async function runDepcruise(plan, root, { execFn = exec, timeoutMs = 120_000 } = {}) {
+  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 });
+  if (res.timedOut) return { error: `dependency-cruiser timed out after ${timeoutMs / 1000}s` };
+  return { value: res.code === 0 ? 0 : 1 };
+}
+
+/** Run all plans; returns key → result. */
+export async function runAll(plans, root, opts = {}) {
+  const results = {};
+  const runnable = plans.filter((p) => p.status === "run");
+  const eslintResults = await runEslint(runnable, root, opts);
+  if (eslintResults.__error) {
+    for (const p of runnable.filter((x) => x.tool === "eslint" || x.tool === "eslint-sonarjs")) {
+      results[p.key] = { error: eslintResults.__error };
+    }
+  } else {
+    for (const [key, value] of Object.entries(eslintResults)) results[key] = value;
+  }
+  for (const p of runnable) {
+    if (p.tool === "eslint" || p.tool === "eslint-sonarjs") continue;
+    if (p.tool === "jscpd") results[p.key] = await runJscpd(p, root, opts);
+    else if (p.tool === "madge") results[p.key] = await runMadge(p, root, opts);
+    else if (p.tool === "dependency-cruiser") results[p.key] = await runDepcruise(p, root, opts);
+  }
+  return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.7.0",
+  "version": "0.8.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",
@@ -25,7 +25,8 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "skills/"
+    "skills/",
+    "lib/"
   ],
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/skills/aia-asf/SKILL.md

@@ -220,6 +220,8 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 
 **Large work:** run `/asf verify` — it mechanically validates the **spec-to-code traceability matrix** (M1): every `met` spec must carry `trace` (outcome → codePath → testFile + assertion), testFile must exist, assertion must appear in it. FAIL rows block delivery. **Verify ingested specs from external planning docs too** — the doc's ✅ markers are claims, not evidence.
 
+**Code Health Gate (large work, Gate 8):** run `/asf health` — it measures convolution objectively at function / module / architecture level (see `references/06e-code-health.md`) and fails the gate when thresholds are crossed. The gate is **on by default** with conservative thresholds; configure via `.asf-code-health.json` at the project root. **Fix the cause, not the threshold** (06e Rule 2). Small work shows the report but never blocks.
+
 1. Run the full test suite (all of it, not a subset); fix failures; re-run until green.
 2. **Verify the artifact a user would actually get**: inspect the packaged file list
    (`npm pack` → `tar tzf`), install/load it clean-room in a fresh dir with caches
@@ -280,5 +282,6 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - `references/06-implementation.md` — coding discipline details (incl. M4 challenge designs, M5 trace before claiming)
 - `references/06b-testing-qa.md` — **mandatory testing & QA standard** (14 rules + definition of done)
 - `references/06c-code-quality.md` — **mandatory modularity & maintainability standard** (9 rules, SSOT, testable-standalone, single escalation path, documents-are-code)
+- `references/06e-code-health.md` — **Code Health Gate** (objective convolution measurement; Gate 8 for large work)
 - `references/06d-delegation.md` — **intercom & subagents**: when to message another session, when to spawn isolated workers, the no-mutual-dependencies rule, and why exit codes lie
 - `references/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)

package/skills/aia-asf/references/06b-testing-qa.md

@@ -143,6 +143,7 @@ never arrives, the wiring is dead — that is a failed test.
 - [ ] Web surfaces exercised through a real browser
 - [ ] Every MUST spec `met` with concrete evidence (`update_spec_status`)
 - [ ] **Spec-to-code traceability: every `met` spec carries `trace` (outcome → codePath → testFile + assertion); `/asf verify` mechanically validates it (large work)**
+- [ ] **Code Health Gate passed (or `enabled: false` / `gate.mode: warn` with the report shown)**
 - [ ] **Consumed by a surface: every delivered feature's output is visible in the product (UI or API) — nothing ships as dead machinery**
 - [ ] **E2E behavioral test: every feature spec has a test through the real entry point asserting the operator-facing outcome**
 - [ ] Unverifiable specs → `partial` + asked the user (never self-certified)

package/skills/aia-asf/references/06e-code-health.md

@@ -0,0 +1,115 @@
+# 06e — Code Health Gate
+
+**Status: mandatory for large work (gate blocks), advisory for small work.**
+
+The Code Health Gate is the objective counterpart to the judgment-based rules
+in [06c-code-quality.md](06c-code-quality.md). Where 06c tells you *what* good
+code looks like, 06e *measures* it and fails the gate when the measurement
+crosses a threshold. It exists because judgment alone does not catch gradual
+convolution: a function that grows 5 lines per cycle never triggers a review
+until it is unreadable.
+
+## 1. What it measures
+
+Three levels, each with objective thresholds (all configurable):
+
+| Level | Metric | Tool | Default threshold |
+|---|---|---|---|
+| function | cyclomatic complexity | eslint `complexity` | 20 |
+| function | cognitive complexity | eslint `cognitive-complexity` (sonarjs) | 15 |
+| function | lines per function | eslint `max-lines-per-function` | 50 |
+| function | nesting depth | eslint `max-depth` | 4 |
+| function | parameters | eslint `max-params` | 3 |
+| module | lines per file | eslint `max-lines` | 300 |
+| module | duplication | jscpd | 5% (min 5 lines / 50 tokens) |
+| module | circular imports | madge `--circular` | any cycle = fail |
+| architecture | dependency rules | dependency-cruiser | opt-in (off by default) |
+
+Metrics for languages the project does not use are silently skipped. Metrics
+whose tool is not installed are skipped (or fail the gate when
+`missingTool: "fail"`).
+
+## 2. Invocation
+
+```
+/asf health                # run the gate, print the report
+/asf health --diff         # compare against the committed baseline
+/asf health --update-baseline   # commit current values as the new baseline
+/asf health --json         # machine-readable output
+```
+
+`/asf verify` (large work) runs the gate as **Gate 8** after the M1
+traceability matrix. Small work shows the report but never blocks.
+
+## 3. Configuration
+
+Optional `.asf-code-health.json` at the project root. Merged over the defaults
+(defaults ← project file ← CLI flags). Every level and every metric can be
+switched on/off independently.
+
+```json
+{
+  "enabled": true,
+  "gate": { "mode": "block", "scope": "large" },
+  "missingTool": "warn",
+  "toolTimeoutSeconds": 120,
+  "function": {
+    "complexity": { "max": 20 },
+    "cognitiveComplexity": { "max": 15 },
+    "maxLinesPerFunction": { "max": 50 },
+    "maxDepth": { "max": 4 },
+    "maxParams": { "max": 3 }
+  },
+  "module": {
+    "maxFileLines": { "max": 300 },
+    "duplication": { "thresholdPercent": 5, "minLines": 5, "minTokens": 50 },
+    "circularDependencies": {}
+  },
+  "architecture": {
+    "dependencyRules": { "enabled": false, "config": ".asf-code-health.rules.mjs" }
+  },
+  "ignore": ["**/node_modules/**", "**/dist/**", "**/test/**", "**/*.test.*"]
+}
+```
+
+Semantics:
+
+- `enabled: false` — the gate is off entirely; `/asf health` reports
+  "disabled" and the gate never fires.
+- `gate.mode: "block"` (default) — violations fail the gate (exit 1).
+  `"warn"` — violations are reported but the gate passes.
+- `gate.scope: "large"` (default) — the gate blocks only large work.
+  `"all"` — blocks small work too. `"off"` — never blocks.
+- `missingTool: "warn"` (default) — a missing tool skips its metrics.
+  `"fail"` — a missing tool fails the gate (you cannot verify what you
+  cannot measure).
+- `toolTimeoutSeconds` — hard bound on every tool spawn (Rule 15). A tool
+  that exceeds it is killed and its metrics become errors.
+
+## 4. Baseline & trend
+
+`.asf-code-health-baseline.json` is **committed** so the trend survives across
+machines and CI. `--diff` flags any metric that regressed since the baseline;
+`--update-baseline` records the current values (run it deliberately, when the
+code is in a state you want to hold the line at).
+
+## 5. Tooling
+
+Tools are invoked via `npx --no-install` — they must be devDependencies of the
+project, never dependencies of pi-aia-asf. eslint is invoked with `--rule`
+flags (not the project's own config) so the gate measures against *its*
+thresholds, independent of what the project has configured. The gate never
+installs anything.
+
+## 6. Rules
+
+1. **Run it before delivery.** Large work cannot be delivered with a failing
+   gate (unless the user explicitly overrides).
+2. **Fix the cause, not the threshold.** Raising a threshold requires a
+   written justification in the commit message; silently raising it to make
+   the gate pass is a violation of 06c Rule 1.
+3. **The gate is a floor, not a ceiling.** Passing thresholds does not mean
+   the code is good — 06c rules still apply.
+4. **Never disable the gate to ship.** If a metric is genuinely inapplicable,
+   disable that metric in `.asf-code-health.json` with a comment in the
+   commit message, not the whole gate.