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

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/filesystem/file-lock.d.ts

@@ -0,0 +1,11 @@
+export declare class LockTimeoutError extends Error {
+    readonly code = "LOCK_TIMEOUT";
+    readonly lockPath: string;
+    constructor(lockPath: string, attempts: number);
+}
+/**
+ * Run `fn` while holding an exclusive lock on a sidecar file at
+ * `<filePath>.lock`. The lock is released in `finally` (close fd +
+ * unlink lock file). Throws LockTimeoutError after MAX_LOCK_RETRIES.
+ */
+export declare function withFileLockSync<T>(filePath: string, fn: () => T): T;

package/dist/services/filesystem/file-lock.js

@@ -0,0 +1,152 @@
+/**
+ * Cross-process file lock — sync, atomic, no third-party deps.
+ *
+ * Used by writeSharedEntry (shared-channel.ts) and appendHeartbeat /
+ * markCompleted (dispatch-record-writer.ts) to guard the
+ * read-modify-write sequence against lost updates from concurrent
+ * writers (slice 2026-06-23-audit-3rd finding #2 + #3).
+ *
+ * Mechanism: write a sidecar `.lock` file next to the target via
+ * `fs.openSync(path, 'wx')`. The `wx` flag maps to O_CREAT|O_EXCL on
+ * POSIX (atomic) and `CreateFileW(... CREATE_NEW)` on Windows (also
+ * atomic). The second opener fails with EEXIST. We retry with capped
+ * exponential backoff up to MAX_LOCK_RETRIES, falling through to
+ * LOCK_TIMEOUT if the lock cannot be acquired.
+ *
+ * Stale-lock reaping: a crashed previous holder leaves a `.lock` file
+ * behind. We reap locks older than LOCK_STALE_MS by unlinking before
+ * retrying. This trades a one-time stale-lock window for bounded
+ * recovery without leaking orphan locks.
+ *
+ * Why not fs.flock? Node's `fs.flock` is POSIX-only; on Windows it
+ * throws ERR_FEATURE_UNAVAILABLE_ON_PLATFORM. The `.lock` file
+ * pattern works uniformly across platforms and survives process
+ * crashes (the file remains; the next acquirer reaps it).
+ */
+import { closeSync, existsSync, mkdirSync, openSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const MAX_LOCK_RETRIES = 100;
+const LOCK_RETRY_BASE_MS = 5;
+const LOCK_RETRY_MAX_MS = 50;
+const LOCK_STALE_MS = 30_000;
+export class LockTimeoutError extends Error {
+    code = 'LOCK_TIMEOUT';
+    lockPath;
+    constructor(lockPath, attempts) {
+        super(`LOCK_TIMEOUT: failed to acquire ${lockPath} after ${attempts} retries ` +
+            `(a prior holder may be alive or the lock is stale; it will be reaped ` +
+            `after ${LOCK_STALE_MS}ms of inactivity)`);
+        this.lockPath = lockPath;
+    }
+}
+/**
+ * Run `fn` while holding an exclusive lock on a sidecar file at
+ * `<filePath>.lock`. The lock is released in `finally` (close fd +
+ * unlink lock file). Throws LockTimeoutError after MAX_LOCK_RETRIES.
+ */
+export function withFileLockSync(filePath, fn) {
+    const target = resolve(filePath);
+    const lockPath = `${target}.lock`;
+    // Ensure the parent dir exists before openSync('wx') — first-write
+    // callers (e.g. writeSharedEntry on a fresh batch) reach the lock
+    // BEFORE writeAtomic's mkdirSync(dir, { recursive: true }) runs.
+    const dir = dirname(target);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Wall-clock guard (slice 014): in pathological slow-system cases, the
+    // retry backoff could push wall-clock above LOCK_STALE_MS. Cap the loop at
+    // LOCK_STALE_MS regardless of attempts; throw the existing LockTimeoutError.
+    //
+    // Slice 2026-07-12-fix note: the slice 014 implementation re-checked
+    // `isStaleLock(lockPath)` at the TOP of every loop iteration. Under
+    // vitest-on-Windows slowdown (each `spinSleep` actually waits hundreds of
+    // ms because of event-loop preemption), the wall clock would cross
+    // `LOCK_STALE_MS` mid-loop and the reaper would unlink a still-fresh
+    // lock — `file-lock.test.ts` "does NOT reap a fresh .lock (<30s old)"
+    // caught this: the lock was reaped at iter ~54 after 30s of retries,
+    // defeating the test that asserts the fresh lock should block. The fix
+    // is to check staleness ONCE, before the loop, and inside the loop
+    // only retry on EEXIST. A crashed previous holder is reaped at entry;
+    // after we begin the retry-backoff phase, the lock is by definition
+    // non-stale (or absent after a race with another reaper), so a stale
+    // check on each iteration only adds risk of spuriously reaping a lock
+    // we just decided was live.
+    const startedAt = Date.now();
+    let attempts = 0;
+    let fd = null;
+    // One-shot stale reap before the loop: if a previous holder crashed and
+    // left the lock older than LOCK_STALE_MS, unlink it now so the first
+    // `openSync(lockPath, 'wx')` attempt can succeed.
+    if (isStaleLock(lockPath)) {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // race: another process reaped it; loop will try to acquire directly.
+        }
+    }
+    while (attempts < MAX_LOCK_RETRIES) {
+        // Wall-clock guard runs at the top of each iteration so a slow retry
+        // backoff (e.g. vitest on Windows) never lets us outlive the stale
+        // threshold and re-enter the reaper branch on a still-live lock.
+        if (Date.now() - startedAt > LOCK_STALE_MS) {
+            throw new LockTimeoutError(lockPath, attempts);
+        }
+        try {
+            fd = openSync(lockPath, 'wx');
+            break;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'EEXIST')
+                throw err;
+            attempts += 1;
+            // Exponential backoff capped at LOCK_RETRY_MAX_MS.
+            const wait = Math.min(LOCK_RETRY_BASE_MS * 2 ** Math.min(attempts, 6), LOCK_RETRY_MAX_MS);
+            spinSleep(wait);
+        }
+    }
+    if (fd === null) {
+        throw new LockTimeoutError(lockPath, attempts);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // fd may already be closed by the OS on a crash; ignore.
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // Best-effort: stale .lock is harmless; the next acquirer reaps.
+        }
+    }
+}
+function isStaleLock(lockPath) {
+    try {
+        const s = statSync(lockPath);
+        return Date.now() - s.mtimeMs > LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Synchronous sleep via busy-wait. Bounded by MAX_LOCK_RETRIES *
+ * LOCK_RETRY_MAX_MS = 5s worst case. The alternative — async sleep —
+ * would force every lock consumer to become async, which is a much
+ * larger refactor for a slice whose lock contention is rare (concurrent
+ * `peaks sub-agent share` for the same batch).
+ */
+function spinSleep(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        /* intentional spin */
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+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;
+}