peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/tech/tech-service.d.ts

@@ -0,0 +1,69 @@
+import type { WorkspaceConfig } from '../config/config-types.js';
+export type TechWaveName = 'scan' | 'document' | 'review' | 'reducer';
+export type TechStatusValue = 'unavailable' | 'missing' | 'blocked' | 'approved';
+export type TechPlanRequest = {
+    sessionId: string;
+    goal: string;
+    swarm: boolean;
+    dryRun: true;
+    artifactWorkspacePath?: string;
+    workspace?: WorkspaceConfig;
+};
+export type TechWave = {
+    name: TechWaveName;
+    taskIds: string[];
+};
+export type TechTask = {
+    taskId: string;
+    wave: TechWaveName;
+    workerKind: string;
+    purpose: string;
+    inputs: string[];
+    outputs: string[];
+    dependsOn: string[];
+    conflictGroup: string;
+    briefPath: string;
+};
+export type TechPlanGraph = {
+    available: true;
+    sessionId: string;
+    goal: string;
+    swarm: boolean;
+    dryRun: true;
+    artifactRoot: string;
+    waves: TechWave[];
+    tasks: TechTask[];
+    outputs: {
+        taskGraph: string;
+        waveManifests: string[];
+        reviewChecklist: string;
+        approvalTemplate: string;
+    };
+    blockedReasons: string[];
+    nextActions: string[];
+};
+export type TechPlanPreview = {
+    available: false;
+    behavior: 'preview';
+    reason: string;
+    preview: Omit<TechPlanGraph, 'available'>;
+    nextActions: readonly string[];
+};
+export type TechPlanResult = TechPlanGraph | TechPlanPreview;
+export type TechStatus = {
+    sessionId: string;
+    status: TechStatusValue;
+    artifactRoot: string;
+    requiredArtifacts: string[];
+    missingArtifacts: string[];
+    approvalRecord: string | null;
+    blockedReasons: string[];
+    nextActions: string[];
+};
+export declare const TECH_REQUIRED_ARTIFACTS: readonly string[];
+export declare function createTechPlan(request: TechPlanRequest): TechPlanResult;
+export declare function getTechStatus(options: {
+    sessionId: string;
+    artifactWorkspacePath?: string;
+    workspace?: WorkspaceConfig;
+}): TechStatus;

package/dist/services/tech/tech-service.js

