peaks-loop 3.0.0

package/dist/src/cli/cli-helpers.js

@@ -0,0 +1,78 @@
+import { fail, getErrorMessage, ok, redactSensitiveErrorMessage } from '../shared/result.js';
+const MINIMAX_API_HOST = 'api.minimaxi.com';
+export function printResult(io, result, asJson = false) {
+    if (asJson) {
+        io.stdout(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.ok) {
+        io.stderr(`${result.code}: ${result.message}`);
+        for (const action of result.nextActions) {
+            io.stderr(`- ${action}`);
+        }
+        return;
+    }
+    io.stdout(JSON.stringify(result.data, null, 2));
+    for (const warning of result.warnings) {
+        io.stderr(`warning: ${warning}`);
+    }
+    for (const action of result.nextActions) {
+        io.stdout(`next: ${action}`);
+    }
+}
+export function addJsonOption(command) {
+    return command.option('--json', 'print machine-readable JSON envelope');
+}
+export function failUnsupportedNonDryRun(io, command, asJson) {
+    printResult(io, fail(command, 'UNSUPPORTED_NON_DRY_RUN', 'Only dry-run planning is supported', {}, ['Rerun with --dry-run or omit --no-dry-run']), asJson);
+    process.exitCode = 1;
+}
+export function isRecommendationWorkflow(value) {
+    return value === 'code-refactor' || value === 'product-refactor' || value === 'frontend-design';
+}
+export function isArtifactProvider(value) {
+    return value === 'github' || value === 'gitlab';
+}
+export function isArtifactSetupStep(value) {
+    return value === 'detect' || value === 'configure' || value === 'validate' || value === 'complete';
+}
+export function isArtifactRepoSegment(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
+}
+export function isMiniMaxHttpsUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && url.hostname === MINIMAX_API_HOST && url.username.length === 0 && url.password.length === 0 && url.search.length === 0 && url.hash.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseConfigLayer(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return value === 'user' || value === 'project' ? value : null;
+}
+export function printInvalidConfigLayer(io, command, asJson) {
+    printResult(io, fail(command, 'INVALID_CONFIG_LAYER', 'Config layer must be user or project', {}, ['Use --layer user or --layer project']), asJson);
+    process.exitCode = 1;
+}
+export function multipleOption(value, previous) {
+    return [...(previous || []), value];
+}
+export function summarizeMiniMaxSmokeResult(result) {
+    return { ...result, responseText: null, summary: null };
+}
+export function summarizeMiniMaxWorkerResult(result) {
+    const provider = summarizeMiniMaxSmokeResult(result.provider);
+    return {
+        ...result,
+        provider,
+        reviewHandoff: {
+            model: result.reviewHandoff.model,
+            prompt: '[redacted]'
+        }
+    };
+}
+export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/src/cli/commands/agent-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * peaks agent * CLI surface — Slice: ECC 64 agents soft-optional
+ * integration (per spec §7.2 line 818).
+ *
+ * Registers the new `peaks agent` top-level command with two
+ * subcommands:
+ *   - `peaks agent run <name> [--target <path>]`  — shell out to
+ *     `npx ecc agent run <name> --target <path> --json` when ECC
+ *     is installed; soft-fail with the 4-option install prompt
+ *     when it isn't.
+ *   - `peaks agent list`                          — emit the 12
+ *     canonical ECC agents (the wrapper hardcodes the
+ *     most-used subset; the full 64-agent list is
+ *     discoverable at runtime via `npx ecc agent list`).
+ *
+ * The wrapper service is `src/services/agent/ecc-agent-service.ts`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerAgentCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/agent-commands.js

@@ -0,0 +1,48 @@
+import { runEccAgent, validateEccAgent, CANONICAL_ECC_AGENTS, } from '../../services/agent/ecc-agent-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerAgentCommands(program, io) {
+    const agent = program
+        .command('agent')
+        .description('Run an ECC agent (soft-optional per spec §7.2). 64 agents are npm-installable via npx ecc; peaks-cli shells out when ECC is installed and soft-fails with a 4-option install prompt when it is not. Native peaks-cli diagnostics still run via `peaks doctor scan`.');
+    addJsonOption(agent
+        .command('run <name>')
+        .description(`Run an ECC agent by name (e.g. 'security-reviewer', 'code-reviewer'). The canonical subprocess is \`npx ecc agent run <name> --target <path> --json\`.`)
+        .option('--target <path>', 'project root or file to analyze (default: cwd)')
+        .option('--enable', 'enable the ECC subprocess for this call (overrides default-off; soft-fails with the 4-option install prompt when ECC is missing)')).action(async (name, options) => {
+        const validationError = validateEccAgent(name);
+        if (validationError !== null) {
+            printResult(io, fail('agent.run', 'INVALID_AGENT_NAME', validationError, { agent: name }, [
+                'Use `peaks agent list` to see the canonical 12 agents',
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const projectRoot = options.target ?? process.cwd();
+        try {
+            const result = runEccAgent({
+                agent: name,
+                projectRoot,
+                enableAgent: options.enable === true,
+            });
+            const data = { ...result, projectRoot };
+            const nextActions = [];
+            if (result.reason === 'flag-enabled-but-ecc-missing') {
+                nextActions.push('ECC not installed. Pick one of the four options below:', '  a) Install: run `npx ecc --help` to install, then re-run `peaks agent run`.', '  b) Skip this run: use the peaks-cli native diagnostic via `peaks doctor scan`.', '  c) Skip forever: run `peaks preferences set agentShieldEnabled false`.', '  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §7.2.');
+            }
+            const envelope = ok('agent.run', data, [...result.warnings], nextActions);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('agent.run', 'AGENT_RUN_FAILED', message, { agent: name, projectRoot, spawned: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(agent
+        .command('list')
+        .description(`List the 12 canonical ECC agents (peaks-cli ships a static subset; the full 64 are ECC-discovered).`)).action((options) => {
+        const envelope = ok('agent.list', { agents: CANONICAL_ECC_AGENTS.map((a) => ({ name: a.name, description: a.description })) }, [], ['Run any agent with: `peaks agent run <name> --target <path>`']);
+        printResult(io, envelope, options.json);
+    });
+}

package/dist/src/cli/commands/audit-commands.d.ts

@@ -0,0 +1,28 @@
+/**
+ * peaks audit * CLI surface — Slice L2.1 + L2.3 P2-a.
+ *
+ * Registers the new `peaks audit` top-level command with the
+ * `red-lines` (L2.1) and `static` (L2.3 P2-a) subcommands.
+ * Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
+ * we verified that no `peaks audit` top-level exists; this is the only
+ * file that owns the registration.
+ */
+import { Command } from 'commander';
+import { type AgentShieldState } from '../../services/audit/static-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+import type { RedLineAudit } from '../../services/audit/types.js';
+import type { AuditDecisionRecord } from '../../services/audit/decision-writer.js';
+export interface AuditGoalData {
+    readonly status: 'scaffold-only';
+    readonly serviceWired: true;
+    readonly providerBinding: 'pending-follow-up-slice';
+    readonly need: string;
+    readonly projectRoot: string;
+}
+export interface StaticAuditData {
+    readonly audit: RedLineAudit;
+    readonly agentShield: AgentShieldState;
+    /** Populated only when `--record` is passed. Persisted decision record path. */
+    readonly decision?: AuditDecisionRecord;
+}
+export declare function registerAuditCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,437 @@
+/**
+ * peaks audit * CLI surface — Slice L2.1 + L2.3 P2-a.
+ *
+ * Registers the new `peaks audit` top-level command with the
+ * `red-lines` (L2.1) and `static` (L2.3 P2-a) subcommands.
+ * Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first.md`
+ * we verified that no `peaks audit` top-level exists; this is the only
+ * file that owns the registration.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runRedLinesAudit } from '../../services/audit/red-lines-service.js';
+import { runStaticAudit } from '../../services/audit/static-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+import { writeAuditDecision } from '../../services/audit/decision-writer.js';
+import { computeProseRatio } from '../../services/audit/prose-ratio-calculator.js';
+import { writeMachineOutput, writeNarrative, writePrompt, } from '../../services/audit/artifact-writer.js';
+const SUPPORTED_ARTIFACT_KINDS = [
+    'decision',
+    'prompt',
+    'machine-output',
+    'narrative',
+];
+function isSupportedArtifactKind(value) {
+    return SUPPORTED_ARTIFACT_KINDS.includes(value);
+}
+/** Whitelist of supported `--llm-provider` values for `peaks audit goal`. */
+const SUPPORTED_LLM_PROVIDERS = ['stub'];
+function isSupportedLlmProvider(value) {
+    return SUPPORTED_LLM_PROVIDERS.includes(value);
+}
+function validateProjectRoot(projectArg) {
+    const projectRoot = resolve(projectArg);
+    if (!existsSync(projectRoot)) {
+        return { ok: false, code: 'PROJECT_NOT_FOUND', message: `project path does not exist: ${projectArg}` };
+    }
+    let stat;
+    try {
+        stat = statSync(projectRoot);
+    }
+    catch (error) {
+        return { ok: false, code: 'INVALID_PROJECT', message: getErrorMessage(error) };
+    }
+    if (!stat.isDirectory()) {
+        return { ok: false, code: 'INVALID_PROJECT', message: `project path is not a directory: ${projectArg}` };
+    }
+    return { ok: true, projectRoot };
+}
+export function registerAuditCommands(program, io) {
+    const audit = program
+        .command('audit')
+        .description('Audit a project for compliance with peaks-cli red lines (P0 / P1 / P2 tiers)');
+    addJsonOption(audit
+        .command('red-lines')
+        .description('Scan skills/, .claude/rules/, and openspec/changes/ for MANDATORY / BLOCKING / MUST NOT / RED LINE markers; classify each as cli-backed / partial / prose-only')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        const validation = validateProjectRoot(options.project);
+        if (!validation.ok) {
+            printResult(io, fail('audit.red-lines', validation.code, validation.message, { totalRedLines: 0, cliBacked: 0, partial: 0, proseOnly: 0, audit: [], enforcerFindings: [] }, ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = runRedLinesAudit({ projectRoot: validation.projectRoot });
+            const nextActions = [];
+            if (result.audit.proseOnly > 0) {
+                nextActions.push(`${result.audit.proseOnly} prose-only red lines remain. Plan P1/P2 enforcers in L2.2-L2.4.`);
+            }
+            if (result.audit.cliBacked > 0) {
+                nextActions.push(`${result.audit.cliBacked} red lines are now cli-backed. Re-run after each enforcer lands to track the prose-only ratio.`);
+            }
+            const envelope = ok('audit.red-lines', result.audit, result.warnings.map((w) => `${w.file}: ${w.message}`), nextActions);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            printResult(io, fail('audit.red-lines', 'SCANNER_FAILED', getErrorMessage(error), { totalRedLines: 0, cliBacked: 0, partial: 0, proseOnly: 0, audit: [], enforcerFindings: [] }, ['Inspect scanner logs and re-run with the same --project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // Slice #6 L2.3 P2-a: peaks audit static — soft-optional ECC
+    // AgentShell integration. Reads `.peaks/preferences.json`'s
+    // `agentShieldEnabled` flag (default false). The CLI flags
+    // `--enable-agent-shield` / `--disable-agent-shield` override
+    // the preference for a single call.
+    //
+    // Slice K1 (2.8.0): `--record` persists the audit snapshot as a
+    // project-memory decision at `.peaks/memory/audit-decisions/<slug>.md`.
+    // `--rid <id>` is an optional disambiguator for multiple audits on
+    // the same day (slug becomes `audit-decision-<date>-<rid>`).
+    // Per `peaks-cli-when-adding-a-new-subcommand-check-for-existing-top-level-first`
+    // and the dev-preference red line "Default-no on new CLI commands",
+    // we extend the existing command rather than register a new subcommand.
+    addJsonOption(audit
+        .command('static')
+        .description('Run the static audit (peaks-cli lint + optional ECC AgentShield subprocess). Per spec §5.3.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--enable-agent-shield', 'force-enable ECC AgentShield subprocess for this call (overrides preference)')
+        .option('--disable-agent-shield', 'force-disable ECC AgentShield subprocess for this call (overrides preference)')
+        .option('--record', 'persist the audit snapshot to .peaks/memory/audit-decisions/ as a project-memory decision')
+        .option('--rid <rid>', 'disambiguator for the decision record slug (used with --record; pairs multiple audits on the same day)')).action(async (options) => {
+        const validation = validateProjectRoot(options.project);
+        if (!validation.ok) {
+            printResult(io, fail('audit.static', validation.code, validation.message, emptyStaticAuditData(), ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // Resolve the flag override. `--enable-agent-shield` and
+        // `--disable-agent-shield` are mutually exclusive; we surface
+        // a 422 if both are passed.
+        if (options.enableAgentShield && options.disableAgentShield) {
+            printResult(io, fail('audit.static', 'FLAGS_CONFLICT', '`--enable-agent-shield` and `--disable-agent-shield` are mutually exclusive', emptyStaticAuditData(), ['Pass at most one of the two flags']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // Slice K1: `--rid` is meaningful only with `--record`. Surface a 422
+        // when the user passes `--rid` without `--record` so the CLI fails
+        // loudly rather than silently ignoring the request id.
+        if (options.rid && !options.record) {
+            printResult(io, fail('audit.static', 'FLAGS_CONFLICT', '`--rid` requires `--record` (decision slug disambiguator has no effect without persistence)', emptyStaticAuditData(), ['Pass `--record` together with `--rid <id>`, or omit `--rid`']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = runStaticAudit({
+                projectRoot: validation.projectRoot,
+                ...(options.enableAgentShield
+                    ? { enableAgentShield: true }
+                    : options.disableAgentShield
+                        ? { enableAgentShield: false }
+                        : {}),
+            });
+            // Persist the decision record when `--record` is set. The writer is
+            // idempotent at the slug level (same date+rid → same file); repeated
+            // runs overwrite. Failures here are surfaced as warnings so the
+            // primary audit JSON still reaches the caller.
+            let decision;
+            let recordWarning;
+            if (options.record) {
+                try {
+                    decision = writeAuditDecision(result.audit, {
+                        projectRoot: validation.projectRoot,
+                        ...(options.rid ? { rid: options.rid } : {})
+                    });
+                }
+                catch (writeError) {
+                    recordWarning = `Failed to write decision record: ${getErrorMessage(writeError)}`;
+                }
+            }
+            const data = {
+                audit: result.audit,
+                agentShield: result.agentShield,
+                ...(decision ? { decision } : {})
+            };
+            const nextActions = [];
+            // Per spec §5.3 + §7.2: when ECC is not installed, surface
+            // the canonical 4-option user opt-in UX (a/b/c/d) via
+            // nextActions. The peaks-cli `peaks audit static` CLI is
+            // non-interactive (JSON envelope by default), so the 4
+            // options are surfaced as machine-readable action strings
+            // — same pattern as understand-commands.ts `INSTALL_HINT`.
+            if (!result.agentShield.installed) {
+                nextActions.push('ECC AgentShield not installed. Pick one of the four options below:');
+                nextActions.push('  a) Install: run `npx ecc-agentshield --help` to install, then re-run `peaks audit static`.');
+                nextActions.push('  b) Skip this run: pass `--disable-agent-shield` to suppress the subprocess for this call.');
+                nextActions.push('  c) Skip forever: run `peaks preferences set agentShieldEnabled false` (writes to `.peaks/preferences.json`).');
+                nextActions.push('  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.3 + §7.2.');
+            }
+            if (result.agentShield.spawned && result.agentShield.findings.length > 0) {
+                nextActions.push(`${result.agentShield.findings.length} ECC findings merged into the audit. Review with \`peaks audit static --json\`.`);
+            }
+            if (decision) {
+                nextActions.push(`Decision record written: ${decision.filePath}`);
+                nextActions.push(`Index synced: ${decision.indexSynced ? 'yes' : 'no'} (memory hot.decision[] now includes this audit)`);
+            }
+            const warnings = recordWarning ? [...result.warnings, recordWarning] : [...result.warnings];
+            const envelope = ok('audit.static', data, warnings, nextActions);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            printResult(io, fail('audit.static', 'SCANNER_FAILED', getErrorMessage(error), emptyStaticAuditData(), ['Inspect scanner logs and re-run with the same --project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // v2.14.0 Slice C Group G3: `peaks audit prose-ratio` — CI gate.
+    // Calls `peaks audit static --json` internally, parses the prose-only
+    // ratio, exits 1 if the ratio exceeds the target (default 5%).
+    // Rationale: a single CLI primitive for the CI gate; the underlying
+    // ratio lives in static-service.ts (computed via prose-ratio-calculator).
+    addJsonOption(audit
+        .command('prose-ratio')
+        .description('Compute the prose-only ratio (informational entries excluded). Exits 1 if ratio > target (default 5%).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--target <n>', 'maximum prose-only ratio (0-1, default 0.05)', '0.05')).action(async (options) => {
+        const validation = validateProjectRoot(options.project);
+        if (!validation.ok) {
+            printResult(io, fail('audit.prose-ratio', validation.code, validation.message, emptyProseRatioResult(), ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const target = Number.parseFloat(options.target);
+        if (!Number.isFinite(target) || target < 0 || target > 1) {
+            printResult(io, fail('audit.prose-ratio', 'INVALID_TARGET', `--target must be a number between 0 and 1 (got "${options.target}")`, emptyProseRatioResult(), ['Pass --target 0.05 (default) or another number in [0, 1]']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = runStaticAudit({ projectRoot: validation.projectRoot });
+            const ratio = computeProseRatio(result.audit.audit, { target });
+            const envelope = ok('audit.prose-ratio', ratio, [], [
+                ratio.exceeds
+                    ? `Prose-only ratio ${(ratio.ratio * 100).toFixed(2)}% exceeds target ${(ratio.target * 100).toFixed(2)}% (${ratio.proseOnly}/${ratio.totalRedLines})`
+                    : `Prose-only ratio ${(ratio.ratio * 100).toFixed(2)}% within target ${(ratio.target * 100).toFixed(2)}% (${ratio.proseOnly}/${ratio.totalRedLines})`
+            ]);
+            printResult(io, envelope, options.json);
+            if (ratio.exceeds) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('audit.prose-ratio', 'SCANNER_FAILED', getErrorMessage(error), emptyProseRatioResult(), ['Inspect scanner logs and re-run with the same --project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // Fix M1 (W5) — `peaks audit goal` CLI wrapper around `auditGoal()`.
+    // The service is correctly implemented but is NOT yet wired to a real
+    // LLM provider; this CLI exposes the route with a `stub` provider that
+    // returns a scaffold envelope. A follow-up slice will bind a real
+    // provider. Until then, non-stub providers fail loudly with
+    // `LLM_PROVIDER_NOT_IMPLEMENTED` so callers cannot silently no-op.
+    addJsonOption(audit
+        .command('goal')
+        .description('Audit a human need across 6 dimensions and propose a goal (peaks-audit primitive)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--need <text>', 'the human need to audit (becomes input.need for auditGoal())')
+        .option('--llm-provider <name>', 'LLM provider name (default: stub)', 'stub')).action(async (options) => {
+        const validation = validateProjectRoot(options.project);
+        if (!validation.ok) {
+            printResult(io, fail('audit.goal', validation.code, validation.message, emptyAuditGoalData(options.need, options.project), ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const provider = options.llmProvider ?? 'stub';
+        if (!isSupportedLlmProvider(provider)) {
+            printResult(io, fail('audit.goal', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, emptyAuditGoalData(options.need, validation.projectRoot), [
+                'Re-run with `--llm-provider stub` (default) to exercise the wired route.',
+                'Real provider binding is tracked as a follow-up slice; see peaks-audit skill notes.'
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // Stub provider: surface a structured "scaffold ready" envelope so the
+        // CLI route is wired and a CI test can verify it without a real LLM.
+        const data = {
+            status: 'scaffold-only',
+            serviceWired: true,
+            providerBinding: 'pending-follow-up-slice',
+            need: options.need,
+            projectRoot: validation.projectRoot,
+        };
+        const envelope = ok('audit.goal', data, [], [
+            'auditGoal() service is wired and reachable. The stub provider returns a scaffold envelope so CI can verify the route without a real LLM.',
+            'A follow-up slice will bind a real LLM provider; until then, non-stub providers fail loudly with `LLM_PROVIDER_NOT_IMPLEMENTED`.'
+        ]);
+        printResult(io, envelope, options.json);
+    });
+    // ---------------------------------------------------------------------------
+    // peaks audit artifact write — Slice 2026-06-26-audit-artifact-writer-generalization
+    //
+    // First-class CLI surface for the 4 audit artifact types. Replaces the
+    // 2026-06-22 "hand `git add` into .peaks/memory/" anti-pattern that left
+    // 4 orphan files. Each kind routes to exactly one writer in
+    // artifact-writer.ts; the writer enforces canonical frontmatter, so the
+    // memory-shape guard never fires for new writes.
+    // ---------------------------------------------------------------------------
+    const artifact = audit
+        .command('artifact')
+        .description('Manage audit artifacts (decision / prompt / machine-output / narrative) under .peaks/memory/');
+    addJsonOption(artifact
+        .command('write')
+        .description('Persist a single audit artifact to .peaks/memory/ via the artifact-writer (canonical frontmatter)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--kind <kind>', `artifact kind (${SUPPORTED_ARTIFACT_KINDS.join(' | ')})`)
+        .requiredOption('--input <path>', 'path to source file (markdown for prompt/narrative; JSON for machine-output)')
+        .option('--name <name>', 'display name (H1 in body); defaults to file basename')
+        .option('--description <text>', 'description field for frontmatter; defaults to a generic placeholder')
+        .option('--rid <id>', 'optional request id to disambiguate multiple writes on the same day')
+        .option('--dry-run', 'render the markdown but do not write to disk', false)).action((options) => {
+        const validation = validateProjectRoot(options.project);
+        if (!validation.ok) {
+            printResult(io, fail('audit.artifact.write', validation.code, validation.message, {
+                kind: 'narrative',
+                slug: '',
+                title: '',
+                date: '',
+                filePath: '',
+                memoryDir: '',
+                indexPath: '',
+                indexSynced: false,
+            }, ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        if (!isSupportedArtifactKind(options.kind)) {
+            printResult(io, fail('audit.artifact.write', 'INVALID_KIND', `Unknown --kind "${options.kind}". Supported: ${SUPPORTED_ARTIFACT_KINDS.join(', ')}.`, {
+                kind: 'narrative',
+                slug: '',
+                title: '',
+                date: '',
+                filePath: '',
+                memoryDir: '',
+                indexPath: '',
+                indexSynced: false,
+            }, [
+                `Re-run with --kind <one of ${SUPPORTED_ARTIFACT_KINDS.join(' | ')}>`,
+                'See .peaks/memory/audit-artifact-convention.md for the 4 artifact types.',
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const inputAbs = resolve(options.input);
+        if (!existsSync(inputAbs)) {
+            printResult(io, fail('audit.artifact.write', 'INPUT_NOT_FOUND', `--input file not found: ${options.input}`, {
+                kind: options.kind,
+                slug: '',
+                title: '',
+                date: '',
+                filePath: '',
+                memoryDir: '',
+                indexPath: '',
+                indexSynced: false,
+            }, ['Verify the --input path is correct (relative paths resolve against cwd)']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const baseName = options.name ?? options.input.split(/[\\/]/).pop() ?? 'untitled';
+        const description = options.description ??
+            `Audit artifact (${options.kind}) archived via peaks audit artifact write on ${new Date().toISOString().slice(0, 10)}.`;
+        const writeOpts = {
+            projectRoot: validation.projectRoot,
+            dryRun: options.dryRun === true,
+            ...(options.rid ? { rid: options.rid } : {}),
+        };
+        let record;
+        try {
+            switch (options.kind) {
+                case 'prompt': {
+                    const body = readFileSync(inputAbs, 'utf8');
+                    record = writePrompt({ name: baseName, description, body }, writeOpts);
+                    break;
+                }
+                case 'machine-output': {
+                    const json = readFileSync(inputAbs, 'utf8');
+                    record = writeMachineOutput({ name: baseName, description, json }, writeOpts);
+                    break;
+                }
+                case 'narrative': {
+                    const body = readFileSync(inputAbs, 'utf8');
+                    record = writeNarrative({ name: baseName, description, body }, writeOpts);
+                    break;
+                }
+                case 'decision': {
+                    // --kind decision requires JSON of `RedLineAudit` shape; for now
+                    // surface a clear error so callers don't silently write junk.
+                    printResult(io, fail('audit.artifact.write', 'KIND_DECISION_USE_STATIC_RECORD', `--kind decision should use 'peaks audit static --record' which writes a RedLineAudit snapshot. 'peaks audit artifact write --kind decision' is reserved for future direct-snapshot writes (not implemented yet).`, {
+                        kind: 'decision',
+                        slug: '',
+                        title: '',
+                        date: '',
+                        filePath: '',
+                        memoryDir: '',
+                        indexPath: '',
+                        indexSynced: false,
+                    }, ["Re-run with 'peaks audit static --record --project <root>' for RedLineAudit snapshots."]), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                default: {
+                    // Unreachable: isSupportedArtifactKind already filtered.
+                    throw new Error(`unreachable: kind=${options.kind}`);
+                }
+            }
+        }
+        catch (err) {
+            printResult(io, fail('audit.artifact.write', 'WRITE_FAILED', getErrorMessage(err), {
+                kind: options.kind,
+                slug: '',
+                title: '',
+                date: '',
+                filePath: '',
+                memoryDir: '',
+                indexPath: '',
+                indexSynced: false,
+            }, ['Inspect the error message; for --kind machine-output ensure --input is valid JSON']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('audit.artifact.write', record, [], [
+            `Artifact written via ${record.kind} writer.`,
+            record.indexSynced
+                ? 'Memory index regenerated; entry will appear in `peaks project memories` on next read.'
+                : 'Memory index NOT regenerated; run `peaks project memories --project <root>` to refresh.',
+        ]), options.json);
+    });
+}
+function emptyStaticAuditData() {
+    return {
+        audit: { totalRedLines: 0, cliBacked: 0, partial: 0, proseOnly: 0, audit: [], enforcerFindings: [] },
+        agentShield: {
+            spawned: false,
+            installed: false,
+            reason: 'flag-disabled',
+            findings: [],
+        },
+    };
+}
+function emptyAuditGoalData(need, projectRoot) {
+    return {
+        status: 'scaffold-only',
+        serviceWired: true,
+        providerBinding: 'pending-follow-up-slice',
+        need,
+        projectRoot,
+    };
+}
+function emptyProseRatioResult() {
+    return {
+        totalRedLines: 0,
+        cliBacked: 0,
+        partial: 0,
+        proseOnly: 0,
+        informational: 0,
+        ratio: 0,
+        target: 0.05,
+        exceeds: false,
+    };
+}

package/dist/src/cli/commands/capability-commands.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import type { PeaksConfig } from '../../services/config/config-types.js';
+import type { CapabilityMapSourceFilter } from '../../services/recommendations/recommendation-types.js';
+import { type ProgramIO } from '../cli-helpers.js';
+type CapabilityMapOptions = {
+    json?: boolean;
+    source: string;
+};
+export declare function registerCapabilityCommands(program: Command, io: ProgramIO): void;
+export declare function runCapabilityStatus(io: ProgramIO, options: {
+    json?: boolean;
+}): void;
+export declare function runCapabilityMap(io: ProgramIO, options: CapabilityMapOptions): void;
+export declare function getInstalledCapabilityIds(_config: PeaksConfig): string[];
+export declare function parseCapabilityMapSource(source: string): CapabilityMapSourceFilter | null;
+export {};