peaks-loop 4.0.41 → 4.0.43

package/dist/cli/commands/test-commands.js

@@ -6,14 +6,18 @@
  *
  *   1. Auto-detects the framework from package.json (devDependencies +
  *      dependencies) via detectTestFramework().
- *   2. Spawns the framework's CLI with --cache enabled (overriding any
+ *   2. Resolves the project-LOCAL runner binary (node_modules) and spawns
+ *      that, so the command works where the runner is not on PATH — notably
+ *      Windows, where node_modules/.bin/vitest.cmd is not spawnable without
+ *      a shell. PATH is a last resort and is reported, not silent.
+ *   3. Spawns the framework's CLI with --cache enabled (overriding any
  *      --no-cache in the consumer's `test` script). The user can
  *      opt back into no-cache via `peaks test --no-cache` or
  *      `peaks test --passthrough`.
- *   3. Skips tests where (fileMtime, fileSha256) is unchanged AND the
+ *   4. Skips tests where (fileMtime, fileSha256) is unchanged AND the
  *      previous run status was 'passed' (per-test fingerprint cache at
  *      `<projectRoot>/.peaks/_runtime/test-cache/<hash>.json`).
- *   4. Exits 0 on all-pass / all-skip; exits 1 on any failure.
+ *   5. Exits 0 on all-pass / all-skip; exits 1 on any failure.
  *
  * The CLI is invoked by USER (not just by skill) per slice 2.5.0
  * sub-fix B (G16) — a documented exception to the
@@ -30,6 +34,8 @@
  *   peaks test --framework <name>     — force a specific framework
  */
 import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { getErrorMessage } from '../cli-helpers.js';
 import { clearTestCache, detectTestFramework } from '../../services/test-cache/test-cache-service.js';
@@ -81,10 +87,120 @@ export function buildRunnerArgv(framework, patterns, options) {
     // mocha — no built-in --cache flag; we just pass the patterns.
     return [...patterns];
 }
