clementine-agent 1.0.95 → 1.0.97

package/dist/agent/prompt-overrides/loader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Prompt Overrides — loader.
+ *
+ * Reads markdown files from ~/.clementine/prompt-overrides/ and serves
+ * scope-resolved override text for a given (jobName, agentSlug). Hot-reloads
+ * via fs.watch (debounced).
+ *
+ * No package builtins — these are purely user/LLM authored. The directory
+ * is created on first load so users have an obvious empty home for overrides.
+ */
+import type { PromptOverride } from './types.js';
+export interface LoaderOptions {
+    baseDir?: string;
+}
+export declare function loadPromptOverrides(opts?: LoaderOptions): PromptOverride[];
+export declare function getLoadedOverrides(): PromptOverride[];
+/**
+ * Resolve overrides applicable to a given job: global + agent (if agentSlug
+ * matches) + job (if jobName matches), sorted by priority ascending and
+ * concatenated into a single string. Empty if no overrides apply.
+ */
+export declare function loadPromptOverridesForJob(jobName: string, agentSlug?: string, opts?: LoaderOptions): string;
+/** Install fs.watch on the overrides directory tree. Safe to call multiple times. */
+export declare function watchPromptOverrides(opts?: LoaderOptions): void;
+/** Test-only: clear cached state. */
+export declare function _resetLoaderState(): void;
+//# sourceMappingURL=loader.d.ts.map

package/dist/agent/prompt-overrides/loader.js

