peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,82 @@
+/**
+ * tech-change-id-service — change-id-axis slice of the tech planner (rid-012).
+ *
+ * Purpose:
+ *   The original `peaks tech plan` / `peaks tech status` (in `tech-service.ts`)
+ *   is keyed by an active session id (the change-id axis was removed in
+ *   v2.19.0). This module provides the *consumer-side wiring* that lets the
+ *   same CLI surface be re-keyed by an explicit `--change-id <id>` for the
+ *   OpenSpec / change-driven workflow. The path math, change-id validation,
+ *   and workspace-unavailable response are all delegated to the rid-009
+ *   helpers in `src/services/openspec/artifact-boundary.ts`.
+ *
+ * Style:
+ *   - Named function exports (matches `artifact-boundary.ts`).
+ *   - Hand-rolled `Result<T, E>` unions — no `neverthrow` dep.
+ *   - Pure path math; never reads the filesystem.
+ *
+ * Hard ban:
+ *   - This file MUST NOT import from `peaks-loop-shared` (stays inside
+ *     peaks-loop per §9 of the rid-012 plan).
+ *   - This file MUST NOT touch `src/services/openspec/artifact-boundary.ts`
+ *     (rid-009 helpers are frozen; we only consume via import).
+ */
+import type { WorkspaceConfig } from '../config/config-types.js';
+import { type BoundaryError, type ChangeIdError, type PlanArtifactPathOutput, type WorkspaceUnavailableResponse, type Result } from '../openspec/artifact-boundary.js';
+export type TechArtifactPathResult = PlanArtifactPathOutput;
+export type TechChangeArtifacts = {
+    taskGraph: TechArtifactPathResult;
+    waveManifests: TechArtifactPathResult[];
+    reviewChecklist: TechArtifactPathResult;
+    approvalTemplate: TechArtifactPathResult;
+};
+export type TechChangeStatusValue = 'unavailable' | 'missing' | 'blocked' | 'approved';
+export type TechChangeStatus = {
+    changeId: string;
+    status: TechChangeStatusValue;
+    artifactRoot: string;
+    requiredArtifacts: string[];
+    missingArtifacts: string[];
+    approvalRecord: string | null;
+    blockedReasons: string[];
+    nextActions: string[];
+};
+/**
+ * Validate a change-id string. This is a thin consumer-side wrapper that
+ * delegates to `validateChangeId` (rid-009). The wrapper exists so the
+ * change-id-axis service has a single named export point (`validateTechChangeId`)
+ * and so the test file can import it without reaching across to openspec.
+ */
+export declare function validateTechChangeId(id: string): Result<{
+    changeId: string;
+}, ChangeIdError>;
+/**
+ * Plan the 5 artifact-relative paths the tech-change-id planner needs to
+ * expose:
+ *   - `taskGraph`           → `<id>/architecture/tech-task-graph.json`
+ *   - `waveManifests`       → `<id>/architecture/waves/wave-<n>-<wave>.json` (4)
+ *   - `reviewChecklist`     → `<id>/architecture/tech-review-checklist.md`
+ *   - `approvalTemplate`    → `<id>/architecture/tech-approval-record.template.md`
+ *
+ * Delegates to `planArtifactPath` (rid-009) for each one. Returns the FIRST
+ * failure (so callers get a single, deterministic BoundaryError).
+ *
+ * Pure path math — does not touch the filesystem.
+ */
+export declare function planTechArtifactPath(input: {
+    changeId: string;
+    workspaceRoot: string;
+    requestId: string;
+}): Result<TechChangeArtifacts, BoundaryError>;
+/**
+ * Build the workspace-unavailable response for the change-id-axis tech
+ * planner. Thin wrapper around `buildWorkspaceUnavailable` (rid-009) so
+ * the same single source of truth (nextActions constant) is reused.
+ *
+ * The `mode` discriminator matches the existing artifact-boundary shape
+ * (`'preview-only' | 'blocked'`).
+ */
+export declare function buildTechWorkspaceUnavailable(input: {
+    mode: WorkspaceUnavailableResponse['mode'];
+}): WorkspaceUnavailableResponse;
+export type { WorkspaceConfig };

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