-function runRunner(framework, argv, projectRoot) {
+/** `<pkg>/package.json#bin`, resolved to the absolute JS entry it points at. */
+function readBinEntry(pkgJsonPath, name, read) {
+    let pkg = {};
+    try {
+        pkg = JSON.parse(read(pkgJsonPath));
+    }
+    catch {
+        // Not fatal: fall through to the `.bin` shim below, and the not-found
+        // error still names this package.json in `searched`.
+        pkg = {};
+    }
+    const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[name];
+    if (typeof rel !== 'string' || rel.length === 0)
+        return null;
+    return resolve(dirname(pkgJsonPath), rel);
+}
+/**
+ * Convert a resolved executable + argv into a form `spawn` can launch with
+ * `shell: false`.
+ *
+ * A Windows `.cmd`/`.bat` shim cannot be spawned directly (spawn → EINVAL).
+ * The obvious fix, `spawn(shim, argv, { shell: true })`, re-splits argv inside
+ * cmd.exe: a pattern `tests/a b/x.test.ts` arrives as THREE args (measured).
+ * Invoking cmd.exe ourselves with `/d /s /c` keeps argv intact.
+ */
+function toSpawnable(exe, argv, platform, env) {
+    if (platform === 'win32' && /\.(?:cmd|bat)$/i.test(exe)) {
+        return { command: env.ComSpec ?? 'cmd.exe', args: ['/d', '/s', '/c', exe, ...argv] };
+    }
+    return { command: exe, args: argv };
+}
+/** Spawnable PATH hits, in preference order (`where`/`which` avoided so this
+ * stays in-process and testable). */
+function resolveFromPath(name, platform, env, exists) {
+    const dirs = (env.PATH ?? '').split(platform === 'win32' ? ';' : ':').filter((d) => d.length > 0);
+    const exts = platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = join(dir, name + ext);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the consumer project's LOCAL runner, and the form of it that
+ * `spawn` can actually launch on this platform.
+ *
+ * Probed, in order (every probe is reported when nothing is found):
+ *   1. `<root>/node_modules/.bin/<runner>` (+ `.cmd`/`.exe` on Windows) —
+ *      the project-local runner the command documents.
+ *   2. `<root>/node_modules/<runner>/package.json` → its `bin` JS entry.
+ *   3. PATH — last resort only; the caller prints a visible notice.
+ *
+ * Between 1 and 2 the **JS entry** wins: `spawn` runs it as
+ * `node <entry> …`, which is identical on Windows and POSIX and never
+ * routes argv through a shell. The `.cmd` shim is only a fallback because
+ * it needs cmd.exe to launch it (see `toSpawnable`).
+ */
+export function resolveRunner(framework, argv, projectRoot, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const exists = deps.existsSync ?? existsSync;
+    const read = deps.readFileSync ?? ((path) => readFileSync(path, 'utf8'));
+    const env = deps.env ?? process.env;
+    const nodeExec = deps.nodeExecPath ?? process.execPath;
+    const searched = [];
+    // 1. Project-local `.bin` shim.
+    const binDir = join(projectRoot, 'node_modules', '.bin');
+    const shimExts = platform === 'win32' ? ['.cmd', '.exe'] : [''];
+    let shim = null;
+    for (const ext of shimExts) {
+        const candidate = join(binDir, framework + ext);
+        searched.push(candidate);
+        if (shim === null && exists(candidate))
+            shim = candidate;
+    }
+    // 2. Project-local package entry.
+    const pkgJsonPath = join(projectRoot, 'node_modules', framework, 'package.json');
+    searched.push(pkgJsonPath);
+    const entry = exists(pkgJsonPath) ? readBinEntry(pkgJsonPath, framework, read) : null;
+    if (entry !== null && exists(entry)) {
+        return { ok: true, command: nodeExec, args: [entry, ...argv], via: `local ${entry}`, fromPath: false };
+    }
+    if (shim !== null) {
+        return { ok: true, ...toSpawnable(shim, argv, platform, env), via: `local ${shim}`, fromPath: false };
+    }
+    // 3. PATH — last resort.
+    const onPath = resolveFromPath(framework, platform, env, exists);
+    searched.push(`PATH lookup for "${framework}"`);
+    if (onPath !== null) {
+        return { ok: true, ...toSpawnable(onPath, argv, platform, env), via: `PATH: ${onPath}`, fromPath: true };
+    }
+    return { ok: false, searched };
+}
+/** Actionable message for the no-runner case — never a raw ENOENT. */
+export function formatRunnerNotFound(framework, searched) {
+    return [
+        `RUNNER_NOT_FOUND: no ${framework} runner found for this project. Looked for:`,
+        ...searched.map((p) => `  - ${p}`),
+        `Install it (e.g. \`npm i -D ${framework}\`) or pass --framework <name>.`
+    ].join('\n');
+}
+export function runRunner(framework, argv, projectRoot, deps = {}) {
+    const resolution = resolveRunner(framework, argv, projectRoot, deps);
+    if (!resolution.ok) {
+        return Promise.reject(new Error(formatRunnerNotFound(framework, resolution.searched)));
+    }
+    const notice = resolution.fromPath
+        ? `[peaks test] no local ${framework} under ${join(projectRoot, 'node_modules')}; falling back to ${resolution.via}\n`
+        : null;
     return new Promise((resolveRun, reject) => {
-        const cmd = framework === 'vitest' ? 'vitest' : framework === 'jest' ? 'jest' : 'mocha';
-        const proc = spawn(cmd, argv, {
+        const spawnFn = deps.spawnFn ?? spawn;
+        const proc = spawnFn(resolution.command, resolution.args, {
             cwd: projectRoot,
             env: process.env,
             stdio: ['ignore', 'pipe', 'pipe']
@@ -95,7 +211,7 @@ function runRunner(framework, argv, projectRoot) {
         proc.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
         proc.on('error', (err) => reject(err));
         proc.on('close', (code) => {
-            resolveRun({ code: code ?? 0, stdout, stderr });
+            resolveRun({ code: code ?? 0, stdout, stderr, notice });
         });
     });
 }
@@ -173,6 +289,8 @@ export function registerTestCommands(program, _io) {
             });
             // Stream the runner's output to the user.
             const result = await runRunner(framework, argv, projectRoot);
+            if (result.notice !== null)
+                process.stderr.write(result.notice);
             process.stdout.write(result.stdout);
             process.stderr.write(result.stderr);
             if (result.code !== 0) {

package/dist/services/audit/audit-goal-service.js

@@ -31,19 +31,39 @@ const REQUIRED_DIMENSIONS = [
     'alternatives',
     'constraints'
 ];
+/**
+ * The allowed values for the three constrained fields.
+ *
+ * These are stated in the prompt AND enforced below: a prompt alone is a
+ * request, not a gate. Before this, the prompt named only `severity` with no
+ * allowed values, the model answered `severity: "high"`, and the gate passed
+ * it — leaving every downstream consumer that switches on
+ * `info | concern | blocker` holding a value it has never seen.
+ */
+const SEVERITIES = ['info', 'concern', 'blocker'];
+const EFFORTS = ['small', 'medium', 'large', 'epic'];
+const CONFIDENCES = ['high', 'medium', 'low'];
 const SYSTEM_PROMPT = `You are auditing a software development need. Produce a structured JSON response with EXACTLY these fields:
 - summary (1-2 sentence summary of the need)
 - audit (array of EXACTLY 6 objects, one per dimension: correctness, completeness, scope, risks, alternatives, constraints; each with dimension, finding, severity)
 - proposedGoal (what success looks like)
 - successCriteria (list of acceptance criteria)
-- roughEffort (small | medium | large | epic)
-- confidence (high | medium | low)
+- roughEffort (one of exactly: small | medium | large | epic)
+- confidence (one of exactly: high | medium | low)
 - rationale (one paragraph tying audit to goal)
 
+severity is one of exactly: info | concern | blocker. Do not invent other values.
+Any value outside the lists above is rejected and the whole response is discarded — a value that is merely plausible is not acceptable.
+
 Output ONLY valid JSON, no prose.`;
 export async function auditGoal(input, llmRunner) {
     const userPrompt = `Need: ${input.need}\n\nAudit this need across the 6 dimensions and propose a goal.`;
-    const response = await llmRunner.call(SYSTEM_PROMPT, userPrompt, { maxTokens: 2000 });
+    // 8000, not 2000: the reply is a six-dimension JSON audit, and a reasoning
+    // model shares this budget with its own thinking blocks — measured against
+    // the session's provider, a 2000-token cap returns `stop_reason: max_tokens`
+    // with the JSON cut off mid-string. That is still ONE bounded call; it is
+    // just one the model can finish.
+    const response = await llmRunner.call(SYSTEM_PROMPT, userPrompt, { maxTokens: 8000 });
     let parsed;
     try {
         parsed = JSON.parse(response.output);
@@ -59,6 +79,21 @@ export async function auditGoal(input, llmRunner) {
     if (missing.length > 0) {
         throw new IncompleteAuditError(`Missing required audit dimensions: ${missing.join(', ')}`);
     }
+    // Coverage is not validity: a reply can carry all six dimensions and still
+    // hand downstream consumers enum values that do not exist. An out-of-enum
+    // value fails here — it is never coerced into a valid one, because silently
+    // repairing the model's output is what makes the enum decorative.
+    for (const entry of parsed.audit) {
+        if (!SEVERITIES.includes(entry.severity)) {
+            throw new IncompleteAuditError(`Invalid severity for dimension "${entry.dimension}": ${JSON.stringify(entry.severity)}. Allowed values: ${SEVERITIES.join(', ')}.`);
+        }
+    }
+    if (!EFFORTS.includes(parsed.roughEffort)) {
+        throw new IncompleteAuditError(`Invalid roughEffort: ${JSON.stringify(parsed.roughEffort)}. Allowed values: ${EFFORTS.join(', ')}.`);
+    }
+    if (!CONFIDENCES.includes(parsed.confidence)) {
+        throw new IncompleteAuditError(`Invalid confidence: ${JSON.stringify(parsed.confidence)}. Allowed values: ${CONFIDENCES.join(', ')}.`);
+    }
     return parsed;
 }
 function isAuditGoalOutput(value) {

package/dist/services/doctor/doctor-service/checks/ecc-hooks-schema-drift.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Check: the third-party ECC plugin ships `hooks/hooks.json` keys that
+ * Claude Code's plugin hook schema ignores
+ * (`integration:ecc-hooks-schema-drift`).
+ *
+ * 2026-09-12 — Claude Code prints this at startup when the ECC plugin
+ * (github.com/affaan-m/ECC) is installed:
+ *
+ *   ecc: hooks.json: unknown keys "$schema", "description" in
+ *   hooks.PreToolUse[0], "id" in hooks.PreToolUse[0], ... and 42 more ignored
+ *
+ * Claude Code's plugin hook schema accepts exactly `{ matcher, hooks }`
+ * on a matcher group, and at the document root `hooks` plus an OPTIONAL
+ * top-level `description`. ECC ships a
+ * root `$schema` plus `description` AND `id` on each of its 23 matcher
+ * groups across 7 events — 47 ignored keys, matching the warning
+ * verbatim. The warning is cosmetic (the 23 hooks still load).
+ *
+ * peaks-loop does NOT write this file, and every ECC release checked
+ * (v2.2.0 / v2.2.1 / main) carries the same keys, so upgrading the
+ * plugin does not clear the warning. This check exists so a user who
+ * hits the startup line does not have to re-investigate it from
+ * scratch.
+ *
+ * Probing is split out of the check so the check itself stays a pure
+ * mapping over `EccHooksDriftProbeResult`. Tests inject the probe to
+ * keep the real `~/.claude/plugins/` tree out of fixtures.
+ */
+import type { DoctorCheckPlugin, EccHooksDriftProbeResult } from '../types.js';
+/**
+ * Unknown keys found in a plugin `hooks.json`. Mirrors the shape of
+ * Claude Code's own startup warning so the doctor message can name the
+ * same things.
+ */
+export type EccHooksDriftFinding = {
+    /** Total ignored keys (`rootKeys` + every unknown key on every matcher group). */
+    readonly unknownKeyCount: number;
+    /** Unknown keys directly under the document root (e.g. `$schema`). */
+    readonly rootKeys: ReadonlyArray<string>;
+    /** Distinct unknown keys seen on matcher groups (e.g. `description`, `id`). */
+    readonly entryKeys: ReadonlyArray<string>;
+    /** Matcher groups carrying at least one unknown key. */
+    readonly entryCount: number;
+};
+/**
+ * Pure mapping over a parsed plugin `hooks.json` payload. Exported so
+ * tests drive the key scan without touching the real plugin tree.
+ */
+export declare function findEccHooksSchemaDrift(payload: unknown): EccHooksDriftFinding;
+/**
+ * Resolve the ECC plugin's install path from Claude Code's plugin
+ * manifest (`~/.claude/plugins/installed_plugins.json`), which is the
+ * only version-agnostic way to find the versioned cache directory
+ * (`…/plugins/cache/ecc/ecc/<version>/`). Exported so tests drive the
+ * lookup with an explicit manifest path.
+ */
+export declare function readEccInstallPath(manifestPath: string): string | null;
+/**
+ * Default probe: reads the ECC plugin manifest + its `hooks/hooks.json`.
+ * `homeDir` is injectable so tests can drive the real probe against a
+ * temp dir; the zero-arg call keeps using the real homedir, so the
+ * function stays assignable to `EccHooksDriftProbe`.
+ */
+export declare function defaultEccHooksDriftProbe(homeDir?: string): EccHooksDriftProbeResult;
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/ecc-hooks-schema-drift.js

@@ -0,0 +1,186 @@
+/**
+ * Check: the third-party ECC plugin ships `hooks/hooks.json` keys that
+ * Claude Code's plugin hook schema ignores
+ * (`integration:ecc-hooks-schema-drift`).
+ *
+ * 2026-09-12 — Claude Code prints this at startup when the ECC plugin
+ * (github.com/affaan-m/ECC) is installed:
+ *
+ *   ecc: hooks.json: unknown keys "$schema", "description" in
+ *   hooks.PreToolUse[0], "id" in hooks.PreToolUse[0], ... and 42 more ignored
+ *
+ * Claude Code's plugin hook schema accepts exactly `{ matcher, hooks }`
+ * on a matcher group, and at the document root `hooks` plus an OPTIONAL
+ * top-level `description`. ECC ships a
+ * root `$schema` plus `description` AND `id` on each of its 23 matcher
+ * groups across 7 events — 47 ignored keys, matching the warning
+ * verbatim. The warning is cosmetic (the 23 hooks still load).
+ *
+ * peaks-loop does NOT write this file, and every ECC release checked
+ * (v2.2.0 / v2.2.1 / main) carries the same keys, so upgrading the
+ * plugin does not clear the warning. This check exists so a user who
+ * hits the startup line does not have to re-investigate it from
+ * scratch.
+ *
+ * Probing is split out of the check so the check itself stays a pure
+ * mapping over `EccHooksDriftProbeResult`. Tests inject the probe to
+ * keep the real `~/.claude/plugins/` tree out of fixtures.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+const CHECK_ID = 'integration:ecc-hooks-schema-drift';
+/** Claude Code's plugin hook schema accepts exactly these keys on a matcher group. */
+const ALLOWED_MATCHER_GROUP_KEYS = ['matcher', 'hooks'];
+/**
+ * …and at the document root: `hooks`, plus an OPTIONAL top-level
+ * `description` (Claude Code's plugin hooks docs, "Reference scripts by
+ * path", document a top-level `description` for `hooks/hooks.json` and
+ * place it as a sibling of `hooks`). A top-level `description` is
+ * therefore legal — and is exactly the shape an upstream ECC fix would
+ * land on when it consolidates its 23 per-matcher descriptions into one.
+ */
+const ALLOWED_ROOT_KEYS = ['hooks', 'description'];
+const NO_DRIFT = {
+    unknownKeyCount: 0,
+    rootKeys: [],
+    entryKeys: [],
+    entryCount: 0
+};
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Pure mapping over a parsed plugin `hooks.json` payload. Exported so
+ * tests drive the key scan without touching the real plugin tree.
+ */
+export function findEccHooksSchemaDrift(payload) {
+    if (!isPlainObject(payload))
+        return NO_DRIFT;
+    const rootKeys = Object.keys(payload).filter((key) => !ALLOWED_ROOT_KEYS.includes(key));
+    const hooks = payload.hooks;
+    if (!isPlainObject(hooks)) {
+        return { ...NO_DRIFT, unknownKeyCount: rootKeys.length, rootKeys };
+    }
+    const entryKeys = new Set();
+    let entryKeyTotal = 0;
+    let entryCount = 0;
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isPlainObject(group))
+                continue;
+            const unknown = Object.keys(group).filter((key) => !ALLOWED_MATCHER_GROUP_KEYS.includes(key));
+            if (unknown.length === 0)
+                continue;
+            entryCount += 1;
+            entryKeyTotal += unknown.length;
+            for (const key of unknown)
+                entryKeys.add(key);
+        }
+    }
+    return {
+        unknownKeyCount: rootKeys.length + entryKeyTotal,
+        rootKeys,
+        entryKeys: [...entryKeys].sort(),
+        entryCount
+    };
+}
+function readJsonIfPresent(path) {
+    if (!existsSync(path))
+        return null;
+    // Parse errors intentionally propagate to the check's own catch, which
+    // reports them as a `skipping check` message instead of swallowing them.
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/**
+ * Resolve the ECC plugin's install path from Claude Code's plugin
+ * manifest (`~/.claude/plugins/installed_plugins.json`), which is the
+ * only version-agnostic way to find the versioned cache directory
+ * (`…/plugins/cache/ecc/ecc/<version>/`). Exported so tests drive the
+ * lookup with an explicit manifest path.
+ */
+export function readEccInstallPath(manifestPath) {
+    const manifest = readJsonIfPresent(manifestPath);
+    if (!isPlainObject(manifest))
+        return null;
+    const plugins = manifest.plugins;
+    if (!isPlainObject(plugins))
+        return null;
+    for (const [name, records] of Object.entries(plugins)) {
+        if (!name.startsWith('ecc@'))
+            continue;
+        if (!Array.isArray(records))
+            continue;
+        for (const record of records) {
+            if (!isPlainObject(record))
+                continue;
+            const installPath = record.installPath;
+            if (typeof installPath === 'string' && installPath.length > 0)
+                return installPath;
+        }
+    }
+    return null;
+}
+/**
+ * Default probe: reads the ECC plugin manifest + its `hooks/hooks.json`.
+ * `homeDir` is injectable so tests can drive the real probe against a
+ * temp dir; the zero-arg call keeps using the real homedir, so the
+ * function stays assignable to `EccHooksDriftProbe`.
+ */
+export function defaultEccHooksDriftProbe(homeDir = homedir()) {
+    const manifestPath = join(homeDir, '.claude', 'plugins', 'installed_plugins.json');
+    const installPath = readEccInstallPath(manifestPath);
+    if (installPath === null)
+        return { hooksPath: null, hooks: null };
+    const hooksPath = join(installPath, 'hooks', 'hooks.json');
+    return { hooksPath, hooks: readJsonIfPresent(hooksPath) };
+}
+function run({ options }) {
+    const probe = options.eccHooksDriftProbe ?? defaultEccHooksDriftProbe;
+    try {
+        const { hooksPath, hooks } = probe();
+        if (hooksPath === null) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: 'ECC plugin not installed (no `ecc@*` entry in ~/.claude/plugins/installed_plugins.json); no plugin hook schema drift to report'
+                }];
+        }
+        if (hooks === null) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: `No readable ECC plugin hooks.json at ${hooksPath}; no plugin hook schema drift to report`
+                }];
+        }
+        const finding = findEccHooksSchemaDrift(hooks);
+        if (finding.unknownKeyCount === 0) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: `ECC plugin hooks.json at ${hooksPath} carries only the keys Claude Code accepts (matcher/hooks per matcher group); the startup "unknown keys ... ignored" warning will not appear`
+                }];
+        }
+        const rootPart = finding.rootKeys.length === 0 ? '' : `at the root: ${finding.rootKeys.join(', ')}; `;
+        return [{
+                id: CHECK_ID,
+                ok: false,
+                severity: 'warning',
+                message: `ECC plugin hooks.json at ${hooksPath} carries ${finding.unknownKeyCount} key(s) that Claude Code's plugin hook schema ignores (${rootPart}on ${finding.entryCount} matcher group(s): ${finding.entryKeys.join(', ')}). Claude Code prints \`ecc: hooks.json: unknown keys ... ignored\` at startup; every hook still loads, so this warning is cosmetic. Source: the third-party ECC plugin (github.com/affaan-m/ECC) ships these keys in every release (v2.2.0 / v2.2.1 / main) — peaks-loop does NOT write this file. Fix: none inside peaks-loop; upstream ECC must drop them from its hooks/hooks.json (its scripts/ci/validate-hooks.js validates shape only, never a key allow-list, so ECC's own CI stays green). Upgrading ECC will not help.`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: `ECC hooks schema-drift probe failed (${getErrorMessage(error)}); skipping check`
+            }];
+    }
+}
+export const check = {
+    name: 'ecc-hooks-schema-drift',
+    run
+};

