peaks-loop 4.0.42 → 4.0.44

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/codegraph/codegraph-autorefresh.js

@@ -38,6 +38,7 @@
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized, } from './codegraph-service.js';
+import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.
@@ -107,6 +108,17 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
                     note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
                 };
             }
+            // That init just wrote upstream's 99-rule default `exclude`
+            // template, some of which block tracked source files — the same
+            // self-heal the CLI's `peaks codegraph init` performs, via the
+            // same shared helper. Skipped, this path would stamp the
+            // peaks-loop marker over an incomplete index that no later
+            // `init` (it would no-op) could ever repair.
+            //
+            // Never throws (the helper catches everything), and
+            // `reindex: false` because the index call below covers the
+            // recovered files.
+            await repairCodegraphExcludeFromProject(projectRoot, runner, { reindex: false });
         }
         const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
         const result = await executeCodegraphInvocation(invocation, runner);

package/dist/services/codegraph/codegraph-exclude-integrity.d.ts

@@ -0,0 +1,61 @@
+import { type CodegraphExcludeViolation } from './codegraph-exclude-reconciler.js';
+/**
+ * Exit code `peaks codegraph status` uses when the index is
+ * demonstrably incomplete. Distinct from the upstream pass-through
+ * exit code and from `CODEGRAPH_INIT_CONFLICT_EXIT_CODE` (73) so a CI
+ * job can tell "codegraph said no" apart from "peaks-loop found a
+ * tracked source file the index silently dropped".
+ */
+export declare const CODEGRAPH_INTEGRITY_EXIT_CODE = 74;
+export type CodegraphExcludeRuleImpact = {
+    /** The `exclude` rule that must be dropped. */
+    readonly rule: string;
+    /** Distinct tracked source files this single rule blocks. */
+    readonly blockedCount: number;
+};
+export type CodegraphExcludeIntegrityReport = {
+    /** Absolute path of the reconciled `.codegraph/config.json`. */
+    readonly configPath: string;
+    /** True when at least one tracked source file is blocked. */
+    readonly gap: boolean;
+    /** Tracked files that pass the config's `include` filter at all. */
+    readonly trackedSourceCount: number;
+    /** Distinct tracked source files blocked by at least one rule. */
+    readonly excludedTrackedCount: number;
+    /** One entry per (file, rule) pair — see S1's reconciler. */
+    readonly violations: readonly CodegraphExcludeViolation[];
+    /** Rules that must be dropped; empty exactly when `gap` is false. */
+    readonly rulesToRemove: readonly string[];
+    /** Per-rule blocked-file counts, in `rulesToRemove` order. */
+    readonly ruleImpacts: readonly CodegraphExcludeRuleImpact[];
+};
+/**
+ * True when `<projectRoot>/.codegraph/config.json` exists, i.e. when an
+ * exclude list is actually in play here. Both consumers use this to
+ * stay SILENT on a project that never ran `peaks codegraph init`: there
+ * is no exclusion to report, and a missing config is not a finding.
+ *
+ * Note the difference from `isCodegraphInitialized` in
+ * `codegraph-service.ts`, which probes `codegraph.db` (upstream's own
+ * definition of "initialized"). The exclude list is written by upstream
+ * init, so its presence is the narrower question this module asks.
+ */
+export declare function isCodegraphExcludeConfigPresent(projectRoot: string): boolean;
+/**
+ * Read the project's git-tracked files + `.codegraph/config.json` and
+ * fold the reconciliation into a report.
+ *
+ * Throws (never silently degrades) when the project is not a git work
+ * tree, when the config is missing, or when it is malformed — callers
+ * that must stay alive (doctor, `status`) catch and surface the reason.
+ */
+export declare function inspectCodegraphExcludeIntegrity(projectRoot: string): CodegraphExcludeIntegrityReport;
+/**
+ * Human-readable detail lines for a gapped report: the headline count,
+ * then the offending rules, then a sample of the blocked files so an
+ * operator can point at a concrete path without re-running anything.
+ *
+ * Returns an empty array for a clean report — the caller decides
+ * whether "clean" is worth printing at all.
+ */
+export declare function renderCodegraphExcludeIntegrityLines(report: CodegraphExcludeIntegrityReport): readonly string[];

package/dist/services/codegraph/codegraph-exclude-integrity.js

