peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/cli/commands/lease-metrics-commands.js

@@ -0,0 +1,231 @@
+/**
+ * `peaks lease-metrics` — slice 2026-07-29-worktree-l2-extended Part 4.A + Part 5.
+ *
+ * Part 4.A: aggregate lease-kind observability events for one session,
+ * render per-kind counts + a 5-event chronological tail.
+ *
+ * Part 5 adds:
+ *   - `--rate`         : leak-rate computation (spawn - release - gc)
+ *                        plus lifetime stats (avg / p99) per lease id.
+ *   - `--all-sessions` : aggregate across every session under
+ *                        `.peaks/_runtime/<sid>/metrics/slices.jsonl`
+ *                        for the given project root. Useful for
+ *                        cross-session dashboards.
+ *
+ * Aggregation is pure (operates on already-read ObservabilityEvent[]);
+ * the IO layer is the JSONL read at the call site. The reader filters
+ * on `category === 'lease'`; the schema is the same as every other
+ * observability event (Part 4.A reused the existing schema v1).
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { readObservabilityEvents } from '../../services/observability/observability-service.js';
+const EMPTY_COUNTS = {
+    spawn: 0,
+    renew: 0,
+    release: 0,
+    gc: 0,
+    autoRelease: 0,
+    'autoRelease-failed': 0,
+    'autoRelease-skipped': 0
+};
+/** Compute per-kind counts + chronological tail from a list of events. */
+function aggregateLeaseEvents(leaseEvents) {
+    const counts = { ...EMPTY_COUNTS };
+    const recent = [];
+    for (const ev of leaseEvents) {
+        const detail = (ev.detail ?? {});
+        const kind = typeof detail['kind'] === 'string' ? detail['kind'] : 'unknown';
+        const leaseId = typeof detail['leaseId'] === 'string' ? detail['leaseId'] : '';
+        const rid = typeof detail['rid'] === 'string' ? detail['rid'] : null;
+        const reason = typeof detail['reason'] === 'string' ? detail['reason'] : null;
+        if (kind in counts) {
+            counts[kind] = (counts[kind] ?? 0) + 1;
+        }
+        recent.push({ ts: ev.ts, kind, leaseId, rid, reason });
+    }
+    recent.sort((a, b) => b.ts.localeCompare(a.ts));
+    return { counts: counts, tail: recent.slice(0, 5) };
+}
+export function recomputeRate(leaseEvents) {
+    // Count per-kind in one pass.
+    const counts = { ...EMPTY_COUNTS };
+    for (const ev of leaseEvents) {
+        const detail = (ev.detail ?? {});
+        const kind = typeof detail['kind'] === 'string' ? detail['kind'] : 'unknown';
+        if (kind in counts) {
+            counts[kind] = (counts[kind] ?? 0) + 1;
+        }
+    }
+    const totalSpawn = counts['spawn'] ?? 0;
+    const totalRelease = (counts['release'] ?? 0) + (counts['gc'] ?? 0) + (counts['autoRelease'] ?? 0);
+    const estimatedActive = Math.max(0, totalSpawn - totalRelease);
+    const estimatedLeaked = Math.max(0, estimatedActive - (counts['autoRelease-failed'] ?? 0));
+    // Pair each lease id: first spawn → first terminal.
+    const firstSpawn = new Map();
+    const firstTerminal = new Map();
+    const tsOf = (ev) => Date.parse(ev.ts);
+    const leaseIdOf = (ev) => {
+        const d = (ev.detail ?? {});
+        return typeof d['leaseId'] === 'string' ? d['leaseId'] : '';
+    };
+    const kindOf = (ev) => {
+        const d = (ev.detail ?? {});
+        return typeof d['kind'] === 'string' ? d['kind'] : 'unknown';
+    };
+    for (const ev of leaseEvents) {
+        const id = leaseIdOf(ev);
+        if (id === '')
+            continue;
+        const t = tsOf(ev);
+        const k = kindOf(ev);
+        if (k === 'spawn' && !firstSpawn.has(id)) {
+            firstSpawn.set(id, t);
+        }
+        else if (k === 'release' || k === 'gc' || k === 'autoRelease' || k === 'autoRelease-failed') {
+            if (!firstTerminal.has(id))
+                firstTerminal.set(id, t);
+        }
+    }
+    const lifetimes = [];
+    for (const [id, start] of firstSpawn) {
+        const end = firstTerminal.get(id);
+        if (end === undefined)
+            continue;
+        const dt = end - start;
+        if (dt >= 0)
+            lifetimes.push(dt);
+    }
+    lifetimes.sort((a, b) => a - b);
+    const avg = lifetimes.length === 0 ? null : Math.round(lifetimes.reduce((s, v) => s + v, 0) / lifetimes.length);
+    const p99 = lifetimes.length === 0
+        ? null
+        : lifetimes[Math.min(lifetimes.length - 1, Math.floor(lifetimes.length * 0.99))] ?? null;
+    return {
+        totalSpawn,
+        totalTerminal: totalRelease,
+        estimatedActive,
+        estimatedLeaked,
+        completedLifetimes: lifetimes.length,
+        avgLifetimeMs: avg,
+        p99LifetimeMs: p99
+    };
+}
+/**
+ * Part 5: enumerate every session under `.peaks/_runtime/` for a
+ * project root and aggregate their lease events. Sessions without
+ * a `metrics/slices.jsonl` are skipped silently (a clean project
+ * has no lease events to report; that's not an error).
+ */
+export function readAllSessionLeaseEvents(projectRoot) {
+    const runtimeDir = join(projectRoot, '.peaks', '_runtime');
+    if (!existsSync(runtimeDir))
+        return { sessions: [], missingSessions: 0 };
+    let entries;
+    try {
+        entries = readdirSync(runtimeDir);
+    }
+    catch {
+        return { sessions: [], missingSessions: 0 };
+    }
+    const sessions = [];
+    let missing = 0;
+    for (const sid of entries) {
+        const sessionDir = join(runtimeDir, sid);
+        try {
+            if (!statSync(sessionDir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        try {
+            const all = readObservabilityEvents(projectRoot, sid);
+            const leaseEvents = all.filter((e) => e.category === 'lease');
+            if (leaseEvents.length === 0) {
+                missing++;
+                continue;
+            }
+            sessions.push({ sessionId: sid, events: leaseEvents });
+        }
+        catch {
+            missing++;
+        }
+    }
+    return { sessions, missingSessions: missing };
+}
+export function registerLeaseMetricsCommand(parent, io) {
+    addJsonOption(parent
+        .command('lease-metrics')
+        .description('Aggregate lease-kind observability events. Default: per-kind counts + 5-event tail for the current session. --rate: leak rate + lifetime stats. --all-sessions: aggregate across every session under .peaks/_runtime/.')
+        .option('--session <sid>', 'override session id (default: read .peaks/_runtime/session.json)')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')
+        .option('--rate', 'compute leak rate (spawn - terminal) + lifetime stats (avg / p99)')
+        .option('--all-sessions', 'aggregate across every session under .peaks/_runtime/ (ignores --session)')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const allSessions = options.allSessions === true;
+            const showRate = options.rate === true;
+            if (allSessions) {
+                // Aggregate across every session.
+                const { sessions, missingSessions } = readAllSessionLeaseEvents(projectRoot);
+                const allEvents = sessions.flatMap((s) => s.events);
+                const { counts, tail } = aggregateLeaseEvents(allEvents);
+                const rate = showRate ? recomputeRate(allEvents) : null;
+                const envelope = {
+                    mode: 'all-sessions',
+                    projectRoot,
+                    sessionCount: sessions.length,
+                    missingSessions,
+                    sessions: sessions.map((s) => ({ sessionId: s.sessionId, leaseEvents: s.events.length })),
+                    totalEvents: allEvents.length,
+                    counts,
+                    tail
+                };
+                if (rate !== null)
+                    envelope['rate'] = rate;
+                printResult(io, ok('lease.metrics', envelope, [], [
+                    `${sessions.length} session(s) reported lease events; ${missingSessions} session(s) had no events.`,
+                    showRate && rate !== null
+                        ? `${rate.estimatedActive} estimated active, ${rate.estimatedLeaked} estimated leaked across sessions.`
+                        : 'Pass --rate to see leak-rate + lifetime stats.'
+                ]), options.json);
+                return;
+            }
+            // Single-session path (the Part 4.A default).
+            const sessionId = options.session ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+            const allEvents = readObservabilityEvents(projectRoot, sessionId);
+            const leaseEvents = allEvents.filter((e) => e.category === 'lease');
+            const { counts, tail } = aggregateLeaseEvents(leaseEvents);
+            const rate = showRate ? recomputeRate(leaseEvents) : null;
+            const envelope = {
+                mode: 'single-session',
+                sessionId,
+                projectRoot,
+                totalEvents: allEvents.length,
+                leaseEvents: leaseEvents.length,
+                counts,
+                tail
+            };
+            if (rate !== null)
+                envelope['rate'] = rate;
+            printResult(io, ok('lease.metrics', envelope, [], [
+                `${leaseEvents.length} lease-kind events recorded for session ${sessionId}.`,
+                showRate && rate !== null
+                    ? `${rate.estimatedActive} estimated active, ${rate.estimatedLeaked} estimated leaked.`
+                    : 'Run `peaks audit metrics --project .` for the full observability dashboard, or pass --rate / --all-sessions.'
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('lease.metrics', 'METRICS_READ_FAILED', err instanceof Error ? err.message : String(err), { sessionId: options.session }, [
+                'Verify the project root + session id are correct.',
+                'For the full observability stream, run `peaks audit metrics --project .`.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/lease-stats-commands.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `peaks lease-stats` — slice 2026-07-29-worktree-l2-extended Part 6.
+ *
+ * Single top-level command that aggregates lease observability for
+ * the whole project root and returns a summary envelope suitable
+ * for dashboards / pipelines:
+ *
+ *   - per-kind counts (same as peaks lease-metrics)
+ *   - leak rate (estimatedActive / estimatedLeaked)
+ *   - per-rid breakdown: which request ids are still "alive"
+ *     (i.e. the rid has a spawn event with no terminal)
+ *   - per-role breakdown: lease spawns split by role
+ *   - per-isolation breakdown: 'worktree' | 'container' | 'none'
+ *     (Part 8 adds 'container')
+ *
+ * The per-rid / per-role / per-isolation breakdowns use the
+ * `rid` / `role` fields on the observability detail (Part 4.A
+ * emitter passes these). The 'isolation' field is read off the
+ * underlying dispatch record via the readObservabilityEvents
+ * reader — but the events themselves don't carry isolation
+ * mode. To get that, we walk the dispatch records (not events)
+ * and join on the dispatch's `isolation` field. This is a
+ * cross-file read but the operation is cheap (each session's
+ * dispatch records are a small JSON set).
+ *
+ * Why this is a separate command from `peaks lease-metrics`:
+ * `lease-metrics` answers "what events did I record?" (event
+ * stream semantics). `lease-stats` answers "what's the project
+ * status right now?" (state semantics). The two compose:
+ * `lease-metrics --all-sessions` is the input, `lease-stats`
+ * is the answer.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type RateStats } from './lease-metrics-commands.js';
+type RidCount = {
+    rid: string;
+    count: number;
+};
+type RoleCount = {
+    role: string;
+    count: number;
+};
+type IsolationCount = {
+    isolation: 'worktree' | 'container' | 'none';
+    count: number;
+};
+type LeaseStats = {
+    readonly projectRoot: string;
+    readonly sessionCount: number;
+    readonly totalLeaseEvents: number;
+    readonly rate: RateStats;
+    readonly perRid: ReadonlyArray<RidCount>;
+    readonly perRole: ReadonlyArray<RoleCount>;
+    readonly perIsolation: ReadonlyArray<IsolationCount>;
+};
+export declare function computeLeaseStats(args: {
+    projectRoot: string;
+    eventsBySession: ReadonlyArray<{
+        sessionId: string;
+        events: ReadonlyArray<unknown>;
+    }>;
+}): LeaseStats;
+export declare function registerLeaseStatsCommand(parent: Command, io: ProgramIO): void;
+export {};

package/dist/cli/commands/lease-stats-commands.js

@@ -0,0 +1,107 @@
+/**
+ * `peaks lease-stats` — slice 2026-07-29-worktree-l2-extended Part 6.
+ *
+ * Single top-level command that aggregates lease observability for
+ * the whole project root and returns a summary envelope suitable
+ * for dashboards / pipelines:
+ *
+ *   - per-kind counts (same as peaks lease-metrics)
+ *   - leak rate (estimatedActive / estimatedLeaked)
+ *   - per-rid breakdown: which request ids are still "alive"
+ *     (i.e. the rid has a spawn event with no terminal)
+ *   - per-role breakdown: lease spawns split by role
+ *   - per-isolation breakdown: 'worktree' | 'container' | 'none'
+ *     (Part 8 adds 'container')
+ *
+ * The per-rid / per-role / per-isolation breakdowns use the
+ * `rid` / `role` fields on the observability detail (Part 4.A
+ * emitter passes these). The 'isolation' field is read off the
+ * underlying dispatch record via the readObservabilityEvents
+ * reader — but the events themselves don't carry isolation
+ * mode. To get that, we walk the dispatch records (not events)
+ * and join on the dispatch's `isolation` field. This is a
+ * cross-file read but the operation is cheap (each session's
+ * dispatch records are a small JSON set).
+ *
+ * Why this is a separate command from `peaks lease-metrics`:
+ * `lease-metrics` answers "what events did I record?" (event
+ * stream semantics). `lease-stats` answers "what's the project
+ * status right now?" (state semantics). The two compose:
+ * `lease-metrics --all-sessions` is the input, `lease-stats`
+ * is the answer.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { readAllSessionLeaseEvents, recomputeRate } from './lease-metrics-commands.js';
+function tallyByField(events, field) {
+    const out = new Map();
+    for (const ev of events) {
+        const v = ev.detail[field];
+        if (typeof v !== 'string' || v.length === 0)
+            continue;
+        out.set(v, (out.get(v) ?? 0) + 1);
+    }
+    return out;
+}
+export function computeLeaseStats(args) {
+    // The events pass through `tallyByField` (which only reads
+    // `detail`) and through `recomputeRate` (which reads `detail` +
+    // `ts`). The interface is widened to `unknown` here so the
+    // caller can pass any observability-event-shaped object;
+    // `recomputeRate`'s parameter type is the canonical
+    // `ObservabilityEvent[]`, so we cast at the boundary.
+    const allEvents = args.eventsBySession.flatMap((s) => s.events);
+    const rate = recomputeRate(allEvents);
+    const ridTally = tallyByField(allEvents, 'rid');
+    const roleTally = tallyByField(allEvents, 'role');
+    const isoTally = new Map();
+    for (const ev of allEvents) {
+        const detail = ev.detail;
+        const iso = typeof detail['isolation'] === 'string' ? detail['isolation'] : 'none';
+        isoTally.set(iso, (isoTally.get(iso) ?? 0) + 1);
+    }
+    return {
+        projectRoot: args.projectRoot,
+        sessionCount: args.eventsBySession.length,
+        totalLeaseEvents: allEvents.length,
+        rate,
+        perRid: Array.from(ridTally.entries())
+            .map(([rid, count]) => ({ rid, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 20),
+        perRole: Array.from(roleTally.entries())
+            .map(([role, count]) => ({ role, count }))
+            .sort((a, b) => b.count - a.count),
+        perIsolation: Array.from(isoTally.entries())
+            .map(([isolation, count]) => ({ isolation: isolation, count }))
+            .sort((a, b) => b.count - a.count)
+    };
+}
+export function registerLeaseStatsCommand(parent, io) {
+    addJsonOption(parent
+        .command('lease-stats')
+        .description('Project-wide lease summary: counts, leak rate, per-rid / per-role / per-isolation breakdown. Always aggregates across every session in the project root.')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const { sessions } = readAllSessionLeaseEvents(projectRoot);
+            const eventsBySession = sessions.map((s) => ({
+                sessionId: s.sessionId,
+                events: s.events.map((e) => ({ detail: (e.detail ?? {}) }))
+            }));
+            const stats = computeLeaseStats({ projectRoot, eventsBySession });
+            printResult(io, ok('lease.stats', stats, [], [
+                `${stats.totalLeaseEvents} lease events across ${stats.sessionCount} session(s); ${stats.rate.estimatedActive} estimated active, ${stats.rate.estimatedLeaked} estimated leaked.`,
+                stats.perRid.length > 0 ? `Top rid: ${stats.perRid[0]?.rid} (${stats.perRid[0]?.count} events).` : '',
+                'Pipe to `jq` or paste into a dashboard for visual rendering.'
+            ].filter(Boolean)), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('lease.stats', 'STATS_READ_FAILED', err instanceof Error ? err.message : String(err), { projectRoot: options.project }, [
+                'Verify the project root is correct.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/legacy-commands.js

@@ -8,7 +8,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { detectLegacy } from '../../services/legacy/legacy-detector.js';
-import { ok } from '../../shared/result.js';
+import { ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerLegacyCommands(program, io) {
     addJsonOption(program

package/dist/cli/commands/log-commands.js

@@ -16,7 +16,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { tailLog, listLogFiles } from '../../services/log/log-commands-service.js';
 import { getErrorMessage, printResult, addJsonOption } from '../cli-helpers.js';
-import { ok, fail } from '../../shared/result.js';
+import { ok, fail } from 'peaks-loop-shared/result';
 export function registerLogCommands(program, io) {
     const log = program
         .command('log')

package/dist/cli/commands/loop-commands.js

@@ -25,7 +25,7 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { openStateDb } from '../../services/skillhub/sqlite-store.js';
 import { writeBundle, BundleNotShareableError, BundleAssetNotFoundError, } from '../../services/share/bundle-writer.js';

package/dist/cli/commands/loop-eval-commands.js

@@ -7,7 +7,7 @@ import { runMonotonicCheck, resolveMonotonicContext } from '../../services/loop/
 import { resolveLoopSpec, persistSpec, buildSpec, lintLoopSpec, lintSpecFile, specPath, MONOTONIC_TERMINATION, DEFAULT_MAX_CYCLES } from '../../services/loop/spec-service.js';
 import { runLoop, resolveRunContext } from '../../services/loop/run-driver.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 const VALID_EVALUATORS = new Set([
     'karpathy',

package/dist/cli/commands/memory-commands.js

@@ -2,7 +2,7 @@ import { findProjectRoot } from '../../services/config/config-safety.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { loadMemoryIndex, searchMemoryWithResults } from '../../services/memory/memory-search-service.js';
 import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult } from '../cli-helpers.js';
 import { join } from 'node:path';
 const VALID_KINDS = [

package/dist/cli/commands/migrate-1-4-1-command.js

@@ -6,7 +6,7 @@
  * `.peaks/_runtime/<sid>/<role>/<file>.md` path. Default is dry-run; pass
  * `--apply` to actually `rename` the files and remove emptied legacy dirs.
  */
-import { ok, fail } from '../../shared/result.js';
+import { ok, fail } from 'peaks-loop-shared/result';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { addJsonOption } from '../cli-helpers.js';
 import { planMigrate1_4_1, applyMigrate1_4_1 } from '../../services/workspace/migrate-1-4-1-service.js';

package/dist/cli/commands/migrate-v2-10-to-v2-11-command.js

@@ -18,7 +18,7 @@
 import { addJsonOption } from '../cli-helpers.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { planV2ToV11Migration, applyV2ToV11Migration, dryRunV2ToV11Migration } from '../../services/migration/v2-10-to-v2-11-service.js';
-import { ok, fail } from '../../shared/result.js';
+import { ok, fail } from 'peaks-loop-shared/result';
 export function registerMigrateV2ToV11Command(workspace, io) {
     addJsonOption(workspace
         .command('migrate-v2-10-to-v2-11')

package/dist/cli/commands/mut-commands.d.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { type StrykerInvoker } from '../../services/mut/mut-runner.js';
+import { type StrykerInvoker } from 'peaks-loop-mut';
 import type { ProgramIO } from '../cli-helpers.js';
 export interface MutCommandsOptions {
     readonly invokeStryker: StrykerInvoker;

package/dist/cli/commands/mut-commands.js

@@ -15,11 +15,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { Command } from 'commander';
-import { scanAssertions } from '../../services/mut/assert-scanner.js';
-import { runMutation } from '../../services/mut/mut-runner.js';
-import { buildMutReport } from '../../services/mut/report-builder.js';
-import { createProductionStrykerInvoker } from '../../services/mut/production-stryker.js';
-import { MutReportSchema } from '../../services/mut/types.js';
+import { scanAssertions, runMutation, buildMutReport, createProductionStrykerInvoker, MutReportSchema, } from 'peaks-loop-mut';
 /**
  * Pure helper: a stub AssertionsReport used when only Stryker ran.
  * The mutants-only path does NOT touch the AST scanner; we still need

package/dist/cli/commands/observability-commands.js

@@ -19,7 +19,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { getSessionIdCanonical } from '../../services/session/session-manager.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { aggregateFanout, aggregateRepairCycles, aggregateSlices, aggregateStatus, filterByPeriod, periodStartIso, readAllSessionEvents, readSessionEvents } from '../../services/observability/aggregation.js';

package/dist/cli/commands/openspec-commands.js

@@ -3,11 +3,11 @@ import { loadOpenSpecChange, scanOpenSpec } from '../../services/openspec/opensp
 import { projectOpenSpecToRdInput } from '../../services/openspec/openspec-bridge-service.js';
 import { renderOpenSpecChange } from '../../services/openspec/openspec-render-service.js';
 import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
-import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
+import { archiveOpenSpecChange, OpenSpecArchiveError } from '../../services/openspec/openspec-archive-service.js';
 import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
 import { proposeFromDoctor } from '../../services/openspec/openspec-propose-from-doctor-service.js';
-import { runDoctor } from '../../services/doctor/doctor-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { runDoctor } from '../../services/doctor/index.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function resolveScanOptions(project) {
     if (project === undefined) {
@@ -143,6 +143,8 @@ export function registerOpenSpecCommands(program, io) {
         .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
         .option('--project <path>', 'project root containing an openspec/ directory')
         .option('--apply', 'actually move the change directory')
+        .option('--force', 'bypass the Pre-cond 2 Coverage Evidence gate (use only after confirming the gap is acceptable for this archive)')
+        .option('--coverage-summary <path>', 'override coverage-summary.json discovery (Fix-6B). Default: <projectRoot>/coverage/coverage-summary.json, then <projectRoot>/openspec/coverage-summary.json')
         .option('--archive-dir <name>', 'archive subdirectory name (default: archive)')).action(async (changeId, options) => {
         try {
             const scan = resolveScanOptions(options.project);
@@ -153,6 +155,12 @@ export function registerOpenSpecCommands(program, io) {
             if (options.apply === true) {
                 archiveOptions.apply = true;
             }
+            if (options.force === true) {
+                archiveOptions.force = true;
+            }
+            if (options.coverageSummary !== undefined) {
+                archiveOptions.coverageSummaryPath = options.coverageSummary;
+            }
             if (options.archiveDir !== undefined) {
                 archiveOptions.archiveDirName = options.archiveDir;
             }
@@ -162,9 +170,21 @@ export function registerOpenSpecCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, ok('openspec.archive', result, [], result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
+            const warnings = [];
+            if (result.coverageGateBypassed === true) {
+                warnings.push('Coverage gate bypassed via --force; archived with at least one uncovered requirement.');
+            }
+            if (result.coverageMismatchBypassed === true) {
+                warnings.push('Coverage summary mismatch bypassed via --force; archived with at least one capability below 100%.');
+            }
+            printResult(io, ok('openspec.archive', result, warnings, result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
         }
         catch (error) {
+            if (error instanceof OpenSpecArchiveError) {
+                printResult(io, fail('openspec.archive', error.code, getErrorMessage(error), error.detail, nextActionsForArchiveError(error.code)), options.json);
+                process.exitCode = 1;
+                return;
+            }
             printResult(io, fail('openspec.archive', 'OPENSPEC_ARCHIVE_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
             process.exitCode = 1;
         }
@@ -235,3 +255,44 @@ export function registerOpenSpecCommands(program, io) {
         }
     });
 }
+/**
+ * Per-error-code remediation hints for the archive gate.
+ * Centralized here so the catch block stays readable and the next-actions
+ * can be reviewed in isolation.
+ */
+function nextActionsForArchiveError(code) {
+    switch (code) {
+        case 'OPENSPEC_COVERAGE_GATE_PARTIAL':
+            return [
+                'Update the Coverage Evidence table to mark each failing requirement as covered',
+                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
+            ];
+        case 'OPENSPEC_COVERAGE_GATE_FAILED':
+            return [
+                'Add the missing Coverage Evidence or Capability Mapping block to proposal.md (see error.message)',
+                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED':
+            return [
+                'Fix the proposal.md Coverage Evidence table — the heading exists but no parsable rows were found',
+                'Expected shape: | capability | requirement | status | testAnchor | with status in {covered, partial, uncovered}'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_MISSING':
+            return [
+                'Run `pnpm test:coverage` (which invokes scripts/coverage-c8.mjs) to generate coverage-summary.json',
+                'Or pass --coverage-summary <path> to point at an existing summary',
+                'Or re-run with --force to bypass the gate'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_STALE':
+            return [
+                'Re-run `pnpm test:coverage` to refresh coverage-summary.json',
+                'Or re-run with --force to bypass the gate after confirming the source delta is acceptable'
+            ];
+        case 'OPENSPEC_COVERAGE_EVIDENCE_MISMATCH':
+            return [
+                'Inspect error.detail.mismatches[] — each entry lists the failing capability, file, and actual pct',
+                'Close the coverage gap (add tests or update the Capability Mapping block in proposal.md)',
+                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
+            ];
+    }
+}

package/dist/cli/commands/perf-audit-commands.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
-import { detectPerfAudit, isPerfAuditEnvelope, runPerfAudit, } from '../../services/audit-independent/perf-audit-service.js';
+import { detectPerfAudit, isPerfAuditEnvelope, runPerfAudit, } from '../../services/audit-independent/index.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 function resolveEnvelope(envelopePath) {
     if (envelopePath === undefined || envelopePath === '-') {
         // Read from stdin
@@ -36,7 +36,7 @@ function readStdinSync() {
 }
 export function registerPerfAuditCommands(program, io) {
     const perfAudit = program
-        .command('perf-audit')
+        .command('perf-audit', { hidden: true })
         .description('Independent performance audit skill driver. Reads the immutable peaks-prd handoff (sha256-locked) + the project-level perf-template.md, then writes a structured perf-<rid>.md artifact. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 3). See skills/bee/peaks-perf-audit/SKILL.md for the full workflow.');
     addJsonOption(perfAudit
         .command('detect')

package/dist/cli/commands/perf-commands.js

@@ -1,5 +1,5 @@
 import { executePerfBaselineInit, resolveProjectRootFromCwd } from '../../services/perf/perf-baseline-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerPerfCommands(program, io) {
     const perf = program.command('perf').description('Manage performance baseline scaffolding for the RD stage');

package/dist/cli/commands/polyrepo-commands.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok, getErrorMessage } from '../../shared/result.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
 import { PolyrepoService } from '../../services/polyrepo/polyrepo-service.js';
 function parseChildren(raw) {
     if (raw === undefined || raw.length === 0)