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

package/dist/services/observability/jsonl-store.d.ts

@@ -0,0 +1,59 @@
+/**
+ * JSONL append-only store for observability events.
+ *
+ * Slice A of v2.11.1 (slice topology observability). Pure file I/O —
+ * no schema knowledge lives here. Schema/validation lives in
+ * `observability-service.ts`.
+ *
+ * Layout: `.peaks/_runtime/<sessionId>/metrics/slices.jsonl` — one file
+ * per session, append-only. Mtime-based cross-session prune keeps at
+ * most `MAX_METRICS_FILES` files in the repo (mirrors the
+ * `peaks session checkpoint` contract).
+ *
+ * Write path is fire-and-forget: errors (disk full, permission
+ * denied, ENOENT mid-write) are swallowed silently per PRD Q4
+ * (full-auto must never fail-loud on observability).
+ */
+export declare const METRICS_DIR = "metrics";
+export declare const METRICS_FILENAME = "slices.jsonl";
+export declare const MAX_METRICS_FILES = 10;
+/** Absolute path to a session's metrics JSONL file. */
+export declare function metricsFilePath(projectRoot: string, sessionId: string): string;
+/** Absolute path to a session's metrics directory. */
+export declare function metricsDirPath(projectRoot: string, sessionId: string): string;
+/**
+ * Append one line to the session's metrics JSONL file. Creates the
+ * directory tree on demand. Returns true on success, false on any
+ * error (the caller MUST treat false as "drop silently" per Q4).
+ */
+export declare function appendMetricLine(projectRoot: string, sessionId: string, line: string): boolean;
+/**
+ * Read all non-empty lines from a session's metrics JSONL file.
+ * Returns [] when the file does not exist. Does NOT parse — callers
+ * decide what counts as valid (see `observability-service.ts`
+ * `readObservabilityEvents` for the schema-aware reader).
+ */
+export declare function readMetricLines(projectRoot: string, sessionId: string): string[];
+export type SessionMetricsEntry = {
+    sessionId: string;
+    mtimeMs: number;
+    path: string;
+};
+/**
+ * List every session that currently has a metrics JSONL on disk,
+ * paired with its mtime. Ordered by sessionId for determinism; the
+ * caller decides mtime ordering (see `pruneMetricsFiles`).
+ */
+export declare function listSessionDirsWithMetrics(projectRoot: string): SessionMetricsEntry[];
+/**
+ * Prune the metrics files across all sessions, retaining at most
+ * `MAX_METRICS_FILES` by mtime (newest kept). Returns the list of
+ * removed absolute paths. Best-effort: a failed removal is silently
+ * skipped (matches Q4 fire-and-forget contract).
+ */
+export declare function pruneMetricsFiles(projectRoot: string): string[];
+export declare const JSONL_STORE_CONSTANTS: {
+    readonly METRICS_DIR: "metrics";
+    readonly METRICS_FILENAME: "slices.jsonl";
+    readonly MAX_METRICS_FILES: 10;
+};

package/dist/services/observability/jsonl-store.js

