peaks-loop 3.0.0

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

@@ -0,0 +1,119 @@
+/**
+ * Slice topology observability — schema + emit (Slice A of v2.11.1).
+ *
+ * Public surface:
+ *   - `emitObservabilityEvent(event, options)` — fire-and-forget write
+ *     to `.peaks/_runtime/<event.sessionId>/metrics/slices.jsonl`.
+ *   - `readObservabilityEvents(projectRoot, sessionId)` — schema-aware
+ *     reader that skips malformed lines and unknown schema versions
+ *     (per PRD Q3 forward-compat).
+ *
+ * Schema-versioned (schemaVersion: 1). The zod schema is the source of
+ * truth for the wire format. `ts` and `sessionId` are required; the
+ * caller is responsible for passing them (so each hook site has a
+ * canonical session binding even when run in a sub-agent).
+ *
+ * Per PRD Q4, `emit` MUST NEVER throw or fail-loud. All error paths
+ * collapse to `written: false` with a `reason` string so the caller can
+ * log if it wants — but the calling hook site itself swallows the
+ * result (fire-and-forget by convention).
+ */
+import { z } from 'zod';
+import { appendMetricLine, metricsFilePath, pruneMetricsFiles, readMetricLines } from './jsonl-store.js';
+export const OBSERVABILITY_SCHEMA_VERSION = 1;
+export const OBSERVABILITY_CATEGORIES = [
+    'slice-transition',
+    'dispatch',
+    'checkpoint',
+    'mode-gate',
+    'context-trigger',
+    'post-compact'
+];
+// v2.12.0 fan-out collapse: `security-reviewer` (in-process RD slot)
+// moved out to the standalone `peaks-security-audit` skill; the matching
+// perf slot was `perf-baseline-reviewer` which is replaced by the
+// standalone `peaks-perf-audit` skill. The 1-minor-release back-compat
+// window keeps `security-reviewer` readable as a deprecated alias (see
+// the dispatcher in `src/services/rd/reviewer-dispatch-policy.ts`);
+// observability drops it because no new events carry that role tag.
+export const OBSERVABILITY_SUBAGENT_ROLES = [
+    'rd',
+    'qa',
+    'code-reviewer',
+    'karpathy-reviewer',
+    'peaks-security-audit',
+    'peaks-perf-audit'
+];
+export const ObservabilityEventSchema = z.object({
+    schemaVersion: z.literal(OBSERVABILITY_SCHEMA_VERSION),
+    ts: z.string().datetime({ offset: true }),
+    sessionId: z.string().min(1),
+    category: z.enum(OBSERVABILITY_CATEGORIES),
+    sliceRid: z.string().min(1).optional(),
+    role: z.enum(OBSERVABILITY_SUBAGENT_ROLES).optional(),
+    detail: z.record(z.unknown())
+});
+/**
+ * Append a single observability event to the session's JSONL metrics
+ * file. Synchronous (small append, sub-ms in practice) and
+ * fire-and-forget by construction — the caller never awaits, and the
+ * function never throws.
+ *
+ * On success, also triggers the cross-session prune
+ * (`pruneMetricsFiles`). The prune is best-effort and cheap when the
+ * session count is below `MAX_METRICS_FILES`.
+ */
+export function emitObservabilityEvent(event, options) {
+    const path = metricsFilePath(options.projectRoot, event.sessionId);
+    const validation = ObservabilityEventSchema.safeParse(event);
+    if (!validation.success) {
+        return { written: false, path, reason: 'invalid-schema' };
+    }
+    const line = JSON.stringify(validation.data);
+    const ok = appendMetricLine(options.projectRoot, event.sessionId, line);
+    if (ok) {
+        // Cheap when below cap; only walks .peaks/_runtime/ + stat each file.
+        pruneMetricsFiles(options.projectRoot);
+        return { written: true, path };
+    }
+    return { written: false, path, reason: 'write-failed' };
+}
+/**
+ * Read all events from a session's metrics file, skipping malformed
+ * lines and any record whose `schemaVersion` does not match the
+ * current `OBSERVABILITY_SCHEMA_VERSION` (forward-compat per Q3).
+ *
+ * Returns [] when the session has no metrics file yet.
+ */
+export function readObservabilityEvents(projectRoot, sessionId) {
+    const lines = readMetricLines(projectRoot, sessionId);
+    const events = [];
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const validation = ObservabilityEventSchema.safeParse(raw);
+        if (!validation.success) {
+            continue;
+        }
+        events.push(validation.data);
+    }
+    return events;
+}
+/**
+ * True when the candidate record validates against the current
+ * schema (re-exported as a convenience for callers that already have
+ * parsed JSON and want to skip forward-compat records).
+ */
+export function isCurrentSchemaVersion(record) {
+    return ObservabilityEventSchema.safeParse(record).success;
+}
+export const OBSERVABILITY_CONSTANTS = {
+    SCHEMA_VERSION: OBSERVABILITY_SCHEMA_VERSION,
+    CATEGORIES: OBSERVABILITY_CATEGORIES,
+    SUBAGENT_ROLES: OBSERVABILITY_SUBAGENT_ROLES
+};