@@ -0,0 +1,98 @@
+// src/services/codegraph/codegraph-exclude-integrity.ts
+//
+// Slice S2 of `2026-09-12-codegraph-exclude-integrity` — the READ-ONLY
+// integrity report shared by `peaks codegraph status` and the
+// `capability:codegraph-exclude-integrity` doctor check.
+//
+// S1's reconciler computes the raw truth (`violations` /
+// `rulesToRemove`). This module folds it into a verdict-shaped report
+// that both consumers can render and gate on, so neither of them has
+// to re-derive "is there a gap, how big, and which rules cause it".
+//
+// It NEVER writes `.codegraph/config.json`. The only write path is
+// `codegraph-exclude-repair.ts`, reachable from `peaks codegraph init`
+// (fresh-initialization self-heal) and the explicit
+// `peaks codegraph repair-exclude` command. Read stays read.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CODEGRAPH_CONFIG_FILENAME, reconcileCodegraphExcludeFromProject } from './codegraph-exclude-reconciler.js';
+import { CODEGRAPH_DIR_NAME } from './codegraph-service.js';
+/**
+ * Exit code `peaks codegraph status` uses when the index is
+ * demonstrably incomplete. Distinct from the upstream pass-through
+ * exit code and from `CODEGRAPH_INIT_CONFLICT_EXIT_CODE` (73) so a CI
+ * job can tell "codegraph said no" apart from "peaks-loop found a
+ * tracked source file the index silently dropped".
+ */
+export const CODEGRAPH_INTEGRITY_EXIT_CODE = 74;
+/** How many offending rules and blocked files we name on the human path. */
+const MAX_REPORTED_RULES = 10;
+const MAX_REPORTED_FILES = 10;
+/**
+ * True when `<projectRoot>/.codegraph/config.json` exists, i.e. when an
+ * exclude list is actually in play here. Both consumers use this to
+ * stay SILENT on a project that never ran `peaks codegraph init`: there
+ * is no exclusion to report, and a missing config is not a finding.
+ *
+ * Note the difference from `isCodegraphInitialized` in
+ * `codegraph-service.ts`, which probes `codegraph.db` (upstream's own
+ * definition of "initialized"). The exclude list is written by upstream
+ * init, so its presence is the narrower question this module asks.
+ */
+export function isCodegraphExcludeConfigPresent(projectRoot) {
+    return existsSync(join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME));
+}
+/**
+ * Read the project's git-tracked files + `.codegraph/config.json` and
+ * fold the reconciliation into a report.
+ *
+ * Throws (never silently degrades) when the project is not a git work
+ * tree, when the config is missing, or when it is malformed — callers
+ * that must stay alive (doctor, `status`) catch and surface the reason.
+ */
+export function inspectCodegraphExcludeIntegrity(projectRoot) {
+    const result = reconcileCodegraphExcludeFromProject(projectRoot);
+    const blockedCounts = new Map();
+    for (const violation of result.violations) {
+        blockedCounts.set(violation.matchedRule, (blockedCounts.get(violation.matchedRule) ?? 0) + 1);
+    }
+    return {
+        configPath: join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME),
+        gap: result.excludedTrackedCount > 0,
+        trackedSourceCount: result.trackedSourceCount,
+        excludedTrackedCount: result.excludedTrackedCount,
+        violations: result.violations,
+        rulesToRemove: result.rulesToRemove,
+        ruleImpacts: result.rulesToRemove.map((rule) => ({ rule, blockedCount: blockedCounts.get(rule) ?? 0 }))
+    };
+}
+/**
+ * Human-readable detail lines for a gapped report: the headline count,
+ * then the offending rules, then a sample of the blocked files so an
+ * operator can point at a concrete path without re-running anything.
+ *
+ * Returns an empty array for a clean report — the caller decides
+ * whether "clean" is worth printing at all.
+ */
+export function renderCodegraphExcludeIntegrityLines(report) {
+    if (!report.gap) {
+        return [];
+    }
+    const lines = [
+        `[FAIL] codegraph index is incomplete: ${report.excludedTrackedCount} of ${report.trackedSourceCount} tracked source files are excluded by ${report.rulesToRemove.length} rule(s).`
+    ];
+    for (const impact of report.ruleImpacts.slice(0, MAX_REPORTED_RULES)) {
+        lines.push(`  rule ${impact.rule} blocks ${impact.blockedCount} tracked file(s)`);
+    }
+    if (report.ruleImpacts.length > MAX_REPORTED_RULES) {
+        lines.push(`  … and ${report.ruleImpacts.length - MAX_REPORTED_RULES} more rule(s)`);
+    }
+    for (const violation of report.violations.slice(0, MAX_REPORTED_FILES)) {
+        lines.push(`  excluded: ${violation.path} <- ${violation.matchedRule}`);
+    }
+    if (report.violations.length > MAX_REPORTED_FILES) {
+        lines.push(`  … and ${report.violations.length - MAX_REPORTED_FILES} more file/rule pair(s)`);
+    }
+    lines.push('Run `peaks codegraph repair-exclude --project <root>` to drop these rules, back up the config, and rebuild the index.');
+    return lines;
+}

package/dist/services/codegraph/codegraph-exclude-reconciler.d.ts

@@ -0,0 +1,26 @@
+export declare function matchesCodegraphGlob(filePath: string, pattern: string): boolean;
+export type CodegraphExcludeReconcileInput = {
+    readonly trackedFiles: readonly string[];
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+};
+export type CodegraphExcludeViolation = {
+    readonly path: string;
+    readonly matchedRule: string;
+};
+export type CodegraphExcludeReconcileResult = {
+    readonly violations: readonly CodegraphExcludeViolation[];
+    readonly rulesToRemove: readonly string[];
+    readonly trackedSourceCount: number;
+    readonly excludedTrackedCount: number;
+};
+export declare function reconcileCodegraphExclude(input: CodegraphExcludeReconcileInput): CodegraphExcludeReconcileResult;
+export declare const CODEGRAPH_CONFIG_FILENAME = "config.json";
+export type CodegraphExcludeConfig = {
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+};
+export declare function readTrackedFiles(projectRoot: string): readonly string[];
+export declare function assertStringArray(value: unknown, field: string, configPath: string): readonly string[];
+export declare function readCodegraphExcludeConfig(projectRoot: string): CodegraphExcludeConfig;
+export declare function reconcileCodegraphExcludeFromProject(projectRoot: string): CodegraphExcludeReconcileResult;