@@ -0,0 +1,120 @@
+/**
+ * JSONL append-only store for observability events.
+ *
+ * Slice A of v2.11.1 (slice topology observability). Pure file I/O —
+ * no schema knowledge lives here. Schema/validation lives in
+ * `observability-service.ts`.
+ *
+ * Layout: `.peaks/_runtime/<sessionId>/metrics/slices.jsonl` — one file
+ * per session, append-only. Mtime-based cross-session prune keeps at
+ * most `MAX_METRICS_FILES` files in the repo (mirrors the
+ * `peaks session checkpoint` contract).
+ *
+ * Write path is fire-and-forget: errors (disk full, permission
+ * denied, ENOENT mid-write) are swallowed silently per PRD Q4
+ * (full-auto must never fail-loud on observability).
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+export const METRICS_DIR = 'metrics';
+export const METRICS_FILENAME = 'slices.jsonl';
+export const MAX_METRICS_FILES = 10;
+/** Absolute path to a session's metrics JSONL file. */
+export function metricsFilePath(projectRoot, sessionId) {
+    return join(getSessionDir(projectRoot, sessionId), METRICS_DIR, METRICS_FILENAME);
+}
+/** Absolute path to a session's metrics directory. */
+export function metricsDirPath(projectRoot, sessionId) {
+    return join(getSessionDir(projectRoot, sessionId), METRICS_DIR);
+}
+/**
+ * Append one line to the session's metrics JSONL file. Creates the
+ * directory tree on demand. Returns true on success, false on any
+ * error (the caller MUST treat false as "drop silently" per Q4).
+ */
+export function appendMetricLine(projectRoot, sessionId, line) {
+    try {
+        const dir = metricsDirPath(projectRoot, sessionId);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        appendFileSync(metricsFilePath(projectRoot, sessionId), line + '\n', 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read all non-empty lines from a session's metrics JSONL file.
+ * Returns [] when the file does not exist. Does NOT parse — callers
+ * decide what counts as valid (see `observability-service.ts`
+ * `readObservabilityEvents` for the schema-aware reader).
+ */
+export function readMetricLines(projectRoot, sessionId) {
+    const path = metricsFilePath(projectRoot, sessionId);
+    if (!existsSync(path)) {
+        return [];
+    }
+    const raw = readFileSync(path, 'utf8');
+    return raw.split(/\r?\n/).filter((line) => line.length > 0);
+}
+/**
+ * List every session that currently has a metrics JSONL on disk,
+ * paired with its mtime. Ordered by sessionId for determinism; the
+ * caller decides mtime ordering (see `pruneMetricsFiles`).
+ */
+export function listSessionDirsWithMetrics(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
+    if (!existsSync(runtimeRoot)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of readdirSync(runtimeRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const path = metricsFilePath(projectRoot, entry.name);
+        if (!existsSync(path)) {
+            continue;
+        }
+        out.push({
+            sessionId: entry.name,
+            mtimeMs: statSync(path).mtimeMs,
+            path
+        });
+    }
+    out.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+    return out;
+}
+/**
+ * Prune the metrics files across all sessions, retaining at most
+ * `MAX_METRICS_FILES` by mtime (newest kept). Returns the list of
+ * removed absolute paths. Best-effort: a failed removal is silently
+ * skipped (matches Q4 fire-and-forget contract).
+ */
+export function pruneMetricsFiles(projectRoot) {
+    const all = listSessionDirsWithMetrics(projectRoot);
+    if (all.length <= MAX_METRICS_FILES) {
+        return [];
+    }
+    all.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const toRemove = all.slice(MAX_METRICS_FILES);
+    const removed = [];
+    for (const { path } of toRemove) {
+        try {
+            rmSync(path, { force: true });
+            removed.push(path);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // best-effort: do not throw out of prune
+        }
+    }
+    return removed;
+}
+export const JSONL_STORE_CONSTANTS = {
+    METRICS_DIR,
+    METRICS_FILENAME,
+    MAX_METRICS_FILES
+};

package/dist/services/observability/observability-service.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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';
+export declare const OBSERVABILITY_SCHEMA_VERSION: 1;
+export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"];
+export type ObservabilityCategory = typeof OBSERVABILITY_CATEGORIES[number];
+export declare const OBSERVABILITY_SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
+export type ObservabilitySubagentRole = typeof OBSERVABILITY_SUBAGENT_ROLES[number];
+export declare const ObservabilityEventSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    ts: z.ZodString;
+    sessionId: z.ZodString;
+    category: z.ZodEnum<["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"]>;
+    sliceRid: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"]>>;
+    detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    schemaVersion: 1;
+    ts: string;
+    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact";
+    detail: Record<string, unknown>;
+    role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
+    sliceRid?: string | undefined;
+}, {
+    sessionId: string;
+    schemaVersion: 1;
+    ts: string;
+    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact";
+    detail: Record<string, unknown>;
+    role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
+    sliceRid?: string | undefined;
+}>;
+export type ObservabilityEvent = z.infer<typeof ObservabilityEventSchema>;
+export type EmitOptions = {
+    /** Absolute path to the project root (where `.peaks/_runtime/` lives). */
+    projectRoot: string;
+};
+export type EmitFailureReason = 'invalid-schema' | 'write-failed';
+export type EmitResult = {
+    /** True when the JSONL line was appended; false on any error path. */
+    written: boolean;
+    /** Absolute path to the metrics file the event was written to (or would be). */
+    path: string;
+    /** Set only when `written` is false. */
+    reason?: EmitFailureReason;
+};
+/**
+ * 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 declare function emitObservabilityEvent(event: ObservabilityEvent, options: EmitOptions): EmitResult;
+/**
+ * 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 declare function readObservabilityEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];
+/**
+ * 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 declare function isCurrentSchemaVersion(record: unknown): record is ObservabilityEvent;
+export declare const OBSERVABILITY_CONSTANTS: {
+    readonly SCHEMA_VERSION: 1;
+    readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"];
+    readonly SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
+};

package/dist/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/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/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/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/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/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>;