peaks-loop 4.0.0-beta.3 → 4.0.0-beta.30

package/dist/src/services/understand/understand-scan-service.js

@@ -1,170 +0,0 @@
-import { stat } from 'node:fs/promises';
-import { join } from 'node:path';
-import { isDirectory, pathExists, readText } from '../../shared/fs.js';
-import { getErrorMessage } from '../../shared/result.js';
-import { loadPreferences } from '../preferences/preferences-service.js';
-function defaultArtifactDir(projectRoot) {
-    return join(projectRoot, '.understand-anything');
-}
-function countArrayField(record, key) {
-    const value = record[key];
-    return Array.isArray(value) ? value.length : 0;
-}
-async function readFlag(path) {
-    return { exists: await pathExists(path), path };
-}
-async function readGraph(graphPath) {
-    if (!(await pathExists(graphPath))) {
-        return { exists: false, path: graphPath };
-    }
-    const stats = await stat(graphPath);
-    const raw = await readText(graphPath);
-    try {
-        const parsed = JSON.parse(raw);
-        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            return {
-                exists: true,
-                path: graphPath,
-                sizeBytes: stats.size,
-                parseError: 'knowledge-graph.json must be a JSON object'
-            };
-        }
-        const record = parsed;
-        return {
-            exists: true,
-            path: graphPath,
-            sizeBytes: stats.size,
-            topLevelFields: Object.keys(record).sort(),
-            counts: {
-                nodes: countArrayField(record, 'nodes'),
-                edges: countArrayField(record, 'edges'),
-                layers: countArrayField(record, 'layers'),
-                tours: countArrayField(record, 'tours')
-            }
-        };
-    }
-    catch (error) {
-        return {
-            exists: true,
-            path: graphPath,
-            sizeBytes: stats.size,
-            parseError: getErrorMessage(error)
-        };
-    }
-}
-export async function scanUnderstandAnything(options) {
-    const artifactDir = options.artifactDir ?? defaultArtifactDir(options.projectRoot);
-    const exists = await isDirectory(artifactDir);
-    // L3.1: read uaPrompt from preferences.json (graceful — returns 'unset' if missing/broken)
-    const uaPrompt = await readUaPrompt(options.projectRoot);
-    if (!exists) {
-        return {
-            exists: false,
-            artifactDir,
-            graph: { exists: false, path: join(artifactDir, 'knowledge-graph.json') },
-            intermediate: { exists: false, path: join(artifactDir, 'intermediate') },
-            diffOverlay: { exists: false, path: join(artifactDir, 'diff-overlay.json') },
-            uaPrompt
-        };
-    }
-    const graph = await readGraph(join(artifactDir, 'knowledge-graph.json'));
-    const intermediate = await readFlag(join(artifactDir, 'intermediate'));
-    const diffOverlay = await readFlag(join(artifactDir, 'diff-overlay.json'));
-    return { exists: true, artifactDir, graph, intermediate, diffOverlay, uaPrompt };
-}
-async function readUaPrompt(projectRoot) {
-    try {
-        const prefs = await loadPreferences(projectRoot);
-        return prefs.uaPrompt;
-    }
-    catch {
-        return 'unset';
-    }
-}
-function pickStringId(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        return null;
-    }
-    const record = value;
-    for (const key of ['id', 'path', 'name', 'label']) {
-        const candidate = record[key];
-        if (typeof candidate === 'string' && candidate.length > 0) {
-            return candidate;
-        }
-    }
-    return null;
-}
-function pickStringField(record, key) {
-    const value = record[key];
-    return typeof value === 'string' && value.length > 0 ? value : null;
-}
-function pickNameArray(record, key) {
-    const value = record[key];
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value
-        .map((entry) => {
-        if (typeof entry === 'string') {
-            return entry;
-        }
-        return pickStringId(entry);
-    })
-        .filter((entry) => entry !== null);
-}
-export async function summarizeKnowledgeGraph(options) {
-    const scanOptions = { projectRoot: options.projectRoot };
-    if (options.artifactDir !== undefined) {
-        scanOptions.artifactDir = options.artifactDir;
-    }
-    const scan = await scanUnderstandAnything(scanOptions);
-    const sampleSize = options.sampleSize ?? 5;
-    if (!scan.graph.exists) {
-        return {
-            exists: false,
-            path: scan.graph.path,
-            generatedAt: null,
-            topLevelFields: [],
-            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
-            layerNames: [],
-            tourNames: [],
-            sampleNodes: []
-        };
-    }
-    if (scan.graph.parseError !== undefined) {
-        return {
-            exists: true,
-            path: scan.graph.path,
-            generatedAt: null,
-            topLevelFields: [],
-            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
-            layerNames: [],
-            tourNames: [],
-            sampleNodes: [],
-            parseError: scan.graph.parseError
-        };
-    }
-    const raw = await readText(scan.graph.path);
-    const parsed = JSON.parse(raw);
-    const record = parsed;
-    const generatedAt = pickStringField(record, 'generatedAt');
-    const nodes = Array.isArray(record.nodes) ? record.nodes : [];
-    const sampleNodes = nodes.slice(0, sampleSize)
-        .map((entry) => pickStringId(entry))
-        .filter((entry) => entry !== null);
-    return {
-        exists: true,
-        path: scan.graph.path,
-        generatedAt,
-        topLevelFields: Object.keys(record).sort(),
-        counts: {
-            nodes: countArrayField(record, 'nodes'),
-            edges: countArrayField(record, 'edges'),
-            layers: countArrayField(record, 'layers'),
-            tours: countArrayField(record, 'tours')
-        },
-        layerNames: pickNameArray(record, 'layers'),
-        tourNames: pickNameArray(record, 'tours'),
-        sampleNodes
-    };
-}

