clementine-agent 1.0.93 → 1.0.95

package/dist/agent/advisor-rules/builtin/010-circuit-breaker-cooldown.yaml

@@ -0,0 +1,18 @@
+schemaVersion: 1
+id: circuit-breaker-cooldown
+description: >
+  Skip the run when 5+ consecutive errors are followed by a recent (within
+  60min) run — circuit breaker is engaged and we are still cooling down.
+priority: 10
+when:
+  - kind: consecutiveErrorsAtLeast
+    count: 5
+  - kind: lastRunWithinMs
+    ms: 3600000
+then:
+  - kind: skipWithReason
+    reason: "consecutive errors — circuit breaker engaged"
+    reasonTemplate: "{{ consecutiveErrors }} consecutive errors — circuit breaker engaged (next probe in {{ cooldownProbeMin }}m)"
+stopOnFire: true
+log:
+  reason: Circuit breaker — cooling down

package/dist/agent/advisor-rules/builtin/011-circuit-breaker-no-runs.yaml

@@ -0,0 +1,15 @@
+schemaVersion: 1
+id: circuit-breaker-no-runs
+description: >
+  Defensive — if we have 5+ consecutive errors but no recent runs (state
+  divergence), skip without probe info. Should virtually never fire.
+priority: 11
+when:
+  - kind: consecutiveErrorsAtLeast
+    count: 5
+  - kind: noRecentRuns
+then:
+  - kind: skipWithReason
+    reason: "consecutive errors — circuit breaker engaged"
+    reasonTemplate: "{{ consecutiveErrors }} consecutive errors — circuit breaker engaged"
+stopOnFire: true

package/dist/agent/advisor-rules/builtin/020-prompt-too-long.yaml

@@ -0,0 +1,20 @@
+schemaVersion: 1
+id: prompt-too-long
+description: >
+  When recent runs hit prompt-length limits, append conciseness guidance
+  rather than bumping turns. Runs before turn-limit-hits and shadows it
+  via skipIf so the turn-bump rule does not fire when prompt size is the
+  real constraint.
+priority: 20
+appliesTo:
+  jobMode: standard
+when:
+  - kind: recentTerminalReason
+    reason: prompt_too_long
+    window: 5
+    atLeast: 1
+then:
+  - kind: appendPromptEnrichment
+    text: "\n\n⚠ Previous runs hit prompt length limits. Be concise. Minimize system prompt injection."
+log:
+  reason: Prompt too long detected — adding conciseness guidance

package/dist/agent/advisor-rules/builtin/025-turn-limit-hits.yaml

@@ -0,0 +1,24 @@
+schemaVersion: 1
+id: turn-limit-hits
+description: >
+  When recent runs hit max_turns, bump maxTurns up to the tier cap. Skips
+  unleashed jobs (they manage turns via UNLEASHED_PHASE_TURNS) and skips
+  when prompt_too_long is the real constraint.
+priority: 25
+appliesTo:
+  jobMode: standard
+skipIf:
+  - kind: recentTerminalReason
+    reason: prompt_too_long
+    window: 5
+    atLeast: 1
+when:
+  - kind: recentTerminalReason
+    reason: max_turns
+    window: 5
+    atLeast: 2
+then:
+  - kind: bumpMaxTurns
+    multiplier: 1.5
+log:
+  reason: Adjusting maxTurns due to turn-limit hits

package/dist/agent/advisor-rules/builtin/026-suppress-turn-bump-low-success.yaml

@@ -0,0 +1,17 @@
+schemaVersion: 1
+id: suppress-turn-bump-low-success
+description: >
+  Clear the maxTurns adjustment if past advisor decisions show turn
+  adjustments succeed less than 20% of the time for this job.
+priority: 26
+when:
+  - kind: adviceFieldSet
+    field: adjustedMaxTurns
+  - kind: interventionStatBelow
+    stat: turnAdjustSuccessRate
+    threshold: 0.2
+then:
+  - kind: clearAdviceField
+    field: adjustedMaxTurns
+log:
+  reason: Suppressing turn adjustment — historically ineffective