@@ -0,0 +1,160 @@
+/**
+ * Prompt Overrides — loader.
+ *
+ * Reads markdown files from ~/.clementine/prompt-overrides/ and serves
+ * scope-resolved override text for a given (jobName, agentSlug). Hot-reloads
+ * via fs.watch (debounced).
+ *
+ * No package builtins — these are purely user/LLM authored. The directory
+ * is created on first load so users have an obvious empty home for overrides.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, watch as fsWatch } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import matter from 'gray-matter';
+import { BASE_DIR } from '../../config.js';
+const logger = pino({ name: 'clementine.prompt-overrides' });
+function rootDir(baseDir) {
+    return path.join(baseDir, 'prompt-overrides');
+}
+// ── State ────────────────────────────────────────────────────────────
+let cached = [];
+let watcherInstalled = false;
+let watchDebounce = null;
+// ── Parse one file ───────────────────────────────────────────────────
+function parseOverride(filePath, scope, scopeKey) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = matter(raw);
+        const fm = (parsed.data ?? {});
+        const body = parsed.content.trim();
+        if (!body)
+            return null;
+        const defaultPriority = scope === 'global' ? 10 :
+            scope === 'agent' ? 50 :
+                100;
+        return {
+            body,
+            priority: typeof fm.priority === 'number' ? fm.priority : defaultPriority,
+            sourcePath: filePath,
+            scope,
+            scopeKey,
+        };
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to parse prompt override — skipping');
+        return null;
+    }
+}
+function readMarkdownFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => path.join(dir, f));
+}
+// ── Loader ───────────────────────────────────────────────────────────
+export function loadPromptOverrides(opts) {
+    const baseDir = opts?.baseDir ?? BASE_DIR;
+    const root = rootDir(baseDir);
+    if (!existsSync(root)) {
+        mkdirSync(root, { recursive: true });
+    }
+    const out = [];
+    // _global.md (or any *.md) at root with bare name "_global"
+    const globalPath = path.join(root, '_global.md');
+    if (existsSync(globalPath)) {
+        const o = parseOverride(globalPath, 'global', null);
+        if (o)
+            out.push(o);
+    }
+    // agents/<slug>.md
+    for (const f of readMarkdownFiles(path.join(root, 'agents'))) {
+        const slug = path.basename(f, '.md');
+        const o = parseOverride(f, 'agent', slug);
+        if (o)
+            out.push(o);
+    }
+    // jobs/<jobName>.md
+    for (const f of readMarkdownFiles(path.join(root, 'jobs'))) {
+        const jobName = path.basename(f, '.md');
+        const o = parseOverride(f, 'job', jobName);
+        if (o)
+            out.push(o);
+    }
+    cached = out;
+    logger.info({ total: out.length, global: out.filter(o => o.scope === 'global').length, agent: out.filter(o => o.scope === 'agent').length, job: out.filter(o => o.scope === 'job').length }, 'Prompt overrides loaded');
+    return out;
+}
+export function getLoadedOverrides() {
+    return cached;
+}
+/**
+ * Resolve overrides applicable to a given job: global + agent (if agentSlug
+ * matches) + job (if jobName matches), sorted by priority ascending and
+ * concatenated into a single string. Empty if no overrides apply.
+ */
+export function loadPromptOverridesForJob(jobName, agentSlug, opts) {
+    // Use cached if loaded, else load fresh.
+    if (cached.length === 0) {
+        loadPromptOverrides(opts);
+    }
+    const applicable = cached.filter(o => {
+        if (o.scope === 'global')
+            return true;
+        if (o.scope === 'agent')
+            return agentSlug != null && o.scopeKey === agentSlug;
+        if (o.scope === 'job')
+            return o.scopeKey === jobName;
+        return false;
+    });
+    if (applicable.length === 0)
+        return '';
+    applicable.sort((a, b) => a.priority - b.priority);
+    return applicable.map(o => o.body).join('\n\n');
+}
+/** Install fs.watch on the overrides directory tree. Safe to call multiple times. */
+export function watchPromptOverrides(opts) {
+    if (watcherInstalled)
+        return;
+    const baseDir = opts?.baseDir ?? BASE_DIR;
+    const root = rootDir(baseDir);
+    if (!existsSync(root)) {
+        mkdirSync(root, { recursive: true });
+    }
+    // Pre-create subdirs so fs.watch picks up future changes
+    for (const sub of ['agents', 'jobs']) {
+        const p = path.join(root, sub);
+        if (!existsSync(p))
+            mkdirSync(p, { recursive: true });
+    }
+    try {
+        fsWatch(root, { recursive: true }, () => {
+            if (watchDebounce)
+                clearTimeout(watchDebounce);
+            watchDebounce = setTimeout(() => {
+                try {
+                    loadPromptOverrides(opts);
+                }
+                catch (err) {
+                    logger.warn({ err }, 'Hot reload failed — keeping previous overrides');
+                }
+            }, 250);
+        });
+        watcherInstalled = true;
+        logger.debug({ root }, 'Watching prompt-overrides for hot reload');
+    }
+    catch (err) {
+        logger.warn({ err }, 'Failed to install prompt-overrides watcher — hot reload disabled');
+    }
+}
+/** Test-only: clear cached state. */
+export function _resetLoaderState() {
+    cached = [];
+    watcherInstalled = false;
+    if (watchDebounce) {
+        clearTimeout(watchDebounce);
+        watchDebounce = null;
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/agent/prompt-overrides/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Prompt Overrides — schema types.
+ *
+ * Markdown files in ~/.clementine/prompt-overrides/ that get prepended to
+ * cron job prompts at runtime. Frontmatter is optional; the bare body of
+ * a markdown file is enough to override a prompt.
+ *
+ * Layout:
+ *   _global.md                — appended for every job (low priority)
+ *   agents/<slug>.md          — every job for an agent
+ *   jobs/<jobName>.md         — specific job
+ *
+ * Default priority: global=10, agent=50, job=100. Lower priority concatenates first
+ * (i.e. "outermost" — read by the LLM earlier).
+ */
+export type OverridePosition = 'append' | 'prepend';
+export interface PromptOverrideFrontmatter {
+    schemaVersion?: 1;
+    priority?: number;
+    position?: OverridePosition;
+}
+export interface PromptOverride {
+    /** Raw body content (markdown), with frontmatter stripped. */
+    body: string;
+    /** Effective priority (frontmatter > scope default). */
+    priority: number;
+    /** Where the file lives — for logging only. */
+    sourcePath: string;
+    /** What scope this override targets. */
+    scope: 'global' | 'agent' | 'job';
+    /** For job/agent scope, the matched name; null for global. */
+    scopeKey: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/prompt-overrides/types.js

@@ -0,0 +1,17 @@
+/**
+ * Prompt Overrides — schema types.
+ *
+ * Markdown files in ~/.clementine/prompt-overrides/ that get prepended to
+ * cron job prompts at runtime. Frontmatter is optional; the bare body of
+ * a markdown file is enough to override a prompt.
+ *
+ * Layout:
+ *   _global.md                — appended for every job (low priority)
+ *   agents/<slug>.md          — every job for an agent
+ *   jobs/<jobName>.md         — specific job
+ *
+ * Default priority: global=10, agent=50, job=100. Lower priority concatenates first
+ * (i.e. "outermost" — read by the LLM earlier).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/gateway/cron-scheduler.js

@@ -17,6 +17,7 @@ import { listAllGoals, findGoalPath, readGoalById } from '../tools/shared.js';
 import { scanner } from '../security/scanner.js';
 import { parseAllWorkflows as parseAllWorkflowsSync } from '../agent/workflow-runner.js';
 import { SelfImproveLoop } from '../agent/self-improve.js';
+import { loadPromptOverridesForJob, watchPromptOverrides } from '../agent/prompt-overrides/loader.js';
 import { logAuditJsonl } from '../agent/hooks.js';
 import { listBackgroundTasks, markDone as markBgTaskDone, markFailed as markBgTaskFailed, markRunning as markBgTaskRunning, } from '../agent/background-tasks.js';
 import { outcomeStatusFromGoalDisposition, recentDecisions, recordDecisionOutcome, } from '../agent/proactive-ledger.js';
@@ -451,6 +452,7 @@ export class CronScheduler {
         this.watchCronFile();
         this.watchAgentsDir();
         this.watchWorkflowDir();
+        watchPromptOverrides();
         this.watchTriggers();
         // Deep-mode jobs are owned by the router (_deliverDeepResult). The
         // cron-scheduler callbacks below only dispatch for cron-originated runs;
@@ -888,6 +890,17 @@ export class CronScheduler {
                 ...advisorApplied,
             }, 'Execution advisor applied overrides');
         }
+        // User-authored prompt overrides — applied AFTER advisor enrichment so user
+        // intent sits at the top of the final prompt. These are static per-file,
+        // not subject to advisor suppression rules.
+        const userOverride = loadPromptOverridesForJob(job.name, job.agentSlug);
+        if (userOverride) {
+            // Mutable copy if not already cloned by the advisor block above.
+            if (!advisorApplied)
+                job = { ...job };
+            job.prompt = `${userOverride}\n\n${job.prompt}`;
+            logger.debug({ job: job.name, overrideLen: userOverride.length }, 'Applied user prompt overrides');
+        }
         // Compute effective timeout: advisor override > standard default
         const effectiveTimeoutMs = job.mode !== 'unleashed'
             ? (advice.adjustedTimeoutMs ?? CRON_STANDARD_TIMEOUT_MS)

package/dist/gateway/failure-diagnostics.d.ts

@@ -27,23 +27,40 @@ export type FixOperation = {
     op: 'remove';
     field: string;
 };
+/** CRON.md frontmatter edit (the original auto-apply shape). */
+export interface AutoApplyCron {
+    kind?: 'cron';
+    agentSlug?: string;
+    operations: FixOperation[];
+}
+/** Write a YAML rule to ~/.clementine/advisor-rules/user/<ruleId>.yaml */
+export interface AutoApplyAdvisorRule {
+    kind: 'advisor-rule';
+    ruleId: string;
+    yamlContent: string;
+}
+/** Write a markdown override to ~/.clementine/prompt-overrides/... */
+export interface AutoApplyPromptOverride {
+    kind: 'prompt-override';
+    scope: 'global' | 'agent' | 'job';
+    scopeKey?: string;
+    content: string;
+}
+export type AutoApply = AutoApplyCron | AutoApplyAdvisorRule | AutoApplyPromptOverride;
 export interface Diagnosis {
     rootCause: string;
     confidence: 'high' | 'medium' | 'low';
     proposedFix: {
-        type: 'config_change' | 'prompt_change' | 'agent_scope' | 'disable' | 'credential_refresh' | 'escalate_to_owner';
+        type: 'config_change' | 'prompt_change' | 'agent_scope' | 'disable' | 'credential_refresh' | 'advisor_rule' | 'prompt_override' | 'escalate_to_owner';
         details: string;
         diff?: string;
         /**
-         * When present, the fix can be applied with one click via the
-         * /api/cron/broken-jobs/:jobName/apply-fix endpoint. Operations are
-         * silently filtered against EDITABLE_FIELDS — a proposal that mixes
-         * safe and unsafe edits gets the unsafe ones dropped.
+         * When present, the fix can be applied with one click via the dashboard's
+         * apply-fix endpoint. Three shapes (kind=cron|advisor-rule|prompt-override).
+         * Each kind has its own validator that runs in sanitizeAutoApply before
+         * the proposal is cached, and again in fix-applier before any write.
          */
-        autoApply?: {
-            agentSlug?: string;
-            operations: FixOperation[];
-        };
+        autoApply?: AutoApply;
     };
     riskLevel: 'low' | 'medium' | 'high';
     generatedAt: string;

package/dist/gateway/failure-diagnostics.js

@@ -173,28 +173,43 @@ function buildPrompt(broken, jobDef, agentProfile, recentRuns) {
         '',
         '## Auto-apply contract',
         '',
-        'When (and ONLY when) the fix is a simple edit to one of these scalar fields — tier, mode, max_hours, max_turns, max_retries, enabled, agentSlug, work_dir, model, always_deliver, after, timeout_ms — also populate `proposedFix.autoApply`. The owner can one-click approve it from the dashboard.',
+        'When the fix is mechanical — set or remove a known scalar field, write a small advisor rule, or add prompt guidance — ALSO populate `proposedFix.autoApply`. The owner can one-click approve it. There are three KINDS of auto-apply, pick the one that matches:',
         '',
-        'For multi-line fields (prompt, pre_check, context, success_criteria), or for credential refreshes, or any change you are not very confident about: OMIT autoApply entirely. The owner will handle those manually.',
+        '### kind: "cron" (default — edit CRON.md frontmatter)',
+        'Use for: tier, mode, max_hours, max_turns, max_retries, enabled, agentSlug, work_dir, model, always_deliver, after, timeout_ms.',
+        'Shape: { "kind": "cron", "agentSlug"?: "...", "operations": [...] }',
+        'Operations: { "op": "set", "field": "<name>", "value": <scalar> } or { "op": "remove", "field": "<name>" }.',
+        'If the job is agent-scoped (job name has ":"), set agentSlug to the prefix.',
+        'Examples:',
+        '- Remove unleashed + companion + cap turns: { "kind": "cron", "operations": [{"op":"remove","field":"mode"}, {"op":"remove","field":"max_hours"}, {"op":"set","field":"max_turns","value":25}] }',
+        '- Bump maxTurns: { "kind": "cron", "operations": [{"op":"set","field":"max_turns","value":10}] }',
         '',
-        `If the job is agent-scoped (job name includes ":"), set autoApply.agentSlug to the part BEFORE the colon. Otherwise omit it (global CRON.md).`,
+        '### kind: "advisor-rule" (write a YAML rule to ~/.clementine/advisor-rules/user/)',
+        'Use when the fix is a behavioral rule that should affect ALL jobs matching some scope, not just one cron job. Examples: "for unleashed jobs, never bump maxTurns" or "for ross-the-sdr, always set timeout to 900s on max_turns errors".',
+        'Shape: { "kind": "advisor-rule", "ruleId": "kebab-case-id", "yamlContent": "<full yaml body>" }',
+        'The YAML body must be a valid advisor rule (schemaVersion: 1, id, description, priority, when, then). User rules at priority 100+ override builtins of the same id.',
+        'Example:',
+        '{ "kind": "advisor-rule", "ruleId": "ross-aggressive-timeout", "yamlContent": "schemaVersion: 1\\nid: ross-aggressive-timeout\\ndescription: Bump timeout for ross\\npriority: 105\\nappliesTo:\\n  agentSlug: ross-the-sdr\\nwhen:\\n  - kind: recentTimeoutHits\\n    window: 5\\n    atLeast: 1\\nthen:\\n  - kind: bumpTimeoutMs\\n    multiplier: 2.0" }',
         '',
-        'Operations use the shape { "op": "set", "field": "<name>", "value": <scalar> } or { "op": "remove", "field": "<name>" }. Values are strings, numbers, or booleans.',
+        '### kind: "prompt-override" (write a markdown file to ~/.clementine/prompt-overrides/)',
+        'Use when the fix is "give the LLM more guidance for this job/agent". Examples: a job consistently misses an edge case, an agent needs a reminder about output format.',
+        'Shape: { "kind": "prompt-override", "scope": "job"|"agent"|"global", "scopeKey": "<job or agent name>", "content": "<markdown body>" }',
+        'For scope=global, omit scopeKey. For scope=agent, scopeKey is the agent slug. For scope=job, scopeKey is the BARE job name (no agent prefix).',
+        'Example:',
+        '{ "kind": "prompt-override", "scope": "job", "scopeKey": "market-leader-followup", "content": "If the inbox query returns 0 rows, batch the duplicate-task cleanup in groups of 50 using bash heredoc loops. Do not enumerate task IDs in the prompt." }',
         '',
-        'Examples:',
-        '- Remove unleashed mode + its companion: operations: [{"op":"remove","field":"mode"}, {"op":"remove","field":"max_hours"}, {"op":"set","field":"max_turns","value":25}]',
-        '- Scope a broken global job to Ross\'s profile: operations: [{"op":"set","field":"agentSlug","value":"ross-the-sdr"}]',
-        '- Bump maxTurns on an under-resourced job: operations: [{"op":"set","field":"max_turns","value":10}]',
+        '## When NOT to use autoApply',
+        'For credential refreshes, multi-line CRON.md edits beyond the scalar allowlist, or any change you are not confident about: OMIT autoApply entirely. The owner will handle those manually.',
         '',
         '## Output schema (JSON only, no markdown fences):',
         '{',
-        '  "rootCause": "1-2 sentences explaining WHY the job is failing, referencing specific fields or error patterns from the CURRENT config",',
+        '  "rootCause": "1-2 sentences explaining WHY the job is failing",',
         '  "confidence": "high|medium|low",',
         '  "proposedFix": {',
-        '    "type": "config_change|prompt_change|agent_scope|disable|credential_refresh|escalate_to_owner",',
-        '    "details": "prose description of the fix, citing the exact field(s) to change",',
-        '    "diff": "optional: exact before/after diff",',
-        '    "autoApply": "optional: { agentSlug?, operations: [...] } — ONLY for simple scalar-field edits on the allowlist"',
+        '    "type": "config_change|prompt_change|agent_scope|disable|credential_refresh|advisor_rule|prompt_override|escalate_to_owner",',
+        '    "details": "prose description of the fix",',
+        '    "diff": "optional: before/after diff",',
+        '    "autoApply": "optional: one of the three shapes above"',
         '  },',
         '  "riskLevel": "low|medium|high"',
         '}',
@@ -230,32 +245,42 @@ function parseResponse(raw) {
     }
 }
 /**
- * Strictly validate and filter autoApply. Drops ops on non-allowlisted fields
- * silently (rather than rejecting the whole diagnosis). Returns null if
- * nothing valid remains.
+ * Strictly validate and filter autoApply. Dispatches on `kind` (default 'cron'
+ * for back-compat). Returns null if validation fails for the chosen kind.
  */
 function sanitizeAutoApply(raw) {
     if (!raw || typeof raw !== 'object')
         return null;
     const obj = raw;
+    const kind = typeof obj.kind === 'string' ? obj.kind : 'cron';
+    if (kind === 'cron')
+        return sanitizeAutoApplyCron(obj);
+    if (kind === 'advisor-rule')
+        return sanitizeAutoApplyAdvisorRule(obj);
+    if (kind === 'prompt-override')
+        return sanitizeAutoApplyPromptOverride(obj);
+    return null;
+}
+function sanitizeAutoApplyCron(raw) {
+    const obj = raw;
     if (!Array.isArray(obj.operations))
         return null;
     const operations = [];
     for (const op of obj.operations) {
         if (!op || typeof op !== 'object')
             continue;
-        const raw = op;
-        if (typeof raw.field !== 'string')
+        const r = op;
+        if (typeof r.field !== 'string')
             continue;
-        if (!EDITABLE_FIELDS.has(raw.field))
+        if (!EDITABLE_FIELDS.has(r.field))
             continue;
-        if (raw.op === 'remove') {
-            operations.push({ op: 'remove', field: raw.field });
+        if (r.op === 'remove') {
+            operations.push({ op: 'remove', field: r.field });
         }
-        else if (raw.op === 'set') {
-            const v = raw.value;
+        else if (r.op === 'set') {
+            const v = r.value;
             if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
-                operations.push({ op: 'set', field: raw.field, value: v });
+                operations.push({ op: 'set', field: r.field, value: v });
             }
         }
     }
@@ -264,7 +289,46 @@ function sanitizeAutoApply(raw) {
     const agentSlug = typeof obj.agentSlug === 'string' && /^[a-z0-9-]+$/i.test(obj.agentSlug)
         ? obj.agentSlug
         : undefined;
-    return agentSlug ? { agentSlug, operations } : { operations };
+    return { kind: 'cron', operations, ...(agentSlug ? { agentSlug } : {}) };
+}
+function sanitizeAutoApplyAdvisorRule(raw) {
+    const obj = raw;
+    if (typeof obj.ruleId !== 'string' || !obj.ruleId.trim())
+        return null;
+    if (!/^[a-z0-9-]+$/.test(obj.ruleId))
+        return null; // safe filename
+    if (typeof obj.yamlContent !== 'string' || !obj.yamlContent.trim())
+        return null;
+    if (obj.yamlContent.length > 10_000)
+        return null; // sanity bound
+    return {
+        kind: 'advisor-rule',
+        ruleId: obj.ruleId,
+        yamlContent: obj.yamlContent,
+    };
+}
+function sanitizeAutoApplyPromptOverride(raw) {
+    const obj = raw;
+    if (obj.scope !== 'global' && obj.scope !== 'agent' && obj.scope !== 'job')
+        return null;
+    if (typeof obj.content !== 'string' || !obj.content.trim())
+        return null;
+    if (obj.content.length > 20_000)
+        return null; // sanity bound
+    if (obj.scope === 'global') {
+        return { kind: 'prompt-override', scope: 'global', content: obj.content };
+    }
+    // agent or job — require scopeKey, validate as safe filename
+    if (typeof obj.scopeKey !== 'string' || !obj.scopeKey)
+        return null;
+    if (!/^[a-zA-Z0-9_:-]+$/.test(obj.scopeKey))
+        return null;
+    return {
+        kind: 'prompt-override',
+        scope: obj.scope,
+        scopeKey: obj.scopeKey,
+        content: obj.content,
+    };
 }
 /**
  * Diagnose one broken job. Returns a cached diagnosis if one exists and is

package/dist/gateway/failure-monitor.d.ts

@@ -25,28 +25,7 @@ export interface BrokenJob {
     circuitBreakerEngagedAt: string | null;
     lastAdvisorOpinion: string | null;
     /** Populated asynchronously by the diagnostic agent when available. */
-    diagnosis?: {
-        rootCause: string;
-        confidence: 'high' | 'medium' | 'low';
-        proposedFix: {
-            type: string;
-            details: string;
-            diff?: string;
-            autoApply?: {
-                agentSlug?: string;
-                operations: Array<{
-                    op: 'set';
-                    field: string;
-                    value: string | number | boolean;
-                } | {
-                    op: 'remove';
-                    field: string;
-                }>;
-            };
-        };
-        riskLevel: 'low' | 'medium' | 'high';
-        generatedAt: string;
-    };
+    diagnosis?: import('./failure-diagnostics.js').Diagnosis;
 }
 /**
  * Compute the current set of broken jobs by scanning all run logs.

package/dist/gateway/fix-applier.d.ts

@@ -11,7 +11,7 @@
  * Every apply writes a .bak next to the CRON.md and appends to an audit
  * log before touching the file.
  */
-import { type FixOperation } from './failure-diagnostics.js';
+import { type AutoApply, type FixOperation } from './failure-diagnostics.js';
 export interface ApplyResult {
     ok: boolean;
     message: string;
@@ -20,15 +20,19 @@ export interface ApplyResult {
     skippedOps?: FixOperation[];
     diff?: string;
 }
+export interface ApplyOptions {
+    dryRun?: boolean;
+    /** Override BASE_DIR for advisor-rule and prompt-override write paths. Tests only. */
+    baseDir?: string;
+}
 /**
- * Apply a proposed fix to the right CRON.md file. Idempotent with respect
- * to already-applied ops (remove on a missing field is a no-op, set on a
- * matching value is a no-op).
+ * Apply a proposed fix to the right target. Dispatches on autoApply.kind:
+ *   'cron'             — edit CRON.md frontmatter (the original path)
+ *   'advisor-rule'     — write a YAML rule under ~/.clementine/advisor-rules/user/
+ *   'prompt-override'  — write a markdown override under ~/.clementine/prompt-overrides/
+ *
+ * Each path has its own backup/audit. All idempotent: re-applying the same
+ * fix produces the same on-disk state.
  */
-export declare function applyFix(jobName: string, autoApply: {
-    agentSlug?: string;
-    operations: FixOperation[];
-}, opts?: {
-    dryRun?: boolean;
-}): ApplyResult;
+export declare function applyFix(jobName: string, autoApply: AutoApply, opts?: ApplyOptions): ApplyResult;
 //# sourceMappingURL=fix-applier.d.ts.map

package/dist/gateway/fix-applier.js

@@ -11,11 +11,12 @@
  * Every apply writes a .bak next to the CRON.md and appends to an audit
  * log before touching the file.
  */
-import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import pino from 'pino';
+import yaml from 'js-yaml';
 import { AGENTS_DIR, BASE_DIR, CRON_FILE } from '../config.js';
-import { EDITABLE_FIELDS } from './failure-diagnostics.js';
+import { EDITABLE_FIELDS, } from './failure-diagnostics.js';
 const logger = pino({ name: 'clementine.fix-applier' });
 const AUDIT_FILE = path.join(BASE_DIR, 'cron', 'fix-applier.log');
 /**
@@ -232,11 +233,26 @@ function findBlockEnd(lines, start) {
     return lines.length;
 }
 /**
- * Apply a proposed fix to the right CRON.md file. Idempotent with respect
- * to already-applied ops (remove on a missing field is a no-op, set on a
- * matching value is a no-op).
+ * Apply a proposed fix to the right target. Dispatches on autoApply.kind:
+ *   'cron'             — edit CRON.md frontmatter (the original path)
+ *   'advisor-rule'     — write a YAML rule under ~/.clementine/advisor-rules/user/
+ *   'prompt-override'  — write a markdown override under ~/.clementine/prompt-overrides/
+ *
+ * Each path has its own backup/audit. All idempotent: re-applying the same
+ * fix produces the same on-disk state.
  */
 export function applyFix(jobName, autoApply, opts = {}) {
+    // Default 'cron' for back-compat with old AutoApplyCron objects without kind.
+    const kind = autoApply.kind ?? 'cron';
+    if (kind === 'cron')
+        return applyCronFix(jobName, autoApply, opts);
+    if (kind === 'advisor-rule')
+        return applyAdvisorRuleFix(jobName, autoApply, opts);
+    if (kind === 'prompt-override')
+        return applyPromptOverrideFix(jobName, autoApply, opts);
+    return { ok: false, message: `Unknown autoApply.kind: ${String(kind)}` };
+}
+function applyCronFix(jobName, autoApply, opts) {
     const cronFile = resolveCronFile(jobName, autoApply);
     if (!cronFile) {
         return { ok: false, message: `No CRON.md found for ${jobName}` };
@@ -280,6 +296,7 @@ export function applyFix(jobName, autoApply, opts = {}) {
     const newContent = newLines.join('\n');
     writeFileSync(cronFile, newContent);
     appendAudit({
+        kind: 'cron',
         jobName,
         file: cronFile,
         applied,
@@ -296,6 +313,108 @@ export function applyFix(jobName, autoApply, opts = {}) {
         diff,
     };
 }
+// ── Advisor rule writer ──────────────────────────────────────────────
+function userRulesDir(baseDir) {
+    return path.join(baseDir, 'advisor-rules', 'user');
+}
+function applyAdvisorRuleFix(jobName, autoApply, opts) {
+    const targetDir = userRulesDir(opts.baseDir ?? BASE_DIR);
+    // Validate that the YAML parses and has the minimum schema shape. Don't
+    // require full Phase 2 zod validation here — the loader will reject invalid
+    // rules at read time and the next reload — but catch obvious malformed input.
+    let parsed;
+    try {
+        parsed = yaml.load(autoApply.yamlContent);
+    }
+    catch (err) {
+        return { ok: false, message: `Invalid YAML in advisor-rule body: ${String(err)}` };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { ok: false, message: 'advisor-rule yamlContent did not parse as a YAML object' };
+    }
+    const r = parsed;
+    if (r.schemaVersion !== 1) {
+        return { ok: false, message: 'advisor-rule must declare schemaVersion: 1' };
+    }
+    if (typeof r.id !== 'string' || r.id !== autoApply.ruleId) {
+        return { ok: false, message: `advisor-rule yamlContent id must match ruleId="${autoApply.ruleId}"` };
+    }
+    if (!Array.isArray(r.when) || !Array.isArray(r.then)) {
+        return { ok: false, message: 'advisor-rule must have when[] and then[] arrays' };
+    }
+    const targetPath = path.join(targetDir, `${autoApply.ruleId}.yaml`);
+    const diff = `+ advisor-rule ${autoApply.ruleId} → ${targetPath}`;
+    if (opts.dryRun) {
+        return { ok: true, message: 'Dry run: advisor-rule would be written', file: targetPath, diff };
+    }
+    try {
+        mkdirSync(targetDir, { recursive: true });
+        const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, autoApply.yamlContent);
+        renameSync(tmp, targetPath);
+    }
+    catch (err) {
+        return { ok: false, message: `Failed to write advisor rule: ${String(err)}` };
+    }
+    appendAudit({ kind: 'advisor-rule', jobName, file: targetPath, ruleId: autoApply.ruleId, diff });
+    logger.info({ jobName, ruleId: autoApply.ruleId, file: targetPath }, 'Applied advisor-rule fix');
+    return {
+        ok: true,
+        message: `Wrote advisor rule ${autoApply.ruleId} (hot-reloads on next eval)`,
+        file: targetPath,
+        diff,
+    };
+}
+// ── Prompt override writer ───────────────────────────────────────────
+function promptOverridesDir(baseDir) {
+    return path.join(baseDir, 'prompt-overrides');
+}
+function applyPromptOverrideFix(jobName, autoApply, opts) {
+    const root = promptOverridesDir(opts.baseDir ?? BASE_DIR);
+    // Resolve target path from scope.
+    let targetPath;
+    if (autoApply.scope === 'global') {
+        targetPath = path.join(root, '_global.md');
+    }
+    else {
+        if (!autoApply.scopeKey) {
+            return { ok: false, message: `prompt-override scope=${autoApply.scope} requires scopeKey` };
+        }
+        if (/[\/\\\.]/.test(autoApply.scopeKey)) {
+            return { ok: false, message: 'prompt-override scopeKey cannot contain "/", "\\", or "."' };
+        }
+        const sub = autoApply.scope === 'agent' ? 'agents' : 'jobs';
+        targetPath = path.join(root, sub, `${autoApply.scopeKey}.md`);
+    }
+    const diff = `+ prompt-override ${autoApply.scope}${autoApply.scopeKey ? `:${autoApply.scopeKey}` : ''} → ${targetPath}`;
+    if (opts.dryRun) {
+        return { ok: true, message: 'Dry run: prompt-override would be written', file: targetPath, diff };
+    }
+    try {
+        mkdirSync(path.dirname(targetPath), { recursive: true });
+        const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, autoApply.content);
+        renameSync(tmp, targetPath);
+    }
+    catch (err) {
+        return { ok: false, message: `Failed to write prompt override: ${String(err)}` };
+    }
+    appendAudit({
+        kind: 'prompt-override',
+        jobName,
+        file: targetPath,
+        scope: autoApply.scope,
+        scopeKey: autoApply.scopeKey,
+        diff,
+    });
+    logger.info({ jobName, scope: autoApply.scope, scopeKey: autoApply.scopeKey, file: targetPath }, 'Applied prompt-override fix');
+    return {
+        ok: true,
+        message: `Wrote prompt override ${autoApply.scope}${autoApply.scopeKey ? `:${autoApply.scopeKey}` : ''}`,
+        file: targetPath,
+        diff,
+    };
+}
 function appendAudit(entry) {
     try {
         mkdirSync(path.dirname(AUDIT_FILE), { recursive: true });

package/dist/tools/admin-tools.js

@@ -1671,6 +1671,72 @@ export function registerAdminTools(server) {
             `Reason: ${reason}\n\n` +
             `The daemon will validate in a staging worktree, then commit + build + restart if compilation succeeds.`);
     });
+    // ── Prompt Overrides ────────────────────────────────────────────────────
+    server.tool('prompt_override_write', 'Write a markdown file under ~/.clementine/prompt-overrides/ that gets prepended to a job\'s prompt at runtime. Use this when you identify that a specific cron job, agent, or all jobs need additional guidance, context, or constraints. Survives `npm update -g clementine` and reloads in <1s. Scopes: "global" (every job), "agent" (every job for one agent), "job" (one specific job).', {
+        scope: z.enum(['global', 'agent', 'job']).describe('Which jobs the override applies to'),
+        scopeKey: z.string().optional().describe('For scope=agent: the agent slug. For scope=job: the job name. Ignored for scope=global.'),
+        content: z.string().min(1).describe('Markdown body to prepend to the prompt. May include optional gray-matter frontmatter for priority/position.'),
+        reason: z.string().describe('Why this override is being written — for the audit log.'),
+    }, async ({ scope, scopeKey, content, reason }) => {
+        if ((scope === 'agent' || scope === 'job') && !scopeKey) {
+            return textResult(`Error: scope="${scope}" requires scopeKey to be provided.`);
+        }
+        if (scopeKey && /[\/\\\.]/.test(scopeKey)) {
+            return textResult('Error: scopeKey cannot contain "/", "\\", or "."');
+        }
+        const ROOT = path.join(BASE_DIR, 'prompt-overrides');
+        let targetPath;
+        if (scope === 'global') {
+            targetPath = path.join(ROOT, '_global.md');
+        }
+        else if (scope === 'agent') {
+            targetPath = path.join(ROOT, 'agents', `${scopeKey}.md`);
+        }
+        else {
+            targetPath = path.join(ROOT, 'jobs', `${scopeKey}.md`);
+        }
+        try {
+            mkdirSync(path.dirname(targetPath), { recursive: true });
+            const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+            writeFileSync(tmp, content);
+            renameSync(tmp, targetPath);
+            logger.info({ scope, scopeKey, targetPath, reason, contentLen: content.length }, 'Wrote prompt override');
+            return textResult(`Prompt override written.\n` +
+                `Scope: ${scope}${scopeKey ? ` (${scopeKey})` : ''}\n` +
+                `Path: ${targetPath}\n` +
+                `Reason: ${reason}\n\n` +
+                `The override will be picked up on the next job run (hot-reloads via fs.watch within ~1s).`);
+        }
+        catch (err) {
+            logger.error({ err, scope, scopeKey, targetPath }, 'Failed to write prompt override');
+            return textResult(`Failed to write prompt override: ${String(err)}`);
+        }
+    });
+    server.tool('prompt_override_list', 'List all prompt overrides currently active in ~/.clementine/prompt-overrides/, grouped by scope. Use this to see what overrides exist before writing or removing one.', {}, async () => {
+        const ROOT = path.join(BASE_DIR, 'prompt-overrides');
+        if (!existsSync(ROOT)) {
+            return textResult('No prompt-overrides directory yet. Use prompt_override_write to create one.');
+        }
+        const lines = ['## Prompt Overrides'];
+        const globalPath = path.join(ROOT, '_global.md');
+        if (existsSync(globalPath))
+            lines.push(`- global: _global.md`);
+        const agentsDir = path.join(ROOT, 'agents');
+        if (existsSync(agentsDir)) {
+            for (const f of readdirSync(agentsDir).filter(f => f.endsWith('.md'))) {
+                lines.push(`- agent: ${path.basename(f, '.md')}`);
+            }
+        }
+        const jobsDir = path.join(ROOT, 'jobs');
+        if (existsSync(jobsDir)) {
+            for (const f of readdirSync(jobsDir).filter(f => f.endsWith('.md'))) {
+                lines.push(`- job: ${path.basename(f, '.md')}`);
+            }
+        }
+        if (lines.length === 1)
+            lines.push('(none)');
+        return textResult(lines.join('\n'));
+    });
     server.tool('update_self', 'Check for and apply upstream code updates. Can check without applying, or check and apply in one step.', {
         action: z.enum(['check', 'apply']).describe('"check" to see if updates are available, "apply" to pull and restart'),
     }, async ({ action }) => {

package/package.json

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