@soleri/core 9.0.3 → 9.2.0

package/src/runtime/facades/vault-facade.ts

@@ -1,6 +1,9 @@
 /**
  * Vault facade — knowledge management ops.
- * search, CRUD, import/export, intake, archival.
+ * search, CRUD, import/export, intake, sharing, linking.
+ * Archival and lifecycle ops are in archive-facade.ts.
+ * Sync ops (git, obsidian, packs) are in sync-facade.ts.
+ * Review ops are in review-facade.ts.
  */
 
 import { z } from 'zod';
@@ -13,7 +16,6 @@ import { createCaptureOps } from '../capture-ops.js';
 import { createIntakeOps } from '../intake-ops.js';
 import { createVaultSharingOps } from '../vault-sharing-ops.js';
 import { createVaultLinkingOps } from '../vault-linking-ops.js';
-import { ObsidianSync } from '../../vault/obsidian-sync.js';
 
 export function createVaultFacadeOps(runtime: AgentRuntime): OpDefinition[] {
   const { vault, brain, intakePipeline, textIngester, vaultManager } = runtime;
@@ -83,16 +85,25 @@ export function createVaultFacadeOps(runtime: AgentRuntime): OpDefinition[] {
         tags: z.array(z.string()).optional(),
         limit: z.number().optional(),
         offset: z.number().optional(),
+        verbose: z.boolean().optional().describe('Return full entry objects instead of summaries'),
       }),
       handler: async (params) => {
-        return vault.list({
+        const verbose = params.verbose === true;
+        const entries = vault.list({
           domain: params.domain as string | undefined,
           type: params.type as string | undefined,
           severity: params.severity as string | undefined,
           tags: params.tags as string[] | undefined,
-          limit: (params.limit as number) ?? 50,
+          limit: (params.limit as number) ?? 20,
           offset: (params.offset as number) ?? 0,
         });
+        if (verbose) {
+          return entries;
+        }
+        // Return lightweight summaries to reduce response size
+        return (entries as Array<{ id: string; title: string; type: string; domain: string; tags?: string[] }>).map(
+          (e) => ({ id: e.id, title: e.title, type: e.type, domain: e.domain, tags: e.tags ?? [] }),
+        );
       },
     },
     {
@@ -432,72 +443,6 @@ export function createVaultFacadeOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
-    // ─── Obsidian Sync ──────────────────────────────────────────
-    {
-      name: 'obsidian_export',
-      description:
-        'Export vault entries to Obsidian-compatible markdown files with YAML frontmatter. Creates domain subdirectories.',
-      auth: 'read',
-      schema: z.object({
-        obsidianDir: z.string().describe('Path to Obsidian vault directory'),
-        types: z.array(z.string()).optional().describe('Filter by entry types'),
-        domains: z.array(z.string()).optional().describe('Filter by domains'),
-        dryRun: z.boolean().optional().describe('Preview without writing files'),
-      }),
-      handler: async (params) => {
-        const sync = new ObsidianSync({ vault });
-        return sync.export(params.obsidianDir as string, {
-          types: params.types as string[] | undefined,
-          domains: params.domains as string[] | undefined,
-          dryRun: params.dryRun as boolean | undefined,
-        });
-      },
-    },
-    {
-      name: 'obsidian_import',
-      description:
-        'Import Obsidian markdown files with YAML frontmatter into the vault. Parses title, type, domain, tags from frontmatter.',
-      auth: 'write',
-      schema: z.object({
-        obsidianDir: z.string().describe('Path to Obsidian vault directory to import from'),
-        defaultType: z
-          .string()
-          .optional()
-          .describe('Default type for entries without frontmatter type'),
-        defaultDomain: z.string().optional().describe('Default domain for entries without one'),
-        dryRun: z.boolean().optional().describe('Preview without modifying vault'),
-      }),
-      handler: async (params) => {
-        const sync = new ObsidianSync({ vault });
-        return sync.import(params.obsidianDir as string, {
-          defaultType: params.defaultType as string | undefined,
-          defaultDomain: params.defaultDomain as string | undefined,
-          dryRun: params.dryRun as boolean | undefined,
-        });
-      },
-    },
-    {
-      name: 'obsidian_sync',
-      description:
-        'Bidirectional sync between vault and Obsidian directory. Modes: push (vault→Obsidian), pull (Obsidian→vault), bidirectional.',
-      auth: 'write',
-      schema: z.object({
-        obsidianDir: z.string().describe('Path to Obsidian vault directory'),
-        mode: z
-          .enum(['push', 'pull', 'bidirectional'])
-          .optional()
-          .describe('Sync mode. Default: bidirectional'),
-        dryRun: z.boolean().optional().describe('Preview without making changes'),
-      }),
-      handler: async (params) => {
-        const sync = new ObsidianSync({ vault });
-        return sync.sync(params.obsidianDir as string, {
-          mode: params.mode as 'push' | 'pull' | 'bidirectional' | undefined,
-          dryRun: params.dryRun as boolean | undefined,
-        });
-      },
-    },
-
     // ─── Satellite ops ───────────────────────────────────────────
     ...createVaultExtraOps(runtime),
     ...createCaptureOps(runtime),

package/src/runtime/feature-flags.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Colocated unit tests for feature-flags.ts — filesystem + env var behavior.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FeatureFlags } from './feature-flags.js';
+import { join } from 'node:path';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+describe('FeatureFlags', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'soleri-ff-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    for (const key of Object.keys(process.env)) {
+      if (key.startsWith('SOLERI_FLAG_')) delete process.env[key];
+    }
+  });
+
+  describe('defaults', () => {
+    it('has auth-enforcement off by default', () => {
+      expect(new FeatureFlags().isEnabled('auth-enforcement')).toBe(false);
+    });
+
+    it('has hot-reload on by default', () => {
+      expect(new FeatureFlags().isEnabled('hot-reload')).toBe(true);
+    });
+
+    it('has cognee-sync on by default', () => {
+      expect(new FeatureFlags().isEnabled('cognee-sync')).toBe(true);
+    });
+
+    it('has agency-mode off by default', () => {
+      expect(new FeatureFlags().isEnabled('agency-mode')).toBe(false);
+    });
+
+    it('returns false for unknown flags', () => {
+      expect(new FeatureFlags().isEnabled('does-not-exist')).toBe(false);
+    });
+  });
+
+  describe('file persistence', () => {
+    it('persists and loads flags from file', () => {
+      const path = join(tempDir, 'flags.json');
+      const f1 = new FeatureFlags(path);
+      f1.set('auth-enforcement', true);
+
+      const f2 = new FeatureFlags(path);
+      expect(f2.isEnabled('auth-enforcement')).toBe(true);
+    });
+
+    it('creates parent directories if needed', () => {
+      const path = join(tempDir, 'nested', 'deep', 'flags.json');
+      const flags = new FeatureFlags(path);
+      flags.set('hot-reload', false);
+      const data = JSON.parse(readFileSync(path, 'utf-8'));
+      expect(data['hot-reload']).toBe(false);
+    });
+
+    it('handles corrupt JSON gracefully', () => {
+      const path = join(tempDir, 'bad.json');
+      writeFileSync(path, '{{{invalid');
+      const flags = new FeatureFlags(path);
+      // Falls back to defaults
+      expect(flags.isEnabled('hot-reload')).toBe(true);
+    });
+
+    it('ignores non-boolean values in file', () => {
+      const path = join(tempDir, 'mixed.json');
+      writeFileSync(path, JSON.stringify({ 'hot-reload': 'yes', telemetry: false }));
+      const flags = new FeatureFlags(path);
+      // 'yes' is not boolean, so default (true) stays
+      expect(flags.isEnabled('hot-reload')).toBe(true);
+      expect(flags.isEnabled('telemetry')).toBe(false);
+    });
+
+    it('works in-memory when no file path given', () => {
+      const flags = new FeatureFlags();
+      flags.set('custom-flag', true);
+      expect(flags.isEnabled('custom-flag')).toBe(true);
+    });
+  });
+
+  describe('env var overrides', () => {
+    it('SOLERI_FLAG_TELEMETRY=false overrides default', () => {
+      process.env.SOLERI_FLAG_TELEMETRY = 'false';
+      expect(new FeatureFlags().isEnabled('telemetry')).toBe(false);
+    });
+
+    it('supports =1 as truthy', () => {
+      process.env.SOLERI_FLAG_AGENCY_MODE = '1';
+      expect(new FeatureFlags().isEnabled('agency-mode')).toBe(true);
+    });
+
+    it('env overrides file values', () => {
+      const path = join(tempDir, 'flags.json');
+      writeFileSync(path, JSON.stringify({ telemetry: true }));
+      process.env.SOLERI_FLAG_TELEMETRY = 'false';
+      expect(new FeatureFlags(path).isEnabled('telemetry')).toBe(false);
+    });
+
+    it('supports custom flag names via env', () => {
+      process.env.SOLERI_FLAG_MY_EXPERIMENT = 'true';
+      expect(new FeatureFlags().isEnabled('my-experiment')).toBe(true);
+    });
+  });
+
+  describe('getAll', () => {
+    it('includes all built-in flags', () => {
+      const all = new FeatureFlags().getAll();
+      expect(Object.keys(all)).toContain('auth-enforcement');
+      expect(Object.keys(all)).toContain('hot-reload');
+      expect(Object.keys(all)).toContain('telemetry');
+      expect(Object.keys(all)).toContain('cognee-sync');
+    });
+
+    it('reports source as env when env var set', () => {
+      process.env.SOLERI_FLAG_TELEMETRY = 'true';
+      const all = new FeatureFlags().getAll();
+      expect(all['telemetry'].source).toBe('env');
+    });
+
+    it('reports source as default for built-in without env', () => {
+      const all = new FeatureFlags().getAll();
+      expect(all['hot-reload'].source).toBe('default');
+    });
+
+    it('reports source as runtime for custom flags', () => {
+      const flags = new FeatureFlags();
+      flags.set('my-flag', true);
+      expect(flags.getAll()['my-flag'].source).toBe('runtime');
+      expect(flags.getAll()['my-flag'].description).toBe('Custom flag');
+    });
+  });
+});