package/dist/agent/advisor-rules/builtin/030-reflection-quality.yaml

@@ -0,0 +1,17 @@
+schemaVersion: 1
+id: reflection-quality
+description: >
+  When reflections show consistently low quality, delegate to the prompt
+  evolver for prompt enrichment. Skips unleashed jobs.
+priority: 30
+appliesTo:
+  jobMode: standard
+when:
+  - kind: avgReflectionQualityBelow
+    window: 5
+    threshold: 3.0
+    minSamples: 3
+then:
+  - kind: invokePromptEvolver
+log:
+  reason: Built prompt enrichment via prompt evolver

package/dist/agent/advisor-rules/builtin/031-suppress-enrichment-low-success.yaml

@@ -0,0 +1,17 @@
+schemaVersion: 1
+id: suppress-enrichment-low-success
+description: >
+  Clear prompt enrichment if past decisions show enrichment succeeds
+  less than 20% of the time for this job.
+priority: 31
+when:
+  - kind: adviceFieldSet
+    field: promptEnrichment
+  - kind: interventionStatBelow
+    stat: enrichmentSuccessRate
+    threshold: 0.2
+then:
+  - kind: clearAdviceField
+    field: promptEnrichment
+log:
+  reason: Suppressing prompt enrichment — historically ineffective

package/dist/agent/advisor-rules/builtin/040-model-upgrade-on-error.yaml

@@ -0,0 +1,20 @@
+schemaVersion: 1
+id: model-upgrade-on-error
+description: >
+  Upgrade haiku-tier models to sonnet when the SDK reports model_error
+  (precise signal that the model itself is the problem).
+priority: 40
+appliesTo:
+  jobMode: standard
+when:
+  - kind: modelContains
+    substring: haiku
+  - kind: recentTerminalReason
+    reason: model_error
+    window: 5
+    atLeast: 1
+then:
+  - kind: setModel
+    model: sonnet
+log:
+  reason: Upgrading model — SDK reported model_error

package/dist/agent/advisor-rules/builtin/041-model-upgrade-on-failures.yaml

@@ -0,0 +1,22 @@
+schemaVersion: 1
+id: model-upgrade-on-failures
+description: >
+  Fallback model upgrade when haiku-tier shows 3+ recent failures even
+  without an explicit model_error signal.
+priority: 41
+appliesTo:
+  jobMode: standard
+skipIf:
+  - kind: adviceFieldSet
+    field: adjustedModel
+when:
+  - kind: modelContains
+    substring: haiku
+  - kind: recentErrorCount
+    window: 5
+    atLeast: 3
+then:
+  - kind: setModel
+    model: sonnet
+log:
+  reason: Upgrading model from haiku to sonnet due to repeated failures

package/dist/agent/advisor-rules/builtin/042-suppress-model-upgrade-low-success.yaml

@@ -0,0 +1,17 @@
+schemaVersion: 1
+id: suppress-model-upgrade-low-success
+description: >
+  Clear model upgrade if past decisions show model upgrades succeed
+  less than 20% of the time for this job.
+priority: 42
+when:
+  - kind: adviceFieldSet
+    field: adjustedModel
+  - kind: interventionStatBelow
+    stat: modelUpgradeSuccessRate
+    threshold: 0.2
+then:
+  - kind: clearAdviceField
+    field: adjustedModel
+log:
+  reason: Suppressing model upgrade — historically ineffective

package/dist/agent/advisor-rules/builtin/050-timeout-hits.yaml

@@ -0,0 +1,18 @@
+schemaVersion: 1
+id: timeout-hits
+description: >
+  Bump timeout when 2+ recent runs ran past 95% of the standard cron
+  timeout. Skips unleashed jobs (different timeout model).
+priority: 50
+appliesTo:
+  jobMode: standard
+when:
+  - kind: recentTimeoutHits
+    window: 5
+    atLeast: 2
+    thresholdRatio: 0.95
+then:
+  - kind: bumpTimeoutMs
+    multiplier: 1.5
+log:
+  reason: Adjusting timeout due to timeout hits

