peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/feedback/feedback-promotion-service.d.ts

@@ -0,0 +1,123 @@
+/**
+ * v2.15.0 slice 002 — AC-3: feedback-promotion service.
+ *
+ * `.peaks/memory/<name>.md` memories with `metadata.type === 'feedback'`
+ * are user-given rules. They are advisory (LLM-readable) until promoted
+ * to at least one enforcement layer (peaks-sop gate / peaks-hooks
+ * PreToolUse / mode-gate hardFloorCategory). This service is the
+ * primitive behind the `peaks feedback promote` and
+ * `peaks feedback check-unpromoted` CLI commands.
+ *
+ * Promotion tracking convention: a feedback memory is considered
+ * "promoted" when one of the following is true:
+ *
+ *   (a) The memory file contains an HTML comment near the top of the
+ *       body: `<!-- peaks-feedback-promoted: layer=<A|B|C> -->`.
+ *       Written by `peaks feedback promote` so a single read of the
+ *       memory file is enough to determine promotion state.
+ *
+ *   (b) A sibling `.peaks/memory/<name>.promotion.json` exists with
+ *       `{ layer: "A" | "B" | "C", ... }`. Written as a sidecar for
+ *       tooling that prefers machine-readable state over embedded
+ *       comments (e.g. `verify-pipeline` Gate H).
+ *
+ * The comment marker is the SOURCE OF TRUTH for human review; the
+ * sidecar is the source of truth for the scanner. Either is enough
+ * to mark a feedback memory as promoted.
+ */
+export type PromotionLayer = 'A' | 'B' | 'C';
+export declare const PROMOTION_LAYERS: readonly PromotionLayer[];
+export type PromotionLayerDetail = {
+    layer: PromotionLayer;
+    label: string;
+    /** One-line description of what kind of rule belongs on this layer. */
+    description: string;
+};
+export declare const PROMOTION_LAYER_DETAILS: readonly PromotionLayerDetail[];
+export type FeedbackMemory = {
+    /** File basename (without `.md`). */
+    name: string;
+    /** Absolute path to the .md file. */
+    path: string;
+    /** Parsed frontmatter. */
+    frontmatter: {
+        name?: string;
+        description?: string;
+        kind?: string;
+    };
+    /** Body text (after the closing `---`). */
+    body: string;
+    /** Parsed promotion marker (from comment OR sidecar). null when unpromoted. */
+    promotion: {
+        layer: PromotionLayer;
+        source: 'comment' | 'sidecar';
+        detail: string;
+    } | null;
+};
+export type UnpromotedFeedbackEntry = {
+    name: string;
+    path: string;
+    reason: string;
+};
+/**
+ * Parse a single `.peaks/memory/<file>.md` into a FeedbackMemory, or
+ * `null` when the file is missing / unreadable / not a feedback memory.
+ *
+ * The "is this a feedback memory?" check is intentionally narrow: only
+ * frontmatter with `metadata.type === 'feedback'` OR top-level
+ * `type: feedback` qualifies. Other memory kinds (project / rule /
+ * decision / reference / convention / module / lesson) are skipped.
+ */
+export declare function parseFeedbackMemory(filePath: string): FeedbackMemory | null;
+/**
+ * Scan `.peaks/memory/*.md` for feedback memories and return those
+ * that are NOT promoted to any enforcement layer. Pure read; the
+ * CLI command emits the warning list + (with `--strict`) a non-zero
+ * exit code.
+ */
+export declare function listUnpromotedFeedback(opts: {
+    projectRoot: string;
+}): UnpromotedFeedbackEntry[];
+/**
+ * Generate the code stub for a given layer. Returns a Markdown
+ * snippet the LLM / human can paste into the appropriate file. Pure
+ * function — does NOT touch disk. The CLI command wraps this with
+ * the disk write / envelope emission.
+ */
+export declare function generatePromotionStub(opts: {
+    layer: PromotionLayer;
+    feedbackName: string;
+    feedbackBody: string;
+}): {
+    snippet: string;
+    targetFiles: string[];
+};
+export type FeedbackPromoteEnvelope = {
+    name: string;
+    feedbackPath: string;
+    layer: PromotionLayer;
+    layerDetail: string;
+    generatedFiles: string[];
+    snippet: string;
+    promotedAt: string;
+    promotedBy: string;
+};
+/**
+ * Write the promotion marker + sidecar. Also writes the envelope to
+ * `.peaks/_runtime/<sid>/rd/feedback-promote-<name>.json` for QA
+ * auditing. Returns the envelope so the CLI can emit it.
+ *
+ * The promotion marker is embedded in the memory file (so it
+ * travels with the file across git history); the sidecar is a
+ * machine-readable mirror. Both are written; either alone is
+ * enough for the scanner.
+ */
+export declare function promoteFeedback(opts: {
+    feedbackPath: string;
+    layer: PromotionLayer;
+    promotedBy: string;
+    sessionId: string;
+    projectRoot: string;
+    dryRun?: boolean;
+}): FeedbackPromoteEnvelope;
+export declare function isPromotionLayer(value: string): value is PromotionLayer;