package/src/runtime/github-integration.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseRemoteUrl,
+  extractIssueNumber,
+  detectGitHubRemote,
+  getIssueDetails,
+  closeIssueWithComment,
+} from './github-integration.js';
+
+describe('parseRemoteUrl', () => {
+  it('parses HTTPS remote with .git suffix', () => {
+    const result = parseRemoteUrl('https://github.com/acme/widget.git');
+    expect(result).toEqual({ owner: 'acme', repo: 'widget' });
+  });
+
+  it('parses HTTPS remote without .git suffix', () => {
+    const result = parseRemoteUrl('https://github.com/acme/widget');
+    expect(result).toEqual({ owner: 'acme', repo: 'widget' });
+  });
+
+  it('parses SSH remote with .git suffix', () => {
+    const result = parseRemoteUrl('git@github.com:acme/widget.git');
+    expect(result).toEqual({ owner: 'acme', repo: 'widget' });
+  });
+
+  it('parses SSH remote without .git suffix', () => {
+    const result = parseRemoteUrl('git@github.com:acme/widget');
+    expect(result).toEqual({ owner: 'acme', repo: 'widget' });
+  });
+
+  it('returns null for non-GitHub URLs', () => {
+    expect(parseRemoteUrl('https://gitlab.com/acme/widget.git')).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(parseRemoteUrl('')).toBeNull();
+  });
+
+  it('returns null for random text', () => {
+    expect(parseRemoteUrl('not-a-url-at-all')).toBeNull();
+  });
+});
+
+describe('extractIssueNumber', () => {
+  it('extracts issue number from #NNN', () => {
+    expect(extractIssueNumber('fixes #42')).toBe(42);
+  });
+
+  it('extracts first match when multiple present', () => {
+    expect(extractIssueNumber('#10 and #20')).toBe(10);
+  });
+
+  it('returns null when no issue number', () => {
+    expect(extractIssueNumber('no issues here')).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(extractIssueNumber('')).toBeNull();
+  });
+
+  it('handles issue in sentence context', () => {
+    expect(extractIssueNumber('closes #789 in this PR')).toBe(789);
+  });
+});
+
+describe('detectGitHubRemote', () => {
+  it('returns null when git command fails', async () => {
+    // Pass a path that is not a git repo
+    const result = await detectGitHubRemote('/tmp/definitely-not-a-repo-' + Date.now());
+    expect(result).toBeNull();
+  });
+});
+
+describe('getIssueDetails', () => {
+  it('returns null when gh CLI is not available or fails', async () => {
+    // gh issue view on a non-existent repo will fail
+    const result = await getIssueDetails('nonexistent-owner-xyz', 'nonexistent-repo-xyz', 99999);
+    expect(result).toBeNull();
+  });
+});
+
+describe('closeIssueWithComment', () => {
+  it('does not throw when gh CLI is not available', async () => {
+    // Should degrade gracefully
+    await expect(
+      closeIssueWithComment('nonexistent-owner-xyz', 'nonexistent-repo-xyz', 99999, 'test'),
+    ).resolves.toBeUndefined();
+  });
+});

