@delegance/claude-autopilot 5.5.2 → 7.2.0

package/dist/src/cli/scan.js

@@ -8,6 +8,8 @@ import { loadIgnoreRules, parseConfigIgnore, applyIgnoreRules } from "../core/ig
 import { saveCachedFindings } from "../core/persist/findings-cache.js";
 import { appendCostLog } from "../core/persist/cost-log.js";
 import { detectLLMKey, LLM_KEY_HINTS } from "../core/detect/llm-key.js";
+import { resolveEngineEnabled } from "../core/run-state/resolve-engine.js";
+import { runPhaseWithLifecycle } from "../core/run-state/run-phase-with-lifecycle.js";
 const C = {
     reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
     green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', cyan: '\x1b[36m',
@@ -50,7 +52,17 @@ function collectFiles(target, cwd) {
 function collectAllFiles(cwd) {
     return collectFiles(cwd, cwd);
 }
-export async function runScan(options = {}) {
+/**
+ * v6.2.0 — extract the `RunPhase<ScanInput, ScanOutput>` construction out of
+ * `runScan(options)` so the new top-level `autopilot` orchestrator can drive
+ * `runPhase` itself with a shared `phaseIdx` against the same run dir.
+ *
+ * The legacy `runScan(options)` keeps calling this builder internally (then
+ * `runPhaseWithLifecycle` for single-phase runs) so direct CLI behavior is
+ * byte-for-byte identical to v6.1. Parity is asserted by
+ * `tests/cli/scan-builder-parity.test.ts`.
+ */
+export async function buildScanPhase(options) {
     const cwd = options.cwd ?? process.cwd();
     const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
     let config = { configVersion: 1 };
@@ -73,46 +85,52 @@ export async function runScan(options = {}) {
         console.error(fmt('dim', '    guardrail scan src/auth/'));
         console.error(fmt('dim', '    guardrail scan --all'));
         console.error(fmt('dim', '    guardrail scan --ask "is there SQL injection?" src/db/'));
-        return 1;
+        return { kind: 'early-exit', exitCode: 1 };
     }
     // Deduplicate
     files = [...new Set(files)];
     if (files.length === 0) {
         console.log(fmt('yellow', '[scan] No code files found at the specified path(s)'));
-        return 0;
+        return { kind: 'early-exit', exitCode: 0 };
     }
     if (options.dryRun) {
         console.log(fmt('bold', `[scan] Would scan ${files.length} file(s):`));
         for (const f of files)
             console.log(fmt('dim', `  ${path.relative(cwd, f)}`));
-        return 0;
+        return { kind: 'early-exit', exitCode: 0 };
     }
     // Auto-detect stack if not in config
     if (!config.stack) {
         config = { ...config, stack: detectStack(cwd) ?? undefined };
     }
     // Build review engine
-    if (!detectLLMKey().hasKey) {
-        console.error(fmt('red', '[scan] No LLM API key — set one of:'));
-        for (const { name, url, note } of LLM_KEY_HINTS) {
-            const suffix = note ? `  (${note})` : '';
-            console.error(fmt('dim', `         ${name.padEnd(18)} ${url}${suffix}`));
-        }
-        return 1;
-    }
-    const engineRef = typeof config.reviewEngine === 'string' ? config.reviewEngine
-        : (config.reviewEngine?.adapter ?? 'auto');
     let engine;
-    try {
-        engine = await loadAdapter({
-            point: 'review-engine',
-            ref: engineRef,
-            options: typeof config.reviewEngine === 'object' ? config.reviewEngine.options : undefined,
-        });
+    if (options.__testReviewEngine) {
+        // Test-only fast path — skip the LLM key check and the adapter loader.
+        engine = options.__testReviewEngine;
     }
-    catch (err) {
-        console.error(fmt('red', `[scan] Could not load review engine: ${err instanceof Error ? err.message : String(err)}`));
-        return 1;
+    else {
+        if (!detectLLMKey().hasKey) {
+            console.error(fmt('red', '[scan] No LLM API key — set one of:'));
+            for (const { name, url, note } of LLM_KEY_HINTS) {
+                const suffix = note ? `  (${note})` : '';
+                console.error(fmt('dim', `         ${name.padEnd(18)} ${url}${suffix}`));
+            }
+            return { kind: 'early-exit', exitCode: 1 };
+        }
+        const engineRef = typeof config.reviewEngine === 'string' ? config.reviewEngine
+            : (config.reviewEngine?.adapter ?? 'auto');
+        try {
+            engine = await loadAdapter({
+                point: 'review-engine',
+                ref: engineRef,
+                options: typeof config.reviewEngine === 'object' ? config.reviewEngine.options : undefined,
+            });
+        }
+        catch (err) {
+            console.error(fmt('red', `[scan] Could not load review engine: ${err instanceof Error ? err.message : String(err)}`));
+            return { kind: 'early-exit', exitCode: 1 };
+        }
     }
     const focusLabel = options.focus && options.focus !== 'all' ? options.focus : null;
     const relFiles = files.map(f => path.relative(cwd, f));
@@ -123,9 +141,94 @@ export async function runScan(options = {}) {
         console.log(fmt('dim', `  question: ${options.ask}`));
     if (focusLabel)
         console.log(fmt('dim', `  focus: ${focusLabel}`));
+    // Pre-flight resolution just for the banner; the helper re-resolves
+    // internally with identical precedence so the engine path stays
+    // deterministic. Keeping this inline preserves the legacy "engine: on
+    // (<source>)" banner that scan emitted before v6.0.6.
+    const engineBanner = resolveEngineEnabled({
+        ...(options.cliEngine !== undefined ? { cliEngine: options.cliEngine } : {}),
+        ...(options.envEngine !== undefined ? { envValue: options.envEngine } : {}),
+        ...(typeof config.engine?.enabled === 'boolean' ? { configEnabled: config.engine.enabled } : {}),
+    });
+    if (engineBanner.enabled) {
+        console.log(fmt('dim', `  engine: on (${engineBanner.source})`));
+    }
     console.log('');
     // Build a focused git summary / prompt context
     const focusHint = buildFocusHint(options.ask, focusLabel);
+    const scanInput = {
+        files,
+        relFiles,
+        cwd,
+        config,
+        engine,
+        focusHint,
+        ...(options.ask !== undefined ? { ask: options.ask } : {}),
+        focusLabel,
+        all: options.all === true,
+    };
+    // The wrapped phase body — pure call-the-LLM-and-process-findings work.
+    // Extracted into a RunPhase so the engine path and the legacy path share
+    // the exact same logic. Engine-off callers invoke this directly via
+    // `executeScanPhase()`; engine-on callers route through `runPhase()`.
+    const phase = {
+        name: 'scan',
+        // scan re-issues identical LLM queries against the same code — re-running
+        // is safe and cheap-ish to retry.
+        idempotent: true,
+        // No git push, no PR comment, no provider-side mutation. The cost-log
+        // append + findings-cache write are local file IO that's already
+        // overwrite-style; replays are safe.
+        hasSideEffects: false,
+        run: executeScanPhase,
+    };
+    return {
+        kind: 'phase',
+        phase,
+        input: scanInput,
+        config,
+        renderResult: (output) => renderScanOutput(output, scanInput),
+    };
+}
+export async function runScan(options = {}) {
+    const built = await buildScanPhase(options);
+    if (built.kind === 'early-exit')
+        return built.exitCode;
+    const { phase, input, config, renderResult } = built;
+    // v6.0.6 — lifecycle wiring (createRun → runPhase → run.complete + state
+    // snapshot + lock release) lives in `runPhaseWithLifecycle`. The helper
+    // owns the engine-on/engine-off branch and the failure banner; the caller
+    // just supplies the phase, the input, and the engine-off escape hatch.
+    let output;
+    try {
+        const result = await runPhaseWithLifecycle({
+            cwd: input.cwd,
+            phase,
+            input,
+            config,
+            cliEngine: options.cliEngine,
+            envEngine: options.envEngine,
+            runEngineOff: () => executeScanPhase(input),
+        });
+        output = result.output;
+    }
+    catch {
+        // Helper already printed the failure banner + emitted run.complete
+        // failed + refreshed state.json + released the lock. Surface the
+        // legacy non-zero exit so existing CI / scripts are unaffected.
+        return 1;
+    }
+    return renderResult(output);
+}
+// ---------------------------------------------------------------------------
+// Phase body — the LLM call + finding processing + cost-log append + findings
+// cache write. Extracted from runScan so the engine-on path can wrap it via
+// `runPhase` and the engine-off path can call it directly. Returns a
+// JSON-serializable ScanOutput so the engine can persist it as `result` on
+// the phase snapshot.
+// ---------------------------------------------------------------------------
+async function executeScanPhase(input) {
+    const { files, relFiles, cwd, config, engine, focusHint, ask } = input;
     const result = await runReviewPhase({
         touchedFiles: relFiles,
         engine,
@@ -149,11 +252,47 @@ export async function runScan(options = {}) {
     // Apply ignore rules
     const ignoreRules = [...loadIgnoreRules(cwd), ...parseConfigIgnore(config.ignore)];
     const findings = applyIgnoreRules(result.findings, ignoreRules);
+    // Persist findings so `guardrail fix` can read them
+    saveCachedFindings(cwd, findings);
+    // Persist run to cost log so `claude-autopilot costs` reflects scans, not
+    // just full pipeline runs. Previously scan never wrote to the log, so the
+    // costs report stayed frozen at whatever the last `run` invocation produced.
+    appendCostLog(cwd, {
+        timestamp: new Date().toISOString(),
+        files: files.length,
+        inputTokens: result.usage?.input ?? 0,
+        outputTokens: result.usage?.output ?? 0,
+        costUSD: result.costUSD ?? 0,
+        durationMs: result.durationMs,
+    });
+    return {
+        fileCount: files.length,
+        findings: findings.map(f => ({
+            severity: f.severity,
+            message: f.message,
+            ...(f.file !== undefined ? { file: f.file } : {}),
+            ...(f.line !== undefined ? { line: f.line } : {}),
+            ...(f.suggestion !== undefined ? { suggestion: f.suggestion } : {}),
+        })),
+        ...(result.costUSD !== undefined ? { costUSD: result.costUSD } : {}),
+        durationMs: result.durationMs,
+        ...(result.rawOutputs !== undefined ? { rawOutputs: result.rawOutputs } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Render — translate ScanOutput back to the legacy stdout banner + exit code.
+// Lives outside the wrapped phase because it's pure presentation; doing the
+// rendering inside the phase would couple the engine path's idempotency to
+// console output, which we don't want.
+// ---------------------------------------------------------------------------
+function renderScanOutput(output, input) {
+    const { findings, costUSD, durationMs, rawOutputs } = output;
+    const { ask } = input;
     // Print results
-    if (findings.length === 0 && options.ask && result.rawOutputs && result.rawOutputs.length > 0) {
+    if (findings.length === 0 && ask && rawOutputs && rawOutputs.length > 0) {
         // --ask returned prose rather than structured findings — surface raw response
         console.log(fmt('cyan', `Answer:`));
-        for (const raw of result.rawOutputs) {
+        for (const raw of rawOutputs) {
             // Strip markdown fences and the ## Findings / ## Review Summary headers if present
             const cleaned = raw.replace(/^##\s+Review Summary\s*\n/gm, '').replace(/^##\s+Findings\s*\n/gm, '').trim();
             console.log(cleaned);
@@ -196,21 +335,8 @@ export async function runScan(options = {}) {
             console.log('');
         }
     }
-    // Persist findings so `guardrail fix` can read them
-    saveCachedFindings(cwd, findings);
-    // Persist run to cost log so `claude-autopilot costs` reflects scans, not
-    // just full pipeline runs. Previously scan never wrote to the log, so the
-    // costs report stayed frozen at whatever the last `run` invocation produced.
-    appendCostLog(cwd, {
-        timestamp: new Date().toISOString(),
-        files: files.length,
-        inputTokens: result.usage?.input ?? 0,
-        outputTokens: result.usage?.output ?? 0,
-        costUSD: result.costUSD ?? 0,
-        durationMs: result.durationMs,
-    });
-    if (result.costUSD !== undefined) {
-        console.log(fmt('dim', `  $${result.costUSD.toFixed(4)} · ${result.durationMs}ms`));
+    if (costUSD !== undefined) {
+        console.log(fmt('dim', `  $${costUSD.toFixed(4)} · ${durationMs}ms`));
     }
     const fixable = findings.filter(f => f.severity === 'critical' || f.severity === 'warning');
     if (fixable.length > 0) {

package/dist/src/cli/setup.d.ts

@@ -1,3 +1,4 @@
+import { type DetectionResult } from './detector.ts';
 export type ProfileName = 'security-strict' | 'team' | 'solo';
 export interface SetupOptions {
     cwd?: string;
@@ -6,4 +7,33 @@ export interface SetupOptions {
     profile?: ProfileName;
 }
 export declare function runSetup(options?: SetupOptions): Promise<void>;
+/**
+ * Append `entries` to `<cwd>/.gitignore` if missing. Returns the entries
+ * actually added (empty array when all already present, .gitignore is empty
+ * + we don't want to create one, etc.).
+ *
+ * Behavior:
+ *   - .gitignore exists: parse line-by-line, skip entries already present
+ *     (exact match after trim, ignoring leading `!`), append the rest.
+ *   - .gitignore missing: create it with the entries. Reasonable default
+ *     for a fresh `setup` since the user is opting into autopilot's cache.
+ *
+ * Idempotent: safe to call twice with the same entries.
+ */
+export declare function ensureGitignoreEntries(cwd: string, entries: string[]): Promise<string[]>;
+/**
+ * Write a starter `<cwd>/CLAUDE.md` if none exists. Pulls stack-detection
+ * info from the same `detection` result that drove preset selection, so the
+ * scaffolded conventions match the actual project.
+ *
+ * The starter doc is intentionally short (~35 lines) — a real project will
+ * grow it. The goal is to give downstream agents an anchor for the most
+ * common "I had to guess" decisions the v7.1.6 benchmark agent reported:
+ * commit-message style, test command, error class shape, prompt location.
+ *
+ * Returns true when the file was written (false if it already exists; we
+ * never overwrite — operator opted into autopilot, not into us nuking
+ * their docs).
+ */
+export declare function ensureStarterClaudeMd(cwd: string, detection: DetectionResult): Promise<boolean>;
 //# sourceMappingURL=setup.d.ts.map

package/dist/src/cli/setup.js

@@ -138,6 +138,26 @@ export async function runSetup(options = {}) {
     for (const line of presetContent.trimEnd().split('\n')) {
         console.log(`  ${DIM(line)}`);
     }
+    // v7.1.7 — Auto-add `.guardrail-cache/` and `node_modules/` to .gitignore.
+    // Per the v7.1.6 blank-repo benchmark, these are the two most common
+    // day-1 paper cuts: `setup` creates the cache dir on first run, and (for
+    // Node projects) `npm install` creates `node_modules` — neither belongs
+    // in git. Skipped silently if already present or no .gitignore exists
+    // and we don't want to create one without consent.
+    const gitignoreAdds = await ensureGitignoreEntries(cwd, [
+        '.guardrail-cache/',
+        'node_modules/',
+    ]);
+    if (gitignoreAdds.length > 0) {
+        console.log(`\n  ${PASS}  Added to .gitignore: ${DIM(gitignoreAdds.join(', '))}`);
+    }
+    // v7.1.7 — Auto-scaffold a starter CLAUDE.md if none exists. Closes ~5 of
+    // 6 friction points the benchmark agent hit on a blank repo (commit
+    // style, error class shape, test runner choice, etc.).
+    const claudeMdAdded = await ensureStarterClaudeMd(cwd, detection);
+    if (claudeMdAdded) {
+        console.log(`  ${PASS}  Wrote starter CLAUDE.md`);
+    }
     let hookInstalled = false;
     if (!options.skipHook) {
         const hookCode = await runHook('install', { cwd, silent: true });
@@ -152,6 +172,19 @@ export async function runSetup(options = {}) {
     console.log('\nChecking prerequisites…');
     await runDoctor();
     console.log(`\n${BOLD('Next steps:')}\n`);
+    // v7.1.9 — Generic+low-confidence detection prompt. The v7.1.8 benchmark
+    // re-run on a truly blank repo (no package.json / go.mod / language signal)
+    // surfaced this: setup runs fine but downstream agents get a CLAUDE.md
+    // saying "Detected: Generic (low confidence)" with no concrete next step
+    // to improve detection. Surfacing the actionable "scaffold a stack file
+    // first" hint converts a paper-cut into a one-liner.
+    if (detection.preset === 'generic' && detection.confidence === 'low') {
+        console.log(`  ${WARN}  ${CYAN('Stack detection: Generic (low confidence).')}`);
+        console.log(`       For higher-quality reviews + stack-specific presets, scaffold a`);
+        console.log(`       package manifest first, then re-run setup:`);
+        console.log(`         npm init -y                              ${DIM('# or: pnpm init, go mod init, cargo init')}`);
+        console.log(`         npx claude-autopilot setup --force       ${DIM('# re-detect with the new manifest')}\n`);
+    }
     if (!hasKey) {
         console.log(`  1. ${CYAN('Set an LLM API key')} — guardrail needs one to review code:`);
         console.log(`       export ANTHROPIC_API_KEY=sk-ant-...     # https://console.anthropic.com/`);
@@ -175,4 +208,108 @@ export async function runSetup(options = {}) {
         }
     }
 }
+// ---------------------------------------------------------------------------
+// v7.1.7 — setup-verb day-1 polish helpers
+// ---------------------------------------------------------------------------
+/**
+ * Append `entries` to `<cwd>/.gitignore` if missing. Returns the entries
+ * actually added (empty array when all already present, .gitignore is empty
+ * + we don't want to create one, etc.).
+ *
+ * Behavior:
+ *   - .gitignore exists: parse line-by-line, skip entries already present
+ *     (exact match after trim, ignoring leading `!`), append the rest.
+ *   - .gitignore missing: create it with the entries. Reasonable default
+ *     for a fresh `setup` since the user is opting into autopilot's cache.
+ *
+ * Idempotent: safe to call twice with the same entries.
+ */
+export async function ensureGitignoreEntries(cwd, entries) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    let existing = [];
+    let existingContent = '';
+    try {
+        existingContent = await fsAsync.readFile(gitignorePath, 'utf8');
+        existing = existingContent
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0 && !l.startsWith('#'));
+    }
+    catch {
+        // File doesn't exist — that's fine, we'll create it below.
+    }
+    const present = new Set(existing.map((l) => l.replace(/^!/, '')));
+    const missing = entries.filter((e) => !present.has(e.replace(/^!/, '')));
+    if (missing.length === 0)
+        return [];
+    // Build the appended block. Add a trailing newline first so we don't
+    // collide with a no-final-newline file.
+    const needsLeadingNewline = existingContent.length > 0 && !existingContent.endsWith('\n');
+    const block = (needsLeadingNewline ? '\n' : '') +
+        (existingContent.length > 0 ? '# claude-autopilot (v7.1.7+)\n' : '') +
+        missing.join('\n') +
+        '\n';
+    await fsAsync.writeFile(gitignorePath, existingContent + block, 'utf8');
+    return missing;
+}
+/**
+ * Write a starter `<cwd>/CLAUDE.md` if none exists. Pulls stack-detection
+ * info from the same `detection` result that drove preset selection, so the
+ * scaffolded conventions match the actual project.
+ *
+ * The starter doc is intentionally short (~35 lines) — a real project will
+ * grow it. The goal is to give downstream agents an anchor for the most
+ * common "I had to guess" decisions the v7.1.6 benchmark agent reported:
+ * commit-message style, test command, error class shape, prompt location.
+ *
+ * Returns true when the file was written (false if it already exists; we
+ * never overwrite — operator opted into autopilot, not into us nuking
+ * their docs).
+ */
+export async function ensureStarterClaudeMd(cwd, detection) {
+    const dest = path.join(cwd, 'CLAUDE.md');
+    if (fs.existsSync(dest))
+        return false;
+    const stackLabel = PRESET_LABELS[detection.preset] ?? detection.preset;
+    const today = new Date().toISOString().slice(0, 10);
+    const body = [
+        `# CLAUDE.md`,
+        ``,
+        `Project conventions for AI-assisted contributions. Auto-scaffolded by`,
+        `\`claude-autopilot setup\` on ${today}; edit freely.`,
+        ``,
+        `## Stack`,
+        ``,
+        `- **Detected:** ${stackLabel} (${detection.confidence} confidence)`,
+        `- **Test command:** \`${detection.testCommand}\``,
+        `- **Evidence:** ${detection.evidence}`,
+        ``,
+        `## Conventions`,
+        ``,
+        `- **Commit messages:** Conventional Commits (\`feat:\`, \`fix:\`,`,
+        `  \`docs:\`, \`refactor:\`, \`test:\`, \`chore:\`). One sentence first`,
+        `  line, optional body.`,
+        `- **Branches:** \`feat/<topic>\`, \`fix/<topic>\`, \`chore/<topic>\`.`,
+        `- **Errors:** prefer custom \`Error\` subclasses with a string \`code\``,
+        `  field for programmatic handling. Example:`,
+        `  \`\`\`ts`,
+        `  class FetchFailed extends Error { code = 'fetch_failed' as const; }`,
+        `  \`\`\``,
+        `- **Tests:** colocated with source under \`tests/\` or \`__tests__/\`.`,
+        `  Run via \`${detection.testCommand}\`.`,
+        ``,
+        `## Patterns to mimic`,
+        ``,
+        `- TODO: as the project grows, list 2-3 example files agents should`,
+        `  read first to learn local style.`,
+        ``,
+        `## Common pitfalls`,
+        ``,
+        `- TODO: list any non-obvious gotchas — env-var quirks, ordering`,
+        `  requirements, footguns the test suite won't catch.`,
+        ``,
+    ].join('\n');
+    await fsAsync.writeFile(dest, body, 'utf8');
+    return true;
+}
 //# sourceMappingURL=setup.js.map

package/dist/src/cli/spec.d.ts

@@ -0,0 +1,66 @@
+import type { GuardrailConfig } from '../core/config/types.ts';
+import { type RunPhase } from '../core/run-state/phase-runner.ts';
+export interface SpecCommandOptions {
+    cwd?: string;
+    configPath?: string;
+    /**
+     * v6.0.3 — engine knob inputs. Same shape and precedence as scan / costs /
+     * fix / brainstorm (CLI > env > config > built-in default off in v6.0.x).
+     */
+    cliEngine?: boolean;
+    envEngine?: string;
+    /**
+     * Test-only seam — when true, the phase body returns its result without
+     * printing the advisory banner. Lets engine-smoke tests assert the
+     * `state.json` + `events.ndjson` lifecycle without polluting stdout.
+     * Production callers (the CLI dispatcher) MUST NOT pass this.
+     */
+    __silent?: boolean;
+}
+/**
+ * Phase input — minimal. The CLI verb body is a print-and-exit advisory.
+ * Captured as a struct so the engine path's phase body matches the
+ * engine-off path call signature.
+ *
+ * Exported so the v6.2.0 orchestrator's phase registry can carry the typed
+ * I/O shape on its `PhaseRegistration<SpecInput, SpecOutput>` slot.
+ */
+export interface SpecInput {
+    cwd: string;
+    silent: boolean;
+}
+/**
+ * Phase output — JSON-serializable acknowledgment. Mirrors the shape of
+ * `BrainstormOutput`. Persisted as `result` on `phases/spec.json`.
+ */
+export interface SpecOutput {
+    /** Always 'advisory' for v6.0.3 — the CLI verb is a Claude Code pointer. */
+    kind: 'advisory';
+    nextActions: string[];
+}
+/** v6.2.0 — see scan.ts for the kind='early-exit' rationale. Spec has no
+ *  early-exit branches today (it just creates a config struct and returns
+ *  an advisory) so this discriminant is included for shape parity with the
+ *  other builders. */
+export interface BuildSpecPhaseEarlyExit {
+    kind: 'early-exit';
+    exitCode: number;
+}
+export interface BuildSpecPhaseResult {
+    kind: 'phase';
+    phase: RunPhase<SpecInput, SpecOutput>;
+    input: SpecInput;
+    config: GuardrailConfig;
+    renderResult: (output: SpecOutput) => number;
+}
+/**
+ * v6.2.0 — extract the `RunPhase<SpecInput, SpecOutput>` construction out of
+ * `runSpec(options)` so the new top-level `autopilot` orchestrator can drive
+ * `runPhase` itself with a shared `phaseIdx` against the same run dir.
+ *
+ * Parity with `runSpec(options)` is asserted by
+ * `tests/cli/spec-builder-parity.test.ts`.
+ */
+export declare function buildSpecPhase(options: SpecCommandOptions): Promise<BuildSpecPhaseResult | BuildSpecPhaseEarlyExit>;
+export declare function runSpec(options?: SpecCommandOptions): Promise<number>;
+//# sourceMappingURL=spec.d.ts.map

package/dist/src/cli/spec.js

@@ -0,0 +1,132 @@
+// src/cli/spec.ts
+//
+// v6.0.3 — wrap the `spec` pipeline phase through `runPhase`.
+//
+// `spec` is the second phase of the autopilot pipeline (brainstorm → spec →
+// plan → implement → migrate → validate → pr → review). Like `brainstorm`, it
+// is implemented primarily as a Claude Code skill, not as a standalone CLI
+// subcommand. The CLI verb that ships in this binary is an advisory shim: it
+// points the user at the Claude Code skill and the next pipeline verbs. There
+// is no LLM call in the CLI verb body and no provider side effects. The
+// pure-LLM spec writing happens in Claude Code; the spec markdown produced
+// there lands at `docs/superpowers/specs/<slug>.md` (a local file write —
+// the recipe treats local file writes as acceptable inside the phase body,
+// identical precedent to `fix.ts` editing local source files).
+//
+// Idempotency / side effects (deviation note vs. spec table):
+//   - The spec table at docs/specs/v6-run-state-engine.md says
+//     `idempotent: no` for `spec` because re-running produces NEW LLM
+//     content each invocation. v6.0.3 declares `idempotent: true` to match
+//     the engine's actual semantics ("safe to retry without
+//     reconciliation"): the CLI verb itself is a printed advisory that is
+//     byte-for-byte identical on every invocation, has no externalRefs to
+//     reconcile, and no provider state to roll back. Same reasoning as the
+//     brainstorm wrap. See `src/cli/brainstorm.ts` for the longer
+//     deviation rationale.
+//   - `hasSideEffects: false` — the CLI verb prints to stdout. No provider
+//     calls, no git push, no PR creation, no remote API write.
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { loadConfig } from "../core/config/loader.js";
+import { runPhaseWithLifecycle } from "../core/run-state/run-phase-with-lifecycle.js";
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    cyan: '\x1b[36m', red: '\x1b[31m',
+};
+const fmt = (c, t) => `${C[c]}${t}${C.reset}`;
+/**
+ * v6.2.0 — extract the `RunPhase<SpecInput, SpecOutput>` construction out of
+ * `runSpec(options)` so the new top-level `autopilot` orchestrator can drive
+ * `runPhase` itself with a shared `phaseIdx` against the same run dir.
+ *
+ * Parity with `runSpec(options)` is asserted by
+ * `tests/cli/spec-builder-parity.test.ts`.
+ */
+export async function buildSpecPhase(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
+    let config = { configVersion: 1 };
+    if (fs.existsSync(configPath)) {
+        const loaded = await loadConfig(configPath);
+        if (loaded)
+            config = loaded;
+    }
+    const specInput = { cwd, silent: options.__silent === true };
+    const phase = {
+        name: 'spec',
+        // Pure-LLM spec writing happens in the Claude Code skill, not here.
+        // The CLI verb is an advisory print with no externalRefs to reconcile
+        // and no provider state to roll back. Safe to retry. (Deviation from
+        // the spec table noted at the top of the file.)
+        idempotent: true,
+        // No provider calls, no git push, no PR creation. Identical to costs
+        // and brainstorm.
+        hasSideEffects: false,
+        run: async (input) => executeSpecPhase(input),
+    };
+    return {
+        kind: 'phase',
+        phase,
+        input: specInput,
+        config,
+        renderResult: (output) => renderSpecOutput(output, specInput),
+    };
+}
+export async function runSpec(options = {}) {
+    const built = await buildSpecPhase(options);
+    if (built.kind === 'early-exit')
+        return built.exitCode;
+    const { phase, input, config, renderResult } = built;
+    // v6.0.6 — lifecycle wiring lives in `runPhaseWithLifecycle`.
+    let output;
+    try {
+        const result = await runPhaseWithLifecycle({
+            cwd: input.cwd,
+            phase,
+            input,
+            config,
+            cliEngine: options.cliEngine,
+            envEngine: options.envEngine,
+            runEngineOff: () => executeSpecPhase(input),
+        });
+        output = result.output;
+    }
+    catch {
+        return 1;
+    }
+    return renderResult(output);
+}
+// ---------------------------------------------------------------------------
+// Phase body — produce the advisory payload. Pure: no provider calls.
+// ---------------------------------------------------------------------------
+async function executeSpecPhase(_input) {
+    return {
+        kind: 'advisory',
+        nextActions: [
+            'Approve a brainstorm output, then invoke /autopilot from Claude Code',
+            'The autopilot skill writes the implementation plan + executes the pipeline',
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Render — translate SpecOutput back to the stdout advisory + exit code.
+// ---------------------------------------------------------------------------
+function renderSpecOutput(_output, input) {
+    if (input.silent)
+        return 0;
+    console.log(`
+${fmt('bold', '[spec]')} Spec writing is a Claude Code skill, not a standalone CLI subcommand.
+
+Invoke it from Claude Code:
+
+  ${fmt('cyan', '/brainstorm')}                         Interactive spec writing (entry point)
+  ${fmt('cyan', '/autopilot')}                          Full pipeline from an approved spec
+  ${fmt('cyan', '/migrate')}                            Database migration phase (stack-dependent)
+
+Specs land at ${fmt('dim', 'docs/superpowers/specs/<slug>.md')} — once approved, /autopilot consumes them.
+
+Full pipeline docs: https://github.com/axledbetter/claude-autopilot#the-pipeline-phase-by-phase
+`);
+    return 0;
+}
+//# sourceMappingURL=spec.js.map