package/dist/src/services/upgrade/upgrade-service.js

@@ -1,403 +0,0 @@
-/**
- * peaks upgrade --to 2.0 — umbrella service for the 1.x → 2.0
- * migration.
- *
- * Per the "one-key completion" + "minimal-user-operation" tenets
- * (2026-06-11), the typical upgrade path is:
- *
- *   $ npm i -g peaks-loop@2.0   # postinstall does everything
- *
- * OR (postinstall skipped / manual fallback):
- *
- *   $ peaks upgrade --to 2.0
- *
- * The umbrella orchestrates 7 sub-commands:
- *   1. config migrate       (already ships as `peaks config migrate`)
- *   2. standards migrate    (`peaks standards migrate --from-claude-rules`)
- *   3. memory extract       (already ships as `peaks memory extract`)
- *   4. hooks install        (already ships as `peaks hooks install`)
- *   5. skill sync           (this session, `peaks skill sync --all`)
- *   6. audit verify         (already ships as `peaks audit red-lines`)
- *   7. write upgrade record (in-process, .peaks/memory/upgrade-2.0-*.md)
- *
- * Each sub-step is a thin shell-out to the existing CLI; the
- * umbrella's only in-process work is the audit and the upgrade
- * record write. Sub-step failures are SOFT (logged + nextActions
- * populated) so the umbrella never blocks a successful partial
- * upgrade.
- */
-import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { join, dirname, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runRedLinesAudit } from '../audit/red-lines-service.js';
-import { savePreferences } from '../preferences/preferences-service.js';
-import { migrateGitignoreFile } from './gitignore-migrate-service.js';
-/**
- * Default substep executor — wraps `spawnSync` with the same
- * stdio / encoding / timeout config the umbrella has used since
- * v1. Exported for test coverage: the seam-preservation test
- * imports this directly to verify the normalized return shape
- * on a spawn failure (e.g. a non-existent command).
- */
-export const defaultSubstepExecutor = (command, args, timeoutMs) => {
-    const start = Date.now();
-    try {
-        const result = spawnSync(command, args, {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'pipe'],
-            timeout: timeoutMs,
-        });
-        return {
-            status: result.status,
-            stdout: result.stdout ?? '',
-            stderr: result.stderr ?? '',
-            durationMs: Date.now() - start,
-        };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-            status: null,
-            stdout: '',
-            stderr: message,
-            durationMs: Date.now() - start,
-        };
-    }
-};
-const STEPS = [
-    { name: 'config-migrate', args: (p) => ['config', 'migrate', '--project', p, '--apply', '--json'] },
-    { name: 'standards-migrate', args: (p) => ['standards', 'migrate', '--from-claude-rules', '--project', p, '--apply', '--json'] },
-    // memory extract is special: its --artifact takes literal file
-    // paths (memory-service rejects glob patterns via realpathSync).
-    // The umbrella expands the three documented patterns
-    // (skills/**/SKILL.md, CLAUDE.md, .claude/rules/**/*.md) on disk
-    // and passes the resulting literal list. See runUpgrade's special
-    // case below for the args resolution; the args function here is
-    // a placeholder so the STEPS table stays uniform.
-    { name: 'memory-extract', args: (p) => ['memory', 'extract', '--project', p, '--json'] },
-    { name: 'hooks-install', args: (p) => ['hooks', 'install', '--project', p, '--json'] },
-    { name: 'skill-sync', args: (p) => ['skill', 'sync', '--all', '--project', p, '--json'] },
-    { name: 'audit-verify', args: (p) => ['audit', 'red-lines', '--project', p, '--json'] },
-];
-/**
- * Walk `<root>` recursively and collect every file whose basename
- * matches `predicate`. Returns absolute paths.
- *
- * Mirrors `readMarkdownFilesRecursive` in
- * src/services/standards/migrate-claude-rules-service.ts so the
- * umbrella does not pull a new glob dependency (Node 20+ engine
- * constraint — `fs.globSync` requires Node 22+).
- */
-function collectFilesRecursive(root, predicate) {
-    if (!existsSync(root))
-        return [];
-    const stat = statSync(root);
-    if (stat.isFile()) {
-        return predicate(root.split(/[\\/]/).pop() ?? '') ? [root] : [];
-    }
-    if (!stat.isDirectory())
-        return [];
-    const out = [];
-    for (const entry of readdirSync(root)) {
-        const child = join(root, entry);
-        let childStat;
-        try {
-            childStat = statSync(child);
-        }
-        catch {
-            continue;
-        }
-        if (childStat.isFile()) {
-            if (predicate(entry))
-                out.push(child);
-        }
-        else if (childStat.isDirectory()) {
-            out.push(...collectFilesRecursive(child, predicate));
-        }
-    }
-    return out;
-}
-/**
- * Resolve the three documented memory-extract artifact patterns
- * against a real project tree. Returns project-relative paths
- * (memory-service joins them with --project root) so the
- * realpathSync inside memory-service's assertInsideProject
- * succeeds.
- *
- * Patterns:
- *   - skills/[asterisk][asterisk]/SKILL.md       (project-root convention)
- *   - .claude/skills/[asterisk][asterisk]/SKILL.md (Claude-Code consumer convention; ice-cola)
- *   - CLAUDE.md
- *   - .claude/rules/[asterisk][asterisk]/[asterisk].md
- *
- * Returns an empty list when none of the roots exist. The
- * caller marks the step skipped in that case.
- */
-function expandMemoryArtifacts(projectRoot) {
-    const out = [];
-    // skills/**/SKILL.md (peaks-loop repo convention)
-    const skillFiles = collectFilesRecursive(join(projectRoot, 'skills'), (name) => name === 'SKILL.md');
-    for (const abs of skillFiles) {
-        out.push(relative(projectRoot, abs));
-    }
-    // .claude/skills/**/SKILL.md (Claude-Code consumer convention;
-    // surfaced by ice-cola dogfood 2026-06-12 — the 1.x install
-    // landed skills under .claude/skills/, not <root>/skills/)
-    const claudeSkillFiles = collectFilesRecursive(join(projectRoot, '.claude', 'skills'), (name) => name === 'SKILL.md');
-    for (const abs of claudeSkillFiles) {
-        out.push(relative(projectRoot, abs));
-    }
-    // CLAUDE.md (literal)
-    const claudeMd = join(projectRoot, 'CLAUDE.md');
-    if (existsSync(claudeMd) && statSync(claudeMd).isFile()) {
-        out.push('CLAUDE.md');
-    }
-    // .claude/rules/**/*.md
-    const claudeRules = collectFilesRecursive(join(projectRoot, '.claude', 'rules'), (name) => name.endsWith('.md'));
-    for (const abs of claudeRules) {
-        out.push(relative(projectRoot, abs));
-    }
-    return out;
-}
-function read1xVersion(cwd) {
-    const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '';
-    if (home.length === 0)
-        return null;
-    const global = join(home, '.peaks', 'config.json');
-    if (!existsSync(global))
-        return null;
-    try {
-        const raw = JSON.parse(readFileSync(global, 'utf8'));
-        if (typeof raw.version === 'string')
-            return raw.version;
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        // ignore
-    }
-    return null;
-}
-function runStep(peaksBin, name, args, timeoutMs = 60_000, executor = defaultSubstepExecutor) {
-    // The global `peaks` shim is a `/bin/sh` symlink script (the
-    // npm install postinstall creates `peaks` → `peaks.sh` on
-    // Windows). cmd.exe (the default Windows shell) cannot run
-    // `.sh` scripts directly, so the shim fails with "unknown
-    // command 'migrate'" etc. The fix: prefer the local node
-    // binary + the peaks.js script path. The umbrella resolves
-    // the script path at startup; only falls back to `peaks` if
-    // no script path is available (Unix-only).
-    let command;
-    let spawnArgs;
-    if (peaksBin.includes('\\') || peaksBin.includes('/')) {
-        // peaksBin is a real path (e.g. /c/.../bin/peaks.js);
-        // invoke directly via node.
-        command = process.execPath;
-        spawnArgs = [peaksBin, ...args];
-    }
-    else {
-        // peaksBin is just "peaks" — best-effort shell exec.
-        command = peaksBin;
-        spawnArgs = args;
-    }
-    // The executor normalizes spawn errors to { status: null, stderr: ... }
-    // so no try/catch wrapper is needed here — the call always returns
-    // a shaped record. See defaultSubstepExecutor for the reference impl.
-    const result = executor(command, spawnArgs, timeoutMs);
-    return {
-        name,
-        status: result.status === 0 ? 'pass' : 'fail',
-        exitCode: result.status,
-        stdout: result.stdout,
-        stderr: result.stderr,
-        durationMs: result.durationMs,
-    };
-}
-function writeUpgradeRecord(projectRoot, result) {
-    try {
-        const memoryDir = join(projectRoot, '.peaks', 'memory');
-        mkdirSync(memoryDir, { recursive: true });
-        const date = new Date().toISOString().slice(0, 10);
-        const file = join(memoryDir, `upgrade-2.0-${date}.md`);
-        const lines = [];
-        lines.push(`# Upgrade to peaks-loop 2.0 — ${date}`);
-        lines.push('');
-        lines.push(`> Auto-generated by \`peaks upgrade --to 2.0${result.applied ? ' --auto' : ''}\`.`);
-        lines.push(`> Per the "one-key completion" + "minimal-user-operation" tenets.`);
-        lines.push('');
-        if (result.fromVersion !== null) {
-            lines.push(`**From version**: ${result.fromVersion}`);
-        }
-        lines.push(`**To version**: 2.0.0`);
-        lines.push(`**Project root**: \`${result.projectRoot}\``);
-        lines.push('');
-        lines.push('## Sub-step results');
-        lines.push('');
-        lines.push('| step | status | exitCode | durationMs |');
-        lines.push('|------|--------|----------|------------|');
-        for (const step of result.steps) {
-            lines.push(`| ${step.name} | ${step.status} | ${step.exitCode ?? 'n/a'} | ${step.durationMs} |`);
-        }
-        lines.push('');
-        if (result.auditBefore !== null || result.auditAfter !== null) {
-            lines.push('## Audit snapshot');
-            lines.push('');
-            if (result.auditBefore !== null) {
-                lines.push(`- Before: totalRedLines=${result.auditBefore.totalRedLines}, cliBacked=${result.auditBefore.cliBacked}`);
-            }
-            if (result.auditAfter !== null) {
-                lines.push(`- After:  totalRedLines=${result.auditAfter.totalRedLines}, cliBacked=${result.auditAfter.cliBacked}`);
-            }
-            lines.push('');
-        }
-        lines.push('## Next actions');
-        lines.push('');
-        for (const a of result.nextActions) {
-            lines.push(`- ${a}`);
-        }
-        writeFileSync(file, lines.join('\n') + '\n', 'utf8');
-        return file;
-    }
-    catch (err) {
-        process.stderr.write(`peaks upgrade: failed to write upgrade record: ${err instanceof Error ? err.message : String(err)}\n`);
-        return null;
-    }
-}
-export function runUpgrade(input) {
-    // Resolve the peaks binary. Default: the peaks.js script
-    // co-located with this compiled module (the user just installed
-    // peaks-loop globally, but the global `peaks` shim is a .sh
-    // script that cmd.exe can't run on Windows). Falling back
-    // to just "peaks" lets the umbrella work when invoked from
-    // a Unix-style environment that can run the shim directly.
-    const here = dirname(fileURLToPath(import.meta.url));
-    // Walk up from the compiled location to find bin/peaks.js.
-    // The compiled service lives at dist/src/services/upgrade/upgrade-service.js;
-    // bin/peaks.js is at the peaks-loop root.
-    const peaksBin = input.peaksBin ??
-        resolve(here, '..', '..', '..', '..', 'bin', 'peaks.js');
-    const fallbackPeaks = 'peaks';
-    const resolvedPeaksBin = existsSync(peaksBin) ? peaksBin : fallbackPeaks;
-    // Resolve the executor once at the top of runUpgrade so every
-    // sub-step call shares the same instance. Tests pass a fake
-    // executor via UpgradeInput.executor; production callers omit
-    // it and get the default spawnSync wrapper.
-    const executor = input.executor ?? defaultSubstepExecutor;
-    const fromVersion = read1xVersion(input.projectRoot);
-    const steps = [];
-    const warnings = [];
-    const nextActions = [];
-    // Ensure .peaks/preferences.json exists. This is the file the
-    // 1.x detector keys off — without it, `peaks upgrade --detect-1x`
-    // keeps returning isOneX=true after a successful upgrade and the
-    // user gets stuck in a re-prompt loop. savePreferences with an
-    // empty override merges with DEFAULT_PREFERENCES and writes; if
-    // the file already exists the user's values are preserved.
-    // Real bug surfaced by ice-cola dogfood 2026-06-12.
-    try {
-        savePreferences(input.projectRoot, {});
-    }
-    catch (err) {
-        warnings.push(`ensure-preferences failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    // Migrate .gitignore so 2.0 tracked artifacts
-    // (.peaks/standards/, .peaks/memory/*.md durable memories,
-    // .peaks/PROJECT.md) aren't silently hidden by a 1.x wholesale
-    // `/.peaks/` ignore rule. Real bug surfaced by ice-cola dogfood
-    // 2026-06-12: every consumer artifact was being dropped from git
-    // status. Service is idempotent + creates a timestamped backup
-    // before any write.
-    try {
-        const giResult = migrateGitignoreFile({ projectRoot: input.projectRoot, apply: true });
-        if (giResult.changed && giResult.appliedWrite && giResult.backupPath !== null) {
-            nextActions.push(`Updated .gitignore — removed stale wholesale .peaks rule(s): ${giResult.removedRules.join(', ')}. Backup at ${giResult.backupPath}.`);
-        }
-        else if (giResult.missing) {
-            warnings.push('gitignore-migrate skipped: project has no .gitignore');
-        }
-    }
-    catch (err) {
-        warnings.push(`gitignore-migrate failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    // Audit BEFORE the upgrade (baseline)
-    let auditBefore = null;
-    try {
-        const r = runRedLinesAudit({ projectRoot: input.projectRoot });
-        auditBefore = { totalRedLines: r.audit.totalRedLines, cliBacked: r.audit.cliBacked };
-    }
-    catch (err) {
-        warnings.push(`audit-before failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    // Run the 6 sub-steps
-    for (const step of STEPS) {
-        if (step.name === 'memory-extract') {
-            // Special case: expand the three glob patterns to literal
-            // paths before spawning. memory-service rejects literal
-            // '**' in artifact paths (assertInsideProject's realpathSync
-            // throws ENOENT) and refuses to run without --artifact.
-            const artifacts = expandMemoryArtifacts(input.projectRoot);
-            if (artifacts.length === 0) {
-                steps.push({
-                    name: 'memory-extract',
-                    status: 'skipped',
-                    exitCode: null,
-                    stdout: '',
-                    stderr: 'no skills/, CLAUDE.md, or .claude/rules/ artifacts found in the project',
-                    durationMs: 0,
-                });
-                continue;
-            }
-            const args = ['memory', 'extract', '--project', input.projectRoot, '--artifact', ...artifacts, '--apply', '--json'];
-            const r = runStep(resolvedPeaksBin, 'memory-extract', args, 60_000, executor);
-            steps.push(r);
-            if (r.status === 'fail') {
-                warnings.push(`memory-extract failed: ${r.stderr.slice(0, 200)}`);
-            }
-            continue;
-        }
-        const args = step.args(input.projectRoot);
-        const r = runStep(resolvedPeaksBin, step.name, args, 60_000, executor);
-        steps.push(r);
-        if (r.status === 'fail') {
-            warnings.push(`${step.name} failed: ${r.stderr.slice(0, 200)}`);
-        }
-    }
-    // Audit AFTER the upgrade (verify)
-    let auditAfter = null;
-    try {
-        const r = runRedLinesAudit({ projectRoot: input.projectRoot });
-        auditAfter = { totalRedLines: r.audit.totalRedLines, cliBacked: r.audit.cliBacked };
-    }
-    catch (err) {
-        warnings.push(`audit-after failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    const passedCount = steps.filter((s) => s.status === 'pass').length;
-    const failedCount = steps.filter((s) => s.status === 'fail').length;
-    const skippedCount = steps.filter((s) => s.status === 'skipped').length;
-    const applied = failedCount === 0;
-    if (failedCount > 0) {
-        nextActions.push(`${failedCount} sub-step(s) failed. Run \`peaks upgrade --to 2.0\` again to retry the failed steps.`);
-    }
-    if (input.auto !== true) {
-        nextActions.push('Run `peaks audit red-lines --project .` to verify the L2 catalog is healthy.');
-    }
-    nextActions.push('See `docs/UPGRADING-2.0.md` for the manual fallback if this auto-upgrade fails.');
-    // Write the upgrade record (always, even on partial failure —
-    // the user gets a forensic artifact either way)
-    const partial = {
-        applied,
-        fromVersion,
-        toVersion: '2.0.0',
-        projectRoot: input.projectRoot,
-        steps,
-        passedCount,
-        failedCount,
-        skippedCount,
-        auditBefore,
-        auditAfter,
-        upgradeRecordPath: null,
-        nextActions,
-        warnings,
-    };
-    const upgradeRecordPath = writeUpgradeRecord(input.projectRoot, partial);
-    return { ...partial, upgradeRecordPath };
-}

package/dist/src/services/verdict/envelopes.d.ts

@@ -1,93 +0,0 @@
-/**
- * peaks-loop v2.13.3 — Envelope unification (AC-1: real markdown parse).
- *
- * The 5 input envelopes feeding `aggregateVerdict()` have always been
- * heterogeneous (peaks-security-audit / peaks-perf-audit / karpathy /
- * peaks-mut / peaks-qa). v2.13.1 shipped precedence wiring without
- * touching the on-disk shapes. v2.13.2 introduced a discriminated-union
- * type projection `AnyEnvelope` and 5 pure parser functions.
- *
- * v2.13.3 dogfood bug #1: parseSecurity/Perf previously only supported
- * a JSON.parse path. The real v2.12.0 audit files at
- * `.peaks/_runtime/<sid>/audit/security.md` and `audit/perf.md` are
- * YAML frontmatter + markdown body — NOT JSON. The fix preserves
- * the JSON.parse path (back-compat for unit tests + any consumer that
- * passed JSON explicitly) and adds a markdown fallback that extracts
- * `verdict:` from the frontmatter and parses `## Findings` bullets.
- *
- * Karpathy §2 (Simplicity First):
- *   - single file, ~210 lines, zero new IO.
- *   - re-uses existing strict-shape guards (isSecurityAuditEnvelope /
- *     isPerfAuditEnvelope) — no duplicate validation logic.
- *   - parsers return `null` on malformed input (mirrors loadMutReport's
- *     "missing → null" contract). Callers can detect "envelope missing"
- *     without throwing.
- */
-import { type SecurityAuditEnvelope } from '../audit-independent/security-audit-service.js';
-import { type PerfAuditEnvelope } from '../audit-independent/perf-audit-service.js';
-import { type KarpathyEnvelope, type MutEnvelope, type QaEnvelope, type AggregatorInput } from './verdict-aggregator.js';
-/**
- * `kind` is the discriminator. The on-disk file format is unchanged;
- * this field exists only in the TS type projection. The aggregator
- * accepts both the legacy `{security, perf, ...}` shape and the new
- * union via a thin adapter (`aggregateFromEnvelopes`).
- */
-export type AnyEnvelope = {
-    kind: 'security';
-    envelope: SecurityAuditEnvelope;
-} | {
-    kind: 'perf';
-    envelope: PerfAuditEnvelope;
-} | {
-    kind: 'karpathy';
-    envelope: KarpathyEnvelope;
-} | {
-    kind: 'mut';
-    envelope: MutEnvelope;
-} | {
-    kind: 'qa';
-    envelope: QaEnvelope;
-};
-/**
- * v2.13.3 AC-1 — parse real v2.12.0 audit markdown.
- *
- * Strategy (per PRD AC-1 mitigation):
- *   1. Try JSON.parse first (back-compat with prior unit tests + any
- *      consumer that passes a JSON string explicitly).
- *   2. Fall back to markdown parse: extract `verdict:` from YAML
- *      frontmatter, parse `## Findings` bullets in the body, return
- *      a SecurityAuditEnvelope.
- *   3. Return null when neither path yields a valid envelope.
- */
-export declare function parseSecurityEnvelope(md: string): SecurityAuditEnvelope | null;
-export declare function parsePerfEnvelope(md: string): PerfAuditEnvelope | null;
-/**
- * Karpathy review is stored as markdown (`.peaks/_runtime/<sid>/rd/karpathy-review.md`).
- * We parse the 3 state lines that drive the aggregator:
- *   - `gateAction: pass | warn | block`
- *   - `verdict: pass | warn | block`  (alias for gateAction)
- *   - `passed: true | false`
- * Plus the violations list under a `## Violations` heading, where each
- * bullet begins with `[SEVERITY] file:line — hint` and declares a
- * guideline tag like `(simplicity-first)`.
- */
-export declare function parseKarpathyEnvelope(md: string): KarpathyEnvelope | null;
-/**
- * Mut envelope is JSON. Mirrors `loadMutReport`'s contract: missing
- * fields → null. The strict shape matches `MutReportJson` in
- * `services/mut/types.ts`.
- */
-export declare function parseMutEnvelope(json: unknown): MutEnvelope | null;
-/**
- * QA test report is markdown under `qa/test-reports/<rid>.md`.
- * The verdict line is `verdict: pass | return-to-rd | blocked` and
- * optionally carries a `reportPath:` line. Anything else → null.
- */
-export declare function parseQaEnvelope(md: string): QaEnvelope | null;
-/**
- * Convert a partial list of `AnyEnvelope` values to the legacy
- * `AggregatorInput` shape. `null` envelopes are skipped (a missing
- * envelope is treated as "audit not run" — same semantics as
- * `AggregatorInput` without that key).
- */
-export declare function envelopesToAggregatorInput(list: ReadonlyArray<AnyEnvelope | null>): AggregatorInput;