package/src/runtime/github-integration.ts

@@ -0,0 +1,159 @@
+/**
+ * GitHub integration helpers for the planning lifecycle.
+ *
+ * Provides lightweight wrappers around git and the `gh` CLI for:
+ *   - Detecting the GitHub remote from a project path
+ *   - Extracting issue numbers from text
+ *   - Closing issues with a comment
+ *   - Fetching issue details
+ *
+ * All functions degrade gracefully — if `gh` is not installed or not
+ * authenticated, they return null / no-op instead of throwing.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GitHubRemote {
+  owner: string;
+  repo: string;
+}
+
+export interface GitHubIssueDetails {
+  title: string;
+  body: string;
+  labels: string[];
+}
+
+// ---------------------------------------------------------------------------
+// detectGitHubRemote
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the GitHub owner/repo from the git remote in a project directory.
+ * Parses both HTTPS and SSH remote URLs.
+ * Returns null if not a git repo or no GitHub remote found.
+ */
+export async function detectGitHubRemote(projectPath: string): Promise<GitHubRemote | null> {
+  try {
+    const { stdout } = await execFileAsync('git', ['remote', 'get-url', 'origin'], {
+      cwd: projectPath,
+      timeout: 10_000,
+      signal: AbortSignal.timeout(10_000),
+    });
+    return parseRemoteUrl(stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a GitHub owner/repo from a remote URL.
+ * Supports HTTPS and SSH formats.
+ */
+export function parseRemoteUrl(url: string): GitHubRemote | null {
+  // HTTPS: https://github.com/owner/repo.git
+  const https = url.match(/github\.com\/([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (https) return { owner: https[1], repo: https[2] };
+
+  // SSH: git@github.com:owner/repo.git
+  const ssh = url.match(/github\.com:([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (ssh) return { owner: ssh[1], repo: ssh[2] };
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// extractIssueNumber
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a GitHub issue number (#NNN) from arbitrary text.
+ * Matches patterns like "#123", "issue #456", "fixes #789", "closes #42".
+ * Returns the first match, or null if none found.
+ */
+export function extractIssueNumber(text: string): number | null {
+  const match = text.match(/#(\d+)/);
+  if (!match) return null;
+  const num = parseInt(match[1], 10);
+  return Number.isFinite(num) ? num : null;
+}
+
+// ---------------------------------------------------------------------------
+// getIssueDetails
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch issue details (title, body, labels) using the `gh` CLI.
+ * Returns null if `gh` is not available or the issue cannot be fetched.
+ */
+export async function getIssueDetails(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+): Promise<GitHubIssueDetails | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      'gh',
+      [
+        'issue', 'view', String(issueNumber),
+        '--repo', `${owner}/${repo}`,
+        '--json', 'title,body,labels',
+      ],
+      {
+        timeout: 10_000,
+        signal: AbortSignal.timeout(10_000),
+      },
+    );
+    const parsed = JSON.parse(stdout.trim()) as {
+      title: string;
+      body: string;
+      labels: Array<{ name: string }>;
+    };
+    return {
+      title: parsed.title,
+      body: parsed.body ?? '',
+      labels: (parsed.labels ?? []).map((l) => l.name),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// closeIssueWithComment
+// ---------------------------------------------------------------------------
+
+/**
+ * Close a GitHub issue and leave a comment summarizing what was done.
+ * No-ops gracefully if `gh` is not available.
+ */
+export async function closeIssueWithComment(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  comment: string,
+): Promise<void> {
+  const repoSlug = `${owner}/${repo}`;
+  try {
+    // Add comment first, then close
+    await execFileAsync(
+      'gh',
+      ['issue', 'comment', String(issueNumber), '--repo', repoSlug, '--body', comment],
+      { timeout: 10_000, signal: AbortSignal.timeout(10_000) },
+    );
+    await execFileAsync(
+      'gh',
+      ['issue', 'close', String(issueNumber), '--repo', repoSlug],
+      { timeout: 10_000, signal: AbortSignal.timeout(10_000) },
+    );
+  } catch {
+    // Graceful degradation — gh not available or auth expired
+  }
+}

package/src/runtime/grading-ops.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createGradingOps } from './grading-ops.js';
+import type { AgentRuntime } from './types.js';
+import type { OpDefinition } from '../facades/types.js';
+
+function makeMockRuntime() {
+  return {
+    planner: {
+      grade: vi.fn().mockReturnValue({
+        grade: 'B',
+        score: 82,
+        iteration: 1,
+        gaps: [
+          { severity: 'major', category: 'scope', description: 'Missing scope', recommendation: 'Add scope', location: 'plan.scope' },
+          { severity: 'minor', category: 'detail', description: 'Low detail', recommendation: 'Add detail' },
+          { severity: 'critical', category: 'risk', description: 'No risk analysis', recommendation: 'Add risks' },
+        ],
+      }),
+      getCheckHistory: vi.fn().mockReturnValue([
+        { grade: 'C', score: 70, iteration: 1 },
+        { grade: 'B', score: 82, iteration: 2 },
+      ]),
+      getLatestCheck: vi.fn().mockReturnValue({ grade: 'B', score: 82, iteration: 2 }),
+      meetsGrade: vi.fn().mockReturnValue({ meets: true, currentScore: 92, threshold: 90 }),
+    },
+  } as unknown as AgentRuntime;
+}
+
+describe('createGradingOps', () => {
+  let ops: OpDefinition[];
+  let runtime: ReturnType<typeof makeMockRuntime>;
+
+  function findOp(name: string): OpDefinition {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op "${name}" not found`);
+    return op;
+  }
+
+  it('returns 5 ops', () => {
+    runtime = makeMockRuntime();
+    ops = createGradingOps(runtime);
+    expect(ops).toHaveLength(5);
+  });
+
+  it('has correct op names', () => {
+    runtime = makeMockRuntime();
+    ops = createGradingOps(runtime);
+    const names = ops.map((o) => o.name);
+    expect(names).toEqual([
+      'plan_grade',
+      'plan_check_history',
+      'plan_latest_check',
+      'plan_meets_grade',
+      'plan_auto_improve',
+    ]);
+  });
+
+  it('all ops have read auth', () => {
+    runtime = makeMockRuntime();
+    ops = createGradingOps(runtime);
+    for (const op of ops) {
+      expect(op.auth).toBe('read');
+    }
+  });
+
+  describe('plan_grade', () => {
+    it('delegates to planner.grade', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = await findOp('plan_grade').handler({ planId: 'p1' });
+      expect(runtime.planner.grade).toHaveBeenCalledWith('p1');
+      expect(result).toHaveProperty('grade', 'B');
+    });
+  });
+
+  describe('plan_check_history', () => {
+    it('returns count and checks array', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_check_history').handler({ planId: 'p1' })) as Record<string, unknown>;
+      expect(result.planId).toBe('p1');
+      expect(result.count).toBe(2);
+      expect(result.checks).toHaveLength(2);
+    });
+  });
+
+  describe('plan_latest_check', () => {
+    it('returns the latest check', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = await findOp('plan_latest_check').handler({ planId: 'p1' });
+      expect(result).toHaveProperty('grade', 'B');
+    });
+
+    it('returns message when no checks found', async () => {
+      runtime = makeMockRuntime();
+      (runtime.planner.getLatestCheck as ReturnType<typeof vi.fn>).mockReturnValue(null);
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_latest_check').handler({ planId: 'p1' })) as Record<string, unknown>;
+      expect(result.message).toBe('No checks found for this plan.');
+    });
+  });
+
+  describe('plan_meets_grade', () => {
+    it('delegates to planner.meetsGrade', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = await findOp('plan_meets_grade').handler({ planId: 'p1', targetGrade: 'A' });
+      expect(runtime.planner.meetsGrade).toHaveBeenCalledWith('p1', 'A');
+      expect(result).toHaveProperty('meets', true);
+    });
+  });
+
+  describe('plan_auto_improve', () => {
+    it('sorts gaps by severity and groups them', async () => {
+      runtime = makeMockRuntime();
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_auto_improve').handler({ planId: 'p1' })) as Record<string, unknown>;
+      expect(result.grade).toBe('B');
+      expect(result.score).toBe(82);
+      expect(result.totalGaps).toBe(3);
+      expect(result.nextAction).toBe('iterate');
+
+      const grouped = result.gapsBySeverity as Record<string, unknown[]>;
+      expect(grouped.critical).toHaveLength(1);
+      expect(grouped.major).toHaveLength(1);
+      expect(grouped.minor).toHaveLength(1);
+    });
+
+    it('returns approve as nextAction when score >= 90', async () => {
+      runtime = makeMockRuntime();
+      (runtime.planner.grade as ReturnType<typeof vi.fn>).mockReturnValue({
+        grade: 'A', score: 92, iteration: 3, gaps: [],
+      });
+      ops = createGradingOps(runtime);
+      const result = (await findOp('plan_auto_improve').handler({ planId: 'p1' })) as Record<string, unknown>;
+      expect(result.nextAction).toBe('approve');
+      expect(result.totalGaps).toBe(0);
+    });
+  });
+});

package/src/runtime/grading-ops.ts

@@ -22,7 +22,7 @@ export function createGradingOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'plan_grade',
       description:
-        'Grade a plan using 7-pass gap analysis — severity-weighted scoring (critical=30, major=15, minor=2) with substance bonuses for vault-informed depth. Returns grade, score, gaps with recommendations, and iteration number.',
+        'Grade a plan using 8-pass gap analysis — severity-weighted scoring (critical=30, major=15, minor=2) with substance bonuses for vault-informed depth. Includes alternative analysis (pass 8) — plans without alternatives cap at ~85. Returns grade, score, gaps with recommendations, and iteration number.',
       auth: 'read',
       schema: z.object({
         planId: z.string().describe('The plan ID to grade.'),