peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/asset-crystallize-runner.d.ts

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type CrystallizeOptions } from './asset-crystallize-payload.js';
+export declare function runAssetCrystallize(io: ProgramIO, options: CrystallizeOptions): Promise<void>;

package/dist/cli/commands/asset-crystallize-runner.js

@@ -0,0 +1,133 @@
+// src/cli/commands/asset-crystallize-runner.ts
+//
+// The `asset.crystallize` action body and its failure envelopes. Split out of
+// `asset-crystallize-command.ts`; every error code, message and next-action
+// list is unchanged, including the rethrow of an error class the verb does not
+// handle itself.
+import { CrystallizationIntegrityError, BriefSectionError, safeRenderRecommendationPayload, CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief } from '../../services/crystallization/index.js';
+import { printResult } from '../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+import { createCrystallizationService, openAssetDb, parseTriggerFlag, resolveAssetProjectRoot } from './asset-command-shared.js';
+import { briefFromOptions, buildCrystallizePayload, printCrystallizeResult } from './asset-crystallize-payload.js';
+function failCrystallize(io, failure) {
+    printResult(io, fail('asset.crystallize', failure.code, failure.message, failure.data, failure.nextActions), failure.json);
+    process.exitCode = 1;
+}
+function printInvalidTrigger(io, options) {
+    failCrystallize(io, {
+        code: 'ASSET_INVALID_TRIGGER',
+        message: `--trigger must be one of: ${CRYSTALLIZATION_TRIGGERS.join('|')}`,
+        data: { trigger: options.trigger },
+        nextActions: ['Pass a valid --trigger value.'],
+        json: options.json
+    });
+}
+function printMissingBrief(io, err, candidateBrief, json) {
+    const briefErr = err;
+    failCrystallize(io, {
+        code: 'MISSING_BRIEF_SECTION',
+        message: briefErr.message,
+        data: { findings: [...briefErr.findings], flagsProvided: Object.keys(candidateBrief) },
+        nextActions: [
+            'Pass ALL FOUR brief sections via --brief-what-happened / --brief-why-it-matters / --brief-what-learned / --brief-what-action.',
+            'The CLI refuses to render a recommendation without a complete 4-section brief (spec §4.7 / RL-7).'
+        ],
+        json
+    });
+}
+function printRecommendationRejected(io, recommendation, candidateBrief, json) {
+    failCrystallize(io, {
+        code: recommendation.code ?? 'MISSING_BRIEF_SECTION',
+        message: 'recommendation envelope rejected — brief is missing one of its 4 sections',
+        data: { findings: recommendation.findings, briefProvided: candidateBrief },
+        nextActions: [
+            'Pass ALL FOUR brief sections via the matching CLI flags.',
+            'Counts in --brief-bullet may support the brief; they do NOT replace it (spec §4.7 / RL-7).'
+        ],
+        json
+    });
+}
+/** Terminal failures from the service. Anything else is rethrown, as before. */
+function handleCrystallizeError(io, err, json) {
+    if (err instanceof CrystallizationIntegrityError) {
+        const integrityErr = err;
+        failCrystallize(io, {
+            code: integrityErr.code,
+            message: integrityErr.message,
+            data: { findings: [...integrityErr.findings] },
+            nextActions: [
+                integrityErr.code === 'CRYSTALLIZATION_PRE_RUN'
+                    ? 'Re-shape the candidate task so task_status=completed AND gates_passed=true AND evidence_collected=true (spec §5 / RL-2).'
+                    : integrityErr.code === 'MISSING_BRIEF_SECTION'
+                        ? 'Pass ALL FOUR brief sections (RL-7); the CLI refuses to render a recommendation without them.'
+                        : 'Inspect the failure findings and re-shape the payload.'
+            ],
+            json
+        });
+        return;
+    }
+    if (err instanceof BriefSectionError) {
+        const briefErr = err;
+        failCrystallize(io, {
+            code: 'MISSING_BRIEF_SECTION',
+            message: briefErr.message,
+            data: { findings: [...briefErr.findings] },
+            nextActions: ['Pass all 4 brief sections (RL-7).'],
+            json
+        });
+        return;
+    }
+    throw err;
+}
+export async function runAssetCrystallize(io, options) {
+    try {
+        const trigger = parseTriggerFlag(options.trigger);
+        if (!trigger) {
+            printInvalidTrigger(io, options);
+            return;
+        }
+        // Build the brief from CLI flags and re-validate it through
+        // the canonical schema (so a partial brief is caught BEFORE
+        // any DB side effects fire).
+        const candidateBrief = briefFromOptions(options);
+        let brief;
+        try {
+            brief = parseEvidenceBrief(candidateBrief);
+        }
+        catch (err) {
+            if (err instanceof BriefSectionError) {
+                printMissingBrief(io, err, candidateBrief, options.json);
+                return;
+            }
+            throw err;
+        }
+        // Render the recommendation envelope up-front so the CLI can
+        // refuse to write if any brief section is missing. This is
+        // the same code path the crystallization service uses.
+        const recommendation = safeRenderRecommendationPayload({
+            brief,
+            bullets: options.briefBullet ?? [],
+            source_trace_pointers: options.sourceTrace ?? [],
+            evaluator_summary: {
+                one_liner: options.evaluatorSummary ?? '',
+                risk_tags: []
+            }
+        });
+        if (!recommendation.ok) {
+            printRecommendationRejected(io, recommendation, candidateBrief, options.json);
+            return;
+        }
+        const db = openAssetDb(resolveAssetProjectRoot(options.project));
+        try {
+            const svc = createCrystallizationService(db);
+            const result = svc.crystallize(buildCrystallizePayload(options, brief, trigger));
+            printCrystallizeResult(io, recommendation, result, options.json);
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        handleCrystallizeError(io, err, options.json);
+    }
+}

package/dist/cli/commands/asset-dispose-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerAssetDisposeCommand(asset: Command, io: ProgramIO): void;

package/dist/cli/commands/asset-dispose-command.js

@@ -0,0 +1,99 @@
+// src/cli/commands/asset-dispose-command.ts
+//
+// `peaks asset dispose` — trace-only / retain / destroy. Split out of
+// `asset-commands.ts`; the verb name, its options, the envelope shape and
+// every error code are unchanged.
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { DISPOSE_MODES, createCrystallizationService, openAssetDb, resolveAssetProjectRoot } from './asset-command-shared.js';
+function printInvalidDisposeMode(io, options) {
+    printResult(io, fail('asset.dispose', 'ASSET_INVALID_MODE', `--mode must be one of: ${DISPOSE_MODES.join('|')}`, { mode: options.mode }, ['Pass --mode trace_only / retain / destroy.']), options.json);
+    process.exitCode = 1;
+}
+function printDisposeEventNotFound(io, options) {
+    printResult(io, fail('asset.dispose', 'ASSET_EVENT_NOT_FOUND', `crystallization event '${options.crystallizationEvent}' not found`, { eventId: options.crystallizationEvent }, ['Verify the event id.']), options.json);
+    process.exitCode = 1;
+}
+/** `retain` → no DB change; the user wants to keep the event as evidence. */
+function printDisposeRetained(io, existing, mode, json) {
+    printResult(io, ok('asset.dispose', {
+        crystallization_event_id: existing.id,
+        mode,
+        lifecycle_status: existing.lifecycle_status,
+        note: 'no DB change; event retained as-is'
+    }, [], ['Run `peaks asset status --loop <id>` to inspect the lifecycle state of the linked assets.']), json);
+}
+/**
+ * `destroy` → retire the created/updated loop_release rows as well. We do NOT
+ * delete rows — retirement is a status flip (spec §5.6).
+ */
+function retireLinkedLoops(db, updated) {
+    const retireLoop = db.prepare("UPDATE loop_release SET lifecycle_status = 'retired' WHERE id IN (?, ?)");
+    const ids = [
+        updated.created_loop_release_id ?? null,
+        updated.updated_loop_release_id ?? null
+    ].filter((x) => x !== null);
+    for (const id of ids) {
+        retireLoop.run(id, id);
+    }
+}
+function printDisposeResult(io, outcome, json) {
+    printResult(io, ok('asset.dispose', {
+        crystallization_event_id: outcome.existing.id,
+        mode: outcome.mode,
+        lifecycle_status: outcome.updated?.lifecycle_status ?? 'retired',
+        retired_assets: outcome.mode === 'destroy' ? 'loop_release retired (no rows deleted)' : 'none',
+        nextActions: ['Run `peaks asset status` to confirm the lifecycle transition.']
+    }, [], []), json);
+}
+function printDisposeFailure(io, err, options) {
+    printResult(io, fail('asset.dispose', 'ASSET_DISPOSE_FAILED', getErrorMessage(err), { eventId: options.crystallizationEvent }, ['Verify the event id and --mode flag.']), options.json);
+    process.exitCode = 1;
+}
+async function runAssetDispose(io, options) {
+    try {
+        if (!DISPOSE_MODES.includes(options.mode)) {
+            printInvalidDisposeMode(io, options);
+            return;
+        }
+        const mode = options.mode;
+        const db = openAssetDb(resolveAssetProjectRoot(options.project));
+        try {
+            const svc = createCrystallizationService(db);
+            const existing = svc.read(options.crystallizationEvent);
+            if (!existing) {
+                printDisposeEventNotFound(io, options);
+                return;
+            }
+            // trace_only → retire the event row; the source traces are
+            // untouched (workflow traces are immutable per spec §4.3).
+            // retain → no DB change; the user wants to keep the event
+            // as historical evidence.
+            // destroy → retire the event + retire the created/updated
+            // assets (no asset delete; retirement only).
+            if (mode === 'retain') {
+                printDisposeRetained(io, existing, mode, options.json);
+                return;
+            }
+            const updated = svc.updateStatus(existing.id, 'retired');
+            if (mode === 'destroy' && updated) {
+                retireLinkedLoops(db, updated);
+            }
+            printDisposeResult(io, { existing, mode, updated }, options.json);
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        printDisposeFailure(io, err, options);
+    }
+}
+export function registerAssetDisposeCommand(asset, io) {
+    addJsonOption(asset
+        .command('dispose')
+        .description('M5: dispose a crystallization event. mode=trace_only retires the event but keeps the trace; mode=retain keeps both; mode=destroy retires the event and marks the created/updated assets retired.')
+        .requiredOption('--crystallization-event <id>', 'the crystallization event id (returned by `peaks asset crystallize`)')
+        .requiredOption('--mode <mode>', `dispose mode (one of: ${DISPOSE_MODES.join('|')}; default: trace_only)`, 'trace_only')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => runAssetDispose(io, options));
+}

package/dist/cli/commands/asset-status-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerAssetStatusCommand(asset: Command, io: ProgramIO): void;

package/dist/cli/commands/asset-status-command.js

@@ -0,0 +1,100 @@
+// src/cli/commands/asset-status-command.ts
+//
+// `peaks asset status` — loop + bee lifecycle state plus the crystallization
+// events that reference them. Split out of `asset-commands.ts`; the verb name,
+// its options and the envelope shape are unchanged.
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { createCrystallizationService, openAssetDb, resolveAssetProjectRoot } from './asset-command-shared.js';
+/** The events a `--loop` filter selects, deduplicated by id; all of them otherwise. */
+function collectEvents(svc, loop) {
+    if (!loop) {
+        return svc.list();
+    }
+    const events = [
+        ...svc.list({ created_loop_release_id: loop }),
+        ...svc.list({ updated_loop_release_id: loop })
+    ];
+    // Deduplicate by id.
+    const seen = new Set();
+    return events.filter((e) => {
+        const key = e?.id ?? '';
+        if (!key || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Companion query: loop lifecycle counts. We compute from the DB so the CLI is
+ * the single source of truth.
+ */
+function collectLoopCounts(db) {
+    const rows = db
+        .prepare('SELECT lifecycle_status, COUNT(*) AS n FROM loop_release GROUP BY lifecycle_status')
+        .all();
+    return rows.reduce((acc, r) => {
+        acc[r.lifecycle_status] = r.n;
+        return acc;
+    }, {});
+}
+/** Companion query: bee lifecycle counts, narrowed by `--bee` when given. */
+function collectBeeCounts(db, bee) {
+    const rows = db
+        .prepare('SELECT bee_name, COUNT(*) AS n FROM bee_release GROUP BY bee_name ORDER BY bee_name ASC')
+        .all();
+    return rows.filter((r) => bee === undefined || r.bee_name === bee);
+}
+function statusData(options, events, loopCounts, beeCounts) {
+    return {
+        filters: {
+            ...(options.loop !== undefined ? { loop: options.loop } : {}),
+            ...(options.bee !== undefined ? { bee: options.bee } : {})
+        },
+        crystallization_events: events.length,
+        events: events.map((e) => ({
+            id: e?.id,
+            trigger: e?.trigger,
+            lifecycle_status: e?.lifecycle_status,
+            created_loop_release_id: e?.created_loop_release_id,
+            created_bee_release_id: e?.created_bee_release_id,
+            updated_loop_release_id: e?.updated_loop_release_id,
+            updated_bee_release_id: e?.updated_bee_release_id,
+            created_at: e?.created_at
+        })),
+        loop_release_counts_by_lifecycle: loopCounts,
+        bee_release_counts_by_name: beeCounts,
+        nextActions: [
+            options.loop
+                ? `Run \`peaks loop show --loop ${options.loop}\` for the loop detail view.`
+                : "Pass --loop <id> to drill into a specific loop's crystallization history."
+        ]
+    };
+}
+async function runAssetStatus(io, options) {
+    try {
+        const db = openAssetDb(resolveAssetProjectRoot(options.project));
+        try {
+            const svc = createCrystallizationService(db);
+            const events = collectEvents(svc, options.loop);
+            const loopCounts = collectLoopCounts(db);
+            const beeCounts = collectBeeCounts(db, options.bee);
+            printResult(io, ok('asset.status', statusData(options, events, loopCounts, beeCounts), [], []), options.json);
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        printResult(io, fail('asset.status', 'ASSET_STATUS_FAILED', getErrorMessage(err), { loop: options.loop, bee: options.bee }, ['Verify the loop / bee identifiers.']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerAssetStatusCommand(asset, io) {
+    addJsonOption(asset
+        .command('status')
+        .description('M5: list loop + bee lifecycle state. With --loop, returns the loop + all linked bee_releases + all crystallization events referencing them.')
+        .option('--loop <id>', 'filter by loop_release id')
+        .option('--bee <name>', 'filter by bee_name')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => runAssetStatus(io, options));
+}

package/dist/cli/commands/audit-artifact-runners.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `peaks audit artifact` runners — 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.
+ *
+ * The action body moved out of `audit-commands.ts` verbatim; the registrar now
+ * only wires the commands and delegates. Every envelope, error code and hint
+ * string is unchanged.
+ */
+import { type ProgramIO } from '../cli-helpers.js';
+import { type ArtifactWriteOptions } from './audit-command-shared.js';
+export declare const ARTIFACT_GROUP_DESCRIPTION = "Manage audit artifacts (decision / prompt / machine-output / narrative) under .peaks/memory/";
+export declare const ARTIFACT_WRITE_DESCRIPTION = "Persist a single audit artifact to .peaks/memory/ via the artifact-writer (canonical frontmatter)";
+export declare function runArtifactWrite(options: ArtifactWriteOptions, io: ProgramIO): void;

package/dist/cli/commands/audit-artifact-runners.js

@@ -0,0 +1,170 @@
+/**
+ * `peaks audit artifact` runners — 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.
+ *
+ * The action body moved out of `audit-commands.ts` verbatim; the registrar now
+ * only wires the commands and delegates. Every envelope, error code and hint
+ * string is unchanged.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { writeDecision, writeMachineOutput, writeNarrative, writePrompt } from '../../services/audit/artifact-writer.js';
+import { parseRedLineAuditInput, RedLineAuditInputError } from '../../services/audit/red-line-audit-input.js';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { isSupportedArtifactKind, PROJECT_PATH_HINT, SUPPORTED_ARTIFACT_KINDS, validateProjectRoot } from './audit-command-shared.js';
+import { emptyArtifactWriteRecord } from './audit-refusal-data.js';
+export const ARTIFACT_GROUP_DESCRIPTION = 'Manage audit artifacts (decision / prompt / machine-output / narrative) under .peaks/memory/';
+export const ARTIFACT_WRITE_DESCRIPTION = 'Persist a single audit artifact to .peaks/memory/ via the artifact-writer (canonical frontmatter)';
+const INPUT_PATH_HINT = 'Verify the --input path is correct (relative paths resolve against cwd)';
+/** Length of the `YYYY-MM-DD` prefix of an ISO timestamp. */
+const ISO_DATE_LENGTH = 10;
+/**
+ * Names the unreachable `--kind` without tripping the template-expression rule:
+ * by the time the `default` arm runs, the narrowing has reduced `kind` to
+ * `never`, so the message is built from a `string` parameter instead.
+ */
+function unreachableKindError(kind) {
+    return new Error(`unreachable: kind=${kind}`);
+}
+function refuseArtifactWrite(refusal) {
+    printResult(refusal.io, fail('audit.artifact.write', refusal.code, refusal.message, emptyArtifactWriteRecord(refusal.kind), refusal.nextActions), refusal.json);
+    process.exitCode = 1;
+}
+function writeByKind(request) {
+    const writeOpts = {
+        projectRoot: request.projectRoot,
+        dryRun: request.dryRun,
+        ...(request.rid ? { rid: request.rid } : {})
+    };
+    switch (request.kind) {
+        case 'prompt': {
+            const body = readFileSync(request.inputAbs, 'utf8');
+            return writePrompt({ name: request.baseName, description: request.description, body }, writeOpts);
+        }
+        case 'machine-output': {
+            const json = readFileSync(request.inputAbs, 'utf8');
+            return writeMachineOutput({ name: request.baseName, description: request.description, json }, writeOpts);
+        }
+        case 'narrative': {
+            const body = readFileSync(request.inputAbs, 'utf8');
+            return writeNarrative({ name: request.baseName, description: request.description, body }, writeOpts);
+        }
+        case 'decision': {
+            // `--input` is a RedLineAudit JSON document — typically
+            // an archived `peaks audit static` result — validated field by field
+            // before it reaches the writer, because the writer renders whatever
+            // it is given into a memory record with no further checks.
+            // `--name` and `--description` do not apply: the decision slug and
+            // title come from the scan date (and `--rid`), exactly as
+            // `peaks audit static --record` derives them.
+            const audit = parseRedLineAuditInput(readFileSync(request.inputAbs, 'utf8'));
+            return writeDecision(audit, writeOpts);
+        }
+        default: {
+            // Unreachable: isSupportedArtifactKind already filtered.
+            throw unreachableKindError(request.kind);
+        }
+    }
+}
+function artifactWriteNextActions(record) {
+    return [
+        `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.'
+    ];
+}
+function persistArtifact(request) {
+    let record;
+    try {
+        record = writeByKind(request);
+    }
+    catch (err) {
+        // A malformed decision input is the caller's document, not a write
+        // failure: name it as input so the remedy reads as "fix the JSON field".
+        refuseArtifactWrite({
+            io: request.io,
+            json: request.json,
+            kind: request.kind,
+            code: err instanceof RedLineAuditInputError ? 'AUDIT_ARTIFACT_INPUT_INVALID' : 'WRITE_FAILED',
+            message: getErrorMessage(err),
+            nextActions: err instanceof RedLineAuditInputError
+                ? [
+                    'Inspect the named field; --kind decision takes the JSON shape `peaks audit static --json` prints.'
+                ]
+                : ['Inspect the error message; for --kind machine-output ensure --input is valid JSON']
+        });
+        return;
+    }
+    printResult(request.io, ok('audit.artifact.write', record, [], artifactWriteNextActions(record)), request.json);
+}
+/**
+ * The three refusals `--project`, `--kind` and `--input` can earn, in the
+ * order the original action checked them. Prints the envelope and sets the
+ * exit code on failure.
+ */
+function precheckArtifactWrite(options, io) {
+    const validation = validateProjectRoot(options.project);
+    if (!validation.ok) {
+        refuseArtifactWrite({
+            io,
+            json: options.json,
+            kind: 'narrative',
+            code: validation.code,
+            message: validation.message,
+            nextActions: [PROJECT_PATH_HINT]
+        });
+        return { ok: false };
+    }
+    if (!isSupportedArtifactKind(options.kind)) {
+        refuseArtifactWrite({
+            io,
+            json: options.json,
+            kind: 'narrative',
+            code: 'INVALID_KIND',
+            message: `Unknown --kind "${options.kind}". Supported: ${SUPPORTED_ARTIFACT_KINDS.join(', ')}.`,
+            nextActions: [
+                `Re-run with --kind <one of ${SUPPORTED_ARTIFACT_KINDS.join(' | ')}>`,
+                'See .peaks/memory/audit-artifact-convention.md for the 4 artifact types.'
+            ]
+        });
+        return { ok: false };
+    }
+    const inputAbs = resolve(options.input);
+    if (!existsSync(inputAbs)) {
+        refuseArtifactWrite({
+            io,
+            json: options.json,
+            kind: options.kind,
+            code: 'INPUT_NOT_FOUND',
+            message: `--input file not found: ${options.input}`,
+            nextActions: [INPUT_PATH_HINT]
+        });
+        return { ok: false };
+    }
+    return { ok: true, projectRoot: validation.projectRoot, kind: options.kind, inputAbs };
+}
+export function runArtifactWrite(options, io) {
+    const precheck = precheckArtifactWrite(options, io);
+    if (!precheck.ok) {
+        return;
+    }
+    const baseName = options.name ?? options.input.split(/[\\/]/).pop() ?? 'untitled';
+    const description = options.description ??
+        `Audit artifact (${precheck.kind}) archived via peaks audit artifact write on ${new Date().toISOString().slice(0, ISO_DATE_LENGTH)}.`;
+    persistArtifact({
+        io,
+        json: options.json,
+        kind: precheck.kind,
+        inputAbs: precheck.inputAbs,
+        baseName,
+        description,
+        projectRoot: precheck.projectRoot,
+        dryRun: options.dryRun === true,
+        ...(options.rid ? { rid: options.rid } : {})
+    });
+}

package/dist/cli/commands/audit-command-shared.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared plumbing for the `peaks audit *` command family.
+ *
+ * Split out of `audit-commands.ts` (file-size cap) so each runner module can
+ * read the option shapes, the `--project` validation and the two whitelists
+ * without importing the registrar back. Dependency direction is one-way:
+ * nothing here imports `audit-commands.ts`.
+ */
+import type { AuditGoalOutput } from '../../services/audit/audit-goal-types.js';
+import type { AgentShieldState } from '../../services/audit/static-service.js';
+import type { ArtifactKind } from '../../services/audit/artifact-writer.js';
+import type { AuditDecisionRecord } from '../../services/audit/decision-writer.js';
+import type { RedLineAudit } from '../../services/audit/types.js';
+export type RedLinesOptions = {
+    project: string;
+    json?: boolean;
+    noColor?: boolean;
+};
+export type StaticAuditOptions = {
+    project: string;
+    json?: boolean;
+    noColor?: boolean;
+    record?: boolean;
+    rid?: string;
+};
+export type AuditGoalOptions = {
+    project: string;
+    need: string;
+    llmProvider?: string;
+    json?: boolean;
+};
+export type ArtifactWriteOptions = {
+    project: string;
+    kind: string;
+    input: string;
+    description?: string;
+    name?: string;
+    rid?: string;
+    dryRun?: boolean;
+    json?: boolean;
+};
+export type ProseRatioOptions = {
+    project: string;
+    target: string;
+    json?: boolean;
+};
+export declare const SUPPORTED_ARTIFACT_KINDS: readonly ArtifactKind[];
+export declare function isSupportedArtifactKind(value: string): value is ArtifactKind;
+/** Whitelist of supported `--llm-provider` values for `peaks audit goal`. */
+export declare const SUPPORTED_LLM_PROVIDERS: readonly ["anthropic", "stub"];
+export type SupportedLlmProvider = (typeof SUPPORTED_LLM_PROVIDERS)[number];
+/**
+ * The real provider is the default: `peaks audit goal` is the entry gate for
+ * every peaks-* workflow, so it must audit by default and only scaffold when
+ * a caller explicitly asks for `stub`.
+ */
+export declare const DEFAULT_LLM_PROVIDER: SupportedLlmProvider;
+export declare function isSupportedLlmProvider(value: string): value is SupportedLlmProvider;
+/** The one hint every `--project` refusal carries, verbatim. */
+export declare const PROJECT_PATH_HINT = "Verify the project path exists and is a directory";
+/** The one hint every scanner-failure refusal carries, verbatim. */
+export declare const SCANNER_HINT = "Inspect scanner logs and re-run with the same --project path";
+/** `--project` is valid only when it resolves to an existing directory. */
+export type ProjectRootValidation = {
+    ok: true;
+    projectRoot: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export declare function validateProjectRoot(projectArg: string): ProjectRootValidation;
+/** `audit-failed` is a failure envelope's status — never a scaffold, never a success. */
+export type AuditGoalStatus = 'audit-complete' | 'scaffold-only' | 'audit-failed';
+export interface AuditGoalData {
+    readonly status: AuditGoalStatus;
+    /** Which LLM produced (or failed to produce) the audit. `unresolved` = rejected before binding. */
+    readonly providerBinding: 'anthropic-messages-api' | 'stub' | 'unresolved';
+    readonly need: string;
+    readonly projectRoot: string;
+    /** The validated 6-dimension audit. Present on success only. */
+    readonly result?: AuditGoalOutput;
+    /** The bound model. Present on a real run only. */
+    readonly model?: string;
+    /**
+     * Environment variables the binding needed and did not find. Present on a
+     * binding failure only, and verbatim: `fail()` redacts `message`, so this
+     * is the channel that reliably names what the operator must set.
+     */
+    readonly missingEnv?: readonly string[];
+}
+export interface StaticAuditData {
+    readonly audit: RedLineAudit;
+    readonly agentShield: AgentShieldState;
+    /** Populated only when `--record` is passed. Persisted decision record path. */
+    readonly decision?: AuditDecisionRecord;
+}