package/dist/agent/advisor-rules/builtin/060-escalate-sonnet-failures.yaml

@@ -0,0 +1,22 @@
+schemaVersion: 1
+id: escalate-sonnet-failures
+description: >
+  Escalate to unleashed when a sonnet-tier job is still failing after a
+  potential model upgrade. Uses effectiveModelContains so it triggers
+  for jobs that started on sonnet AND for jobs upgraded to sonnet by
+  the model-upgrade rules.
+priority: 60
+appliesTo:
+  jobMode: standard
+when:
+  - kind: effectiveModelContains
+    substring: sonnet
+  - kind: recentErrorCount
+    window: 5
+    atLeast: 3
+then:
+  - kind: escalateWithReason
+    reason: "recent failures on sonnet-tier model"
+    reasonTemplate: "{{ recentErrorCount }} recent failures on sonnet-tier model"
+log:
+  reason: Recommending escalation to unleashed

package/dist/agent/advisor-rules/builtin/061-escalate-sonnet-low-quality.yaml

@@ -0,0 +1,25 @@
+schemaVersion: 1
+id: escalate-sonnet-low-quality
+description: >
+  Escalate when a sonnet-tier job has 3+ low-quality reflections.
+  Companion to escalate-sonnet-failures; runs after so failures-based
+  reason wins if both apply.
+priority: 61
+appliesTo:
+  jobMode: standard
+skipIf:
+  - kind: adviceFieldSet
+    field: shouldEscalate
+when:
+  - kind: effectiveModelContains
+    substring: sonnet
+  - kind: lowQualityReflectionCount
+    window: 5
+    maxQuality: 2
+    atLeast: 3
+then:
+  - kind: escalateWithReason
+    reason: "low-quality reflections despite sonnet-tier model"
+    reasonTemplate: "{{ lowQualityReflectionCount }} low-quality reflections despite sonnet-tier model"
+log:
+  reason: Recommending escalation due to low-quality reflections

package/dist/agent/advisor-rules/builtin/070-escalate-low-confidence-completions.yaml

@@ -0,0 +1,24 @@
+schemaVersion: 1
+id: escalate-low-confidence-completions
+description: >
+  When a job consistently completes successfully but produces low-quality
+  output (2+ low-quality reflections AND 2+ ok runs in the last 3),
+  flag for human review. Skips if any earlier rule already escalated.
+priority: 70
+skipIf:
+  - kind: adviceFieldSet
+    field: shouldEscalate
+when:
+  - kind: lowQualityReflectionCount
+    window: 3
+    maxQuality: 3
+    atLeast: 2
+  - kind: recentSuccessCountAtLeast
+    window: 3
+    atLeast: 2
+then:
+  - kind: escalateWithReason
+    reason: "Job completes but quality is consistently low — may need human review"
+    reasonTemplate: "Job completes but quality is consistently low ({{ lowQualityReflectionCount }}/3 reflections scored ≤3) — may need human review"
+log:
+  reason: Recommending escalation due to low-confidence completions

package/dist/agent/advisor-rules/context.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Advisor Rule Engine — context builder.
+ *
+ * Builds a `RuleContext` from the same data sources the legacy TS advisor reads:
+ *   - CronRunLog for recent run history and consecutive errors
+ *   - readReflections() for reflection JSONL
+ *   - getInterventionStats() for past advisor outcome stats
+ *
+ * Both shadow mode and (eventually) primary mode share this builder so the
+ * data pipeline is identical and any divergence is purely rule-evaluation.
+ */
+import { CronRunLog } from '../../gateway/cron-scheduler.js';
+import type { CronJobDefinition, ExecutionAdvice } from '../../types.js';
+import type { RuleContext } from './types.js';
+/**
+ * Build a fresh RuleContext for a job. Pass an existing `advice` if you want
+ * to mutate it (e.g. shadow mode passes a clone so the TS path's advice is
+ * preserved unchanged).
+ */
+export declare function buildRuleContext(jobName: string, job: CronJobDefinition, options?: {
+    advice?: ExecutionAdvice;
+    nowMs?: number;
+    runLog?: CronRunLog;
+}): RuleContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/agent/advisor-rules/context.js

