peaks-loop 3.0.0

package/dist/src/services/slice/slice-check-types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Type envelope for the `peaks slice check` CLI command.
+ *
+ * `peaks slice check` is the boundary check for the RD micro-cycle
+ * (see `skills/peaks-solo/references/micro-cycle.md`). It bundles the
+ * 4 self-checks that must pass at slice end before the slice is handed
+ * off to peaks-qa:
+ *
+ *   1. typecheck (`npx tsc --noEmit`)
+ *   2. unit tests — by default the **changed-only** suite
+ *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
+ *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      entirely (e.g. docs-only or config-only slices).
+ *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
+ *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
+ *
+ * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
+ * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
+ * This command is for the BOUNDARY, not the inner loop.
+ *
+ * The unit-test stage emits a `unitTestsRunMode` field on the result
+ * envelope so downstream tooling and the QA test-report can record
+ * which mode actually ran: `"changed"` (default), `"full"` (with
+ * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
+ * (with `--allow-pre-existing-failures` when the run failed and the
+ * stage was downgraded to `skipped` with a reason).
+ */
+export type SliceCheckStageStatus = 'pass' | 'fail' | 'skipped';
+export type SliceCheckStage = {
+    /** Stable id for the stage (matches the runbook's check list). */
+    name: 'typecheck' | 'unit-tests' | 'review-fanout' | 'gate-verify-pipeline' | 'mock-placement' | 'audit-regression';
+    /** Human-readable description. */
+    description: string;
+    status: SliceCheckStageStatus;
+    /** Wall-clock duration in ms; null if skipped. */
+    durationMs: number | null;
+    /** Free-form detail (summary line + last error line). */
+    detail: string;
+    /** Optional structured data (e.g. test counts, gate counts). */
+    data?: Record<string, unknown>;
+};
+export type SliceCheckResult = {
+    /** Absolute project root the command operated on. */
+    projectRoot: string;
+    /** Request id the boundary check applies to; null if no slice is active. */
+    rid: string | null;
+    /** All stages in execution order. */
+    stages: SliceCheckStage[];
+    /**
+     * Which unit-test mode actually ran. One of:
+     * - `"changed"` — default: `npx vitest run --changed` (tests for git-changed files only)
+     * - `"full"` — opt-in via `--run-tests`: `npx vitest run` (full suite)
+     * - `"skipped"` — opt-in via `--skip-tests` (stage not executed)
+     * - `"overridden"` — full mode + `--allow-pre-existing-failures` and the run failed;
+     *   stage downgraded to `skipped` with the pre-existing-failure reason
+     */
+    unitTestsRunMode: 'changed' | 'full' | 'skipped' | 'overridden';
+    /** True iff every stage passed (or was skipped) and the boundary is OK to hand off. */
+    boundaryReady: boolean;
+    /** Total wall-clock duration in ms. */
+    totalDurationMs: number;
+    /** Next steps suggested when boundaryReady is false. */
+    nextActions: string[];
+};
+export type SliceCheckOptions = {
+    projectRoot: string;
+    /** When omitted, slice check inspects `.peaks/_runtime/current-change` to find the active rid. */
+    rid?: string;
+    /**
+     * When true, re-run the 3-way review fan-out (peaks-rd's code-review +
+     * security-review + perf-baseline sub-agents) even if the review files
+     * already exist. The default is to verify presence and skip if all 3 are present.
+     */
+    refreshFanout: boolean;
+    /**
+     * When true, run the **full** `npx vitest run` suite at the boundary.
+     * When false (the default), run the **changed-only** suite
+     * (`npx vitest run --changed`) which only exercises tests related to
+     * git-changed files. The changed-only mode is the new default as of
+     * run 017 — full suite costs 30s+ on this repo; the changed-only
+     * mode costs ~1-3s in steady state and is what catches the
+     * regressions that actually matter. The service treats `undefined`
+     * the same as `false`.
+     */
+    runTests?: boolean;
+    /**
+     * When true, skip the unit-test stage entirely. Useful when a slice
+     * has no test surface (e.g. a docs-only or config-only slice), or
+     * when the user wants a "typecheck + review + gate" boundary check
+     * without any test execution.
+     */
+    skipTests: boolean;
+    /**
+     * When true, an `unit-tests` stage that fails is reported as `skipped`
+     * (with a `reason` naming the pre-existing failure count) instead of
+     * `failed`. Used to opt in to bypassing the 28 pre-existing Windows
+     * test failures documented in dogfood-2-f1-f4.md F17. Only meaningful
+     * when the unit-test stage actually runs (i.e. not when `skipTests`
+     * is true). Does NOT affect the other 3 stages (typecheck /
+     * review-fanout / gate-verify-pipeline). Default: false. The service
+     * treats `undefined` the same as `false`.
+     */
+    allowPreExistingFailures?: boolean;
+};

package/dist/src/services/slice/slice-check-types.js

@@ -0,0 +1,28 @@
+/**
+ * Type envelope for the `peaks slice check` CLI command.
+ *
+ * `peaks slice check` is the boundary check for the RD micro-cycle
+ * (see `skills/peaks-solo/references/micro-cycle.md`). It bundles the
+ * 4 self-checks that must pass at slice end before the slice is handed
+ * off to peaks-qa:
+ *
+ *   1. typecheck (`npx tsc --noEmit`)
+ *   2. unit tests — by default the **changed-only** suite
+ *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
+ *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      entirely (e.g. docs-only or config-only slices).
+ *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
+ *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
+ *
+ * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
+ * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
+ * This command is for the BOUNDARY, not the inner loop.
+ *
+ * The unit-test stage emits a `unitTestsRunMode` field on the result
+ * envelope so downstream tooling and the QA test-report can record
+ * which mode actually ran: `"changed"` (default), `"full"` (with
+ * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
+ * (with `--allow-pre-existing-failures` when the run failed and the
+ * stage was downgraded to `skipped` with a reason).
+ */
+export {};

package/dist/src/services/slice/slice-decompose-runners.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Slice Decomposition Service -- default runners.
+ *
+ * See `.peaks/_runtime/2026-06-13-session-86d852/sc/slice-algorithm-design.md`
+ * for the full spec. This module hosts the 3 default runner factories
+ * (CLI-mode, real shell-outs) used by `decomposeSlices` when the caller
+ * does not inject fakes via `DecomposeOptions`. The 6-stage pure
+ * algorithm itself lives in `slice-decompose-service.ts`.
+ *
+ * Public surface (3 exported factories):
+ *
+ *   defaultCodegraphRunner()  -- spawns `npx codegraph <cmd>`
+ *   defaultUnderstandRunner() -- reads .understand-anything/knowledge-graph.json
+ *   defaultImportEdgeRunner() -- reads source files for import statements
+ *
+ * v2.18.3 file-split: this module is the extracted sub-tree of the
+ * pre-split `slice-decompose-service.ts`. Function signatures are
+ * unchanged (verbatim move).
+ */
+import type { CodegraphRunner, ImportEdgeRunner, UnderstandRunner } from './slice-decompose-types.js';
+export declare function defaultCodegraphRunner(): CodegraphRunner;
+export declare function defaultUnderstandRunner(): UnderstandRunner;
+export declare function defaultImportEdgeRunner(): ImportEdgeRunner;

package/dist/src/services/slice/slice-decompose-runners.js

@@ -0,0 +1,174 @@
+/**
+ * Slice Decomposition Service -- default runners.
+ *
+ * See `.peaks/_runtime/2026-06-13-session-86d852/sc/slice-algorithm-design.md`
+ * for the full spec. This module hosts the 3 default runner factories
+ * (CLI-mode, real shell-outs) used by `decomposeSlices` when the caller
+ * does not inject fakes via `DecomposeOptions`. The 6-stage pure
+ * algorithm itself lives in `slice-decompose-service.ts`.
+ *
+ * Public surface (3 exported factories):
+ *
+ *   defaultCodegraphRunner()  -- spawns `npx codegraph <cmd>`
+ *   defaultUnderstandRunner() -- reads .understand-anything/knowledge-graph.json
+ *   defaultImportEdgeRunner() -- reads source files for import statements
+ *
+ * v2.18.3 file-split: this module is the extracted sub-tree of the
+ * pre-split `slice-decompose-service.ts`. Function signatures are
+ * unchanged (verbatim move).
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+export function defaultCodegraphRunner() {
+    return {
+        async query(text, projectRoot) {
+            try {
+                const stdout = runCodegraph(['query', text, '--json', '--project', projectRoot], projectRoot);
+                const parsed = JSON.parse(stdout);
+                if (Array.isArray(parsed)) {
+                    // Upstream envelope: { node: {id, kind, name, filePath, ...}, score }
+                    // Flatten to our CodegraphQueryHit shape.
+                    return parsed
+                        .map((entry) => {
+                        if (entry && typeof entry === 'object' && 'node' in entry) {
+                            const node = entry.node;
+                            return {
+                                id: String(node.id ?? ''),
+                                kind: String(node.kind ?? 'unknown'),
+                                name: String(node.name ?? ''),
+                                filePath: String(node.filePath ?? ''),
+                                score: Number(entry.score ?? 0)
+                            };
+                        }
+                        return null;
+                    })
+                        .filter((h) => h !== null && h.filePath !== '');
+                }
+                return [];
+            }
+            catch {
+                return [];
+            }
+        },
+        async affected(files, projectRoot) {
+            try {
+                const stdout = runCodegraph(['affected', ...files, '--json', '--project', projectRoot], projectRoot);
+                const parsed = JSON.parse(stdout);
+                return {
+                    changedFiles: parsed.changedFiles ?? files,
+                    affectedTests: parsed.affectedTests ?? [],
+                    totalDependentsTraversed: parsed.totalDependentsTraversed ?? 0
+                };
+            }
+            catch {
+                return { changedFiles: files, affectedTests: [], totalDependentsTraversed: 0 };
+            }
+        },
+        async status(projectRoot) {
+            try {
+                const stdout = runCodegraph(['status', '--project', projectRoot], projectRoot);
+                const nodesMatch = /Nodes:\s+([\d,]+)/.exec(stdout);
+                const edgesMatch = /Edges:\s+([\d,]+)/.exec(stdout);
+                const dbMatch = /DB Size:\s+([\d.]+)\s*MB/.exec(stdout);
+                if (!nodesMatch) {
+                    return { indexed: false, nodes: 0, edges: 0, dbMB: 0, freshness: 'unindexed' };
+                }
+                return {
+                    indexed: true,
+                    nodes: parseInt(nodesMatch[1].replace(/,/g, ''), 10),
+                    edges: parseInt(edgesMatch?.[1].replace(/,/g, '') ?? '0', 10),
+                    dbMB: parseFloat(dbMatch?.[1] ?? '0'),
+                    freshness: 'indexed'
+                };
+            }
+            catch {
+                return { indexed: false, nodes: 0, edges: 0, dbMB: 0, freshness: 'unindexed' };
+            }
+        }
+    };
+}
+function runCodegraph(args, projectRoot) {
+    // Use `peaks codegraph` (the peaks wrapper), which adds --project support.
+    // Falls back to raw `codegraph` (no --project) if peaks is not on PATH.
+    const isWin = process.platform === 'win32';
+    // Try `peaks codegraph` first (the wrapper that understands --project).
+    try {
+        return execFileSync('peaks', ['codegraph', ...args], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: isWin,
+            timeout: 60_000,
+            maxBuffer: 32 * 1024 * 1024
+        }).toString('utf8');
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            // Fallback: raw `codegraph` (won't accept --project, drop it)
+            const fallbackArgs = args.filter((a) => a !== '--project' && !a.startsWith('--project='));
+            const localBin = join(projectRoot, 'node_modules', '.bin', 'codegraph');
+            const command = existsSync(localBin) ? localBin : 'npx';
+            const finalArgs = command === 'npx' ? ['codegraph', ...fallbackArgs] : fallbackArgs;
+            return execFileSync(command, finalArgs, {
+                cwd: projectRoot,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: isWin,
+                timeout: 60_000,
+                maxBuffer: 32 * 1024 * 1024
+            }).toString('utf8');
+        }
+        throw error;
+    }
+}
+export function defaultUnderstandRunner() {
+    return {
+        async read(projectRoot) {
+            const kgPath = join(projectRoot, '.understand-anything', 'knowledge-graph.json');
+            if (!existsSync(kgPath))
+                return null;
+            try {
+                const raw = readFileSync(kgPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                return {
+                    nodes: parsed.nodes ?? [],
+                    edges: parsed.edges ?? [],
+                    layers: parsed.layers ?? []
+                };
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                return null;
+            }
+        }
+    };
+}
+export function defaultImportEdgeRunner() {
+    return {
+        async importsOf(projectRoot, files) {
+            const edges = [];
+            for (const file of files) {
+                const absPath = join(projectRoot, file);
+                if (!existsSync(absPath))
+                    continue;
+                try {
+                    const content = readFileSync(absPath, 'utf8');
+                    const importRe = /import\s+(?:type\s+)?(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)?\s*(?:,\s*(?:\{[^}]*\}|\*\s+as\s+\w+|\w+))?\s*from\s+['"]([^'"]+)['"]/g;
+                    let match;
+                    while ((match = importRe.exec(content)) !== null) {
+                        const importPath = match[1];
+                        if (!importPath.startsWith('.'))
+                            continue;
+                        const fromDir = dirname(file);
+                        const tsPath = importPath.replace(/\.js$/, '.ts').replace(/\.jsx$/, '.tsx');
+                        const resolved = relative(projectRoot, join(projectRoot, fromDir, tsPath));
+                        edges.push({ from: file, to: resolved, evidence: match[0] });
+                    }
+                }
+                catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    // Skip unreadable files
+                }
+            }
+            return edges;
+        }
+    };
+}

package/dist/src/services/slice/slice-decompose-service.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Slice Decomposition Service -- the 6-stage pure algorithm.
+ *
+ * See `.peaks/_runtime/2026-06-13-session-86d852/sc/slice-algorithm-design.md`
+ * for the full spec, and `slice-decompose-types.ts` for all input/output
+ * type contracts.
+ *
+ * Public surface (one exported function):
+ *
+ *   decomposeSlices(rid, prdMarkdown, projectRoot, options)
+ *
+ * Default runners (CLI-mode, real shell-outs):
+ *
+ *   defaultCodegraphRunner()  -- spawns `npx codegraph <cmd>`
+ *   defaultUnderstandRunner() -- reads .understand-anything/knowledge-graph.json
+ *   defaultImportEdgeRunner() -- reads source files for import statements
+ *
+ * Tests inject fakes via the `codegraphRunner`, `understandRunner`, and
+ * `importEdgeRunner` fields of `DecomposeOptions`.
+ */
+import type { DecomposeOptions, DecompositionResult } from './slice-decompose-types.js';
+export type { DecomposeOptions };
+export declare function decomposeSlices(rid: string, prdMarkdown: string, projectRoot: string, options?: DecomposeOptions): Promise<DecompositionResult>;
+export { defaultCodegraphRunner, defaultUnderstandRunner, defaultImportEdgeRunner } from './slice-decompose-runners.js';