@@ -0,0 +1,299 @@
+import { closeSync, existsSync, fstatSync, lstatSync, openSync, readSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isInsidePath, stableRealPath } from '../../shared/path-utils.js';
+import { WORKSPACE_UNAVAILABLE_NEXT_ACTIONS } from '../../shared/planner-response.js';
+import { hasValidArtifactWorkspace } from '../artifacts/workspace-service.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+export const TECH_REQUIRED_ARTIFACTS = Object.freeze([
+    'frontend-tech-doc.md',
+    'backend-tech-doc.md',
+    'contract-tech-doc.md',
+    'test-tech-doc.md',
+    'platform-tech-doc.md',
+    'security-tech-doc.md',
+    'ci-tech-doc.md',
+    'migration-tech-doc.md',
+    'tech-review-report.md',
+    'tech-approval-record.md',
+]);
+const TECH_WAVE_TASKS = [
+    { name: 'scan', taskIds: ['tech-architecture-scan', 'tech-frontend-scan', 'tech-backend-scan', 'tech-contract-scan', 'tech-test-scan', 'tech-platform-scan', 'tech-security-scan', 'tech-ci-scan'] },
+    { name: 'document', taskIds: ['tech-frontend-doc-worker', 'tech-backend-doc-worker', 'tech-contract-doc-worker', 'tech-test-doc-worker', 'tech-platform-doc-worker', 'tech-security-doc-worker', 'tech-ci-doc-worker', 'tech-migration-doc-worker'] },
+    { name: 'review', taskIds: ['tech-architecture-reviewer', 'tech-contract-reviewer', 'tech-security-reviewer', 'tech-test-reviewer', 'tech-platform-reviewer', 'tech-risk-reviewer'] },
+    { name: 'reducer', taskIds: ['tech-reducer'] },
+];
+function assertNonEmptyGoal(goal) {
+    if (goal.trim().length === 0) {
+        throw new Error('Goal must be non-empty');
+    }
+}
+function architectureRoot(_sessionId) {
+    // Slice 2026-06-29-change-id-root-removal: descriptor is now the bare
+    // role-relative sub-path `<role>/architecture` (no `.peaks/_runtime/...`
+    // prefix). The on-disk location is resolved by `architectureRootAbs`
+    // via `getSessionDir`. Callers that previously split this string on
+    // the change-id segment need to use the descriptor as-is and resolve
+    // the absolute path via `architectureRootAbs` / `getSessionDir`.
+    return 'rd/architecture';
+}
+function architectureRootAbs(artifactWorkspacePath, sessionId) {
+    // Slice 2026-06-29-change-id-root-removal: on-disk path now resolves
+    // via the session-axis `getSessionDir(root, sessionId)` (the change-id
+    // identifier is reused as the session-dir name for tech-artifact
+    // reads, matching the test helper `writeApprovedTechArtifacts` and
+    // `autonomous-resume-writer.ts`).
+    return join(getSessionDir(artifactWorkspacePath, sessionId), 'rd', 'architecture');
+}
+function hasPlannerArtifactWorkspace(artifactWorkspacePath, workspace) {
+    return !!workspace && hasValidArtifactWorkspace(workspace, artifactWorkspacePath);
+}
+function isEscapedArchitectureRoot(rootPath, artifactWorkspacePath) {
+    if (!existsSync(rootPath)) {
+        return false;
+    }
+    try {
+        const rdRootPath = resolve(rootPath, '..');
+        const sessionRootPath = resolve(rdRootPath, '..');
+        return lstatSync(sessionRootPath).isSymbolicLink()
+            || lstatSync(rdRootPath).isSymbolicLink()
+            || lstatSync(rootPath).isSymbolicLink()
+            || !isInsidePath(stableRealPath(rootPath), stableRealPath(artifactWorkspacePath));
+    }
+    catch {
+        return true;
+    }
+}
+const MAX_TECH_ARTIFACT_BYTES = 256_000;
+function readTechArtifactFile(rootPath, artifact) {
+    const artifactPath = resolve(rootPath, artifact);
+    try {
+        const rootRealPath = stableRealPath(rootPath);
+        const artifactStat = lstatSync(artifactPath);
+        if (artifactStat.isSymbolicLink() || !artifactStat.isFile() || artifactStat.size > MAX_TECH_ARTIFACT_BYTES) {
+            return null;
+        }
+        if (!isInsidePath(stableRealPath(artifactPath), rootRealPath)) {
+            return null;
+        }
+        const fd = openSync(artifactPath, 'r');
+        try {
+            const openedStat = fstatSync(fd);
+            const currentStat = statSync(artifactPath);
+            if (!openedStat.isFile() || openedStat.size > MAX_TECH_ARTIFACT_BYTES || openedStat.dev !== artifactStat.dev || openedStat.ino !== artifactStat.ino || openedStat.dev !== currentStat.dev || openedStat.ino !== currentStat.ino) {
+                return null;
+            }
+            const buffer = Buffer.alloc(openedStat.size);
+            let offset = 0;
+            while (offset < openedStat.size) {
+                const bytesRead = readSync(fd, buffer, offset, openedStat.size - offset, offset);
+                if (bytesRead === 0) {
+                    return null;
+                }
+                offset += bytesRead;
+            }
+            const finalStat = fstatSync(fd);
+            if (finalStat.dev !== openedStat.dev || finalStat.ino !== openedStat.ino) {
+                return null;
+            }
+            return buffer.toString('utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function isValidArtifactFile(rootPath, artifact) {
+    const artifactPath = resolve(rootPath, artifact);
+    try {
+        const artifactStat = lstatSync(artifactPath);
+        if (artifactStat.isSymbolicLink())
+            return false;
+        if (!artifactStat.isFile())
+            return false;
+        if (!isInsidePath(stableRealPath(artifactPath), stableRealPath(rootPath)))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function waveManifestPath(_sessionId, index, wave) {
+    // Slice 2026-06-29-change-id-root-removal: descriptor is now
+    // `rd/architecture/waves/<file>`. The scope root is supplied by the
+    // caller via `getSessionDir`.
+    return `rd/architecture/waves/wave-${index + 1}-${wave}.json`;
+}
+function taskPurpose(taskId, goal) {
+    return `${taskId.replace(/^tech-/, '').replace(/-/g, ' ')} for ${goal}`;
+}
+function createTechGraph(request) {
+    // Slice 2026-06-29-change-id-root-removal: change-id is metadata-only;
+    // no structural validation gate fires here.
+    assertNonEmptyGoal(request.goal);
+    const [scanWave, documentWave, reviewWave] = TECH_WAVE_TASKS;
+    const waves = TECH_WAVE_TASKS.map((wave) => ({ name: wave.name, taskIds: [...wave.taskIds] }));
+    const scanTaskIds = scanWave.taskIds;
+    const documentTaskIds = documentWave.taskIds;
+    const reviewTaskIds = reviewWave.taskIds;
+    const tasks = TECH_WAVE_TASKS.flatMap((wave) => wave.taskIds.map((taskId) => {
+        const dependsOn = wave.name === 'scan'
+            ? []
+            : wave.name === 'document'
+                ? [...scanTaskIds]
+                : wave.name === 'review'
+                    ? [...documentTaskIds]
+                    : [...reviewTaskIds];
+        const briefPath = `rd/architecture/workers/${taskId}/brief.md`;
+        return {
+            taskId,
+            wave: wave.name,
+            workerKind: taskId,
+            purpose: taskPurpose(taskId, request.goal),
+            inputs: [request.goal, architectureRoot(request.sessionId)],
+            outputs: [briefPath],
+            dependsOn,
+            conflictGroup: `tech-${wave.name}`,
+            briefPath,
+        };
+    }));
+    return {
+        sessionId: request.sessionId,
+        goal: request.goal,
+        swarm: request.swarm,
+        dryRun: true,
+        artifactRoot: architectureRoot(request.sessionId),
+        waves,
+        tasks,
+        outputs: {
+            taskGraph: 'rd/architecture/tech-task-graph.json',
+            waveManifests: waves.map((wave, index) => waveManifestPath(request.sessionId, index, wave.name)),
+            reviewChecklist: 'rd/architecture/tech-review-checklist.md',
+            approvalTemplate: 'rd/architecture/tech-approval-record.template.md',
+        },
+        blockedReasons: [],
+        nextActions: [],
+    };
+}
+export function createTechPlan(request) {
+    const graph = createTechGraph(request);
+    if (!request.artifactWorkspacePath || !hasPlannerArtifactWorkspace(request.artifactWorkspacePath, request.workspace)) {
+        return {
+            available: false,
+            behavior: 'preview',
+            reason: 'artifact-workspace-unavailable',
+            preview: graph,
+            nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+        };
+    }
+    return {
+        available: true,
+        ...graph,
+    };
+}
+export function getTechStatus(options) {
+    // Slice 2026-06-29-change-id-root-removal: change-id is metadata-only;
+    // no structural validation gate fires here.
+    const artifactRoot = architectureRoot(options.sessionId);
+    if (!options.artifactWorkspacePath) {
+        return {
+            sessionId: options.sessionId,
+            status: 'unavailable',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            approvalRecord: null,
+            blockedReasons: ['artifact-workspace-unavailable'],
+            nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+        };
+    }
+    if (!hasPlannerArtifactWorkspace(options.artifactWorkspacePath, options.workspace)) {
+        return {
+            sessionId: options.sessionId,
+            status: 'unavailable',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            approvalRecord: null,
+            blockedReasons: ['artifact-workspace-unavailable'],
+            nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+        };
+    }
+    const rootPath = architectureRootAbs(options.artifactWorkspacePath, options.sessionId);
+    const approvalRecord = 'rd/architecture/tech-approval-record.md';
+    if (isEscapedArchitectureRoot(rootPath, options.artifactWorkspacePath)) {
+        return {
+            sessionId: options.sessionId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            approvalRecord: null,
+            blockedReasons: ['tech-artifacts-missing'],
+            nextActions: ['Run peaks tech plan --dry-run, then persist and review the required tech artifacts.'],
+        };
+    }
+    const missingArtifacts = TECH_REQUIRED_ARTIFACTS.filter((artifact) => !existsSync(join(rootPath, artifact)) || !isValidArtifactFile(rootPath, artifact));
+    if (missingArtifacts.length === 1 && missingArtifacts[0] === 'tech-approval-record.md') {
+        return {
+            sessionId: options.sessionId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord: null,
+            blockedReasons: ['tech-approval-missing'],
+            nextActions: ['Create tech-approval-record.md with status: approved after review.'],
+        };
+    }
+    if (missingArtifacts.length > 0) {
+        return {
+            sessionId: options.sessionId,
+            status: missingArtifacts.length === TECH_REQUIRED_ARTIFACTS.length ? 'missing' : 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord: missingArtifacts.includes('tech-approval-record.md') ? null : approvalRecord,
+            blockedReasons: ['tech-artifacts-missing'],
+            nextActions: ['Run peaks tech plan --dry-run, then persist and review the required tech artifacts.'],
+        };
+    }
+    const approvalContent = readTechArtifactFile(rootPath, 'tech-approval-record.md');
+    if (approvalContent === null) {
+        return {
+            sessionId: options.sessionId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord,
+            blockedReasons: ['tech-approval-unreadable'],
+            nextActions: ['Ensure tech-approval-record.md is readable and contains status: approved.'],
+        };
+    }
+    if (!approvalContent.split(/\r?\n/).some((line) => line.trim() === 'status: approved')) {
+        return {
+            sessionId: options.sessionId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord,
+            blockedReasons: ['tech-approval-not-approved'],
+            nextActions: ['Update tech-approval-record.md with status: approved after review.'],
+        };
+    }
+    return {
+        sessionId: options.sessionId,
+        status: 'approved',
+        artifactRoot,
+        requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+        missingArtifacts: [],
+        approvalRecord,
+        blockedReasons: [],
+        nextActions: [],
+    };
+}

package/dist/services/test-cache/test-cache-service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `peaks test` per-test fingerprint cache (slice 2.5.0 sub-fix B).
+ *
+ * Persists per-test results keyed by (file, testName) so a re-run can
+ * skip tests where the file's mtime + sha256 are unchanged AND the
+ * previous run status was "passed". The cache lives at
+ * `<projectRoot>/.peaks/_runtime/test-cache/<hash>.json` and is
+ * session-bound runtime state (gitignored via the existing
+ * `.peaks/_runtime/` rule).
+ *
+ * Schema (per file):
+ *   {
+ *     filePath: string;            // absolute path to the test file
+ *     fileMtime: number;           // mtime in ms
+ *     fileSha256: string;          // hex sha256
+ *     framework: 'jest' | 'vitest' | 'mocha';
+ *     tests: Array<{
+ *       testName: string;
+ *       status: 'passed' | 'failed' | 'skipped';
+ *       durationMs: number;
+ *       lastRun: string;           // ISO timestamp
+ *     }>;
+ *     lastRunAt: string;
+ *   }
+ */
+export type TestFramework = 'jest' | 'vitest' | 'mocha';
+export type TestStatus = 'passed' | 'failed' | 'skipped';
+export interface TestRecord {
+    testName: string;
+    status: TestStatus;
+    durationMs: number;
+    lastRun: string;
+}
+export interface TestCacheFile {
+    filePath: string;
+    fileMtime: number;
+    fileSha256: string;
+    framework: TestFramework;
+    tests: TestRecord[];
+    lastRunAt: string;
+}
+export declare const TEST_CACHE_DIR = "test-cache";
+export declare function testCacheDir(projectRoot: string): string;
+export declare function testCachePath(projectRoot: string, filePath: string): string;
+export declare function sha256OfFile(filePath: string): string;
+export declare function mtimeOfFile(filePath: string): number;
+export declare function readTestCache(projectRoot: string, filePath: string): TestCacheFile | null;
+export declare function writeTestCache(projectRoot: string, cache: TestCacheFile): void;
+export declare function clearTestCache(projectRoot: string): {
+    removed: number;
+};
+export interface CacheLookup {
+    hit: boolean;
+    reason?: 'no-cache' | 'mtime-changed' | 'sha-changed' | 'previous-failed' | 'previous-skipped';
+    cached?: TestRecord;
+}
+/**
+ * Decide whether a test is cacheable (i.e. can be skipped on a re-run).
+ * Returns hit=true if the cache record shows passed AND both
+ * (fileMtime, fileSha256) match the current file state.
+ */
+export declare function isCacheable(projectRoot: string, filePath: string, testName: string): CacheLookup;
+export declare function recordTestResult(projectRoot: string, filePath: string, framework: TestFramework, record: TestRecord): void;
+/**
+ * Detect the consumer project's test framework by reading
+ * package.json devDependencies / dependencies. Picks the dominant
+ * one (most-installed). Returns null if no supported framework
+ * is found.
+ */
+export declare function detectTestFramework(projectRoot: string): TestFramework | null;

package/dist/services/test-cache/test-cache-service.js

@@ -0,0 +1,175 @@
+/**
+ * `peaks test` per-test fingerprint cache (slice 2.5.0 sub-fix B).
+ *
+ * Persists per-test results keyed by (file, testName) so a re-run can
+ * skip tests where the file's mtime + sha256 are unchanged AND the
+ * previous run status was "passed". The cache lives at
+ * `<projectRoot>/.peaks/_runtime/test-cache/<hash>.json` and is
+ * session-bound runtime state (gitignored via the existing
+ * `.peaks/_runtime/` rule).
+ *
+ * Schema (per file):
+ *   {
+ *     filePath: string;            // absolute path to the test file
+ *     fileMtime: number;           // mtime in ms
+ *     fileSha256: string;          // hex sha256
+ *     framework: 'jest' | 'vitest' | 'mocha';
+ *     tests: Array<{
+ *       testName: string;
+ *       status: 'passed' | 'failed' | 'skipped';
+ *       durationMs: number;
+ *       lastRun: string;           // ISO timestamp
+ *     }>;
+ *     lastRunAt: string;
+ *   }
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+export const TEST_CACHE_DIR = 'test-cache';
+export function testCacheDir(projectRoot) {
+    return join(projectRoot, '.peaks', '_runtime', TEST_CACHE_DIR);
+}
+export function testCachePath(projectRoot, filePath) {
+    const abs = resolve(filePath);
+    const hash = createHash('sha256').update(abs).digest('hex').slice(0, 16);
+    return join(testCacheDir(projectRoot), `${hash}.json`);
+}
+export function sha256OfFile(filePath) {
+    const buf = readFileSync(filePath);
+    return createHash('sha256').update(buf).digest('hex');
+}
+export function mtimeOfFile(filePath) {
+    return statSync(filePath).mtimeMs;
+}
+export function readTestCache(projectRoot, filePath) {
+    const path = testCachePath(projectRoot, filePath);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+export function writeTestCache(projectRoot, cache) {
+    const path = testCachePath(projectRoot, cache.filePath);
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(cache, null, 2) + '\n', 'utf8');
+}
+export function clearTestCache(projectRoot) {
+    const dir = testCacheDir(projectRoot);
+    if (!existsSync(dir))
+        return { removed: 0 };
+    let removed = 0;
+    for (const entry of readdirSync(dir)) {
+        if (entry.endsWith('.json')) {
+            unlinkSync(join(dir, entry));
+            removed += 1;
+        }
+    }
+    return { removed };
+}
+/**
+ * Decide whether a test is cacheable (i.e. can be skipped on a re-run).
+ * Returns hit=true if the cache record shows passed AND both
+ * (fileMtime, fileSha256) match the current file state.
+ */
+export function isCacheable(projectRoot, filePath, testName) {
+    const cache = readTestCache(projectRoot, filePath);
+    if (!cache)
+        return { hit: false, reason: 'no-cache' };
+    if (!existsSync(filePath)) {
+        return { hit: false, reason: 'mtime-changed' };
+    }
+    const currentMtime = mtimeOfFile(filePath);
+    const currentSha = sha256OfFile(filePath);
+    if (cache.fileMtime !== currentMtime) {
+        return { hit: false, reason: 'mtime-changed' };
+    }
+    if (cache.fileSha256 !== currentSha) {
+        return { hit: false, reason: 'sha-changed' };
+    }
+    const record = cache.tests.find((t) => t.testName === testName);
+    if (!record)
+        return { hit: false, reason: 'no-cache' };
+    if (record.status !== 'passed') {
+        return { hit: false, reason: record.status === 'failed' ? 'previous-failed' : 'previous-skipped' };
+    }
+    return { hit: true, cached: record };
+}
+export function recordTestResult(projectRoot, filePath, framework, record) {
+    const abs = resolve(filePath);
+    let cache = readTestCache(projectRoot, abs);
+    const mtime = existsSync(abs) ? mtimeOfFile(abs) : Date.now();
+    const sha = existsSync(abs) ? sha256OfFile(abs) : '';
+    if (!cache) {
+        cache = {
+            filePath: abs,
+            fileMtime: mtime,
+            fileSha256: sha,
+            framework,
+            tests: [],
+            lastRunAt: new Date().toISOString()
+        };
+    }
+    else {
+        cache.fileMtime = mtime;
+        cache.fileSha256 = sha;
+        cache.framework = framework;
+        cache.lastRunAt = new Date().toISOString();
+    }
+    const idx = cache.tests.findIndex((t) => t.testName === record.testName);
+    if (idx >= 0) {
+        cache.tests[idx] = record;
+    }
+    else {
+        cache.tests.push(record);
+    }
+    writeTestCache(projectRoot, cache);
+}
+/**
+ * Detect the consumer project's test framework by reading
+ * package.json devDependencies / dependencies. Picks the dominant
+ * one (most-installed). Returns null if no supported framework
+ * is found.
+ */
+export function detectTestFramework(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return null;
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    const all = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {})
+    };
+    const present = [];
+    if (all['jest'] || all['@jest/core'])
+        present.push('jest');
+    if (all['vitest'])
+        present.push('vitest');
+    if (all['mocha'])
+        present.push('mocha');
+    if (present.length === 0)
+        return null;
+    // Deterministic order: jest > vitest > mocha (no "dominant" metric
+    // in package.json; we use the most-common-2.x convention).
+    const order = ['jest', 'vitest', 'mocha'];
+    for (const fw of order) {
+        if (present.includes(fw))
+            return fw;
+    }
+    return present[0] ?? null;
+}

package/dist/services/understand/hybrid-types.d.ts

@@ -0,0 +1,32 @@
+import type { CodegraphExecutionResult } from '../codegraph/codegraph-service.js';
+import type { UnderstandScanReport } from './understand-types.js';
+import type { UnderstandGraphSummary } from './understand-scan-service.js';
+/**
+ * Slice 2026-07-02-codegraph-ua-hybrid — envelope contract for the
+ * `peaks understand context` command. The service layer decides which
+ * evidence to include based on environment detection; the source field
+ * is the authoritative routing signal.
+ */
+export type UnderstandContextSource = 'ua-only' | 'ua-missing-fallback-codegraph' | 'ua-and-codegraph-hybrid' | 'both-missing';
+export type CodegraphContextBlock = {
+    invocation: {
+        subcommand: 'affected';
+        files: string[];
+    };
+    execution: CodegraphExecutionResult;
+    /** Parsed JSON from `codegraph affected --json` when exitCode === 0; null otherwise. */
+    payload: unknown;
+    parseError?: string;
+};
+export type UnderstandContextResult = {
+    projectRoot: string;
+    source: UnderstandContextSource;
+    ua?: {
+        scan: UnderstandScanReport;
+        summary?: UnderstandGraphSummary;
+    };
+    codegraph?: CodegraphContextBlock;
+    /** Wall-clock milliseconds spent on the slowest parallel branch. */
+    durationMs: number;
+    warnings: string[];
+};

package/dist/services/understand/hybrid-types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/understand/understand-hybrid-service.d.ts

@@ -0,0 +1,10 @@
+import { type CodegraphProcessRunner } from '../codegraph/codegraph-service.js';
+import type { UnderstandContextResult } from './hybrid-types.js';
+export type BuildUnderstandContextOptions = {
+    projectRoot: string;
+    files?: string[];
+    sampleSize?: number;
+    artifactDir?: string;
+    codegraphRunner?: CodegraphProcessRunner;
+};
+export declare function buildUnderstandContext(options: BuildUnderstandContextOptions): Promise<UnderstandContextResult>;