clementine-agent 1.0.97 → 1.0.99

package/dist/agent/self-improve.d.ts

@@ -59,8 +59,15 @@ export declare class SelfImproveLoop {
     private parseJsonResponse;
     private withTimeout;
 }
+/** Validate that a proposed change has valid syntax for its target area. */
 export declare function validateProposal(area: string, target: string, proposedChange: string): {
     valid: boolean;
     error?: string;
 };
+/**
+ * Resolve the on-disk path for a prompt-override `target` string.
+ * Accepted forms: 'global', 'agent:<slug>', 'job:<jobName>'. Returns null
+ * for malformed targets.
+ */
+export declare function promptOverridePathForTarget(target: string): string | null;
 //# sourceMappingURL=self-improve.d.ts.map

package/dist/agent/self-improve.js

@@ -11,9 +11,10 @@
 import { randomBytes } from 'node:crypto';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync, } from 'node:fs';
 import matter from 'gray-matter';
+import { load as yamlLoad } from 'js-yaml';
 import path from 'node:path';
 import pino from 'pino';
-import { BASE_DIR, SELF_IMPROVE_DIR, SOUL_FILE, AGENTS_FILE, CRON_FILE, WORKFLOWS_DIR, VAULT_DIR, MEMORY_DB_PATH, AGENTS_DIR, PKG_DIR, CRON_REFLECTIONS_DIR, GOALS_DIR, } from '../config.js';
+import { BASE_DIR, SELF_IMPROVE_DIR, SOUL_FILE, AGENTS_FILE, CRON_FILE, WORKFLOWS_DIR, VAULT_DIR, MEMORY_DB_PATH, AGENTS_DIR, CRON_REFLECTIONS_DIR, GOALS_DIR, } from '../config.js';
 import { listAllGoals } from '../tools/shared.js';
 const logger = pino({ name: 'clementine.self-improve' });
 // ── Defaults ─────────────────────────────────────────────────────────
@@ -23,9 +24,13 @@ const DEFAULT_CONFIG = {
     maxDurationMs: 3_600_000, // 1 hour
     acceptThreshold: 0.7,
     plateauLimit: 3,
-    // 'source' deprecated — self-improvement should produce data (cron, workflow, etc.),
-    // not engine TS edits. Re-add only with CLEMENTINE_ALLOW_SOURCE_EDITS=1.
-    areas: ['soul', 'cron', 'workflow', 'memory', 'agent', 'communication', 'goal'],
+    // 'source' deprecated — self-improvement produces data, not engine TS edits.
+    // 'advisor-rule' writes YAML to ~/.clementine/advisor-rules/user/.
+    // 'prompt-override' writes markdown to ~/.clementine/prompt-overrides/.
+    areas: [
+        'soul', 'cron', 'workflow', 'memory', 'agent', 'communication', 'goal',
+        'advisor-rule', 'prompt-override',
+    ],
     autoApply: true,
     sourceMode: 'skip',
 };
@@ -132,20 +137,22 @@ function checkDrift(proposedContent) {
     return { ok: similarity >= DRIFT_SIMILARITY_THRESHOLD, similarity };
 }
 /** Classify the risk level of a proposed change.
- * - low: agent prompts, individual cron job prompts — auto-apply safe
+ * - low: agent prompts, individual cron job prompts, advisor rules, prompt overrides
  * - medium: SOUL.md, AGENTS.md, MEMORY.md — needs owner approval
- * - high: source code — stays blocked
+ * - high: source code — stays blocked (deprecated path; kept for back-compat)
  */
 function classifyRisk(area) {
     switch (area) {
-        case 'agent': return 'low'; // Agent-scoped, easily reversible
-        case 'cron': return 'low'; // Cron prompt tweaks, low blast radius
-        case 'workflow': return 'low'; // Workflow definitions, scoped
+        case 'agent': return 'low';
+        case 'cron': return 'low';
+        case 'workflow': return 'low';
+        case 'advisor-rule': return 'low'; // YAML files, hot-reloaded, easily deleted
+        case 'prompt-override': return 'low'; // Markdown files, hot-reloaded, easily deleted
         case 'soul': return 'medium'; // Core personality — needs approval
         case 'communication': return 'medium'; // Global operating instructions
         case 'memory': return 'medium'; // Memory config
-        case 'source': return 'high'; // Code changes — always blocked in auto mode
         case 'goal': return 'medium'; // New goals need owner review before activating
+        case 'source': return 'high'; // Deprecated — quarantined in Phase 1
         default: return 'high';
     }
 }