@@ -0,0 +1,117 @@
+/**
+ * tech-change-id-service — change-id-axis slice of the tech planner (rid-012).
+ *
+ * Purpose:
+ *   The original `peaks tech plan` / `peaks tech status` (in `tech-service.ts`)
+ *   is keyed by an active session id (the change-id axis was removed in
+ *   v2.19.0). This module provides the *consumer-side wiring* that lets the
+ *   same CLI surface be re-keyed by an explicit `--change-id <id>` for the
+ *   OpenSpec / change-driven workflow. The path math, change-id validation,
+ *   and workspace-unavailable response are all delegated to the rid-009
+ *   helpers in `src/services/openspec/artifact-boundary.ts`.
+ *
+ * Style:
+ *   - Named function exports (matches `artifact-boundary.ts`).
+ *   - Hand-rolled `Result<T, E>` unions — no `neverthrow` dep.
+ *   - Pure path math; never reads the filesystem.
+ *
+ * Hard ban:
+ *   - This file MUST NOT import from `peaks-loop-shared` (stays inside
+ *     peaks-loop per §9 of the rid-012 plan).
+ *   - This file MUST NOT touch `src/services/openspec/artifact-boundary.ts`
+ *     (rid-009 helpers are frozen; we only consume via import).
+ */
+import { buildWorkspaceUnavailable, planArtifactPath, validateChangeId, } from '../openspec/artifact-boundary.js';
+/**
+ * Wave template names — must match the 4 waves the existing
+ * `tech-service.ts#createTechGraph` produces (scan / document / review /
+ * reducer). The relative path layout follows `design.md §Artifact Layout`
+ * verbatim: `<change-id>/architecture/waves/wave-<index>-<wave>.json`.
+ */
+const TECH_CHANGE_ID_WAVES = ['scan', 'document', 'review', 'reducer'];
+const TECH_ARCHITECTURE_ROOT = '<changeId>/architecture';
+/**
+ * Validate a change-id string. This is a thin consumer-side wrapper that
+ * delegates to `validateChangeId` (rid-009). The wrapper exists so the
+ * change-id-axis service has a single named export point (`validateTechChangeId`)
+ * and so the test file can import it without reaching across to openspec.
+ */
+export function validateTechChangeId(id) {
+    return validateChangeId(id);
+}
+/**
+ * Plan the 5 artifact-relative paths the tech-change-id planner needs to
+ * expose:
+ *   - `taskGraph`           → `<id>/architecture/tech-task-graph.json`
+ *   - `waveManifests`       → `<id>/architecture/waves/wave-<n>-<wave>.json` (4)
+ *   - `reviewChecklist`     → `<id>/architecture/tech-review-checklist.md`
+ *   - `approvalTemplate`    → `<id>/architecture/tech-approval-record.template.md`
+ *
+ * Delegates to `planArtifactPath` (rid-009) for each one. Returns the FIRST
+ * failure (so callers get a single, deterministic BoundaryError).
+ *
+ * Pure path math — does not touch the filesystem.
+ */
+export function planTechArtifactPath(input) {
+    const taskGraphResult = planArtifactPath({
+        changeId: input.changeId,
+        workspaceRoot: input.workspaceRoot,
+        role: 'architecture',
+        requestId: input.requestId,
+        template: `${TECH_ARCHITECTURE_ROOT}/tech-task-graph.json`,
+    });
+    if (!taskGraphResult.ok)
+        return taskGraphResult;
+    const waveManifestResults = [];
+    for (let index = 0; index < TECH_CHANGE_ID_WAVES.length; index += 1) {
+        const wave = TECH_CHANGE_ID_WAVES[index];
+        const waveResult = planArtifactPath({
+            changeId: input.changeId,
+            workspaceRoot: input.workspaceRoot,
+            role: 'architecture',
+            requestId: input.requestId,
+            template: `${TECH_ARCHITECTURE_ROOT}/waves/wave-${index + 1}-${wave}.json`,
+        });
+        if (!waveResult.ok)
+            return waveResult;
+        waveManifestResults.push(waveResult.value);
+    }
+    const reviewChecklistResult = planArtifactPath({
+        changeId: input.changeId,
+        workspaceRoot: input.workspaceRoot,
+        role: 'architecture',
+        requestId: input.requestId,
+        template: `${TECH_ARCHITECTURE_ROOT}/tech-review-checklist.md`,
+    });
+    if (!reviewChecklistResult.ok)
+        return reviewChecklistResult;
+    const approvalTemplateResult = planArtifactPath({
+        changeId: input.changeId,
+        workspaceRoot: input.workspaceRoot,
+        role: 'architecture',
+        requestId: input.requestId,
+        template: `${TECH_ARCHITECTURE_ROOT}/tech-approval-record.template.md`,
+    });
+    if (!approvalTemplateResult.ok)
+        return approvalTemplateResult;
+    return {
+        ok: true,
+        value: {
+            taskGraph: taskGraphResult.value,
+            waveManifests: waveManifestResults,
+            reviewChecklist: reviewChecklistResult.value,
+            approvalTemplate: approvalTemplateResult.value,
+        },
+    };
+}
+/**
+ * Build the workspace-unavailable response for the change-id-axis tech
+ * planner. Thin wrapper around `buildWorkspaceUnavailable` (rid-009) so
+ * the same single source of truth (nextActions constant) is reused.
+ *
+ * The `mode` discriminator matches the existing artifact-boundary shape
+ * (`'preview-only' | 'blocked'`).
+ */
+export function buildTechWorkspaceUnavailable(input) {
+    return buildWorkspaceUnavailable(input);
+}

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;