@@ -0,0 +1,49 @@
+/**
+ * Advisor Rule Engine — context builder.
+ *
+ * Builds a `RuleContext` from the same data sources the legacy TS advisor reads:
+ *   - CronRunLog for recent run history and consecutive errors
+ *   - readReflections() for reflection JSONL
+ *   - getInterventionStats() for past advisor outcome stats
+ *
+ * Both shadow mode and (eventually) primary mode share this builder so the
+ * data pipeline is identical and any divergence is purely rule-evaluation.
+ */
+import { CronRunLog } from '../../gateway/cron-scheduler.js';
+import { CIRCUIT_BREAKER_COOLDOWN_MS as _COOLDOWN_MS, DEFAULT_MAX_TURNS_FALLBACK, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, TIER_MAX_TURNS, getInterventionStats, readReflections, } from '../execution-advisor.js';
+void _COOLDOWN_MS; // currently encoded as a literal in builtin YAMLs; re-export hook
+/**
+ * Build a fresh RuleContext for a job. Pass an existing `advice` if you want
+ * to mutate it (e.g. shadow mode passes a clone so the TS path's advice is
+ * preserved unchanged).
+ */
+export function buildRuleContext(jobName, job, options) {
+    const runLog = options?.runLog ?? new CronRunLog();
+    const recentRuns = runLog.readRecent(jobName, 10);
+    const consecutiveErrors = runLog.consecutiveErrors(jobName);
+    const reflections = readReflections(jobName);
+    const interventionStats = getInterventionStats(jobName);
+    const advice = options?.advice ?? {
+        adjustedMaxTurns: null,
+        adjustedModel: null,
+        adjustedTimeoutMs: null,
+        promptEnrichment: '',
+        shouldEscalate: false,
+        shouldSkip: false,
+    };
+    return {
+        job,
+        jobName,
+        recentRuns,
+        reflections,
+        consecutiveErrors,
+        interventionStats,
+        advice,
+        nowMs: options?.nowMs ?? Date.now(),
+        tierMaxTurns: TIER_MAX_TURNS,
+        defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+        maxTimeoutMs: MAX_TIMEOUT_MS,
+        defaultMaxTurns: DEFAULT_MAX_TURNS_FALLBACK,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/agent/advisor-rules/engine.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Advisor Rule Engine — evaluation.
+ *
+ * Pure functions: `evaluateWhen(condition, ctx)` and `applyThen(action, ctx)`.
+ * Both operate on a RuleContext that holds the job, run history, reflections,
+ * outcome stats, and a mutable ExecutionAdvice.
+ *
+ * No expression language. No eval. Each predicate and action is a closed-set
+ * tag with explicit fields.
+ */
+import type { ExecutionAdvice } from '../../types.js';
+import type { AdvisorRule, RuleContext, ThenAction, WhenCondition } from './types.js';
+export declare function ruleApplies(rule: AdvisorRule, ctx: RuleContext): boolean;
+export declare function evaluateWhen(c: WhenCondition, ctx: RuleContext): boolean;
+export declare function applyThen(a: ThenAction, ctx: RuleContext): void;
+export interface AppliedRuleTrace {
+    ruleId: string;
+    fired: boolean;
+    reason?: string;
+    skippedBy?: string;
+}
+/** Run a single rule against the context, mutating ctx.advice if it fires. */
+export declare function applyRule(rule: AdvisorRule, ctx: RuleContext): AppliedRuleTrace;
+/** Apply all rules in order (already sorted by priority by the loader). */
+export declare function applyRules(rules: AdvisorRule[], ctx: RuleContext): {
+    advice: ExecutionAdvice;
+    traces: AppliedRuleTrace[];
+};
+//# sourceMappingURL=engine.d.ts.map

package/dist/agent/advisor-rules/engine.js

@@ -0,0 +1,240 @@
+/**
+ * Advisor Rule Engine — evaluation.
+ *
+ * Pure functions: `evaluateWhen(condition, ctx)` and `applyThen(action, ctx)`.
+ * Both operate on a RuleContext that holds the job, run history, reflections,
+ * outcome stats, and a mutable ExecutionAdvice.
+ *
+ * No expression language. No eval. Each predicate and action is a closed-set
+ * tag with explicit fields.
+ */
+import { evolvePrompt } from '../prompt-evolver.js';
+// ── Scoping ──────────────────────────────────────────────────────────
+export function ruleApplies(rule, ctx) {
+    const a = rule.appliesTo;
+    if (!a)
+        return true;
+    if (a.agentSlug != null && ctx.job.agentSlug !== a.agentSlug)
+        return false;
+    if (a.jobName != null && ctx.job.name !== a.jobName)
+        return false;
+    if (a.jobMode !== undefined) {
+        const jobMode = ctx.job.mode ?? null;
+        // null in appliesTo.jobMode means "any mode"
+        if (a.jobMode !== null && jobMode !== a.jobMode)
+            return false;
+    }
+    if (a.tier && a.tier.length > 0 && !a.tier.includes(ctx.job.tier))
+        return false;
+    return true;
+}
+// ── Condition evaluation ─────────────────────────────────────────────
+export function evaluateWhen(c, ctx) {
+    switch (c.kind) {
+        case 'recentTerminalReason': {
+            const window = ctx.recentRuns.slice(0, c.window);
+            const hits = window.filter(r => {
+                if (r.status !== 'error' && r.status !== 'retried')
+                    return false;
+                return r.terminalReason === c.reason;
+            });
+            return hits.length >= c.atLeast;
+        }
+        case 'recentErrorCount': {
+            const window = ctx.recentRuns.slice(0, c.window);
+            const errors = window.filter(r => r.status === 'error');
+            return errors.length >= c.atLeast;
+        }
+        case 'recentTimeoutHits': {
+            const ratio = c.thresholdRatio ?? 0.95;
+            const threshold = ctx.defaultTimeoutMs * ratio;
+            const window = ctx.recentRuns.slice(0, c.window);
+            const hits = window.filter(r => r.status === 'error' && r.durationMs >= threshold);
+            return hits.length >= c.atLeast;
+        }
+        case 'avgReflectionQualityBelow': {
+            const recent = ctx.reflections.slice(0, c.window);
+            if (recent.length < c.minSamples)
+                return false;
+            const avg = recent.reduce((sum, r) => sum + r.quality, 0) / recent.length;
+            return avg < c.threshold;
+        }
+        case 'lowQualityReflectionCount': {
+            const recent = ctx.reflections.slice(0, c.window);
+            const low = recent.filter(r => r.quality <= c.maxQuality);
+            return low.length >= c.atLeast;
+        }
+        case 'consecutiveErrorsAtLeast':
+            return ctx.consecutiveErrors >= c.count;
+        case 'lastRunOlderThanMs': {
+            const lastRun = ctx.recentRuns[0];
+            if (!lastRun)
+                return false;
+            const lastRunTime = new Date(lastRun.finishedAt).getTime();
+            return ctx.nowMs - lastRunTime > c.ms;
+        }
+        case 'lastRunWithinMs': {
+            const lastRun = ctx.recentRuns[0];
+            if (!lastRun)
+                return false;
+            const lastRunTime = new Date(lastRun.finishedAt).getTime();
+            return ctx.nowMs - lastRunTime <= c.ms;
+        }
+        case 'noRecentRuns':
+            return ctx.recentRuns.length === 0;
+        case 'modelContains': {
+            const model = ctx.job.model?.toLowerCase() ?? '';
+            return model.includes(c.substring.toLowerCase());
+        }
+        case 'effectiveModelContains': {
+            const sub = c.substring.toLowerCase();
+            const baseModel = ctx.job.model?.toLowerCase() ?? '';
+            const adjusted = (ctx.advice.adjustedModel ?? '').toLowerCase();
+            return baseModel.includes(sub) || adjusted.includes(sub);
+        }
+        case 'recentSuccessCountAtLeast': {
+            const window = ctx.recentRuns.slice(0, c.window);
+            const ok = window.filter(r => r.status === 'ok');
+            return ok.length >= c.atLeast;
+        }
+        case 'adviceFieldSet': {
+            const v = ctx.advice[c.field];
+            // truthy check matches the existing TS suppression pattern
+            return v !== null && v !== undefined && v !== false && v !== '';
+        }
+        case 'interventionStatBelow': {
+            const stat = ctx.interventionStats[c.stat];
+            if (stat === null)
+                return false; // null = no data, do not suppress
+            const minSamples = c.minSamples ?? 0;
+            if (ctx.interventionStats.sampleSize < minSamples)
+                return false;
+            return stat < c.threshold;
+        }
+    }
+}
+// ── Action application ───────────────────────────────────────────────
+export function applyThen(a, ctx) {
+    switch (a.kind) {
+        case 'bumpMaxTurns': {
+            const baseDefault = a.baseDefault ?? ctx.defaultMaxTurns;
+            const multiplier = a.multiplier ?? 1.5;
+            const currentMax = ctx.job.maxTurns ?? baseDefault;
+            const tierCap = ctx.tierMaxTurns[ctx.job.tier] ?? ctx.tierMaxTurns[1];
+            const proposed = Math.ceil(currentMax * multiplier);
+            ctx.advice.adjustedMaxTurns = Math.min(proposed, tierCap);
+            return;
+        }
+        case 'bumpTimeoutMs': {
+            const baseMs = a.baseMs ?? ctx.defaultTimeoutMs;
+            const multiplier = a.multiplier ?? 1.5;
+            const proposed = Math.ceil(baseMs * multiplier);
+            ctx.advice.adjustedTimeoutMs = Math.min(proposed, ctx.maxTimeoutMs);
+            return;
+        }
+        case 'setModel':
+            ctx.advice.adjustedModel = a.model;
+            return;
+        case 'appendPromptEnrichment':
+            ctx.advice.promptEnrichment = (ctx.advice.promptEnrichment || '') + a.text;
+            return;
+        case 'invokePromptEvolver': {
+            const enrichment = evolvePrompt({
+                jobName: ctx.job.name,
+                originalPrompt: ctx.job.prompt,
+                agentSlug: ctx.job.agentSlug,
+            });
+            if (enrichment)
+                ctx.advice.promptEnrichment = enrichment;
+            return;
+        }
+        case 'skipWithReason':
+            ctx.advice.shouldSkip = true;
+            ctx.advice.skipReason = renderReason(a.reasonTemplate ?? a.reason, ctx);
+            return;
+        case 'escalateWithReason':
+            ctx.advice.shouldEscalate = true;
+            ctx.advice.escalationReason = renderReason(a.reasonTemplate ?? a.reason, ctx);
+            return;
+        case 'clearAdviceField': {
+            switch (a.field) {
+                case 'promptEnrichment':
+                    ctx.advice.promptEnrichment = '';
+                    return;
+                case 'adjustedMaxTurns':
+                    ctx.advice.adjustedMaxTurns = null;
+                    return;
+                case 'adjustedModel':
+                    ctx.advice.adjustedModel = null;
+                    return;
+                case 'adjustedTimeoutMs':
+                    ctx.advice.adjustedTimeoutMs = null;
+                    return;
+            }
+            return;
+        }
+    }
+}
+// ── Reason templating (tiny — only context vars, no expressions) ─────
+const TEMPLATE_VARS = {
+    consecutiveErrors: (ctx) => ctx.consecutiveErrors,
+    jobName: (ctx) => ctx.job.name,
+    recentErrorCount: (ctx) => ctx.recentRuns.slice(0, 5).filter(r => r.status === 'error').length,
+    lowQualityReflectionCount: (ctx) => ctx.reflections.slice(0, 5).filter(r => r.quality <= 2).length,
+    cooldownProbeMin: (ctx) => {
+        const lastRun = ctx.recentRuns[0];
+        if (!lastRun)
+            return 0;
+        const lastRunTime = new Date(lastRun.finishedAt).getTime();
+        const elapsed = ctx.nowMs - lastRunTime;
+        const cooldown = 60 * 60 * 1000;
+        return Math.max(0, Math.ceil((cooldown - elapsed) / 60_000));
+    },
+};
+function renderReason(template, ctx) {
+    return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, name) => {
+        const fn = TEMPLATE_VARS[name];
+        return fn ? String(fn(ctx)) : match;
+    });
+}
+/** Run a single rule against the context, mutating ctx.advice if it fires. */
+export function applyRule(rule, ctx) {
+    const trace = { ruleId: rule.id, fired: false };
+    if (!ruleApplies(rule, ctx)) {
+        trace.skippedBy = 'appliesTo';
+        return trace;
+    }
+    if (rule.skipIf && rule.skipIf.length > 0) {
+        for (const cond of rule.skipIf) {
+            if (evaluateWhen(cond, ctx)) {
+                trace.skippedBy = `skipIf:${cond.kind}`;
+                return trace;
+            }
+        }
+    }
+    for (const cond of rule.when) {
+        if (!evaluateWhen(cond, ctx)) {
+            trace.skippedBy = `when:${cond.kind}`;
+            return trace;
+        }
+    }
+    for (const action of rule.then) {
+        applyThen(action, ctx);
+    }
+    trace.fired = true;
+    if (rule.log?.reason)
+        trace.reason = rule.log.reason;
+    return trace;
+}
+/** Apply all rules in order (already sorted by priority by the loader). */
+export function applyRules(rules, ctx) {
+    const traces = [];
+    for (const rule of rules) {
+        const trace = applyRule(rule, ctx);
+        traces.push(trace);
+        if (trace.fired && rule.stopOnFire)
+            break;
+    }
+    return { advice: ctx.advice, traces };
+}
+//# sourceMappingURL=engine.js.map