@@ -836,7 +843,15 @@ export class SelfImproveLoop {
             `Area notes:\n` +
             `- For "goal": target = "{owner}/{goal-slug}" (e.g. "clementine/improve-reply-rates" or "ross-the-sdr/book-demos"). ` +
             `Propose when you observe a pattern in completed tasks or cron runs that suggests a missing or stale goal. ` +
-            `The proposedChange must be a JSON goal object with at minimum: title, description, priority, reviewFrequency.\n\n` +
+            `The proposedChange must be a JSON goal object with at minimum: title, description, priority, reviewFrequency.\n` +
+            `- For "advisor-rule": target = ruleId in kebab-case (e.g. "skip-turn-bump-on-unleashed"). ` +
+            `Use when the fix is a behavioral rule that affects ALL jobs matching some scope, not just one cron job. ` +
+            `Examples: "for unleashed jobs, never bump maxTurns" or "for ross-the-sdr, double timeout on max_turns". ` +
+            `The proposedChange must be a full advisor rule YAML body with: schemaVersion: 1, id (must match target), description, priority (use 100+ to override builtins), appliesTo, when[], then[]. ` +
+            `User rules at priority 100+ override engine builtins of the same id.\n` +
+            `- For "prompt-override": target = "global", "agent:<slug>", or "job:<jobName>" (e.g. "job:market-leader-followup"). ` +
+            `Use when a job/agent needs more standing guidance — markdown that gets prepended to its prompt. ` +
+            `The proposedChange is the markdown body (optionally with gray-matter frontmatter for priority/position).\n\n` +
             `Return your answer as a JSON object matching the schema: { "results": [ ... ] }. Up to 3 items. If absolutely nothing actionable today, return { "results": [] }.`;
         const analysisResult = await this.assistant.runPlanStep('si-analyze', analysisPrompt, {
             tier: 2,
@@ -915,10 +930,6 @@ export class SelfImproveLoop {
                 const agentFile = path.join(AGENTS_DIR, target, 'agent.md');
                 return existsSync(agentFile) ? readFileSync(agentFile, 'utf-8') : '';
             }
-            case 'source': {
-                const srcFile = path.join(PKG_DIR, 'src', target);
-                return existsSync(srcFile) ? readFileSync(srcFile, 'utf-8') : '';
-            }
             case 'communication':
                 return existsSync(AGENTS_FILE) ? readFileSync(AGENTS_FILE, 'utf-8') : '';
             case 'memory': {
@@ -946,6 +957,23 @@ export class SelfImproveLoop {
                     return '(no goals yet for this owner)';
                 return goals.map((g) => `[${g.status ?? 'unknown'}] ${g.title}: ${(g.description ?? '').slice(0, 120)}`).join('\n');
             }
+            case 'advisor-rule': {
+                // target = ruleId (kebab-case). Show user override file if present, else builtin.
+                const userPath = path.join(BASE_DIR, 'advisor-rules', 'user', `${target}.yaml`);
+                if (existsSync(userPath))
+                    return readFileSync(userPath, 'utf-8');
+                const builtinPath = path.join(BASE_DIR, 'advisor-rules', 'builtin', `${target}.yaml`);
+                if (existsSync(builtinPath))
+                    return readFileSync(builtinPath, 'utf-8');
+                return '(no existing advisor rule for this id — proposing a new one)';
+            }
+            case 'prompt-override': {
+                // target = 'global' | 'agent:<slug>' | 'job:<jobName>'
+                const filePath = promptOverridePathForTarget(target);
+                if (filePath && existsSync(filePath))
+                    return readFileSync(filePath, 'utf-8');
+                return '(no existing prompt override for this scope — proposing a new one)';
+            }
             default:
                 return '';
         }
@@ -1011,38 +1039,10 @@ export class SelfImproveLoop {
         if (!targetPath) {
             return `Cannot resolve target path for area=${pending.area}, target=${pending.target}`;
         }
-        // Route source changes through the safe pipeline
+        // 'source' area is deprecated (Phase 1 quarantine). Reject up-front so a
+        // misbehaving proposal cannot reach the safeSourceEdit primitive.
         if (pending.area === 'source') {
-            const { safeSourceEdit } = await import('./safe-restart.js');
-            const result = await safeSourceEdit(PKG_DIR, [
-                { relativePath: `src/${pending.target}`, content: pending.proposedChange },
-            ], { experimentId, reason: `self-improve: ${pending.hypothesis.slice(0, 60)}`, description: pending.hypothesis });
-            if (!result.success) {
-                return `Source edit failed: ${result.error}${result.preflightErrors ? '\n' + result.preflightErrors.join('\n') : ''}`;
-            }
-            // Update experiment log — mark as approved
-            this.updateExperimentStatus(experimentId, 'approved');
-            try {
-                unlinkSync(pendingFile);
-            }
-            catch { /* ignore */ }
-            const state = this.loadState();
-            state.pendingApprovals = Math.max(0, state.pendingApprovals - 1);
-            this.saveState(state);
-            // Schedule impact measurement for 24h later
-            try {
-                appendFileSync(IMPACT_CHECKS_FILE, JSON.stringify({
-                    experimentId,
-                    area: pending.area,
-                    target: pending.target,
-                    appliedAt: new Date().toISOString(),
-                    checkAfterMs: 24 * 60 * 60 * 1000,
-                }) + '\n');
-            }
-            catch (err) {
-                logger.warn({ err }, 'Failed to schedule impact check');
-            }
-            return `Applied source change to ${pending.target} — restart triggered.`;
+            return 'source area is deprecated — propose advisor-rule or prompt-override instead';
         }
         // Goal area: parse JSON, inject required fields, ensure parent dir exists
         if (pending.area === 'goal') {
@@ -1095,6 +1095,7 @@ export class SelfImproveLoop {
             }
         }
         // Write the change (non-source areas)
+        mkdirSync(path.dirname(targetPath), { recursive: true });
         writeFileSync(targetPath, pending.proposedChange);
         // Record version for rollback lineage
         this.recordVersion(experimentId, pending.area, pending.target, pending.hypothesis, pending.before);
@@ -1680,9 +1681,6 @@ export class SelfImproveLoop {
             case 'agent': {
                 return path.join(AGENTS_DIR, target, 'agent.md');
             }
-            case 'source': {
-                return path.join(PKG_DIR, 'src', target);
-            }
             case 'communication':
                 return AGENTS_FILE;
             case 'memory':
@@ -1696,6 +1694,12 @@ export class SelfImproveLoop {
                     return path.join(GOALS_DIR, `${goalSlug}.json`);
                 return path.join(AGENTS_DIR, owner, 'goals', `${goalSlug}.json`);
             }
+            case 'advisor-rule':
+                if (!/^[a-z0-9-]+$/.test(target))
+                    return null;
+                return path.join(BASE_DIR, 'advisor-rules', 'user', `${target}.yaml`);
+            case 'prompt-override':
+                return promptOverridePathForTarget(target);
             default:
                 return null;
         }
@@ -1733,22 +1737,6 @@ export class SelfImproveLoop {
 }
 // ── Utility ──────────────────────────────────────────────────────────
 /** Validate that a proposed change has valid syntax for its target area. */
-/** Files that must never be modified by self-improvement (catastrophic blast radius or self-referential). */
-const SOURCE_BLOCKLIST = new Set([
-    'config.ts',
-    'types.ts',
-    'gateway/router.ts',
-    'gateway/lanes.ts',
-    'gateway/heartbeat-scheduler.ts',
-    'gateway/cron-scheduler.ts',
-    'gateway/security-scanner.ts',
-    'agent/self-improve.ts',
-    'agent/safe-restart.ts',
-    'agent/source-mods.ts',
-    'cli/index.ts',
-    'cli/dashboard.ts',
-    'security/scanner.ts',
-]);
 export function validateProposal(area, target, proposedChange) {
     if (!proposedChange.trim()) {
         return { valid: false, error: 'Proposed change is empty' };
@@ -1790,16 +1778,71 @@ export function validateProposal(area, target, proposedChange) {
         }
     }
     if (area === 'source') {
-        // Check blocklist
-        if (SOURCE_BLOCKLIST.has(target)) {
-            return { valid: false, error: `Source file '${target}' is in the blocklist and cannot be modified by self-improvement` };
+        // Deprecated — Phase 1 quarantined source self-edit. Reject up front so
+        // a misbehaving LLM proposal doesn't even get cached.
+        return { valid: false, error: 'source area is deprecated; propose advisor-rule or prompt-override instead' };
+    }
+    if (area === 'advisor-rule') {
+        // Must parse as YAML and have schemaVersion: 1, id matching target, when[], then[].
+        if (!/^[a-z0-9-]+$/.test(target)) {
+            return { valid: false, error: `advisor-rule target must be kebab-case (got "${target}")` };
+        }
+        let parsed;
+        try {
+            parsed = yamlLoad(proposedChange);
+        }
+        catch (err) {
+            return { valid: false, error: `advisor-rule YAML parse error: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        if (!parsed || typeof parsed !== 'object') {
+            return { valid: false, error: 'advisor-rule body did not parse as a YAML object' };
+        }
+        const r = parsed;
+        if (r.schemaVersion !== 1)
+            return { valid: false, error: 'advisor-rule must declare schemaVersion: 1' };
+        if (typeof r.id !== 'string' || r.id !== target) {
+            return { valid: false, error: `advisor-rule id must match target ("${target}")` };
+        }
+        if (!Array.isArray(r.when) || !Array.isArray(r.then)) {
+            return { valid: false, error: 'advisor-rule must have when[] and then[] arrays' };
+        }
+    }
+    if (area === 'prompt-override') {
+        // target format: 'global' | 'agent:<slug>' | 'job:<jobName>'
+        const path = promptOverridePathForTarget(target);
+        if (!path) {
+            return { valid: false, error: `prompt-override target must be 'global', 'agent:<slug>', or 'job:<jobName>' (got "${target}")` };
+        }
+        if (proposedChange.length > 20_000) {
+            return { valid: false, error: 'prompt-override content exceeds 20KB sanity bound' };
         }
-        // Size sanity: reject wholesale rewrites (proposed content > 2x original would be caught by caller).
-        // Source proposals may be small patches or modules without import/export statements;
-        // callers that apply source changes do the syntax-aware validation.
     }
     return { valid: true };
 }
+/**
+ * Resolve the on-disk path for a prompt-override `target` string.
+ * Accepted forms: 'global', 'agent:<slug>', 'job:<jobName>'. Returns null
+ * for malformed targets.
+ */
+export function promptOverridePathForTarget(target) {
+    const root = path.join(BASE_DIR, 'prompt-overrides');
+    if (target === 'global')
+        return path.join(root, '_global.md');
+    const idx = target.indexOf(':');
+    if (idx <= 0)
+        return null;
+    const scope = target.slice(0, idx);
+    const key = target.slice(idx + 1);
+    if (!key)
+        return null;
+    if (/[\/\\\.]/.test(key))
+        return null;
+    if (scope === 'agent')
+        return path.join(root, 'agents', `${key}.md`);
+    if (scope === 'job')
+        return path.join(root, 'jobs', `${key}.md`);
+    return null;
+}
 function ensureDirs() {
     for (const dir of [SELF_IMPROVE_DIR, PENDING_DIR]) {
         if (!existsSync(dir)) {

package/dist/types.d.ts

@@ -501,7 +501,7 @@ export interface SelfImproveExperiment {
     startedAt: string;
     finishedAt: string;
     durationMs: number;
-    area: 'soul' | 'cron' | 'workflow' | 'memory' | 'agent' | 'source' | 'communication' | 'goal';
+    area: 'soul' | 'cron' | 'workflow' | 'memory' | 'agent' | 'source' | 'communication' | 'goal' | 'advisor-rule' | 'prompt-override';
     target: string;
     hypothesis: string;
     proposedChange: string;
@@ -549,7 +549,7 @@ export interface SelfImproveConfig {
     maxDurationMs: number;
     acceptThreshold: number;
     plateauLimit: number;
-    areas: ('soul' | 'cron' | 'workflow' | 'memory' | 'agent' | 'source' | 'communication' | 'goal')[];
+    areas: ('soul' | 'cron' | 'workflow' | 'memory' | 'agent' | 'source' | 'communication' | 'goal' | 'advisor-rule' | 'prompt-override')[];
     /** Enable tiered auto-apply: low-risk changes apply without approval. Default: false. */
     autoApply?: boolean;
     /** Target a specific agent slug (for per-agent improvement cycles). */

package/dist/vault-migrations/runner.d.ts

@@ -5,10 +5,19 @@
  * Each exports a `migration` object conforming to VaultMigration.
  * State is tracked in ~/.clementine/.vault-migrations.json.
  */
-import type { VaultMigrationSummary } from './types.js';
+import type { MigrationContext, VaultMigrationSummary } from './types.js';
 /**
- * Run all pending vault migrations against the user's vault.
- * Idempotent — safe to call multiple times.
+ * Run all pending migrations. Each is dispatched based on its shape:
+ *   - VaultMigration (no `kind` field) → apply(vaultDir)
+ *   - Migration       (has `kind` field) → apply(MigrationContext)
+ *
+ * Idempotent — safe to call multiple times. State is tracked in
+ * `~/.clementine/.vault-migrations.json` (kept this filename for back-compat).
+ */
+export declare function runMigrations(ctx: MigrationContext, backupDir?: string): Promise<VaultMigrationSummary>;
+/**
+ * Back-compat wrapper: existing call sites pass just vaultDir. Builds a
+ * default MigrationContext from BASE_DIR and PKG_DIR.
  */
 export declare function runVaultMigrations(vaultDir: string, backupDir?: string): Promise<VaultMigrationSummary>;
 //# sourceMappingURL=runner.d.ts.map

package/dist/vault-migrations/runner.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
 import path from 'node:path';
 import pino from 'pino';
-import { VAULT_MIGRATIONS_STATE } from '../config.js';
+import { BASE_DIR, PKG_DIR, VAULT_MIGRATIONS_STATE } from '../config.js';
 const logger = pino({ name: 'clementine.vault-migrations' });
 /** Load the migration state file. Returns empty state if missing or corrupt. */
 function loadState() {
@@ -41,6 +41,7 @@ function backupFile(filePath, backupDir) {
 /**
  * Discover all migration modules in the compiled dist/vault-migrations/ directory.
  * Returns them sorted by filename (numeric prefix ensures correct order).
+ * Accepts both VaultMigration (legacy) and Migration (multi-target) shapes.
  */
 async function discoverMigrations() {
     const migrations = [];
@@ -64,16 +65,24 @@ async function discoverMigrations() {
             }
         }
         catch (err) {
-            logger.warn({ file, err }, 'Failed to load vault migration');
+            logger.warn({ file, err }, 'Failed to load migration');
         }
     }
     return migrations;
 }
+/** Discriminator — true if migration uses the new MigrationContext shape. */
+function isContextMigration(m) {
+    return typeof m.kind === 'string';
+}
 /**
- * Run all pending vault migrations against the user's vault.
- * Idempotent — safe to call multiple times.
+ * Run all pending migrations. Each is dispatched based on its shape:
+ *   - VaultMigration (no `kind` field) → apply(vaultDir)
+ *   - Migration       (has `kind` field) → apply(MigrationContext)
+ *
+ * Idempotent — safe to call multiple times. State is tracked in
+ * `~/.clementine/.vault-migrations.json` (kept this filename for back-compat).
  */
-export async function runVaultMigrations(vaultDir, backupDir) {
+export async function runMigrations(ctx, backupDir) {
     const summary = {
         applied: [],
         skipped: [],
@@ -87,16 +96,14 @@ export async function runVaultMigrations(vaultDir, backupDir) {
     if (migrations.length === 0)
         return summary;
     for (const migration of migrations) {
-        // Skip if already recorded as applied
         if (appliedIds.has(migration.id)) {
             summary.alreadyRun.push(migration.id);
             continue;
         }
         try {
-            // Back up target files before migration
-            if (backupDir) {
-                // Best-effort backup of the vault's 00-System dir (most common target)
-                const systemDir = path.join(vaultDir, '00-System');
+            // Best-effort backup of the vault's 00-System dir for vault-style migrations
+            if (backupDir && !isContextMigration(migration)) {
+                const systemDir = path.join(ctx.vaultDir, '00-System');
                 if (existsSync(systemDir)) {
                     const systemFiles = readdirSync(systemDir).filter(f => f.endsWith('.md'));
                     for (const f of systemFiles) {
@@ -104,36 +111,36 @@ export async function runVaultMigrations(vaultDir, backupDir) {
                     }
                 }
             }
-            const result = migration.apply(vaultDir);
-            if (result.applied) {
+            const result = isContextMigration(migration)
+                ? await migration.apply(ctx)
+                : migration.apply(ctx.vaultDir);
+            const r = result;
+            if (r.applied) {
                 summary.applied.push(migration.id);
-                state.applied.push({
-                    id: migration.id,
-                    appliedAt: new Date().toISOString(),
-                    result: 'applied',
-                });
-                logger.info({ id: migration.id, details: result.details }, 'Vault migration applied');
+                state.applied.push({ id: migration.id, appliedAt: new Date().toISOString(), result: 'applied' });
+                logger.info({ id: migration.id, details: r.details }, 'Migration applied');
             }
-            else if (result.skipped) {
+            else if (r.skipped) {
                 summary.skipped.push(migration.id);
-                // Record as applied so we don't re-check every update
-                state.applied.push({
-                    id: migration.id,
-                    appliedAt: new Date().toISOString(),
-                    result: 'skipped',
-                });
-                logger.info({ id: migration.id, details: result.details }, 'Vault migration skipped (already present)');
+                state.applied.push({ id: migration.id, appliedAt: new Date().toISOString(), result: 'skipped' });
+                logger.info({ id: migration.id, details: r.details }, 'Migration skipped (already present)');
             }
         }
         catch (err) {
             const errMsg = String(err).slice(0, 200);
             summary.failed.push(migration.id);
             summary.errors.push({ id: migration.id, error: errMsg });
-            // Do NOT record as applied — will retry on next update
-            logger.warn({ id: migration.id, err }, 'Vault migration failed');
+            logger.warn({ id: migration.id, err }, 'Migration failed');
         }
     }
     saveState(state);
     return summary;
 }
+/**
+ * Back-compat wrapper: existing call sites pass just vaultDir. Builds a
+ * default MigrationContext from BASE_DIR and PKG_DIR.
+ */
+export async function runVaultMigrations(vaultDir, backupDir) {
+    return runMigrations({ vaultDir, baseDir: BASE_DIR, pkgDir: PKG_DIR }, backupDir);
+}
 //# sourceMappingURL=runner.js.map

package/dist/vault-migrations/types.d.ts

@@ -1,10 +1,27 @@
 /**
- * Vault migration system — types and interfaces.
+ * Migration system — types and interfaces.
  *
- * Vault migrations ship structural changes to user vault files (SOUL.md,
- * AGENTS.md, etc.) alongside code updates. Each migration is idempotent
- * and runs once during `clementine update`.
+ * Migrations ship structural changes to user data files (SOUL.md, AGENTS.md,
+ * advisor rules, prompt overrides, clementine.json, etc.) alongside code
+ * updates. Each migration is idempotent and runs once during `clementine update`.
+ *
+ * Two shapes coexist for back-compat:
+ *   - VaultMigration: takes vaultDir only (the original shape, used by 0001-0003)
+ *   - Migration: takes a MigrationContext { vaultDir, baseDir, pkgDir } so a
+ *     migration can touch advisor-rules/, prompt-overrides/, clementine.json,
+ *     etc. — anything under ~/.clementine/, not just the vault.
+ *
+ * Discriminator: `kind` field. Vault-style migrations omit it.
  */
+export interface MigrationContext {
+    /** ~/.clementine/vault */
+    vaultDir: string;
+    /** ~/.clementine/  (data home — config, state, cache, advisor-rules, etc.) */
+    baseDir: string;
+    /** Package install root (where dist/ lives). For migrations that ship templates. */
+    pkgDir: string;
+}
+/** Original vault-only migration shape. Existing 0001-0003 use this. */
 export interface VaultMigration {
     /** Unique ID matching the filename (e.g., "0001-add-execution-framework"). */
     id: string;
@@ -13,6 +30,15 @@ export interface VaultMigration {
     /** Apply the migration. Must be idempotent — safe to re-run. */
     apply: (vaultDir: string) => MigrationResult;
 }
+/** Multi-target migration shape. Use for any data outside vault/. */
+export interface Migration {
+    /** Discriminator. Vault-only migrations omit this and use VaultMigration. */
+    kind: 'vault' | 'config' | 'advisor-rules' | 'prompt-overrides' | 'multi';
+    id: string;
+    description: string;
+    apply: (ctx: MigrationContext) => MigrationResult | Promise<MigrationResult>;
+}
+export type AnyMigration = VaultMigration | Migration;
 export interface MigrationResult {
     /** True if changes were written to disk. */
     applied: boolean;
@@ -39,4 +65,6 @@ export interface VaultMigrationSummary {
         error: string;
     }>;
 }
+/** Alias — same shape, generalized name now that migrations aren't vault-only. */
+export type MigrationSummary = VaultMigrationSummary;
 //# sourceMappingURL=types.d.ts.map

package/dist/vault-migrations/types.js

@@ -1,9 +1,17 @@
 /**
- * Vault migration system — types and interfaces.
+ * Migration system — types and interfaces.
  *
- * Vault migrations ship structural changes to user vault files (SOUL.md,
- * AGENTS.md, etc.) alongside code updates. Each migration is idempotent
- * and runs once during `clementine update`.
+ * Migrations ship structural changes to user data files (SOUL.md, AGENTS.md,
+ * advisor rules, prompt overrides, clementine.json, etc.) alongside code
+ * updates. Each migration is idempotent and runs once during `clementine update`.
+ *
+ * Two shapes coexist for back-compat:
+ *   - VaultMigration: takes vaultDir only (the original shape, used by 0001-0003)
+ *   - Migration: takes a MigrationContext { vaultDir, baseDir, pkgDir } so a
+ *     migration can touch advisor-rules/, prompt-overrides/, clementine.json,
+ *     etc. — anything under ~/.clementine/, not just the vault.
+ *
+ * Discriminator: `kind` field. Vault-style migrations omit it.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.97",
+  "version": "1.0.99",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",