@delegance/claude-autopilot 2.5.0 → 5.0.0-alpha.2

package/presets/generic/stack.md

@@ -0,0 +1,40 @@
+A generic project with no strong framework signals detected.
+
+This preset makes **no assumptions** about:
+- Database engine or migration runner
+- Type generation
+- Test framework (uses whatever `npm test` / `npm run typecheck` / `npm run lint` find)
+- Deployment target
+
+It enables the core security rules that apply to most codebases — hardcoded secrets, npm audit, SQL injection patterns, missing auth checks, SSRF, insecure redirects.
+
+## What's disabled vs stack-specific presets
+
+- `supabase-rls-bypass` rule (Supabase-only)
+- `schema-alignment` rule (requires declared migration paths)
+- `migrate` phase of the pipeline no-ops with a notice
+
+## Wiring up migrations
+
+If your project uses migrations, create `.claude-autopilot/stack.yaml` with:
+
+```yaml
+migrate:
+  command: "prisma migrate dev"      # or flyway, dbmate, tbls, golang-migrate, etc.
+  environments: [dev, staging, prod]
+  typeGeneration:
+    command: "prisma generate"
+    path: "node_modules/.prisma/client"
+```
+
+Or pick a stack-specific preset at setup time: `claude-autopilot init --preset nextjs-supabase`.
+
+## Things that should flag CRITICAL (universal)
+
+- Secrets committed to code or history
+- SQL string concatenation with user input
+- POST endpoints without auth checks
+- SSRF via user-controlled URLs in `fetch` / `axios`
+- Open redirects (user-controlled `Location` header)
+- Dynamic code evaluation (`eval`, `Function` constructor) with user input
+- Shell command construction with user input

package/presets/nextjs-supabase/{autopilot.config.yaml → guardrail.config.yaml}

@@ -18,6 +18,13 @@ staticRules:
   - npm-audit
   - package-lock-sync
   - supabase-rls-bypass
+  - sql-injection
+  - missing-auth
+  - ssrf
+  - insecure-redirect
+policy:
+  failOn: critical
+  newOnly: false
 thresholds:
   bugbotAutoFix: 85
   bugbotProposePatch: 60

package/scripts/autoregress.ts