package/dist/agent/advisor-rules/loader.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Advisor Rule Engine — loader.
+ *
+ * Reads YAML rule files from:
+ *   1. PKG_DIR/dist/agent/advisor-rules/builtin/*.yaml — engine builtins (npm package)
+ *   2. ~/.clementine/advisor-rules/builtin/*.yaml      — synced copy (rewritten on update)
+ *   3. ~/.clementine/advisor-rules/user/*.yaml         — user/LLM-authored, never overwritten
+ *
+ * User rules with the same `id` as a builtin replace the builtin.
+ * Lower `priority` runs first.
+ *
+ * fs.watch on the user dir triggers hot reload (debounced, atomic swap).
+ */
+import type { AdvisorRule } from './types.js';
+export interface LoaderOptions {
+    baseDir?: string;
+    pkgBuiltinDir?: string;
+}
+/**
+ * Load (or reload) all advisor rules. Idempotent — call from boot, hot-reload, and tests.
+ */
+export declare function loadAdvisorRules(opts?: LoaderOptions): AdvisorRule[];
+/** Read the most recently loaded rule set (no I/O). */
+export declare function getLoadedRules(): AdvisorRule[];
+/** Install fs.watch on the user rules dir. Safe to call multiple times. */
+export declare function watchUserRulesDir(opts?: LoaderOptions): void;
+/** Test-only: clear cached state. */
+export declare function _resetLoaderState(): void;
+//# sourceMappingURL=loader.d.ts.map