package/dist/services/feedback/feedback-promotion-service.js

@@ -0,0 +1,300 @@
+/**
+ * v2.15.0 slice 002 — AC-3: feedback-promotion service.
+ *
+ * `.peaks/memory/<name>.md` memories with `metadata.type === 'feedback'`
+ * are user-given rules. They are advisory (LLM-readable) until promoted
+ * to at least one enforcement layer (peaks-sop gate / peaks-hooks
+ * PreToolUse / mode-gate hardFloorCategory). This service is the
+ * primitive behind the `peaks feedback promote` and
+ * `peaks feedback check-unpromoted` CLI commands.
+ *
+ * Promotion tracking convention: a feedback memory is considered
+ * "promoted" when one of the following is true:
+ *
+ *   (a) The memory file contains an HTML comment near the top of the
+ *       body: `<!-- peaks-feedback-promoted: layer=<A|B|C> -->`.
+ *       Written by `peaks feedback promote` so a single read of the
+ *       memory file is enough to determine promotion state.
+ *
+ *   (b) A sibling `.peaks/memory/<name>.promotion.json` exists with
+ *       `{ layer: "A" | "B" | "C", ... }`. Written as a sidecar for
+ *       tooling that prefers machine-readable state over embedded
+ *       comments (e.g. `verify-pipeline` Gate H).
+ *
+ * The comment marker is the SOURCE OF TRUTH for human review; the
+ * sidecar is the source of truth for the scanner. Either is enough
+ * to mark a feedback memory as promoted.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export const PROMOTION_LAYERS = ['A', 'B', 'C'];
+export const PROMOTION_LAYER_DETAILS = [
+    { layer: 'A', label: 'peaks-sop gate', description: 'Append to sops/*.md and reference from a peaks-sop check. Procedural rules.' },
+    { layer: 'B', label: 'peaks-hooks PreToolUse', description: 'Append a matcher to .peaks/.claude-settings-template.json. Tool-call interception.' },
+    { layer: 'C', label: 'mode-gate hardFloorCategory', description: 'Extend HardFloorCategory + shouldPauseAtGate. Always pauses regardless of mode.' }
+];
+const COMMENT_MARKER_RE = /<!--\s*peaks-feedback-promoted:\s*layer=([ABC])\s*-->/;
+/**
+ * Parse a single `.peaks/memory/<file>.md` into a FeedbackMemory, or
+ * `null` when the file is missing / unreadable / not a feedback memory.
+ *
+ * The "is this a feedback memory?" check is intentionally narrow: only
+ * frontmatter with `metadata.type === 'feedback'` OR top-level
+ * `type: feedback` qualifies. Other memory kinds (project / rule /
+ * decision / reference / convention / module / lesson) are skipped.
+ */
+export function parseFeedbackMemory(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`failed to read feedback memory at ${filePath}: ${err.message}`, { cause: err });
+    }
+    const normalized = raw.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return null;
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex < 0)
+        return null;
+    const frontmatterRaw = normalized.slice(4, endIndex);
+    const body = normalized.slice(endIndex + '\n---\n'.length).trim();
+    let name;
+    let description;
+    let kind;
+    for (const rawLine of frontmatterRaw.split('\n')) {
+        const line = rawLine.trim();
+        if (line.startsWith('name:'))
+            name = line.slice('name:'.length).trim();
+        else if (line.startsWith('description:'))
+            description = line.slice('description:'.length).trim();
+        else if (line.startsWith('type:'))
+            kind = line.slice('type:'.length).trim();
+        else if (line.startsWith('  type:'))
+            kind = line.slice('  type:'.length).trim();
+    }
+    if (kind !== 'feedback')
+        return null;
+    // Comment marker (preferred — embedded in the file itself).
+    let promotion = null;
+    const commentMatch = COMMENT_MARKER_RE.exec(body);
+    if (commentMatch) {
+        const layer = commentMatch[1];
+        const detail = PROMOTION_LAYER_DETAILS.find((l) => l.layer === layer);
+        promotion = {
+            layer,
+            source: 'comment',
+            detail: detail?.label ?? layer
+        };
+    }
+    else {
+        // Sidecar fallback: `<basename>.promotion.json`.
+        const sidecarPath = filePath.replace(/\.md$/, '.promotion.json');
+        if (existsSync(sidecarPath)) {
+            try {
+                const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'));
+                if (sidecar.layer === 'A' || sidecar.layer === 'B' || sidecar.layer === 'C') {
+                    const detail = PROMOTION_LAYER_DETAILS.find((l) => l.layer === sidecar.layer);
+                    promotion = {
+                        layer: sidecar.layer,
+                        source: 'sidecar',
+                        detail: detail?.label ?? sidecar.layer
+                    };
+                }
+            }
+            catch (err) {
+                // malformed sidecar — warn but do not fail the whole parse
+                console.warn(`parseFeedbackMemory: malformed sidecar at ${sidecarPath}: ${err.message}`);
+            }
+        }
+    }
+    return {
+        name: name ?? basename(filePath),
+        path: filePath,
+        frontmatter: {
+            ...(name !== undefined ? { name } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(kind !== undefined ? { kind } : {})
+        },
+        body,
+        promotion
+    };
+}
+function basename(p) {
+    const lastSlash = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+    const base = lastSlash >= 0 ? p.slice(lastSlash + 1) : p;
+    return base.endsWith('.md') ? base.slice(0, -3) : base;
+}
+/**
+ * Scan `.peaks/memory/*.md` for feedback memories and return those
+ * that are NOT promoted to any enforcement layer. Pure read; the
+ * CLI command emits the warning list + (with `--strict`) a non-zero
+ * exit code.
+ */
+export function listUnpromotedFeedback(opts) {
+    const memoryDir = resolve(opts.projectRoot, '.peaks', 'memory');
+    if (!existsSync(memoryDir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(memoryDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (entry.name.startsWith('.'))
+            continue; // skip dotfiles (e.g. .index.json)
+        const parsed = parseFeedbackMemory(join(memoryDir, entry.name));
+        if (parsed === null)
+            continue;
+        // v2.18.4 fix: skip closed feedback memories (frontmatter `closedAt: <iso>`).
+        // Closed memories declare their own "Do not re-introduce this memory as a
+        // live blocker" in the body; counting them as unpromoted would (a) force
+        // operators to promote or delete a deliberately archived record and (b)
+        // contradict the memory's own lifecycle. Verify-pipeline Gate H now
+        // honours the closed state and reports `0 unpromoted` for closed records.
+        if (isClosedMemory(join(memoryDir, entry.name)))
+            continue;
+        if (parsed.promotion === null) {
+            out.push({
+                name: parsed.name,
+                path: parsed.path,
+                reason: 'no promotion marker (comment or sidecar) found — see `peaks feedback promote`'
+            });
+        }
+    }
+    return out;
+}
+/**
+ * v2.18.4 helper: detect a closed feedback memory by reading the raw
+ * frontmatter and checking for a non-empty `closedAt:` field. The check
+ * is intentionally narrow (top-level `closedAt:` only, not `metadata.closedAt`)
+ * because that is the documented convention — memories archived in the
+ * `[[review-memories-extract-and-memory-index]]` family all use top-level.
+ *
+ * Returns `true` when the file is unreadable or has no frontmatter (the
+ * conservative answer; such files fall through to the normal unpromoted scan).
+ */
+function isClosedMemory(filePath) {
+    if (!existsSync(filePath))
+        return false;
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const normalized = raw.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return false;
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex < 0)
+        return false;
+    const frontmatter = normalized.slice(4, endIndex);
+    for (const rawLine of frontmatter.split('\n')) {
+        const line = rawLine.trim();
+        if (line.startsWith('closedAt:')) {
+            const value = line.slice('closedAt:'.length).trim();
+            if (value.length > 0 && value !== '""' && value !== "''")
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Generate the code stub for a given layer. Returns a Markdown
+ * snippet the LLM / human can paste into the appropriate file. Pure
+ * function — does NOT touch disk. The CLI command wraps this with
+ * the disk write / envelope emission.
+ */
+export function generatePromotionStub(opts) {
+    const { layer, feedbackName } = opts;
+    if (layer === 'A') {
+        return {
+            snippet: `# SOP entry for feedback "${feedbackName}"\n\n<!-- Append the rule + acceptance criteria below. Reference from a new peaks-sop gate. -->\n\n## Rule\n\n${opts.feedbackBody.split('\n').slice(0, 5).join('\n')}\n\n## Enforcement\n\nAdd a check to sops/<name>.md and reference from .claude/rules/.`,
+            targetFiles: [`sops/${feedbackName}.md`]
+        };
+    }
+    if (layer === 'B') {
+        return {
+            snippet: `{\n  "matcher": "Bash",\n  "hooks": [\n    {\n      "type": "command",\n      "command": "node -e \\"process.exit(0)\\""\n    }\n  ]\n}\n<!-- Append the rule-specific matcher to .peaks/.claude-settings-template.json -->`,
+            targetFiles: ['.peaks/.claude-settings-template.json']
+        };
+    }
+    // layer === 'C'
+    return {
+        snippet: `// src/services/code/mode-gate.ts\n// 1. Add to HardFloorCategory union: '${feedbackName}-rule'\n// 2. Add to HARD_FLOOR_CATEGORIES\n// 3. Wire shouldPauseAtGate to recognise the new category\n// Tests: tests/unit/services/code/<name>-hard-floor.test.ts (≥6 cases per AC-4)`,
+        targetFiles: ['src/services/code/mode-gate.ts', `tests/unit/services/code/${feedbackName}-hard-floor.test.ts`]
+    };
+}
+/**
+ * Write the promotion marker + sidecar. Also writes the envelope to
+ * `.peaks/_runtime/<sid>/rd/feedback-promote-<name>.json` for QA
+ * auditing. Returns the envelope so the CLI can emit it.
+ *
+ * The promotion marker is embedded in the memory file (so it
+ * travels with the file across git history); the sidecar is a
+ * machine-readable mirror. Both are written; either alone is
+ * enough for the scanner.
+ */
+export function promoteFeedback(opts) {
+    const parsed = parseFeedbackMemory(opts.feedbackPath);
+    if (parsed === null) {
+        throw new Error(`Not a feedback memory: ${opts.feedbackPath}`);
+    }
+    const stub = generatePromotionStub({
+        layer: opts.layer,
+        feedbackName: parsed.name,
+        feedbackBody: parsed.body
+    });
+    const now = new Date().toISOString();
+    const envelope = {
+        name: parsed.name,
+        feedbackPath: parsed.path,
+        layer: opts.layer,
+        layerDetail: PROMOTION_LAYER_DETAILS.find((l) => l.layer === opts.layer)?.label ?? opts.layer,
+        generatedFiles: stub.targetFiles,
+        snippet: stub.snippet,
+        promotedAt: now,
+        promotedBy: opts.promotedBy
+    };
+    if (opts.dryRun === true) {
+        return envelope;
+    }
+    // 1. Embed comment marker in the memory file.
+    const raw = readFileSync(opts.feedbackPath, 'utf8');
+    const normalized = raw.replace(/\r\n/g, '\n');
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex >= 0) {
+        const body = normalized.slice(endIndex + '\n---\n'.length);
+        // If a marker already exists, replace it. Otherwise insert one
+        // at the top of the body.
+        const marker = `<!-- peaks-feedback-promoted: layer=${opts.layer} -->`;
+        const newBody = COMMENT_MARKER_RE.test(body)
+            ? body.replace(COMMENT_MARKER_RE, marker)
+            : `${marker}\n${body}`;
+        const newContent = normalized.slice(0, endIndex + '\n---\n'.length) + newBody;
+        writeFileSync(opts.feedbackPath, newContent, 'utf8');
+    }
+    // 2. Sidecar (machine-readable mirror).
+    const sidecarPath = opts.feedbackPath.replace(/\.md$/, '.promotion.json');
+    writeFileSync(sidecarPath, JSON.stringify({
+        name: parsed.name,
+        layer: opts.layer,
+        layerDetail: envelope.layerDetail,
+        generatedFiles: stub.targetFiles,
+        promotedAt: now,
+        promotedBy: opts.promotedBy
+    }, null, 2), 'utf8');
+    // 3. Envelope to `.peaks/_runtime/<sid>/rd/`.
+    const envelopePath = join(opts.projectRoot, '.peaks', '_runtime', opts.sessionId, 'rd', `feedback-promote-${parsed.name}.json`);
+    const envelopeDir = dirname(envelopePath);
+    if (!existsSync(envelopeDir)) {
+        mkdirSync(envelopeDir, { recursive: true });
+    }
+    writeFileSync(envelopePath, JSON.stringify(envelope, null, 2), 'utf8');
+    return envelope;
+}
+export function isPromotionLayer(value) {
+    return value === 'A' || value === 'B' || value === 'C';
+}

package/dist/services/final-review/final-review-service.d.ts

@@ -0,0 +1,22 @@
+export interface LlmRunner {
+    call(systemPrompt: string, userPrompt: string, opts: {
+        maxTokens: number;
+    }): Promise<{
+        output: string;
+        tokens: {
+            input: number;
+            output: number;
+        };
+    }>;
+}
+import type { FinalReviewOutput } from './final-review-types.js';
+export interface PrepareFinalReviewOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly llmRunner: LlmRunner;
+}
+export declare class IncompleteFinalReviewError extends Error {
+    readonly code: "INCOMPLETE_FINAL_REVIEW";
+    constructor(message: string);
+}
+export declare function prepareFinalReview(rid: string, opts: PrepareFinalReviewOptions): Promise<FinalReviewOutput>;

package/dist/services/final-review/final-review-service.js

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const REQUIRED_DIMENSIONS = [
+    'functional-completeness',
+    'problem-resolution',
+    'no-new-bugs',
+    'existing-functionality-intact'
+];
+const SYSTEM_PROMPT = `You are preparing a 4-dimension business review for human acceptance. Produce a JSON response with EXACTLY these fields:
+- rid (string)
+- generatedAt (ISO timestamp)
+- dimensions (array of EXACTLY 4 objects, one per dimension: functional-completeness, problem-resolution, no-new-bugs, existing-functionality-intact; each with dimension, verdict (pass | fail | inconclusive), summary, evidence (list of {kind, description, [artifact], [link]}), confidence (high | medium | low))
+- overallSummary (one paragraph)
+- allPass (boolean)
+- needsAttention (list of dimension names that need human attention)
+
+Output ONLY valid JSON, no prose.`;
+export class IncompleteFinalReviewError extends Error {
+    code = 'INCOMPLETE_FINAL_REVIEW';
+    constructor(message) {
+        super(message);
+        this.name = 'IncompleteFinalReviewError';
+    }
+}
+export async function prepareFinalReview(rid, opts) {
+    const auditGoalPath = join(opts.projectRoot, '.peaks', '_runtime', opts.sessionId, 'audit-goal', `${rid}.json`);
+    let approvedGoal;
+    try {
+        approvedGoal = JSON.parse(readFileSync(auditGoalPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Cannot read approved goal from ${auditGoalPath}: ${err.message}`);
+    }
+    const userPrompt = `Approved goal's success criteria: ${JSON.stringify(approvedGoal.successCriteria)}\n\nPrepare the 4-dim review evidence.`;
+    const response = await opts.llmRunner.call(SYSTEM_PROMPT, userPrompt, {
+        maxTokens: 3000
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(response.output);
+    }
+    catch (err) {
+        throw new IncompleteFinalReviewError(`LLM output is not valid JSON: ${err.message}`);
+    }
+    const output = parsed;
+    const presentDimensions = new Set(output.dimensions.map((d) => d.dimension));
+    const missing = REQUIRED_DIMENSIONS.filter(d => !presentDimensions.has(d));
+    if (missing.length > 0) {
+        throw new IncompleteFinalReviewError(`Missing required dimensions: ${missing.join(', ')}`);
+    }
+    return output;
+}

package/dist/services/final-review/final-review-types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `prepareFinalReview()` — the 4-dimension business review primitive that gates
+ * end-of-workflow human acceptance in the 10% human / 90% LLM workflow.
+ *
+ * Contract:
+ *   - Reads the approved audit-goal JSON from
+ *     `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`.
+ *   - Calls an injected `LlmRunner` exactly once with a 4-dim review prompt.
+ *   - Parses the LLM output as JSON and validates that the `dimensions`
+ *     array covers ALL four required dimensions
+ *     (functional-completeness, problem-resolution, no-new-bugs,
+ *     existing-functionality-intact).
+ *   - Throws `IncompleteFinalReviewError` if the JSON is malformed or any
+ *     required dimension is missing. Callers MUST treat this as a gate
+ *     failure (return to human for re-prompting) — autonomous work must
+ *     never proceed on a partial review.
+ */
+export type DimensionKind = 'functional-completeness' | 'problem-resolution' | 'no-new-bugs' | 'existing-functionality-intact';
+export type DimensionVerdict = 'pass' | 'fail' | 'inconclusive';
+export type EvidenceKind = 'test-result' | 'test-coverage' | 'manual-spot-check' | 'pre-post-diff' | 'regression-suite' | 'ac-mapping';
+export type DimensionConfidence = 'high' | 'medium' | 'low';
+export interface EvidenceItem {
+    readonly kind: EvidenceKind;
+    readonly description: string;
+    readonly artifact?: string;
+    readonly link?: string;
+}
+export interface DimensionEvidence {
+    readonly dimension: DimensionKind;
+    readonly verdict: DimensionVerdict;
+    readonly summary: string;
+    readonly evidence: readonly EvidenceItem[];
+    readonly confidence: DimensionConfidence;
+}
+export interface FinalReviewOutput {
+    readonly rid: string;
+    readonly generatedAt: string;
+    readonly dimensions: readonly DimensionEvidence[];
+    readonly overallSummary: string;
+    readonly allPass: boolean;
+    readonly needsAttention: readonly DimensionKind[];
+}

package/dist/services/final-review/final-review-types.js

@@ -0,0 +1,18 @@
+/**
+ * `prepareFinalReview()` — the 4-dimension business review primitive that gates
+ * end-of-workflow human acceptance in the 10% human / 90% LLM workflow.
+ *
+ * Contract:
+ *   - Reads the approved audit-goal JSON from
+ *     `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`.
+ *   - Calls an injected `LlmRunner` exactly once with a 4-dim review prompt.
+ *   - Parses the LLM output as JSON and validates that the `dimensions`
+ *     array covers ALL four required dimensions
+ *     (functional-completeness, problem-resolution, no-new-bugs,
+ *     existing-functionality-intact).
+ *   - Throws `IncompleteFinalReviewError` if the JSON is malformed or any
+ *     required dimension is missing. Callers MUST treat this as a gate
+ *     failure (return to human for re-prompting) — autonomous work must
+ *     never proceed on a partial review.
+ */
+export {};

package/dist/services/final-review/index.d.ts

@@ -0,0 +1,2 @@
+export { prepareFinalReview, type PrepareFinalReviewOptions, type LlmRunner, IncompleteFinalReviewError, } from './final-review-service.js';
+export type { DimensionKind, DimensionVerdict, EvidenceKind, DimensionConfidence, EvidenceItem, DimensionEvidence, FinalReviewOutput, } from './final-review-types.js';

package/dist/services/final-review/index.js

@@ -0,0 +1 @@
+export { prepareFinalReview, IncompleteFinalReviewError, } from './final-review-service.js';

package/dist/services/fixture/fixture-capture-service.d.ts

@@ -0,0 +1,87 @@
+import { SANITIZE_RULE_NAMES, type SanitizationReport, type SanitizeRuleName } from './fixture-sanitize-service.js';
+export type EnvelopeKind = 'audit-security' | 'audit-perf' | 'karpathy-review' | 'mut-report' | 'qa-report' | 'prd-handoff';
+export declare const ENVELOPE_KINDS: ReadonlyArray<EnvelopeKind>;
+/**
+ * Map envelope kind → on-disk path segment under `.peaks/_runtime/<sid>/`.
+ * `qa-report` is intentionally absent — the PRD lists 5 envelope types;
+ * `qa-report` is a 6th bonus to widen coverage. All 6 are accepted as
+ * inputs; the replay test enforces ≥5 distinct kinds.
+ */
+export declare const ENVELOPE_ON_DISK_PATH: Record<EnvelopeKind, string>;
+export declare const ENVELOPE_FILE_EXTENSION: Record<EnvelopeKind, 'md' | 'json'>;
+export interface HistoricalCaptureInput {
+    readonly mode: 'historical';
+    readonly sessionId: string;
+    readonly envelopeKind: EnvelopeKind;
+    readonly fixtureId: string;
+    readonly outDir: string;
+    /**
+     * Optional absolute or relative base dir used to resolve the source
+     * path `.peaks/_runtime/<sid>/...`. When omitted, defaults to
+     * `process.cwd()`. The CLI passes `process.cwd()` explicitly;
+     * tests that pre-populate a tmp tree pass the tmp root here.
+     */
+    readonly projectRoot?: string;
+    /**
+     * When true (default), the CLI refuses to write if the source file
+     * does not exist. Set false only in tests where you want to assert
+     * the error path.
+     */
+    readonly requireSource?: boolean;
+}
+export interface DerivedVariantInput {
+    readonly mode: 'derived-variant';
+    /** Path (absolute or relative to cwd) to a previously captured fixture body. */
+    readonly parentFixturePath: string;
+    readonly variant: EdgeCaseVariant;
+    readonly fixtureId: string;
+    readonly outDir: string;
+}
+export type EdgeCaseVariant = 'chinese-colon' | 'yaml-frontmatter-variation' | 'double-format' | 'empty-body' | 'multi-findings' | 'historical-canonical';
+export declare const EDGE_CASE_VARIANTS: ReadonlyArray<EdgeCaseVariant>;
+export type CaptureInput = HistoricalCaptureInput | DerivedVariantInput;
+export interface CapturedFixture {
+    readonly fixtureId: string;
+    readonly envelopeKind: EnvelopeKind;
+    readonly bodyPath: string;
+    readonly metaPath: string;
+    readonly meta: FixtureMeta;
+}
+export interface FixtureMeta {
+    readonly schemaVersion: 1;
+    readonly fixtureId: string;
+    readonly envelopeKind: EnvelopeKind;
+    readonly producer: 'peaks-fixture-capture-cli';
+    readonly producerVersion: '2.14.0';
+    readonly sourceOrigin: {
+        readonly kind: 'historical-artifact' | 'derived-variant';
+        readonly path: string;
+        readonly sessionId: string | null;
+        readonly parentFixtureId: string | null;
+        readonly variantCommand: string | null;
+    };
+    readonly capturedAt: string;
+    readonly sanitization: SanitizationReport;
+    readonly checksum: {
+        readonly algorithm: 'sha256';
+        readonly value: string;
+    };
+    readonly edgeCases: ReadonlyArray<EdgeCaseVariant>;
+}
+/**
+ * Resolve a historical capture: read the source file from disk, sanitize
+ * it, compute the checksum, write the body + `fixture.meta.json` pair.
+ *
+ * Pure orchestration — no command-line parsing here. The CLI in
+ * `scripts/fixture-capture.mjs` validates args and calls this function.
+ *
+ * @throws if the source file does not exist and `requireSource !== false`.
+ */
+export declare function captureHistoricalFixture(input: HistoricalCaptureInput): CapturedFixture;
+/**
+ * Derive a variant fixture from a parent fixture body. The parent must
+ * already be a captured fixture (i.e. it has been sanitized). Variants
+ * are deterministic — same parent + same variant → identical output.
+ */
+export declare function captureDerivedVariant(input: DerivedVariantInput): CapturedFixture;
+export { SANITIZE_RULE_NAMES, type SanitizeRuleName };