package/dist/src/services/observability/report-formatter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Markdown report formatter for slice topology observability.
+ *
+ * Slice D of v2.11.1 (AC-5). Pure functions: inputs are aggregations
+ * from `aggregation.ts`, outputs are stable markdown strings suitable
+ * for pasting into PR descriptions or `.peaks/PROJECT.md` timeline
+ * entries. The CLI subcommand `peaks observability report` wires
+ * the file read + aggregation + format pipeline.
+ *
+ * Format contract (per PRD AC-5):
+ *   - Header: scope, period, generated-at timestamp
+ *   - Slice table: rid | transitions | finalState | durationMs | success
+ *   - Fanout table: role | count
+ *   - Repair-cycle table: sliceRid | cycleCount
+ *   - Top-N slowest slices: same as slice table, sorted by durationMs desc
+ */
+import type { FanoutBreakdown, Period, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation.js';
+export type ReportInput = {
+    scope: 'session' | 'all-sessions';
+    scopeId: string;
+    period: Period;
+    generatedAt: string;
+    status: StatusAggregate;
+    slices: SliceRollup[];
+    fanout: FanoutBreakdown;
+    repairCycles: RepairCycleReport;
+};
+declare function pad(value: string | number, width: number): string;
+declare function formatDurationMs(ms: number | null): string;
+/**
+ * Render the full markdown report. Pure function — no IO. The CLI
+ * layer reads events, calls aggregations, and passes the result here.
+ */
+export declare function renderObservabilityReport(input: ReportInput): string;
+export declare const REPORT_FORMAT_CONSTANTS: {
+    readonly SLOWEST_TOP_N: 5;
+};
+export declare const __reportTestHelpers: {
+    pad: typeof pad;
+    formatDurationMs: typeof formatDurationMs;
+};
+export {};

package/dist/src/services/observability/report-formatter.js

@@ -0,0 +1,156 @@
+/**
+ * Markdown report formatter for slice topology observability.
+ *
+ * Slice D of v2.11.1 (AC-5). Pure functions: inputs are aggregations
+ * from `aggregation.ts`, outputs are stable markdown strings suitable
+ * for pasting into PR descriptions or `.peaks/PROJECT.md` timeline
+ * entries. The CLI subcommand `peaks observability report` wires
+ * the file read + aggregation + format pipeline.
+ *
+ * Format contract (per PRD AC-5):
+ *   - Header: scope, period, generated-at timestamp
+ *   - Slice table: rid | transitions | finalState | durationMs | success
+ *   - Fanout table: role | count
+ *   - Repair-cycle table: sliceRid | cycleCount
+ *   - Top-N slowest slices: same as slice table, sorted by durationMs desc
+ */
+const SLOWEST_TOP_N = 5;
+function pad(value, width) {
+    const str = String(value);
+    return str.length >= width ? str : str + ' '.repeat(width - str.length);
+}
+function formatDurationMs(ms) {
+    if (ms === null || ms === 0)
+        return '0';
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${(ms / 60_000).toFixed(1)}m`;
+}
+function markdownHeader(input) {
+    const lines = [];
+    lines.push('# peaks observability report');
+    lines.push('');
+    lines.push(`- **scope**: ${input.scope === 'all-sessions' ? 'all sessions' : `session \`${input.scopeId}\``}`);
+    lines.push(`- **period**: ${input.period}`);
+    lines.push(`- **generated at**: ${input.generatedAt}`);
+    lines.push(`- **scope marker**: from v2.11.1 install date (no backfill per PRD Q5)`);
+    lines.push('');
+    return lines.join('\n');
+}
+function markdownStatusSummary(status) {
+    const lines = [];
+    lines.push('## Status summary');
+    lines.push('');
+    lines.push('| Metric | Value |');
+    lines.push('|---|---|');
+    lines.push(`| total events | ${status.totalEvents} |`);
+    lines.push(`| total slices | ${status.totalSlices} |`);
+    lines.push(`| success count | ${status.successCount} |`);
+    lines.push(`| fail count | ${status.failCount} |`);
+    lines.push(`| repair-cycle peak | ${status.repairCyclePeak} |`);
+    lines.push(`| fanout cost total | ${status.fanoutCostTotal} |`);
+    lines.push('');
+    return lines.join('\n');
+}
+function markdownSliceTable(slices) {
+    const lines = [];
+    lines.push('## Slices');
+    lines.push('');
+    if (slices.length === 0) {
+        lines.push('_No slice transitions recorded for this period._');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('| rid | transitions | final state | duration | success |');
+    lines.push('|---|---|---|---|---|');
+    for (const slice of slices) {
+        lines.push(`| ${slice.sliceRid} | ${slice.transitions} | ${slice.finalState ?? '—'} | ${formatDurationMs(slice.durationMs)} | ${slice.success ? '✓' : '✗'} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function markdownFanoutTable(fanout) {
+    const lines = [];
+    lines.push('## Fanout');
+    lines.push('');
+    if (fanout.total === 0) {
+        lines.push('_No sub-agent dispatches recorded for this period._');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('| role | count |');
+    lines.push('|---|---|');
+    for (const [role, count] of Object.entries(fanout.perRole)) {
+        if (count > 0) {
+            lines.push(`| ${role} | ${count} |`);
+        }
+    }
+    lines.push(`| **total** | **${fanout.total}** |`);
+    lines.push('');
+    return lines.join('\n');
+}
+function markdownRepairCycleTable(repairCycles) {
+    const lines = [];
+    lines.push('## Repair cycles');
+    lines.push('');
+    if (repairCycles.perSlice.length === 0) {
+        lines.push('_No repair cycles recorded for this period._');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('| slice rid | cycle count |');
+    lines.push('|---|---|');
+    for (const row of repairCycles.perSlice) {
+        lines.push(`| ${row.sliceRid} | ${row.cycleCount} |`);
+    }
+    lines.push('');
+    lines.push(`- **cap**: ${repairCycles.cap}`);
+    lines.push(`- **cap hit**: ${repairCycles.capHit ? 'yes' : 'no'}`);
+    lines.push(`- **slices at cap**: ${repairCycles.capHitCount}`);
+    lines.push('');
+    return lines.join('\n');
+}
+function markdownSlowestSlices(slices) {
+    const lines = [];
+    lines.push(`## Top-${SLOWEST_TOP_N} slowest slices`);
+    lines.push('');
+    const sorted = [...slices]
+        .filter((s) => s.durationMs !== null && s.durationMs > 0)
+        .sort((a, b) => (b.durationMs ?? 0) - (a.durationMs ?? 0))
+        .slice(0, SLOWEST_TOP_N);
+    if (sorted.length === 0) {
+        lines.push('_No slice durations available._');
+        lines.push('');
+        return lines.join('\n');
+    }
+    lines.push('| rid | duration | transitions | final state |');
+    lines.push('|---|---|---|---|');
+    for (const slice of sorted) {
+        lines.push(`| ${slice.sliceRid} | ${formatDurationMs(slice.durationMs)} | ${slice.transitions} | ${slice.finalState ?? '—'} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Render the full markdown report. Pure function — no IO. The CLI
+ * layer reads events, calls aggregations, and passes the result here.
+ */
+export function renderObservabilityReport(input) {
+    const sections = [
+        markdownHeader(input),
+        markdownStatusSummary(input.status),
+        markdownSliceTable(input.slices),
+        markdownFanoutTable(input.fanout),
+        markdownRepairCycleTable(input.repairCycles),
+        markdownSlowestSlices(input.slices)
+    ];
+    return sections.join('\n').trimEnd() + '\n';
+}
+export const REPORT_FORMAT_CONSTANTS = {
+    SLOWEST_TOP_N
+};
+// Surface `pad` for snapshot-test stability assertions; exported only
+// to keep the formatter module self-contained for snapshot diffing.
+export const __reportTestHelpers = { pad, formatDurationMs };

package/dist/src/services/openspec/openspec-archive-service.d.ts

@@ -0,0 +1,12 @@
+import type { OpenSpecScanOptions } from './openspec-scan-service.js';
+export type OpenSpecArchiveOptions = OpenSpecScanOptions & {
+    apply?: boolean;
+    archiveDirName?: string;
+};
+export type OpenSpecArchiveResult = {
+    changeId: string;
+    from: string;
+    to: string;
+    applied: boolean;
+};
+export declare function archiveOpenSpecChange(changeId: string, options?: OpenSpecArchiveOptions): Promise<OpenSpecArchiveResult | null>;

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

@@ -0,0 +1,28 @@
+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._-]*$/;
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+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 openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const archiveDir = options.archiveDirName ?? 'archive';
+    const from = join(openspecRoot, 'changes', changeId);
+    const to = join(openspecRoot, 'changes', archiveDir, changeId);
+    if (!(await isDirectory(from))) {
+        return null;
+    }
+    if (options.apply !== true) {
+        return { changeId, from, to, applied: false };
+    }
+    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 };
+}

package/dist/src/services/openspec/openspec-bridge-service.d.ts

@@ -0,0 +1,16 @@
+import { type OpenSpecScanOptions } from './openspec-scan-service.js';
+export type OpenSpecCommitBoundary = {
+    heading: string;
+    todos: string[];
+    doneItems: string[];
+};
+export type OpenSpecRdInputProjection = {
+    changeId: string;
+    acceptance: string[];
+    whatChanges: string[];
+    dependencies: string[];
+    risks: string[];
+    outOfScope: string[];
+    commitBoundaries: OpenSpecCommitBoundary[];
+};
+export declare function projectOpenSpecToRdInput(changeId: string, options?: OpenSpecScanOptions): Promise<OpenSpecRdInputProjection | null>;

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

@@ -0,0 +1,76 @@
+import { readText } from '../../shared/fs.js';
+import { loadOpenSpecChange } from './openspec-scan-service.js';
+function splitTaskSections(markdown) {
+    const sections = [];
+    let current = null;
+    for (const line of markdown.split(/\r?\n/)) {
+        if (line.startsWith('## ')) {
+            if (current !== null) {
+                sections.push(current);
+            }
+            current = { heading: line.slice(3).trim(), body: [] };
+        }
+        else if (current !== null) {
+            current.body.push(line);
+        }
+    }
+    if (current !== null) {
+        sections.push(current);
+    }
+    return sections;
+}
+const TODO_PATTERN = /^- \[ \] (.+?)\s*$/;
+const DONE_PATTERN = /^- \[[xX]\] (.+?)\s*$/;
+function extractItems(body) {
+    const todos = [];
+    const doneItems = [];
+    for (const rawLine of body) {
+        const line = rawLine.trim();
+        const todoMatch = TODO_PATTERN.exec(line);
+        if (todoMatch !== null) {
+            todos.push(todoMatch[1]);
+            continue;
+        }
+        const doneMatch = DONE_PATTERN.exec(line);
+        if (doneMatch !== null) {
+            doneItems.push(doneMatch[1]);
+        }
+    }
+    return { todos, doneItems };
+}
+async function buildCommitBoundaries(tasksPath) {
+    if (tasksPath === null) {
+        return [];
+    }
+    const markdown = await readText(tasksPath);
+    const boundaries = [];
+    for (const section of splitTaskSections(markdown)) {
+        const { todos, doneItems } = extractItems(section.body);
+        if (todos.length === 0 && doneItems.length === 0) {
+            continue;
+        }
+        boundaries.push({ heading: section.heading, todos, doneItems });
+    }
+    return boundaries;
+}
+export async function projectOpenSpecToRdInput(changeId, options = {}) {
+    const detail = await loadOpenSpecChange(changeId, options);
+    if (detail === null) {
+        return null;
+    }
+    const acceptance = detail.proposal?.acceptanceCriteria ?? [];
+    const whatChanges = detail.proposal?.whatChanges ?? [];
+    const dependencies = detail.proposal?.dependencies ?? [];
+    const risks = detail.proposal?.risks ?? [];
+    const outOfScope = detail.proposal?.outOfScope ?? [];
+    const commitBoundaries = await buildCommitBoundaries(detail.paths.tasks);
+    return {
+        changeId,
+        acceptance,
+        whatChanges,
+        dependencies,
+        risks,
+        outOfScope,
+        commitBoundaries
+    };
+}

package/dist/src/services/openspec/openspec-init-service.d.ts

@@ -0,0 +1,23 @@
+export type OpenSpecInitOptions = {
+    projectRoot: string;
+    apply?: boolean;
+};
+export type OpenSpecInitPlan = {
+    apply: boolean;
+    projectRoot: string;
+    openspecRoot: string;
+    plannedWrites: Array<{
+        path: string;
+        kind: 'directory' | 'file';
+        bytes: number;
+        content: string;
+    }>;
+    alreadyInitialized: boolean;
+    existingFiles: string[];
+};
+export type OpenSpecInitResult = OpenSpecInitPlan & {
+    writtenFiles: string[];
+    createdDirectories: string[];
+};
+export declare function planOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitPlan>;
+export declare function executeOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitResult>;

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

@@ -0,0 +1,122 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists } from '../../shared/fs.js';
+const README_BODY = `# OpenSpec — change proposals for this project
+
+This directory hosts the \`peaks openspec\` change proposal lifecycle:
+
+  render → validate → show → to-rd → ... → archive
+
+Each in-flight proposal lives in \`changes/<id>/\` and contains:
+
+- \`proposal.md\`  — why, what, non-goals, impact
+- \`tasks.md\`     — concrete slices and commit boundaries (consumed by peaks-sc)
+- \`design.md\`   — optional, for non-trivial designs
+- \`specs/\`       — optional, delta-style spec changes (## ADDED / ## MODIFIED / ## REMOVED)
+- \`*.md\`         — any additional narrative the change needs
+
+When a change ships, \`peaks openspec archive <id> --apply\` moves it into
+\`changes/archive/<id>/\`. The archive is the historical record of what
+landed and why.
+
+To scaffold a fresh change in this project:
+
+  peaks openspec render --request <path-to-render-request.json> --apply
+
+For the full lifecycle see \`peaks openspec --help\` and the
+peaks-clause-code skill family.
+`;
+const CHANGES_INDEX_HEADER = `# OpenSpec — change log
+
+This file is the human-readable index of every change that has shipped in
+this project. New entries are added by \`peaks openspec archive\` (when
+\`.apply\` is used); do not hand-edit.
+
+| Date | Change | Status |
+|------|--------|--------|
+`;
+function renderReadme() {
+    return README_BODY;
+}
+function renderChangesIndex() {
+    return CHANGES_INDEX_HEADER;
+}
+function buildPlan(projectRoot, apply) {
+    const openspecRoot = join(projectRoot, 'openspec');
+    const changesRoot = join(openspecRoot, 'changes');
+    const archiveRoot = join(changesRoot, 'archive');
+    const plannedWrites = [
+        { path: openspecRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: changesRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: archiveRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: join(openspecRoot, 'README.md'), kind: 'file', bytes: 0, content: renderReadme() },
+        { path: join(openspecRoot, 'CHANGES.md'), kind: 'file', bytes: 0, content: renderChangesIndex() }
+    ];
+    // Stamp byte counts now that content is finalised.
+    for (const write of plannedWrites) {
+        if (write.kind === 'file') {
+            write.bytes = Buffer.byteLength(write.content, 'utf8');
+        }
+    }
+    return {
+        apply,
+        projectRoot,
+        openspecRoot,
+        plannedWrites,
+        alreadyInitialized: false,
+        existingFiles: []
+    };
+}
+export async function planOpenSpecInit(options) {
+    const openspecRoot = join(options.projectRoot, 'openspec');
+    const plan = buildPlan(options.projectRoot, options.apply ?? false);
+    if (await isDirectory(openspecRoot)) {
+        // Already initialised. Report the existing files so the user can audit
+        // before re-running with --apply. We never overwrite an existing
+        // openspec/ — that is a destructive action and out of scope for init.
+        const existing = [];
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'file' && (await pathExists(write.path))) {
+                existing.push(write.path);
+            }
+        }
+        // Pre-compute which directory writes to keep (those whose target does
+        // not exist yet). .filter cannot be async, so resolve the boolean
+        // set up front.
+        const directoryKeep = new Set();
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory' && !(await isDirectory(write.path))) {
+                directoryKeep.add(write.path);
+            }
+        }
+        plan.plannedWrites = plan.plannedWrites.filter((write) => {
+            if (write.kind === 'directory')
+                return directoryKeep.has(write.path);
+            return !existing.includes(write.path);
+        });
+        plan.alreadyInitialized = existing.length > 0 || (await isDirectory(join(openspecRoot, 'changes')));
+        plan.existingFiles = existing;
+    }
+    return plan;
+}
+export async function executeOpenSpecInit(options) {
+    const plan = await planOpenSpecInit(options);
+    const writtenFiles = [];
+    const createdDirectories = [];
+    if (plan.apply && !plan.alreadyInitialized) {
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory') {
+                if (!(await isDirectory(write.path))) {
+                    await mkdir(write.path, { recursive: true });
+                    createdDirectories.push(write.path);
+                }
+                continue;
+            }
+            if (write.content.length === 0)
+                continue;
+            await writeFile(write.path, write.content, 'utf8');
+            writtenFiles.push(write.path);
+        }
+    }
+    return { ...plan, writtenFiles, createdDirectories };
+}

package/dist/src/services/openspec/openspec-propose-from-doctor-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * openspec-propose-from-doctor-service (Slice L3.3) — generates a draft
+ * OpenSpec change record (proposal.md) from a doctor CRITICAL finding.
+ *
+ * Per L1+L2+L3 redesign §5.4: "CRITICAL → proposal 草稿生成". The doctor
+ * scans the project for issues; when a CRITICAL finding is surfaced,
+ * peaks-cli generates a draft `openspec/changes/<id>/proposal.md` so the
+ * LLM doesn't have to start from scratch.
+ *
+ * The draft proposal is INFORMATIONAL — it requires the LLM to review +
+ * edit before `peaks openspec validate` will accept it.
+ */
+export interface DoctorFinding {
+    readonly id: string;
+    readonly rule: string;
+    readonly detail: string;
+    readonly severity: 'pass' | 'warn' | 'fail';
+}
+export interface ProposeFromDoctorInput {
+    readonly projectRoot: string;
+    readonly finding: DoctorFinding;
+    /** Optional clock for testability. */
+    readonly clock?: () => string;
+}
+export interface ProposeFromDoctorResult {
+    readonly changeId: string;
+    readonly changeDir: string;
+    readonly proposalPath: string;
+    readonly created: boolean;
+}
+export declare function proposeFromDoctor(input: ProposeFromDoctorInput): ProposeFromDoctorResult;