@@ -3,11 +3,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { execSync, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { selectSnapshots } from '../src/snapshots/impact-selector.ts';
+import { selectSnapshots } from './snapshots/impact-selector.ts';
 import OpenAI from 'openai';
-import { buildImportMap } from '../src/snapshots/import-scanner.ts';
+import { buildImportMap } from './snapshots/import-scanner.ts';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -38,11 +38,15 @@ export function diffBaselines(baselineJson: string, currentJson: string): string
 
 function getChangedFiles(since?: string): string[] | null {
   try {
-    const base = since
-      ? since
-      : execSync('git merge-base origin/main HEAD', { cwd: ROOT }).toString().trim();
-    const out = execSync(`git diff ${base} HEAD --name-only`, { cwd: ROOT }).toString();
-    return out.trim().split('\n').filter(Boolean);
+    let base = since;
+    if (!base) {
+      const r = spawnSync('git', ['merge-base', 'origin/main', 'HEAD'], { cwd: ROOT, encoding: 'utf8' });
+      if (r.status !== 0) return null;
+      base = r.stdout.trim();
+    }
+    const r = spawnSync('git', ['diff', base, 'HEAD', '--name-only'], { cwd: ROOT, encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    return r.stdout.trim().split('\n').filter(Boolean);
   } catch { return null; }
 }
 
@@ -146,8 +150,17 @@ function cmdUpdate(args: string[]): number {
       continue;
     }
     process.stdout.write(`  ${snap} ... `);
+    const slug2 = path.basename(snap, '.snap.ts');
+    const baselinePath = path.join(BASELINES_DIR, `${slug2}.json`);
+    const beforeMtime = fs.existsSync(baselinePath) ? fs.statSync(baselinePath).mtimeMs : 0;
     runSnapshot(snap, true);
-    console.log('updated');
+    const captured = fs.existsSync(baselinePath) && fs.statSync(baselinePath).mtimeMs > beforeMtime;
+    if (captured) {
+      console.log('updated');
+    } else {
+      console.error('CAPTURE FAILED (baseline not written)');
+      failed++;
+    }
   }
   return failed > 0 ? 1 : 0;
 }
@@ -167,7 +180,7 @@ Write a snapshot test file. Requirements:
    // @source-commit: {sourceCommit}
    // @generator-version: {version}
 2. Import the module's exported functions under test
-3. Import { normalizeSnapshot } from '../../src/snapshots/serializer.ts'
+3. Import { normalizeSnapshot } from '../../scripts/snapshots/serializer.ts'
 4. Import fs from 'node:fs', describe/it from 'node:test', assert from 'node:assert/strict'
 5. Baseline loading pattern (use slug {slug}):
    const SLUG = '{slug}';
@@ -219,7 +232,10 @@ async function cmdGenerate(args: string[]): Promise<number> {
 
   const client = new OpenAI({ apiKey });
   let sourceCommit = 'unknown';
-  try { sourceCommit = execSync('git rev-parse --short HEAD', { cwd: ROOT }).toString().trim(); } catch {}
+  try {
+    const r = spawnSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: ROOT, encoding: 'utf8' });
+    if (r.status === 0) sourceCommit = r.stdout.trim();
+  } catch {}
   const generatedAt = new Date().toISOString();
 
   for (const srcFile of srcFiles) {

package/skills/autopilot/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: autopilot
+description: After spec approval, automatically execute the full pipeline — plan → implement → migrate → validate → PR → Codex review. No manual intervention required.
+---
+
+# Autopilot — Spec to PR Pipeline
+
+After the user approves a spec during brainstorming, this skill runs the full pipeline automatically.
+
+## Prerequisites
+
+- Approved spec file at `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+- Superpowers plugin installed (`writing-plans`, `using-git-worktrees`, `subagent-driven-development`)
+- Scripts installed and dependencies present (run step 0 preflight to verify)
+
+## CRITICAL: Do Not Pause
+
+**Run the entire pipeline without stopping.** Do NOT:
+- Ask "want me to continue?" between steps
+- Show intermediate results or ask for confirmation
+- Pause to report progress mid-pipeline
+- Wait for user input between any steps
+
+The ONLY time you stop is if a step **fails and cannot be recovered**. Otherwise, execute all steps sequentially and report ONCE at the end (Step 9).
+
+Brief status lines like `[autopilot] Step 3: Executing plan...` are fine. Full summaries, questions, or check-ins are not.
+
+## Pipeline
+
+Execute these steps in order. Do NOT pause between steps unless a step fails.
+
+### Step 0: Preflight
+
+```bash
+npx tsx scripts/preflight.ts
+```
+
+If any check **fails** (red ✗): stop and tell the user what to fix before continuing.
+If checks only **warn** (yellow !): proceed — degraded steps will be noted in the final report.
+If all pass: continue immediately, no user interaction needed.
+
+### Step 1: Write Implementation Plan
+
+```
+Invoke: superpowers:writing-plans
+Input: The approved spec file
+Output: Plan at docs/superpowers/plans/YYYY-MM-DD-<topic>.md
+```
+
+Commit the plan. Do NOT ask the user for execution choice — always use subagent-driven development.
+
+### Step 2: Set Up Worktree
+
+```
+Invoke: superpowers:using-git-worktrees
+Branch: feature/<topic-slug>
+```
+
+After the worktree is created, symlink the local env file into it so scripts
+(validate, Codex review, migrate) can read secrets:
+
+```bash
+# Detect which env file the project uses
+ENV_FILE=$(ls .env.local .env.dev .env.development .env 2>/dev/null | head -1)
+if [ -n "$ENV_FILE" ]; then
+  ln -sf "$(pwd)/$ENV_FILE" ".claude/worktrees/<branch>/$ENV_FILE"
+fi
+```
+
+If no env file is found, note it in the preflight output (step 0 will have caught this).
+
+### Step 3: Execute Plan
+
+```
+Invoke: superpowers:subagent-driven-development
+Input: The plan file
+Mode: dispatch fresh subagent per task
+```
+
+For each task:
+- Dispatch implementer subagent
+- On completion: verify commit landed in worktree
+- Skip formal spec/quality review to maintain speed (the validate step catches issues)
+- If subagent fails to write to worktree: implement directly
+
+### Step 4: Auto-Migrate
+
+For any `.sql` files created in `data/deltas/` during implementation:
+
+```bash
+/migrate
+```
+
+Run against **dev only** by default. Stop after dev succeeds and continue the pipeline.
+
+Only promote to QA → prod if the user has explicitly enabled it (e.g., `AUTOPILOT_ALLOW_PROD_MIGRATIONS=true` in their env) or asked for it directly. Production migrations are irreversible — never auto-promote without a clear signal.
+
+If migration fails, fix the SQL and retry (max 2 retries). If it still fails, stop and report.
+
+### Step 5: Validate
+
+```bash
+npx tsx scripts/validate.ts --commit-autofix --allow-dirty
+```
+
+If FAIL:
+- Read the validation report at `.claude/validation-report.json`
+- Fix the blocking issues
+- Re-run validate
+- Max 3 retry iterations
+
+If PASS: proceed to PR.
+
+### Step 6: Push + Create PR
+
+```bash
+git push -u origin <branch>
+gh pr create --title "<concise title>" --body "<generated PR body with spec link, test plan>"
+```
+
+### Step 7: Codex PR Review
+
+```bash
+npx tsx scripts/codex-pr-review.ts <pr-number>
+```
+
+Posts Codex review as a GitHub PR comment. If critical findings:
+- Fix them on the branch
+- Push
+- Re-run Codex review
+- Max 2 iterations
+
+### Step 8: Bugbot Triage + Fix
+
+Wait 60 seconds for Cursor bugbot to post comments, then:
+
+```bash
+npx tsx scripts/bugbot.ts --pr <pr-number>
+```
+
+Triages each finding (real bug vs false positive), auto-fixes real bugs, dismisses false positives with GitHub replies. If fixes applied:
+- Push
+- Wait for new bugbot comments (30s)
+- Re-run /bugbot
+- Max 3 rounds
+
+### Step 9: Report
+
+Tell the user:
+- PR URL
+- Test count
+- Validation verdict
+- Codex review summary
+- Bugbot triage summary (fixed / dismissed / needs-human)
+- Any human-required items that couldn't be auto-fixed
+
+## Error Recovery
+
+- **Subagent failure:** Re-dispatch with more context or implement directly
+- **Migration failure:** Fix SQL, re-run /migrate
+- **Validate failure:** Fix issues, re-run (max 3 retries)
+- **Codex critical findings:** Fix, push, re-review (max 2 retries)
+- **Bugbot findings:** /bugbot handles triage + fix automatically (max 3 rounds)
+- **Unrecoverable error:** Stop, report what was completed, show remaining work
+
+## When NOT to Use
+
+- During brainstorming (this runs AFTER spec approval)
+- For hotfixes (too heavy — just commit and push)
+- When the user wants manual control over each step

package/skills/claude-autopilot.md

@@ -0,0 +1,80 @@
+---
+name: claude-autopilot
+description: Autonomous development pipeline — brainstorm → spec → plan → implement → migrate → validate → PR → review → merge. Use when the user asks to "ship", "implement", "build", or "autopilot" a feature that's past the idea stage. Runs end-to-end without pausing for check-ins.
+---
+
+# claude-autopilot — Agent Loop
+
+This skill drives the full claude-autopilot pipeline when a user asks Claude to ship a feature. It is an *agent loop*, not a CLI reference — the commands it invokes are an implementation detail. The skill's job is to decide which phase applies, when to pause for user approval, and when to recover from a failed phase.
+
+## When to invoke
+
+- User says "ship X", "implement X", "build X", "autopilot X", or hands Claude a spec and says "go"
+- User approved a spec during `/brainstorm` and the next step is implementation
+- User is resuming a paused pipeline after fixing a failed phase by hand
+
+## When NOT to invoke
+
+- User is still in discovery ("help me think through X") — invoke `brainstorming` first
+- User wants Claude to run one specific phase only (they'll invoke that skill directly — `migrate`, `review`, `triage`, etc.)
+- User is hot-fixing a bug — too heavy, just edit and push
+
+## The pipeline
+
+Each phase writes its output to disk. Claude can stop, the user can edit the artifact, and Claude can resume from that phase without re-running earlier ones.
+
+| Phase | Artifact | What Claude does | When it stops |
+|---|---|---|---|
+| **Brainstorm** | `docs/specs/YYYY-MM-DD-<topic>-design.md` | Invokes `brainstorming` skill to turn idea into reviewed spec | When spec is committed + user approves |
+| **Spec review** | PR comment or inline notes | Invokes `codex-review` skill against the spec file | After one round unless criticals found |
+| **Plan** | `docs/plans/YYYY-MM-DD-<topic>.md` | Invokes `writing-plans` to break spec into phases | When plan is committed |
+| **Plan review** | Inline notes | Invokes `codex-review` skill against the plan | After one round unless criticals found |
+| **Branch** | git worktree at `.claude/worktrees/<slug>` or branch on HEAD | Invokes `using-git-worktrees` or cuts branch directly | When branch exists |
+| **Implement** | Git commits on the branch | Invokes `subagent-driven-development`, one subagent per plan phase | When all plan phases have landing commits |
+| **Migrate** | SQL deltas applied | Invokes `migrate` skill if DB migrations exist in the branch; skips otherwise | When all environments (dev → QA → prod) are in sync |
+| **Validate** | `.claude/validation-report.json` | Runs static rules + tests + typecheck + LLM review via `claude-autopilot run` | When validation passes or after 3 failed retries |
+| **PR** | GitHub PR number | Invokes `commit-push-pr` or runs `gh pr create` directly | When PR is open |
+| **PR review** | PR comment | Invokes `review-2pass` or `codex-pr-review` against the PR | After one round unless criticals found |
+| **Triage** | Bugbot thread replies + follow-up commits | Invokes `bugbot` skill to triage reviewer findings | When all HIGH severity items are resolved or human-dismissed |
+
+## Core rules
+
+1. **Do not pause mid-pipeline.** Once past the Brainstorm gate (which is inherently interactive), execute phases end-to-end. Do not ask "want me to continue?" between phases. Do not show intermediate reports. The user gets one report at the end.
+2. **Each phase's artifact is the source of truth for the next.** If the plan file changes between phases, the implementation uses the new plan. Claude does not keep phase outputs in memory — re-read from disk.
+3. **Failure in a phase triggers recovery, not pause.**
+   - Migration fails → fix the SQL, re-run.
+   - Validation fails → read the report, fix the blockers, re-run (max 3 attempts).
+   - PR review finds criticals → fix on branch, push, re-review (max 2 rounds).
+   - Bugbot finds real bugs → fix, push, re-triage (max 3 rounds).
+   - Unrecoverable failure → stop, report what completed, show what remains.
+4. **Codex review is part of the loop, not optional.** The pipeline explicitly dispatches to `gpt-5.3-codex` for spec review, plan review, and PR review. This is the multi-model moat — don't skip it.
+5. **Skills are swappable.** `review-2pass` and `council` are alternative review phases — a user can configure which runs. The pipeline doesn't hardcode Claude or Codex.
+
+## Phase outputs
+
+Every phase writes to a predictable path. If Claude crashes or the user stops the pipeline, the resume point is "whatever's the newest unfinished artifact."
+
+```
+docs/
+├── specs/YYYY-MM-DD-<topic>-design.md      # from Brainstorm
+├── plans/YYYY-MM-DD-<topic>.md             # from Plan
+└── reviews/<PR>-codex.md                   # from PR review (optional)
+.claude/
+├── validation-report.json                  # from Validate
+└── bugbot-state.json                       # from Triage
+```
+
+## Recovery
+
+- **Resume mid-pipeline.** User runs `/autopilot` after fixing a failed phase. Claude reads the newest artifacts, skips completed phases, starts from the first incomplete one.
+- **Skip a phase.** `/autopilot --skip migrate` — useful when the pipeline auto-detection is wrong (no migrations exist but the skill wants to run).
+- **Rewire a phase.** User edits `.claude/skills/autopilot/SKILL.md` to swap `review-2pass` for `council`. Claude picks up the change on next invocation — skill is the config.
+
+## Why this skill exists separately from CLI subcommands
+
+The CLI subcommands (`claude-autopilot run`, `claude-autopilot migrate`, etc.) are imperative — each does one thing. This skill is declarative — it describes the pipeline's *loop invariants* (phase order, artifact paths, recovery rules, when to pause). Claude reads this skill to decide *which* CLI subcommand to run *next*. Users who want to run one phase by hand use the CLI; users who want Claude to drive the whole pipeline invoke this skill.
+
+See also:
+- `skills/autopilot/SKILL.md` — detailed step-by-step runbook (deprecated alias for this file in v5; retained for back-compat)
+- `skills/migrate/SKILL.md` — migrate phase runbook
+- `skills/guardrail.md` — review phase alias (legacy; use `review` subcommand directly)

package/skills/guardrail.md

@@ -0,0 +1,39 @@
+---
+name: guardrail
+description: (Legacy alias) LLM-powered code review — runs static rules + LLM review over git-changed files. As of v5, this is the review *phase* of claude-autopilot. Invoke via `claude-autopilot run` or the full pipeline via `claude-autopilot` skill.
+---
+
+# guardrail — review phase (legacy alias)
+
+As of `@delegance/claude-autopilot@5.0.0`, `guardrail` is the review phase of the full pipeline, not a standalone product. This skill is preserved as a back-compat alias for Claude Code agents that were configured against v4.x.
+
+**For new configurations**, invoke `skills/claude-autopilot.md` to drive the full pipeline, or use the flat review subcommands (`run`, `scan`, `ci`, etc.) for just the review phase. Grouped syntax (`claude-autopilot review <verb>`) lands in alpha.2.
+
+## What it does
+
+Static rules (`hardcoded-secrets`, `sql-injection`, `missing-auth`, `ssrf`, `insecure-redirect`, `npm-audit`, `package-lock-sync`, `console-log`, `todo-fixme`, `large-file`, `missing-tests`, `brand-tokens`, `schema-alignment`) run first, then an LLM reviewer (`claude`, `codex`, `gemini`, or `openai-compatible`) gets the code with context. Output is SARIF / JUnit / inline PR comments.
+
+## When to use
+
+- Before creating a PR — `claude-autopilot run --base main`
+- To audit a path without git changes — `claude-autopilot scan src/auth/`
+- To ask a targeted question — `claude-autopilot scan --ask "is there an IDOR here?" src/api/`
+- Inside CI — `claude-autopilot ci`
+- Dev loop — `claude-autopilot watch`
+
+## Legacy commands that still work
+
+All v4 `guardrail <cmd>` invocations work unchanged through v5.x. A one-line deprecation notice prints on first invocation per terminal session. Migration guide: `docs/migration/v4-to-v5.md`.
+
+```bash
+guardrail run --base main        # still works — equivalent to `claude-autopilot run --base main`
+guardrail scan src/auth/         # still works
+guardrail ci                     # still works
+```
+
+## What changed in v5
+
+- `guardrail` is now one phase of a pipeline, not a standalone product.
+- The full pipeline runs via the `claude-autopilot` skill or `claude-autopilot` CLI.
+- Review subcommands remain flat in alpha.1 (`run`, `scan`, `ci`, `explain`, `fix`, `baseline`). The grouped `claude-autopilot review <verb>` syntax arrives in alpha.2 as an alias — flat forms will continue to work.
+- The package is `@delegance/claude-autopilot` — the old `@delegance/guardrail` will be a thin tombstone forwarding to the new package in v5.0.0 GA.

package/skills/migrate/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: migrate
+description: Run database migrations against Supabase environments (dev → QA → prod). Validates SQL, executes with ledger tracking, and auto-generates types/supabase.ts.
+---
+
+# Database Migration
+
+Run a migration through the dev → QA → prod pipeline with validation at each step.
+
+## Usage
+
+### 1. Identify the migration file
+
+If given as argument, use that. Otherwise find the most recently modified `.sql` file in `data/deltas/`.
+
+### 2. Validate (dry run on dev)
+
+```bash
+npx tsx scripts/supabase/migrate.ts <file> --env dev --dry-run
+```
+
+Present validation results. If errors, help the user fix them before proceeding.
+
+### 3. Run on dev
+
+```bash
+npx tsx scripts/supabase/migrate.ts <file> --env dev
+```
+
+### 4. Ask the user
+
+> "Migration succeeded on dev. `types/supabase.ts` updated. Promote to QA?"
+
+### 5. Run on QA
+
+```bash
+npx tsx scripts/supabase/migrate.ts --promote qa
+```
+
+### 6. Ask the user
+
+> "Migration succeeded on QA. Promote to prod?"
+
+### 7. Run on prod
+
+```bash
+npx tsx scripts/supabase/migrate.ts --promote prod --confirm-prod
+```
+
+### 8. Commit
+
+After all environments are done, commit the updated `types/supabase.ts` and the migration file:
+
+```bash
+git add types/supabase.ts data/deltas/<migration-file>
+git commit -m "feat: <description of schema change>"
+```
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--env dev\|qa\|prod` | Target environment |
+| `--dry-run` | Validate only, don't execute |
+| `--force` | Allow destructive operations (DROP, TRUNCATE) |
+| `--confirm-prod` | Required for prod execution |
+| `--promote qa\|prod` | Run missing migrations from source env |
+
+## Validation Checks
+
+The system validates before every execution:
+- Duplicate table/column detection
+- snake_case naming enforcement
+- RLS + policy required for every new table
+- Destructive operation blocking (unless --force)
+- Cross-env prerequisite verification
+- Checksum integrity (modified files are rejected)
+- Promotion chain enforcement (prod requires QA first)
+
+## Requirements
+
+- `.claude/supabase-envs.json` with `dbUrl` for each env (gitignored)
+- `postgres` npm package installed

package/src/adapters/council/claude.ts

@@ -0,0 +1,41 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { GuardrailError } from '../../core/errors.ts';
+import { classifyError } from '../review-engine/prompt-builder.ts';
+import type { CouncilAdapter } from './types.ts';
+
+const SYSTEM_PROMPT = `You are a technical advisor reviewing a software design decision. Evaluate the provided context and question critically. Be direct and specific. Surface tradeoffs, risks, and your recommendation.`;
+const MAX_OUTPUT_TOKENS = 2048;
+
+export function makeClaudeCouncilAdapter(model: string, label: string): CouncilAdapter {
+  return {
+    label,
+    async consult(prompt: string, context: string): Promise<string> {
+      const apiKey = process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        throw new GuardrailError('ANTHROPIC_API_KEY not set', { code: 'auth', provider: 'claude' });
+      }
+      const client = new Anthropic({ apiKey });
+      let response: Anthropic.Message;
+      try {
+        response = await client.messages.create({
+          model,
+          max_tokens: MAX_OUTPUT_TOKENS,
+          system: SYSTEM_PROMPT,
+          messages: [{ role: 'user', content: `## Context\n\n${context}\n\n## Question\n\n${prompt}` }],
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const code = classifyError(message);
+        throw new GuardrailError(`Claude council call failed: ${message}`, {
+          code,
+          provider: 'claude',
+          retryable: code === 'rate_limit',
+        });
+      }
+      return response.content
+        .filter(b => b.type === 'text')
+        .map(b => (b as Anthropic.TextBlock).text)
+        .join('');
+    },
+  };
+}

package/src/adapters/council/openai.ts

@@ -0,0 +1,40 @@
+import OpenAI from 'openai';
+import { GuardrailError } from '../../core/errors.ts';
+import { classifyError } from '../review-engine/prompt-builder.ts';
+import type { CouncilAdapter } from './types.ts';
+
+const SYSTEM_PROMPT = `You are a technical advisor reviewing a software design decision. Evaluate the provided context and question critically. Be direct and specific. Surface tradeoffs, risks, and your recommendation.`;
+const MAX_OUTPUT_TOKENS = 2048;
+
+export function makeOpenAICouncilAdapter(model: string, label: string): CouncilAdapter {
+  return {
+    label,
+    async consult(prompt: string, context: string): Promise<string> {
+      const apiKey = process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        throw new GuardrailError('OPENAI_API_KEY not set', { code: 'auth', provider: 'openai' });
+      }
+      const client = new OpenAI({ apiKey });
+      let response: OpenAI.ChatCompletion;
+      try {
+        response = await client.chat.completions.create({
+          model,
+          max_tokens: MAX_OUTPUT_TOKENS,
+          messages: [
+            { role: 'system', content: SYSTEM_PROMPT },
+            { role: 'user', content: `## Context\n\n${context}\n\n## Question\n\n${prompt}` },
+          ],
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const code = classifyError(message);
+        throw new GuardrailError(`OpenAI council call failed: ${message}`, {
+          code,
+          provider: 'openai',
+          retryable: code === 'rate_limit',
+        });
+      }
+      return response.choices[0]?.message?.content ?? '';
+    },
+  };
+}

package/src/adapters/council/types.ts

@@ -0,0 +1,7 @@
+// Council adapters are factory-created (not loaded via src/adapters/loader.ts),
+// so they don't implement AdapterBase. `label` is a display name for output
+// grouping, distinct from the machine-identifier `name` on AdapterBase.
+export interface CouncilAdapter {
+  readonly label: string;
+  consult(prompt: string, context: string): Promise<string>;
+}

package/src/adapters/loader.ts

@@ -1,5 +1,5 @@
 import * as path from 'node:path';
-import { AutopilotError } from '../core/errors.ts';
+import { GuardrailError } from '../core/errors.ts';
 import { checkApiVersionCompatibility, type AdapterBase } from './base.ts';
 
 export type IntegrationPoint = 'review-engine' | 'vcs-host' | 'migration-runner' | 'review-bot-parser';
@@ -42,7 +42,7 @@ export async function loadAdapter<T extends AdapterBase>(options: LoadAdapterOpt
 
   if (isPathRef(ref)) {
     if (!options.unsafeAllowLocalAdapters) {
-      throw new AutopilotError(
+      throw new GuardrailError(
         `Path-based adapter refs require unsafeAllowLocalAdapters:true — set this only for trusted local adapters`,
         { code: 'invalid_config', details: { point, ref } }
       );
@@ -51,7 +51,7 @@ export async function loadAdapter<T extends AdapterBase>(options: LoadAdapterOpt
   } else {
     const builtin = BUILTIN_PATHS[point]?.[ref];
     if (!builtin) {
-      throw new AutopilotError(`Unknown built-in ${point} adapter: "${ref}"`, {
+      throw new GuardrailError(`Unknown built-in ${point} adapter: "${ref}"`, {
         code: 'invalid_config',
         details: { point, ref, available: Object.keys(BUILTIN_PATHS[point] ?? {}) },
       });
@@ -63,7 +63,7 @@ export async function loadAdapter<T extends AdapterBase>(options: LoadAdapterOpt
   try {
     mod = (await import(modulePath)) as { default?: T } | T;
   } catch (err) {
-    throw new AutopilotError(`Failed to import adapter from ${modulePath}`, {
+    throw new GuardrailError(`Failed to import adapter from ${modulePath}`, {
       code: 'invalid_config',
       details: { point, ref, modulePath, cause: err instanceof Error ? err.message : String(err) },
     });
@@ -71,7 +71,7 @@ export async function loadAdapter<T extends AdapterBase>(options: LoadAdapterOpt
 
   const adapter = ('default' in mod ? mod.default : mod) as T;
   if (!adapter || typeof adapter !== 'object') {
-    throw new AutopilotError(`Adapter module did not export a valid adapter object`, {
+    throw new GuardrailError(`Adapter module did not export a valid adapter object`, {
       code: 'invalid_config',
       details: { point, ref, modulePath },
     });
@@ -80,7 +80,7 @@ export async function loadAdapter<T extends AdapterBase>(options: LoadAdapterOpt
   validateShape(adapter, point, modulePath);
 
   if (!checkApiVersionCompatibility(adapter.apiVersion)) {
-    throw new AutopilotError(`Adapter apiVersion ${adapter.apiVersion} incompatible with core`, {
+    throw new GuardrailError(`Adapter apiVersion ${adapter.apiVersion} incompatible with core`, {
       code: 'invalid_config',
       details: { point, ref, adapterApiVersion: adapter.apiVersion },
     });
@@ -99,7 +99,7 @@ function validateShape(adapter: AdapterBase, point: IntegrationPoint, modulePath
     missing.push('name/apiVersion');
   }
   if (missing.length > 0) {
-    throw new AutopilotError(
+    throw new GuardrailError(
       `Adapter at ${modulePath} missing required methods: ${missing.join(', ')}`,
       { code: 'invalid_config', details: { point, modulePath, missing } }
     );

package/src/adapters/review-engine/auto.ts

@@ -1,6 +1,6 @@
 import type { Capabilities } from '../base.ts';
 import type { ReviewEngine, ReviewInput, ReviewOutput } from './types.ts';
-import { AutopilotError } from '../../core/errors.ts';
+import { GuardrailError } from '../../core/errors.ts';
 import { detectProviderUsage, dominantProvider, type Provider } from '../../core/detect/provider-usage.ts';
 
 interface AvailableProvider {
@@ -50,7 +50,7 @@ async function resolveAdapter(cwd: string): Promise<ReviewEngine> {
   const available = getAvailableProviders();
 
   if (available.length === 0) {
-    throw new AutopilotError(
+    throw new GuardrailError(
       'No LLM API key found. Set one of: ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, GROQ_API_KEY',
       { code: 'auth', provider: 'auto' },
     );