peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/services/openspec/openspec-archive-service.js

@@ -1,13 +1,175 @@
-import { mkdir, rename } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { isDirectory } from '../../shared/fs.js';
-const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+import { mkdir, readFile, rename, readdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { isDirectory } from 'peaks-loop-shared/fs';
+import { validateChangeId } from './artifact-boundary.js';
+import { findStaleChangeFiles, parseCapabilityMapping, readC8Summary, resolveCoverageSummaryPath, validateCapabilityCoverage, } from './coverage-evidence-reader.js';
+export class OpenSpecArchiveError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail = {}) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'OpenSpecArchiveError';
+    }
+}
 function defaultOpenSpecRoot() {
     return join(process.cwd(), 'openspec');
 }
+/**
+ * Parse the `## Coverage Evidence` block out of a proposal.md.
+ *
+ * Accepted shape (markdown table):
+ *
+ *     ## Coverage Evidence
+ *
+ *     | capability | requirement | status | testAnchor |
+ *     | --- | --- | --- | --- |
+ *     | quality-gates | 100% coverage for included modules | covered | tests/unit/quality-gates.test.ts |
+ *
+ * Returns `{ present: false }` when the heading is missing. Throws
+ * `OpenSpecArchiveError` with `code: 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED'`
+ * when the heading is present but no parsable rows are extracted.
+ */
+export async function parseCoverageEvidence(proposalPath) {
+    let raw;
+    try {
+        raw = await readFile(proposalPath, 'utf8');
+    }
+    catch {
+        return {
+            rows: [],
+            present: false,
+            capabilityRows: [],
+            summaryStatus: 'unavailable',
+            capabilityValidation: 'not-enforced',
+            staleFiles: [],
+            mismatches: [],
+        };
+    }
+    const lines = raw.split(/\r?\n/);
+    const headingIdx = lines.findIndex((line) => /^##\s+Coverage\s+Evidence\s*$/.test(line));
+    if (headingIdx === -1) {
+        return {
+            rows: [],
+            present: false,
+            capabilityRows: [],
+            summaryStatus: 'unavailable',
+            capabilityValidation: 'not-enforced',
+            staleFiles: [],
+            mismatches: [],
+        };
+    }
+    const rows = [];
+    let i = headingIdx + 1;
+    let inFence = false;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === undefined)
+            break;
+        if (!inFence && /^##\s+/.test(line))
+            break;
+        if (/^```/.test(line.trim())) {
+            inFence = !inFence;
+            i += 1;
+            continue;
+        }
+        const parsed = parseTableRow(line);
+        if (parsed !== null) {
+            rows.push({ ...parsed, line: i + 1 });
+        }
+        i += 1;
+    }
+    if (rows.length === 0) {
+        throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MALFORMED', `proposal.md contains a "## Coverage Evidence" heading but no parsable requirement rows`, { proposalPath });
+    }
+    return {
+        rows,
+        present: true,
+        capabilityRows: [],
+        summaryStatus: 'unavailable',
+        capabilityValidation: 'not-enforced',
+        staleFiles: [],
+        mismatches: [],
+    };
+}
+function parseTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|'))
+        return null;
+    const cells = trimmed.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length < 3)
+        return null;
+    const capability = cells[0];
+    const requirement = cells[1];
+    const statusRaw = cells[2];
+    const testAnchor = cells[3];
+    if (capability === undefined || requirement === undefined || statusRaw === undefined)
+        return null;
+    if (capability.toLowerCase() === 'capability' && requirement.toLowerCase() === 'requirement')
+        return null;
+    if (/^-+$/.test(capability.replace(/\s+/g, '')))
+        return null;
+    const status = statusRaw.toLowerCase();
+    if (status !== 'covered' && status !== 'partial' && status !== 'uncovered')
+        return null;
+    const row = {
+        capability,
+        requirement,
+        status: status,
+    };
+    if (testAnchor !== undefined && testAnchor !== '') {
+        row.testAnchor = testAnchor;
+    }
+    return row;
+}
+/**
+ * Determine whether the change has any spec files (specs/<capability>/spec.md).
+ * When the change has zero spec files, there are no requirements to enforce,
+ * and the Pre-cond 2 gate is skipped — backward-compat for legacy spec-less
+ * changes (e.g. design-only or doc-only changes).
+ */
+async function changeHasSpecs(changeRoot) {
+    const specsRoot = join(changeRoot, 'specs');
+    if (!(await isDirectory(specsRoot)))
+        return false;
+    const entries = await readdir(specsRoot);
+    for (const entry of entries) {
+        const specPath = join(specsRoot, entry, 'spec.md');
+        if (await isDirectory(join(specsRoot, entry))) {
+            try {
+                await readFile(specPath, 'utf8');
+                return true;
+            }
+            catch {
+                // missing spec.md; keep scanning siblings
+            }
+        }
+    }
+    return false;
+}
+function evaluateGate(evidence) {
+    const failing = evidence.rows.filter((r) => r.status !== 'covered');
+    if (failing.length > 0) {
+        return {
+            ok: false,
+            reason: 'requirement-not-fully-covered',
+            failing,
+        };
+    }
+    if (evidence.rows.length === 0) {
+        return {
+            ok: false,
+            reason: 'no-coverage-evidence-block',
+            failing: [],
+        };
+    }
+    return { ok: true };
+}
 export async function archiveOpenSpecChange(changeId, options = {}) {
-    if (!CHANGE_ID_PATTERN.test(changeId)) {
-        throw new Error(`Invalid changeId: ${changeId} (expected letters, digits, dots, underscores, or dashes)`);
+    const changeIdResult = validateChangeId(changeId);
+    if (!changeIdResult.ok) {
+        throw new Error(`changeId ${changeId} does not match [A-Za-z0-9][A-Za-z0-9._-]*`);
     }
     const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
     const archiveDir = options.archiveDirName ?? 'archive';
@@ -16,13 +178,163 @@ export async function archiveOpenSpecChange(changeId, options = {}) {
     if (!(await isDirectory(from))) {
         return null;
     }
+    // Pre-cond 2 (Fix-6A + Fix-6B): Coverage Evidence gate.
+    // Only enforce when the change declares at least one spec (otherwise there
+    // are no requirements to gate on — backward-compat for design-only changes).
+    let coverage;
+    let coverageGateBypassed;
+    let coverageMismatchBypassed;
+    if (options.apply === true && (await changeHasSpecs(from))) {
+        const proposalPath = join(from, 'proposal.md');
+        // --- Fix-6A: parse Coverage Evidence block (declarative half) ---
+        const evidence = await parseCoverageEvidence(proposalPath);
+        coverage = evidence;
+        if (!evidence.present) {
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_GATE_FAILED', `Refusing to archive "${changeId}": proposal.md is missing a "## Coverage Evidence" block. ` +
+                'Add a Coverage Evidence table listing every Requirement from specs/*/spec.md with status covered/partial/uncovered, ' +
+                'or re-run with --force to bypass the gate.', { changeId, reason: 'no-coverage-evidence-block', coverage });
+        }
+        const verdict = evaluateGate(evidence);
+        if (!verdict.ok) {
+            if (options.force === true) {
+                coverageGateBypassed = true;
+            }
+            else {
+                throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_GATE_PARTIAL', `Refusing to archive "${changeId}": ${verdict.failing.length} requirement(s) not fully covered. ` +
+                    'Re-run with --force to bypass the gate, or update the Coverage Evidence table to mark each requirement as covered.', {
+                    changeId,
+                    reason: verdict.reason,
+                    failing: verdict.failing.map((r) => ({
+                        capability: r.capability,
+                        requirement: r.requirement,
+                        status: r.status,
+                        testAnchor: r.testAnchor,
+                        line: r.line,
+                    })),
+                    coverage,
+                });
+            }
+        }
+        // --- Fix-6B: parse Capability Mapping block + validate against c8 summary ---
+        const mapping = await parseCapabilityMapping(proposalPath);
+        coverage = {
+            ...coverage,
+            capabilityRows: mapping.rows,
+        };
+        if (mapping.rows.length === 0) {
+            // No mapping → cannot enforce per-capability. Refuse with the same
+            // gate-failed code but a distinct reason in detail (Fix-6B AC3).
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_GATE_FAILED', `Refusing to archive "${changeId}": proposal.md is missing a "## Capability Mapping" block. ` +
+                'Add a Capability Mapping table listing each declared capability alongside its source file or subtree, ' +
+                'or re-run with --force to bypass the gate.', { changeId, reason: 'no-capability-mapping-block', coverage });
+        }
+        // Discover coverage-summary.json
+        const projectRoot = resolve(openspecRoot, '..');
+        const summaryPathResult = await resolveCoverageSummaryPath({
+            projectRoot,
+            ...(options.coverageSummaryPath !== undefined ? { explicitPath: options.coverageSummaryPath } : {}),
+        });
+        if (!summaryPathResult.ok) {
+            // AC1: missing or not-readable
+            const triedPaths = summaryPathResult.error.code === 'missing' ? summaryPathResult.error.triedPaths : [summaryPathResult.error.path];
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MISSING', `Refusing to archive "${changeId}": no coverage-summary.json found at any of: ${triedPaths.join(', ')}. ` +
+                'Run `pnpm test:coverage` (which invokes scripts/coverage-c8.mjs) to generate one, ' +
+                'or pass --coverage-summary <path> to point at an existing summary, ' +
+                'or re-run with --force to bypass.', {
+                changeId,
+                triedPaths,
+                coverage,
+            });
+        }
+        // Parse summary + check freshness (AC2)
+        let summary;
+        try {
+            summary = await readC8Summary(summaryPathResult.value);
+        }
+        catch (error) {
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MISSING', `Refusing to archive "${changeId}": coverage-summary.json at ${summaryPathResult.value} is malformed (${error.message}). ` +
+                'Re-run `pnpm test:coverage` to regenerate, or pass --coverage-summary <path> to point at a valid summary.', { changeId, path: summaryPathResult.value, coverage });
+        }
+        coverage = {
+            ...coverage,
+            summaryPath: summary.path,
+        };
+        const staleFiles = await findStaleChangeFiles({
+            projectRoot,
+            openspecRoot,
+            changeId,
+            summary,
+        });
+        if (staleFiles.length > 0) {
+            coverage = {
+                ...coverage,
+                summaryStatus: 'stale',
+                staleFiles,
+            };
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_STALE', `Refusing to archive "${changeId}": coverage-summary.json is older than ${staleFiles.length} change file(s). ` +
+                'Re-run `pnpm test:coverage` to refresh, or re-run with --force to bypass.', { changeId, staleFiles, summaryPath: summary.path, coverage });
+        }
+        coverage = {
+            ...coverage,
+            summaryStatus: 'fresh',
+        };
+        // Per-capability coverage check (AC4)
+        const validation = await validateCapabilityCoverage({
+            projectRoot,
+            summary,
+            rows: mapping.rows,
+        });
+        if (!validation.ok) {
+            coverage = {
+                ...coverage,
+                capabilityValidation: 'mismatch',
+                mismatches: validation.mismatches,
+            };
+            if (options.force === true) {
+                coverageMismatchBypassed = true;
+            }
+            else {
+                throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MISMATCH', `Refusing to archive "${changeId}": ${validation.mismatches.length} capability row(s) claim "covered" in proposal.md but c8 reports < 100% coverage. ` +
+                    'Re-run `pnpm test:coverage` after closing the gap, or re-run with --force to bypass.', {
+                    changeId,
+                    mismatches: validation.mismatches,
+                    coverage,
+                });
+            }
+        }
+        else {
+            coverage = {
+                ...coverage,
+                capabilityValidation: 'ok',
+            };
+        }
+    }
+    else if (options.apply === true) {
+        // Spec-less change — surface coverage evidence for visibility, never fail.
+        const proposalPath = join(from, 'proposal.md');
+        coverage = await parseCoverageEvidence(proposalPath);
+    }
     if (options.apply !== true) {
-        return { changeId, from, to, applied: false };
+        return {
+            changeId,
+            from,
+            to,
+            applied: false,
+            ...(coverage !== undefined ? { coverage } : {}),
+        };
     }
     if (await isDirectory(to)) {
         throw new Error(`Refusing to archive: target already exists at ${to}`);
     }
     await mkdir(dirname(to), { recursive: true });
     await rename(from, to);
-    return { changeId, from, to, applied: true };
+    return {
+        changeId,
+        from,
+        to,
+        applied: true,
+        ...(coverage !== undefined ? { coverage } : {}),
+        ...(coverageGateBypassed === true ? { coverageGateBypassed: true } : {}),
+        ...(coverageMismatchBypassed === true ? { coverageMismatchBypassed: true } : {}),
+    };
 }

package/dist/services/openspec/openspec-bridge-service.js

@@ -1,4 +1,4 @@
-import { readText } from '../../shared/fs.js';
+import { readText } from 'peaks-loop-shared/fs';
 import { loadOpenSpecChange } from './openspec-scan-service.js';
 function splitTaskSections(markdown) {
     const sections = [];

package/dist/services/openspec/openspec-init-service.js

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isDirectory, pathExists } from '../../shared/fs.js';
+import { isDirectory, pathExists } from 'peaks-loop-shared/fs';
 const README_BODY = `# OpenSpec — change proposals for this project
 
 This directory hosts the \`peaks openspec\` change proposal lifecycle:

package/dist/services/openspec/openspec-propose-from-doctor-service.js

@@ -12,7 +12,7 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getErrorMessage } from '../../shared/result.js';
+import { getErrorMessage } from 'peaks-loop-shared/result';
 const SLUGIFY = /[^a-z0-9]+/g;
 function slugify(text) {
     return text

package/dist/services/openspec/openspec-render-service.js

@@ -1,9 +1,9 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { isDirectory, pathExists } from '../../shared/fs.js';
+import { isDirectory, pathExists } from 'peaks-loop-shared/fs';
 import { validateAgainstSchema } from '../../shared/json-schema-mini.js';
-const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+import { validateChangeId } from './artifact-boundary.js';
 function defaultOpenSpecRoot() {
     return join(process.cwd(), 'openspec');
 }
@@ -113,8 +113,11 @@ export async function renderOpenSpecChange(request, options = {}) {
             throw new OpenSpecRenderRequestInvalidError(result.errors);
         }
     }
-    else if (!CHANGE_ID_PATTERN.test(request.changeId)) {
-        throw new Error(`Invalid changeId: ${request.changeId} (expected letters, digits, dots, underscores, or dashes)`);
+    else {
+        const changeIdResult = validateChangeId(request.changeId);
+        if (!changeIdResult.ok) {
+            throw new Error(`changeId ${request.changeId} does not match [A-Za-z0-9][A-Za-z0-9._-]*`);
+        }
     }
     const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
     const changeRoot = join(openspecRoot, 'changes', request.changeId);

package/dist/services/openspec/openspec-scan-service.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { isDirectory, listDirectories, pathExists, readText } from '../../shared/fs.js';
+import { isDirectory, listDirectories, pathExists, readText } from 'peaks-loop-shared/fs';
 function defaultOpenSpecRoot() {
     return join(process.cwd(), 'openspec');
 }

package/dist/services/openspec/openspec-validate-service.js

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
-import { isDirectory } from '../../shared/fs.js';
+import { isDirectory } from 'peaks-loop-shared/fs';
 import { loadOpenSpecChange } from './openspec-scan-service.js';
-const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+import { validateChangeId } from './artifact-boundary.js';
 function defaultOpenSpecRoot() {
     return join(process.cwd(), 'openspec');
 }
@@ -10,11 +10,12 @@ async function defaultExternalRunner(_command, _args) {
 }
 function buildInternalIssues(changeId, detail) {
     const issues = [];
-    if (!CHANGE_ID_PATTERN.test(changeId)) {
+    const changeIdResult = validateChangeId(changeId);
+    if (!changeIdResult.ok) {
         issues.push({
             level: 'error',
             rule: 'change-id-format',
-            message: `changeId ${changeId} does not match [A-Za-z0-9][A-Za-z0-9._-]*`
+            message: changeIdResult.error.message
         });
     }
     if (detail === null || detail.proposal === null) {

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

@@ -9,6 +9,16 @@ export function preferencesPath(projectRoot) {
 export function loadPreferences(projectRoot) {
     const filePath = preferencesPath(projectRoot);
     if (!existsSync(filePath)) {
+        // Slice 2026-07-22-orchestrator-memory-preflight: when
+        // .peaks/preferences.json is missing, this returns a clone of
+        // DEFAULT_PREFERENCES, which now carries the `memoryPreflight`
+        // block (see preferences-types.ts). Partial overlays fall through
+        // to mergePreferences below, where the new `memoryPreflight` block
+        // shallow-replaces the default block — `mergePreferences` does not
+        // deep-merge `memoryPreflight` (only `fanout` is deep-merged), so a
+        // partial overlay will replace the whole block. Resolution still
+        // works because `resolveMemoryPreflightConfig` applies field-level
+        // defaults over the partial input (see memory-preflight-config.ts).
         return structuredClone(DEFAULT_PREFERENCES);
     }
     let raw;

package/dist/services/preferences/preferences-types.d.ts

@@ -131,6 +131,19 @@ export interface ProjectPreferences {
      * saved file is rejected at load time.
      */
     readonly fanout: FanoutPreference;
+    /**
+     * Slice 2026-07-22-orchestrator-memory-preflight: orchestrator-side memory
+     * preflight knobs. Optional — `resolveMemoryPreflightConfig` (see
+     * src/services/context/memory-preflight-config.ts) merges over a hard-coded
+     * default block when this key is absent, so legacy preferences.json files
+     * keep working unchanged.
+     */
+    readonly memoryPreflight?: {
+        readonly enabled?: boolean;
+        readonly maxTokens?: number;
+        readonly listCap?: number;
+        readonly contentCacheBytes?: number;
+    };
 }
 export type FanoutMode = 'fan-out';
 export declare const FANOUT_MODES: readonly FanoutMode[];

package/dist/services/preferences/preferences-types.js

@@ -50,4 +50,15 @@ export const DEFAULT_PREFERENCES = {
     fanout: {
         defaultMode: 'fan-out'
     },
+    // Slice 2026-07-22-orchestrator-memory-preflight: defaults aligned with
+    // memory-preflight-config.ts::DEFAULTS. Kept in sync manually because
+    // loadPreferences() returns DEFAULT_PREFERENCES verbatim when the on-disk
+    // file is absent, and partial overlays rely on memoryPreflight being
+    // defined here.
+    memoryPreflight: {
+        enabled: true,
+        maxTokens: 1200,
+        listCap: 12,
+        contentCacheBytes: 6000,
+    },
 };

package/dist/services/qa/screenshot-archive-service.d.ts

@@ -0,0 +1,51 @@
+/**
+ * rid-012 (2026-07-27) — screenshot archive service.
+ *
+ * Purpose: enforce the peaks-qa SKILL.md "Hard contracts for browser
+ * validation" Contract 1 — every Playwright screenshot MUST land under
+ * `.peaks/_runtime/<sessionId>/qa/screenshots/`, not at the project
+ * root. When the LLM forgets to pass `filename` to
+ * `browser_take_screenshot`, Playwright MCP writes to the current
+ * working directory (typically the project root), which scatters
+ * `.png` files at the repo top level. This service is the
+ * remediation: scan a directory, move stray screenshot files into
+ * the canonical screenshots/ subdir under the active QA scope.
+ *
+ * CLI surface (peaks qa archive-screenshots):
+ *   peaks qa archive-screenshots [--source <dir>] [--project <root>]
+ *
+ * Behavior:
+ *   - Scan `--source` for *.png / *.jpg / *.jpeg files (case-insensitive
+ *     extension match). Recurse exactly 1 level deep — the project
+ *     root plus one subdir (covers `./foo.png` + `./screenshots/*.png`).
+ *     Avoid recursing into `.peaks/` or `node_modules/` (artifact dirs).
+ *   - Auto-create `.peaks/_runtime/<session-id>/qa/screenshots/` if
+ *     missing (mkdirSync recursive, mode 0o755).
+ *   - For each stray file: `fs.renameSync(src, dst)`. If `dst` exists
+ *     (filename collision across multiple invocations), suffix with
+ *     `-<ISO-timestamp>` so the move is non-destructive.
+ *   - Return JSON envelope with moved list + skipped list + final
+ *     screenshots/ dir contents.
+ */
+export type ScreenshotExtension = '.png' | '.jpg' | '.jpeg';
+export interface ArchiveScreenshotOptions {
+    readonly sourceDir: string;
+    readonly targetDir: string;
+    readonly now?: Date;
+}
+export interface ArchiveScreenshotEnvelope {
+    readonly scannedSource: string;
+    readonly targetDir: string;
+    readonly moved: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[];
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    readonly targetContentsBefore: readonly string[];
+    readonly targetContentsAfter: readonly string[];
+    readonly archivedAt: string;
+}
+export declare function archiveScreenshots(options: ArchiveScreenshotOptions): ArchiveScreenshotEnvelope;

package/dist/services/qa/screenshot-archive-service.js

@@ -0,0 +1,134 @@
+/**
+ * rid-012 (2026-07-27) — screenshot archive service.
+ *
+ * Purpose: enforce the peaks-qa SKILL.md "Hard contracts for browser
+ * validation" Contract 1 — every Playwright screenshot MUST land under
+ * `.peaks/_runtime/<sessionId>/qa/screenshots/`, not at the project
+ * root. When the LLM forgets to pass `filename` to
+ * `browser_take_screenshot`, Playwright MCP writes to the current
+ * working directory (typically the project root), which scatters
+ * `.png` files at the repo top level. This service is the
+ * remediation: scan a directory, move stray screenshot files into
+ * the canonical screenshots/ subdir under the active QA scope.
+ *
+ * CLI surface (peaks qa archive-screenshots):
+ *   peaks qa archive-screenshots [--source <dir>] [--project <root>]
+ *
+ * Behavior:
+ *   - Scan `--source` for *.png / *.jpg / *.jpeg files (case-insensitive
+ *     extension match). Recurse exactly 1 level deep — the project
+ *     root plus one subdir (covers `./foo.png` + `./screenshots/*.png`).
+ *     Avoid recursing into `.peaks/` or `node_modules/` (artifact dirs).
+ *   - Auto-create `.peaks/_runtime/<session-id>/qa/screenshots/` if
+ *     missing (mkdirSync recursive, mode 0o755).
+ *   - For each stray file: `fs.renameSync(src, dst)`. If `dst` exists
+ *     (filename collision across multiple invocations), suffix with
+ *     `-<ISO-timestamp>` so the move is non-destructive.
+ *   - Return JSON envelope with moved list + skipped list + final
+ *     screenshots/ dir contents.
+ */
+import { existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const SCREENSHOT_EXTS = new Set(['.png', '.jpg', '.jpeg']);
+function isScreenshotFile(name) {
+    const lower = name.toLowerCase();
+    for (const ext of SCREENSHOT_EXTS) {
+        if (lower.endsWith(ext)) {
+            return true;
+        }
+    }
+    return false;
+}
+function listScreenshotFiles(sourceDir, targetDir) {
+    // Recurse 1 level deep. Skip .peaks/ + node_modules/ + hidden dirs.
+    // Also skip the targetDir itself to avoid re-scanning already-archived files
+    // (otherwise the same file would appear twice across calls, and the second
+    // call's collision check would treat it as a duplicate).
+    const targetBaseName = targetDir.split(/[\\/]/).pop();
+    const out = [];
+    const top = readdirSync(sourceDir, { withFileTypes: true });
+    for (const entry of top) {
+        if (entry.name === targetBaseName) {
+            continue;
+        }
+        const full = join(sourceDir, entry.name);
+        if (entry.isFile()) {
+            if (isScreenshotFile(entry.name)) {
+                out.push(full);
+            }
+            continue;
+        }
+        if (entry.isDirectory()) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                continue;
+            }
+            try {
+                const sub = readdirSync(full, { withFileTypes: true });
+                for (const subEntry of sub) {
+                    if (subEntry.isFile() && isScreenshotFile(subEntry.name)) {
+                        out.push(join(full, subEntry.name));
+                    }
+                }
+            }
+            catch {
+                // unreadable subdir — skip silently
+            }
+        }
+    }
+    return out;
+}
+export function archiveScreenshots(options) {
+    const sourceDir = resolve(options.sourceDir);
+    const targetDir = resolve(options.targetDir);
+    const now = options.now ?? new Date();
+    if (!existsSync(sourceDir)) {
+        return {
+            scannedSource: sourceDir,
+            targetDir,
+            moved: [],
+            skipped: [{ path: sourceDir, reason: 'source dir not found' }],
+            targetContentsBefore: [],
+            targetContentsAfter: [],
+            archivedAt: now.toISOString()
+        };
+    }
+    const targetContentsBefore = existsSync(targetDir)
+        ? readdirSync(targetDir)
+        : [];
+    mkdirSync(targetDir, { recursive: true });
+    const candidates = listScreenshotFiles(sourceDir, targetDir);
+    const moved = [];
+    const skipped = [];
+    for (const src of candidates) {
+        const baseName = src.split(/[\\/]/).pop() ?? 'unknown.png';
+        let dst = join(targetDir, baseName);
+        if (existsSync(dst)) {
+            // collision: suffix with ISO timestamp
+            const dot = baseName.lastIndexOf('.');
+            const stem = dot > 0 ? baseName.slice(0, dot) : baseName;
+            const ext = dot > 0 ? baseName.slice(dot) : '';
+            const stamp = now.toISOString().replace(/[:.]/g, '-');
+            dst = join(targetDir, `${stem}-${stamp}${ext}`);
+        }
+        try {
+            renameSync(src, dst);
+            moved.push({ from: src, to: dst });
+        }
+        catch (err) {
+            skipped.push({
+                path: src,
+                reason: err instanceof Error ? err.message : 'rename failed'
+            });
+        }
+    }
+    const targetContentsAfter = readdirSync(targetDir);
+    return {
+        scannedSource: sourceDir,
+        targetDir,
+        moved,
+        skipped,
+        targetContentsBefore,
+        targetContentsAfter,
+        archivedAt: now.toISOString()
+    };
+}