package/dist/services/doctor/doctor-service/plugin-registry.js

@@ -46,6 +46,7 @@ import { check as distSourceVersion } from './checks/dist-source-version.js';
 import { check as multiBinaryDrift } from './checks/multi-binary-drift.js';
 import { check as workspaceLayout } from './checks/workspace-layout.js';
 import { check as gateguardConflict } from './checks/gateguard-conflict.js';
+import { check as eccHooksSchemaDrift } from './checks/ecc-hooks-schema-drift.js';
 import { check as checkIdSchema } from './checks/check-id-schema.js';
 import { check as l3OrphanSessions } from './checks/l3-orphan-sessions.js';
 import { check as l3MemoryHealth } from './checks/l3-memory-health.js';
@@ -73,6 +74,7 @@ export const PLUGINS = [
     multiBinaryDrift, // id "build:multi-binary-drift"
     workspaceLayout, // id "build:workspace-layout-canonical"
     gateguardConflict, // id "integration:gateguard-peaks-conflict"
+    eccHooksSchemaDrift, // id "integration:ecc-hooks-schema-drift"
     checkIdSchema, // id "doctor-self:check-id-pattern"
     l3OrphanSessions, // id "L3:l3-orphan-sessions"
     l3MemoryHealth, // id "L3:l3-memory-health"

package/dist/services/doctor/doctor-service/types.d.ts

@@ -165,6 +165,24 @@ export type GateguardProbeResult = {
     projectSettings: unknown;
 };
 export type GateguardProbe = () => GateguardProbeResult;
+/**
+ * 2026-09-12 — the third-party ECC plugin (github.com/affaan-m/ECC)
+ * ships `$schema` at the root of its `hooks/hooks.json` plus
+ * `description` + `id` on every matcher group. Claude Code's plugin
+ * hook schema accepts only `{ matcher, hooks }` per matcher group, and
+ * at the root `hooks` plus an OPTIONAL top-level `description`, so it
+ * prints an `unknown keys ... ignored`
+ * line at startup for the 47 extra keys (cosmetic — the hooks still
+ * load). The probe is injected so tests never read the real
+ * `~/.claude/plugins/` tree.
+ */
+export type EccHooksDriftProbeResult = {
+    /** Absolute path to the ECC plugin's `hooks/hooks.json` (null when the plugin is not installed). */
+    hooksPath: string | null;
+    /** Parsed `hooks/hooks.json` payload (null when missing / unreadable). */
+    hooks: unknown;
+};
+export type EccHooksDriftProbe = () => EccHooksDriftProbeResult;
 /**
  * Subset of SkillPresence consumed by the doctor (slice-3b: the full
  * `SkillPresence` type lives in `src/services/skills/skill-presence-service.ts`;
@@ -230,6 +248,8 @@ export type DoctorOptions = {
     workspaceLayoutProbe?: WorkspaceLayoutProbe;
     /** Injected for the integration:gateguard-peaks-conflict check (defaults to defaultGateguardProbe on disk). */
     gateguardProbe?: GateguardProbe;
+    /** Injected for the integration:ecc-hooks-schema-drift check (defaults to defaultEccHooksDriftProbe on disk). */
+    eccHooksDriftProbe?: EccHooksDriftProbe;
     /**
      * Slice 2026-06-13-repair-pre-existing-test-failures: injected
      * root for the L3:l3-memory-health check (defaults to

package/dist/services/hooks/write-gate.js

@@ -31,10 +31,11 @@
  *     `scripts/copy-templates.mjs`), which lets one emitted path string be
  *     valid for both the repo and an installed consumer.
  *
- * Contract (`.claude/HOOKS.md`): exit 0 = allow, exit 1 = fall through to the
- * gate — NOT a deny. Only exit 2 blocks a tool call, and this handler never
- * returns it. This handler's job is to stay silent on the paths the gate is
- * meant to skip.
+ * Contract (`.claude/HOOKS.md`): this handler ALWAYS ABSTAINS: exit 0, no
+ * output, on every path. Only exit 2 blocks a tool call, and this handler
+ * never returns it, so any other non-zero exit is a non-blocking ERROR
+ * rather than a decision. See `decide` below for the correction this file
+ * went through.
  *
  * Path source: the hook payload arrives as JSON on STDIN (Claude Code's
  * documented channel; it appends no argv). `process.argv[2]` is honoured as a
@@ -57,11 +58,31 @@ function candidatePath(payload) {
 }
 
 /**
- * The gate decision: allow (0) only for paths under `.peaks/_runtime/`;
- * everything else falls through to the gate (1).
+ * This handler ABSTAINS on every path, including `.peaks/_runtime/`.
+ *
+ * It used to return 1 for anything outside `.peaks/_runtime/`, documented as
+ * "fall through to the gate". That concept does not exist in the Claude Code
+ * hook protocol. Exit 2 is the only code that blocks; every other non-zero
+ * exit is a NON-BLOCKING ERROR — the action still proceeds, but the transcript
+ * shows `<hook> hook error` followed by `Failed with non-blocking status code:
+ * No stderr output`. The "silent fall-through" was therefore the LOUDEST
+ * available outcome, reported once per edit for every path a developer
+ * actually touches.
+ *
+ * The documented abstention is exit 0 with no output: "no decision". All
+ * matching PreToolUse hooks run in parallel and their results are merged
+ * (`deny` > `defer` > `ask` > `allow`), so abstaining neither approves the call
+ * nor suppresses a sibling's deny — the fact gate still applies to every path
+ * it always applied to.
+ *
+ * Runtime behaviour is unchanged for every path. What changes is that the
+ * handler stops reporting a spurious error while abstaining.
  */
 function decide(p) {
-  return p.includes('.peaks/_runtime/') ? 0 : 1;
+  // The path is still read (it is the payload's whole point) but no longer
+  // branches: every path abstains.
+  void p;
+  return 0;
 }
 
 const ARGV_PATH = typeof process.argv[2] === 'string' ? process.argv[2] : '';
@@ -80,8 +101,10 @@ process.stdin.on('end', () => {
   try {
     payload = JSON.parse(raw);
   } catch {
-    // Malformed or empty payload → no path → deny, which is the same
-    // outcome the old form produced for an absent `process.argv[1]`.
+    // Malformed or empty payload → no path. This is NOT a deny: `decide`
+    // abstains for every input including the empty string, and a deny would
+    // take exit 2. The old comment here said "deny" while returning 1, which
+    // is the non-blocking error — the same misreading this file corrects.
     payload = undefined;
   }
   process.exit(decide(candidatePath(payload) || ARGV_PATH));