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

package/src/core/ignore/index.ts

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { minimatch } from 'minimatch';
 import type { Finding } from '../findings/types.ts';
-import type { AutopilotConfig } from '../config/types.ts';
+import type { GuardrailConfig } from '../config/types.ts';
 
 export interface IgnoreRule {
   ruleId: string | '*';  // finding id prefix or '*' for any
@@ -10,7 +10,7 @@ export interface IgnoreRule {
 }
 
 export function loadIgnoreRules(cwd: string): IgnoreRule[] {
-  const filePath = path.join(cwd, '.autopilot-ignore');
+  const filePath = path.join(cwd, '.guardrail-ignore');
   if (!fs.existsSync(filePath)) return [];
 
   const rules: IgnoreRule[] = [];
@@ -37,8 +37,8 @@ function matchesRule(finding: Finding, rule: IgnoreRule): boolean {
   return minimatch(finding.file.replace(/\\/g, '/'), rule.pathGlob, { matchBase: true });
 }
 
-/** Convert `ignore:` entries from autopilot.config.yaml into IgnoreRules. */
-export function parseConfigIgnore(entries: AutopilotConfig['ignore']): IgnoreRule[] {
+/** Convert `ignore:` entries from guardrail.config.yaml into IgnoreRules. */
+export function parseConfigIgnore(entries: GuardrailConfig['ignore']): IgnoreRule[] {
   if (!entries || entries.length === 0) return [];
   return entries.map(entry => {
     if (typeof entry === 'string') {

package/src/core/mcp/concurrency.ts

@@ -0,0 +1,16 @@
+const mutexes = new Map<string, Promise<void>>();
+
+export async function withWriteLock<T>(workspace: string, fn: () => Promise<T>): Promise<T> {
+  let unlock!: () => void;
+  const current = new Promise<void>(resolve => { unlock = resolve; });
+  const prev = mutexes.get(workspace) ?? Promise.resolve();
+  mutexes.set(workspace, current);
+
+  await prev;
+  try {
+    return await fn();
+  } finally {
+    unlock();
+    if (mutexes.get(workspace) === current) mutexes.delete(workspace);
+  }
+}

package/src/core/mcp/handlers/fix-finding.ts

@@ -0,0 +1,126 @@
+// src/core/mcp/handlers/fix-finding.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveWorkspace, assertInWorkspace } from '../workspace.ts';
+import { loadRun, checksumFile } from '../run-store.ts';
+import { withWriteLock } from '../concurrency.ts';
+import { generateFix, buildUnifiedDiff } from '../../fix/generator.ts';
+import type { ReviewEngine } from '../../../adapters/review-engine/types.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+
+export interface FixFindingResult {
+  schema_version: 1;
+  status: 'fixed' | 'reverted' | 'human_required' | 'skipped';
+  reason?: string;
+  patch?: string;
+  commitSha?: string;
+  appliedFiles: string[];
+}
+
+export async function handleFixFinding(
+  input: { run_id: string; finding_id: string; cwd?: string; dry_run?: boolean },
+  config: GuardrailConfig,
+  engine: ReviewEngine,
+): Promise<FixFindingResult> {
+  const workspace = resolveWorkspace(input.cwd);
+
+  const record = loadRun(workspace, input.run_id);
+  if (!record) {
+    throw Object.assign(
+      new Error(`run_not_found: no run with id "${input.run_id}"`),
+      { code: 'run_not_found' },
+    );
+  }
+
+  const finding = record.findings.find(f => f.id === input.finding_id);
+  if (!finding) {
+    throw Object.assign(
+      new Error(`finding_not_found: no finding with id "${input.finding_id}"`),
+      { code: 'finding_not_found' },
+    );
+  }
+
+  // Protected path check
+  if (finding.protectedPath) {
+    return { schema_version: 1, status: 'human_required', reason: 'protected_path', appliedFiles: [] };
+  }
+
+  // Validate finding.file against workspace boundary (run records could be tampered)
+  const absFile = assertInWorkspace(workspace, finding.file);
+
+  // Look up checksum under both the raw finding.file and its relative form,
+  // so the drift check works whether older runs stored absolute or relative keys.
+  const relKey = path.relative(workspace, absFile);
+  const savedChecksum = record.fileChecksums[finding.file] ?? record.fileChecksums[relKey] ?? '';
+
+  // Dry-run path: generate fix, return patch, no mutations
+  if (input.dry_run) {
+    const currentChecksum = checksumFile(absFile);
+    if (savedChecksum && currentChecksum !== savedChecksum) {
+      return { schema_version: 1, status: 'human_required', reason: 'file_changed', appliedFiles: [] };
+    }
+    const genResult = await generateFix(finding, engine, workspace);
+    if (genResult.status !== 'ok') {
+      return { schema_version: 1, status: 'human_required', reason: genResult.reason, appliedFiles: [] };
+    }
+    const patch = buildUnifiedDiff(
+      genResult.originalLines!,
+      genResult.replacementLines!,
+      finding.file,
+      genResult.startLine!,
+      { color: false }, // MCP clients parse patch text — no ANSI
+    );
+    return { schema_version: 1, status: 'skipped', reason: 'dry_run', patch, appliedFiles: [] };
+  }
+
+  // Apply path: checksum validation + fix generation run INSIDE the lock to
+  // prevent TOCTOU between two concurrent fix_finding calls on the same file.
+  return withWriteLock(workspace, async () => {
+    const currentChecksum = checksumFile(absFile);
+    if (savedChecksum && currentChecksum !== savedChecksum) {
+      return { schema_version: 1 as const, status: 'human_required' as const, reason: 'file_changed', appliedFiles: [] };
+    }
+
+    const genResult = await generateFix(finding, engine, workspace);
+    if (genResult.status !== 'ok') {
+      return { schema_version: 1 as const, status: 'human_required' as const, reason: genResult.reason, appliedFiles: [] };
+    }
+
+    const patch = buildUnifiedDiff(
+      genResult.originalLines!,
+      genResult.replacementLines!,
+      finding.file,
+      genResult.startLine!,
+      { color: false },
+    );
+
+    const originalContent = fs.readFileSync(absFile, 'utf8');
+    const allLines = originalContent.split('\n');
+    const newLines = [
+      ...allLines.slice(0, genResult.startLine! - 1),
+      ...genResult.replacementLines!,
+      ...allLines.slice(genResult.endLine!),
+    ];
+
+    const tmpFile = absFile + '.guardrail.tmp';
+    fs.writeFileSync(tmpFile, newLines.join('\n'), 'utf8');
+    fs.renameSync(tmpFile, absFile);
+
+    // Test verification
+    if (config.testCommand) {
+      const { spawnSync } = await import('node:child_process');
+      const testResult = spawnSync('/bin/sh', ['-c', config.testCommand], {
+        cwd: workspace,
+        shell: false,
+        timeout: 120_000,
+        encoding: 'utf8',
+      });
+      if (testResult.status !== 0) {
+        fs.writeFileSync(absFile, originalContent, 'utf8');
+        return { schema_version: 1 as const, status: 'reverted' as const, patch, appliedFiles: [] };
+      }
+    }
+
+    return { schema_version: 1 as const, status: 'fixed' as const, patch, appliedFiles: [finding.file] };
+  });
+}

package/src/core/mcp/handlers/get-capabilities.ts

@@ -0,0 +1,62 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as child_process from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveWorkspace } from '../workspace.ts';
+import type { GuardrailConfig, StaticRuleReference } from '../../config/types.ts';
+
+export interface CapabilitiesResult {
+  schema_version: 1;
+  adapter: string;
+  enabledRules: string[];
+  writeable: boolean;
+  gitAvailable: boolean;
+  testCommandConfigured: boolean;
+  guardrailVersion: string;
+}
+
+function readVersion(): string {
+  try {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../../../package.json');
+    return (JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version: string }).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+function isGitAvailable(workspace: string): boolean {
+  try {
+    // Safe: no user input, static arguments only
+    child_process.execFileSync('git', ['rev-parse', '--git-dir'], {
+      cwd: workspace,
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function extractRuleName(rule: StaticRuleReference): string {
+  return typeof rule === 'string' ? rule : rule.adapter;
+}
+
+export async function handleGetCapabilities(
+  input: { cwd?: string },
+  config: GuardrailConfig,
+  adapterName: string,
+): Promise<CapabilitiesResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  const staticRules = config.staticRules ?? [];
+  const enabledRules = staticRules.map(extractRuleName);
+
+  return {
+    schema_version: 1,
+    adapter: adapterName,
+    enabledRules,
+    writeable: true,
+    gitAvailable: isGitAvailable(workspace),
+    testCommandConfigured: !!config.testCommand,
+    guardrailVersion: readVersion(),
+  };
+}

package/src/core/mcp/handlers/get-findings.ts

@@ -0,0 +1,36 @@
+import { resolveWorkspace } from '../workspace.ts';
+import { loadRun } from '../run-store.ts';
+import type { Finding, Severity } from '../../findings/types.ts';
+
+export interface GetFindingsResult {
+  schema_version: 1;
+  run_id: string;
+  findings: Finding[];
+  cachedAt: string;
+}
+
+// Severity order: index 0 = highest priority
+const SEVERITY_ORDER = ['critical', 'warning', 'note'] as const;
+
+export async function handleGetFindings(input: {
+  run_id: string;
+  severity?: Severity;
+  cwd?: string;
+}): Promise<GetFindingsResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  const record = loadRun(workspace, input.run_id);
+  if (!record) {
+    throw Object.assign(
+      new Error(`run_not_found: no run with id "${input.run_id}"`),
+      { code: 'run_not_found' }
+    );
+  }
+
+  let findings = record.findings;
+  if (input.severity) {
+    const minIdx = SEVERITY_ORDER.indexOf(input.severity);
+    findings = findings.filter(f => SEVERITY_ORDER.indexOf(f.severity) <= minIdx);
+  }
+
+  return { schema_version: 1, run_id: input.run_id, findings, cachedAt: record.createdAt };
+}

package/src/core/mcp/handlers/review-diff.ts

@@ -0,0 +1,65 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import { resolveWorkspace } from '../workspace.ts';
+import { saveRun, checksumFile, pruneOldRuns } from '../run-store.ts';
+import { runGuardrail } from '../../pipeline/run.ts';
+import { resolveGitTouchedFiles } from '../../git/touched-files.ts';
+import { loadRulesFromConfig } from '../../static-rules/registry.ts';
+import { detectGitContext } from '../../detect/git-context.ts';
+import type { ReviewEngine } from '../../../adapters/review-engine/types.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+import type { Finding } from '../../findings/types.ts';
+
+export interface ReviewDiffResult {
+  schema_version: 1;
+  run_id: string;
+  findings: Finding[];
+  human_summary: string;
+  usage?: { costUSD?: number };
+}
+
+export async function handleReviewDiff(
+  input: { base?: string; cwd?: string; static_only?: boolean },
+  config: GuardrailConfig,
+  engine: ReviewEngine,
+): Promise<ReviewDiffResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  pruneOldRuns(workspace, 24 * 60 * 60 * 1000);
+
+  const touchedFiles = resolveGitTouchedFiles({ cwd: workspace, base: input.base });
+  const staticRules = config.staticRules ? await loadRulesFromConfig(config.staticRules) : [];
+  const gitCtx = detectGitContext(workspace);
+
+  const result = await runGuardrail({
+    touchedFiles,
+    config,
+    reviewEngine: engine,
+    staticRules,
+    cwd: workspace,
+    gitSummary: gitCtx.summary ?? undefined,
+    base: input.base,
+    skipReview: input.static_only ?? false,
+  });
+
+  const run_id = crypto.randomUUID();
+  const fileChecksums: Record<string, string> = {};
+  for (const f of touchedFiles) {
+    const abs = path.isAbsolute(f) ? f : path.resolve(workspace, f);
+    fileChecksums[f] = checksumFile(abs);
+  }
+  saveRun(workspace, run_id, result.allFindings, fileChecksums);
+
+  const critCount = result.allFindings.filter(f => f.severity === 'critical').length;
+  const warnCount = result.allFindings.filter(f => f.severity === 'warning').length;
+  const human_summary = result.allFindings.length === 0
+    ? 'No findings — looks clean.'
+    : `${result.allFindings.length} finding${result.allFindings.length !== 1 ? 's' : ''}: ${critCount} critical, ${warnCount} warning.`;
+
+  return {
+    schema_version: 1,
+    run_id,
+    findings: result.allFindings,
+    human_summary,
+    usage: result.totalCostUSD !== undefined ? { costUSD: result.totalCostUSD } : undefined,
+  };
+}

package/src/core/mcp/handlers/scan-files.ts

@@ -0,0 +1,65 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import { resolveWorkspace, assertInWorkspace } from '../workspace.ts';
+import { saveRun, checksumFile, pruneOldRuns } from '../run-store.ts';
+import { runReviewPhase } from '../../pipeline/review-phase.ts';
+import { detectStack } from '../../detect/stack.ts';
+import type { ReviewEngine } from '../../../adapters/review-engine/types.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+import type { Finding } from '../../findings/types.ts';
+
+export interface ScanFilesResult {
+  schema_version: 1;
+  run_id: string;
+  findings: Finding[];
+  human_summary: string;
+}
+
+export async function handleScanFiles(
+  input: { files: string[]; cwd?: string; ask?: string },
+  config: GuardrailConfig,
+  engine: ReviewEngine,
+): Promise<ScanFilesResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  pruneOldRuns(workspace, 24 * 60 * 60 * 1000);
+
+  // Validate all paths before any I/O
+  const resolvedFiles = input.files.map(f => assertInWorkspace(workspace, f));
+
+  const stack = detectStack(workspace) ?? config.stack;
+  const effectiveConfig: GuardrailConfig = input.ask
+    ? { ...config, stack: `${stack ?? 'unknown'}\n\nFocus: ${input.ask}` }
+    : config;
+
+  const result = await runReviewPhase({
+    touchedFiles: resolvedFiles,
+    config: effectiveConfig,
+    engine,
+    cwd: workspace,
+  });
+
+  const run_id = crypto.randomUUID();
+  const fileChecksums: Record<string, string> = {};
+  for (const f of resolvedFiles) {
+    // Store relative key so fix_finding's finding.file lookup matches
+    const relKey = path.relative(workspace, f);
+    fileChecksums[relKey] = checksumFile(f);
+  }
+  // Normalize finding.file to relative paths so downstream lookups against
+  // fileChecksums (keyed by relative paths) work regardless of whether the
+  // review engine echoed absolute or relative paths.
+  const normalizedFindings = result.findings.map(f => {
+    if (!f.file) return f;
+    const rel = path.isAbsolute(f.file) ? path.relative(workspace, f.file) : f.file;
+    return rel === f.file ? f : { ...f, file: rel };
+  });
+  saveRun(workspace, run_id, normalizedFindings, fileChecksums);
+
+  const critCount = result.findings.filter(f => f.severity === 'critical').length;
+  const warnCount = result.findings.filter(f => f.severity === 'warning').length;
+  const human_summary = result.findings.length === 0
+    ? 'No findings.'
+    : `${result.findings.length} finding${result.findings.length !== 1 ? 's' : ''}: ${critCount} critical, ${warnCount} warning.`;
+
+  return { schema_version: 1, run_id, findings: normalizedFindings, human_summary };
+}

package/src/core/mcp/handlers/validate-fix.ts

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+import { resolveWorkspace } from '../workspace.ts';
+import { withWriteLock } from '../concurrency.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+
+export interface ValidateFixResult {
+  schema_version: 1;
+  passed: boolean;
+  output: string;
+  durationMs: number;
+}
+
+export async function handleValidateFix(
+  input: { cwd?: string; files?: string[] },
+  config: GuardrailConfig,
+): Promise<ValidateFixResult> {
+  const workspace = resolveWorkspace(input.cwd);
+
+  if (!config.testCommand) {
+    return { schema_version: 1, passed: true, output: '', durationMs: 0 };
+  }
+
+  return withWriteLock(workspace, async () => {
+    const start = Date.now();
+    const result = spawnSync('/bin/sh', ['-c', config.testCommand!], {
+      cwd: workspace,
+      shell: false,
+      timeout: 120_000,
+      encoding: 'utf8',
+    });
+    const durationMs = Date.now() - start;
+    const raw = ((result.stdout ?? '') + (result.stderr ?? '')).slice(0, 4000);
+
+    return {
+      schema_version: 1 as const,
+      passed: result.status === 0,
+      output: raw,
+      durationMs,
+    };
+  });
+}

package/src/core/mcp/run-store.ts

@@ -0,0 +1,85 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import type { Finding } from '../findings/types.ts';
+
+const RUNS_DIR = '.guardrail-cache/runs';
+
+export interface RunRecord {
+  run_id: string;
+  createdAt: string;
+  findings: Finding[];
+  fileChecksums: Record<string, string>;
+}
+
+function runsDir(cwd: string): string {
+  return path.join(cwd, RUNS_DIR);
+}
+
+// Reject any run_id that isn't a safe filename component — path separators,
+// relative segments, hidden files, or empty strings.
+// run_ids are generated server-side as UUIDs (crypto.randomUUID) so strict
+// validation here is safe. MCP clients that fabricate run_ids get a clear
+// rejection instead of silently reading outside RUNS_DIR.
+const VALID_RUN_ID = /^[A-Za-z0-9_-]+$/;
+
+function assertValidRunId(runId: string): void {
+  if (!runId || typeof runId !== 'string' || !VALID_RUN_ID.test(runId)) {
+    throw Object.assign(
+      new Error(`invalid run_id: "${runId}" (expected alphanumeric + dash/underscore)`),
+      { code: 'invalid_run_id' },
+    );
+  }
+}
+
+function runFilePath(cwd: string, runId: string): string {
+  assertValidRunId(runId);
+  return path.join(runsDir(cwd), `${runId}.json`);
+}
+
+export function saveRun(
+  cwd: string,
+  runId: string,
+  findings: Finding[],
+  fileChecksums: Record<string, string>,
+): void {
+  const dir = runsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  const record: RunRecord = { run_id: runId, createdAt: new Date().toISOString(), findings, fileChecksums };
+  const tmp = runFilePath(cwd, runId) + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf8');
+  fs.renameSync(tmp, runFilePath(cwd, runId));
+}
+
+export function loadRun(cwd: string, runId: string): RunRecord | null {
+  const p = runFilePath(cwd, runId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as RunRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function checksumFile(filePath: string): string {
+  try {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch {
+    return '';
+  }
+}
+
+export function pruneOldRuns(cwd: string, maxAgeMs: number): void {
+  const dir = runsDir(cwd);
+  if (!fs.existsSync(dir)) return;
+  const cutoff = Date.now() - maxAgeMs;
+  for (const entry of fs.readdirSync(dir)) {
+    if (!entry.endsWith('.json')) continue;
+    const full = path.join(dir, entry);
+    try {
+      const stat = fs.statSync(full);
+      if (stat.mtimeMs < cutoff) fs.unlinkSync(full);
+    } catch { /* ignore */ }
+  }
+}

package/src/core/mcp/workspace.ts

@@ -0,0 +1,35 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export function resolveWorkspace(cwd?: string): string {
+  return fs.realpathSync(cwd ?? process.cwd());
+}
+
+export function assertInWorkspace(workspace: string, filePath: string): string {
+  const resolvedWorkspace = fs.realpathSync(workspace);
+  const abs = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(resolvedWorkspace, filePath);
+
+  let resolved: string;
+  try {
+    resolved = fs.realpathSync(abs);
+  } catch {
+    // File doesn't exist yet — check the directory
+    const dir = path.dirname(abs);
+    let resolvedDir: string;
+    try {
+      resolvedDir = fs.realpathSync(dir);
+    } catch {
+      // Parent directory doesn't exist — resolve what we can
+      resolvedDir = path.resolve(dir);
+    }
+    resolved = path.join(resolvedDir, path.basename(abs));
+  }
+
+  const root = resolvedWorkspace.endsWith(path.sep) ? resolvedWorkspace : resolvedWorkspace + path.sep;
+  if (!resolved.startsWith(root) && resolved !== resolvedWorkspace) {
+    throw new Error(`Path "${filePath}" is outside workspace "${workspace}"`);
+  }
+  return resolved;
+}

package/src/core/persist/baseline.ts

@@ -0,0 +1,112 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Finding } from '../findings/types.ts';
+
+const BASELINE_FILE = '.guardrail-baseline.json';
+
+export interface BaselineEntry {
+  id: string;
+  file: string;
+  line?: number;
+  severity: string;
+  message: string;
+  pinnedAt: string;
+  note?: string;
+}
+
+export interface Baseline {
+  version: 1;
+  createdAt: string;
+  updatedAt: string;
+  note?: string;
+  entries: BaselineEntry[];
+}
+
+/** Stable key for matching a finding against a baseline entry. */
+function baselineKey(f: { id: string; file: string; line?: number }): string {
+  return `${f.id}::${f.file}::${f.line ?? ''}`;
+}
+
+export function baselineFilePath(cwd: string, overridePath?: string): string {
+  return overridePath
+    ? path.isAbsolute(overridePath) ? overridePath : path.join(cwd, overridePath)
+    : path.join(cwd, BASELINE_FILE);
+}
+
+export function loadBaseline(cwd: string, overridePath?: string): Baseline | null {
+  const p = baselineFilePath(cwd, overridePath);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as Baseline;
+  } catch {
+    return null;
+  }
+}
+
+export function saveBaseline(cwd: string, findings: Finding[], options: { note?: string; overridePath?: string } = {}): Baseline {
+  const existing = loadBaseline(cwd, options.overridePath);
+  const now = new Date().toISOString();
+  const baseline: Baseline = {
+    version: 1,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    note: options.note ?? existing?.note,
+    entries: findings.map(f => ({
+      id: f.id,
+      file: f.file,
+      line: f.line,
+      severity: f.severity,
+      message: f.message,
+      pinnedAt: now,
+    })),
+  };
+  const p = baselineFilePath(cwd, options.overridePath);
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(baseline, null, 2), 'utf8');
+  fs.renameSync(tmp, p);
+  return baseline;
+}
+
+export function clearBaseline(cwd: string, overridePath?: string): void {
+  const p = baselineFilePath(cwd, overridePath);
+  if (fs.existsSync(p)) fs.unlinkSync(p);
+}
+
+export interface BaselineFilterResult {
+  newFindings: Finding[];
+  baselinedFindings: Finding[];
+  baselinedCount: number;
+}
+
+/** Returns findings NOT present in the baseline (new findings only). */
+export function filterBaselined(findings: Finding[], baseline: Baseline): BaselineFilterResult {
+  const pinned = new Set(baseline.entries.map(baselineKey));
+  const newFindings: Finding[] = [];
+  const baselinedFindings: Finding[] = [];
+  for (const f of findings) {
+    if (pinned.has(baselineKey(f))) {
+      baselinedFindings.push(f);
+    } else {
+      newFindings.push(f);
+    }
+  }
+  return { newFindings, baselinedFindings, baselinedCount: baselinedFindings.length };
+}
+
+export interface BaselineDiff {
+  added: Finding[];       // in current but not in baseline
+  resolved: BaselineEntry[]; // in baseline but not in current
+  unchanged: Finding[];   // in both
+}
+
+/** Diff current findings against a baseline snapshot. */
+export function diffAgainstBaseline(current: Finding[], baseline: Baseline): BaselineDiff {
+  const currentKeys = new Set(current.map(baselineKey));
+  const baselineKeys = new Set(baseline.entries.map(baselineKey));
+
+  return {
+    added:     current.filter(f => !baselineKeys.has(baselineKey(f))),
+    resolved:  baseline.entries.filter(e => !currentKeys.has(baselineKey(e))),
+    unchanged: current.filter(f => baselineKeys.has(baselineKey(f))),
+  };
+}

package/src/core/persist/cost-log.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const CACHE_DIR = '.autopilot-cache';
+const CACHE_DIR = '.guardrail-cache';
 const LOG_FILE = 'costs.jsonl';
 
 export interface CostLogEntry {