clementine-agent 1.0.94 → 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

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

@@ -0,0 +1,202 @@
+/**
+ * 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 { existsSync, mkdirSync, readFileSync, readdirSync, watch as fsWatch, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+import { BASE_DIR, PKG_DIR } from '../../config.js';
+const logger = pino({ name: 'clementine.advisor-rules' });
+// ── Paths ────────────────────────────────────────────────────────────
+/**
+ * Engine builtins shipped in the npm package. Prefer dist/ (post-build); fall
+ * back to src/ for tsx-driven dev runs and unit tests.
+ */
+function resolvePkgBuiltinDir() {
+    const distPath = path.join(PKG_DIR, 'dist', 'agent', 'advisor-rules', 'builtin');
+    if (existsSync(distPath))
+        return distPath;
+    return path.join(PKG_DIR, 'src', 'agent', 'advisor-rules', 'builtin');
+}
+function userBuiltinDir(baseDir) {
+    return path.join(baseDir, 'advisor-rules', 'builtin');
+}
+function userRulesDir(baseDir) {
+    return path.join(baseDir, 'advisor-rules', 'user');
+}
+// ── Validation schema ───────────────────────────────────────────────
+const appliesToSchema = z.object({
+    agentSlug: z.string().nullable().optional(),
+    jobName: z.string().nullable().optional(),
+    jobMode: z.enum(['standard', 'unleashed']).nullable().optional(),
+    tier: z.array(z.number().int().positive()).optional(),
+}).optional();
+const whenSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('recentTerminalReason'), reason: z.string(), window: z.number().int().positive(), atLeast: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('recentErrorCount'), window: z.number().int().positive(), atLeast: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('recentTimeoutHits'), window: z.number().int().positive(), atLeast: z.number().int().nonnegative(), thresholdRatio: z.number().positive().optional() }),
+    z.object({ kind: z.literal('avgReflectionQualityBelow'), window: z.number().int().positive(), threshold: z.number(), minSamples: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('lowQualityReflectionCount'), window: z.number().int().positive(), maxQuality: z.number(), atLeast: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('consecutiveErrorsAtLeast'), count: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('lastRunOlderThanMs'), ms: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('lastRunWithinMs'), ms: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('noRecentRuns') }),
+    z.object({ kind: z.literal('modelContains'), substring: z.string() }),
+    z.object({ kind: z.literal('effectiveModelContains'), substring: z.string() }),
+    z.object({ kind: z.literal('recentSuccessCountAtLeast'), window: z.number().int().positive(), atLeast: z.number().int().nonnegative() }),
+    z.object({ kind: z.literal('adviceFieldSet'), field: z.string() }),
+    z.object({ kind: z.literal('interventionStatBelow'), stat: z.enum(['modelUpgradeSuccessRate', 'turnAdjustSuccessRate', 'enrichmentSuccessRate']), threshold: z.number(), minSamples: z.number().int().nonnegative().optional() }),
+]);
+const thenSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('bumpMaxTurns'), multiplier: z.number().positive().optional(), baseDefault: z.number().int().positive().optional() }),
+    z.object({ kind: z.literal('bumpTimeoutMs'), multiplier: z.number().positive().optional(), baseMs: z.number().int().positive().optional() }),
+    z.object({ kind: z.literal('setModel'), model: z.string() }),
+    z.object({ kind: z.literal('appendPromptEnrichment'), text: z.string() }),
+    z.object({ kind: z.literal('invokePromptEvolver') }),
+    z.object({ kind: z.literal('skipWithReason'), reason: z.string(), reasonTemplate: z.string().optional() }),
+    z.object({ kind: z.literal('escalateWithReason'), reason: z.string(), reasonTemplate: z.string().optional() }),
+    z.object({ kind: z.literal('clearAdviceField'), field: z.enum(['adjustedMaxTurns', 'adjustedModel', 'adjustedTimeoutMs', 'promptEnrichment']) }),
+]);
+const ruleSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    description: z.string(),
+    priority: z.number().int().nonnegative(),
+    appliesTo: appliesToSchema,
+    skipIf: z.array(whenSchema).optional(),
+    when: z.array(whenSchema),
+    then: z.array(thenSchema),
+    stopOnFire: z.boolean().optional(),
+    log: z.object({ reason: z.string().optional() }).optional(),
+});
+// ── Loader ──────────────────────────────────────────────────────────
+let cachedRules = [];
+let watcherInstalled = false;
+let watchDebounce = null;
+function readYamlFile(filePath) {
+    try {
+        return yaml.load(readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to parse advisor rule YAML');
+        return null;
+    }
+}
+function readRulesFromDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith('.yaml') && !entry.endsWith('.yml'))
+            continue;
+        const filePath = path.join(dir, entry);
+        const raw = readYamlFile(filePath);
+        if (!raw)
+            continue;
+        const parsed = ruleSchema.safeParse(raw);
+        if (!parsed.success) {
+            logger.warn({ filePath, errors: parsed.error.issues.slice(0, 3) }, 'Invalid advisor rule schema — skipping');
+            continue;
+        }
+        out.push({ ...parsed.data, _sourcePath: filePath });
+    }
+    return out;
+}
+/** Copy package builtins to the user-visible directory (overwrites). */
+function syncBuiltinsToUserSpace(pkgBuiltinDir, dstDir) {
+    if (!existsSync(pkgBuiltinDir)) {
+        logger.debug({ pkgBuiltinDir }, 'No package builtins directory — skipping sync');
+        return;
+    }
+    if (!existsSync(dstDir)) {
+        mkdirSync(dstDir, { recursive: true });
+    }
+    for (const entry of readdirSync(pkgBuiltinDir)) {
+        if (!entry.endsWith('.yaml') && !entry.endsWith('.yml'))
+            continue;
+        const src = path.join(pkgBuiltinDir, entry);
+        const dst = path.join(dstDir, entry);
+        try {
+            writeFileSync(dst, readFileSync(src));
+        }
+        catch (err) {
+            logger.warn({ err, entry }, 'Failed to sync builtin rule to user-space');
+        }
+    }
+}
+function mergeAndSort(builtins, user) {
+    const byId = new Map();
+    for (const r of builtins)
+        byId.set(r.id, r);
+    for (const r of user)
+        byId.set(r.id, r); // user overrides builtin
+    return Array.from(byId.values()).sort((a, b) => a.priority - b.priority);
+}
+/**
+ * Load (or reload) all advisor rules. Idempotent — call from boot, hot-reload, and tests.
+ */
+export function loadAdvisorRules(opts) {
+    const baseDir = opts?.baseDir ?? BASE_DIR;
+    const pkgBuiltinDir = opts?.pkgBuiltinDir ?? resolvePkgBuiltinDir();
+    syncBuiltinsToUserSpace(pkgBuiltinDir, userBuiltinDir(baseDir));
+    const builtins = readRulesFromDir(pkgBuiltinDir);
+    const userDir = userRulesDir(baseDir);
+    const user = existsSync(userDir) ? readRulesFromDir(userDir) : [];
+    cachedRules = mergeAndSort(builtins, user);
+    logger.info({ builtinCount: builtins.length, userCount: user.length, total: cachedRules.length }, 'Advisor rules loaded');
+    return cachedRules;
+}
+/** Read the most recently loaded rule set (no I/O). */
+export function getLoadedRules() {
+    return cachedRules;
+}
+/** Install fs.watch on the user rules dir. Safe to call multiple times. */
+export function watchUserRulesDir(opts) {
+    if (watcherInstalled)
+        return;
+    const baseDir = opts?.baseDir ?? BASE_DIR;
+    const userDir = userRulesDir(baseDir);
+    if (!existsSync(userDir)) {
+        mkdirSync(userDir, { recursive: true });
+    }
+    try {
+        fsWatch(userDir, () => {
+            if (watchDebounce)
+                clearTimeout(watchDebounce);
+            watchDebounce = setTimeout(() => {
+                try {
+                    loadAdvisorRules(opts);
+                }
+                catch (err) {
+                    logger.warn({ err }, 'Hot reload failed — keeping previous rule set');
+                }
+            }, 250);
+        });
+        watcherInstalled = true;
+        logger.debug({ dir: userDir }, 'Watching user rules dir for hot reload');
+    }
+    catch (err) {
+        logger.warn({ err }, 'Failed to install rule watcher — hot reload disabled');
+    }
+}
+/** Test-only: clear cached state. */
+export function _resetLoaderState() {
+    cachedRules = [];
+    watcherInstalled = false;
+    if (watchDebounce) {
+        clearTimeout(watchDebounce);
+        watchDebounce = null;
+    }
+}
+//# sourceMappingURL=loader.js.map

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

@@ -0,0 +1,159 @@
+/**
+ * Advisor Rule Engine — schema types.
+ *
+ * Rules are data, not code. They live as YAML files in ~/.clementine/advisor-rules/
+ * and replace the hardcoded TS rule helpers in execution-advisor.ts. Engine builtins
+ * ship in src/agent/advisor-rules/builtin/ and get copied to user-space on first init.
+ *
+ * Design constraints:
+ *   - No expression language. All `then` actions are named operations with explicit fields.
+ *     Anything more complex stays as a TS hook (then.invokeBuiltin).
+ *   - Closed-set conditions and operations. Adding a new one requires an engine update,
+ *     never an `eval()`.
+ *   - User-authored rules in user/ override engine builtins of the same id.
+ */
+import type { CronJobDefinition, CronRunEntry, ExecutionAdvice, TerminalReason } from '../../types.js';
+/** Scoping — at least one field must match (or be null/absent) for the rule to apply. */
+export interface AppliesTo {
+    agentSlug?: string | null;
+    jobName?: string | null;
+    /** "standard" | "unleashed" | null (null means any mode, including unset) */
+    jobMode?: 'standard' | 'unleashed' | null;
+    tier?: number[];
+}
+/** Conditions are a closed set. The engine knows how to evaluate each kind. */
+export type WhenCondition = {
+    kind: 'recentTerminalReason';
+    reason: TerminalReason;
+    window: number;
+    atLeast: number;
+} | {
+    kind: 'recentErrorCount';
+    window: number;
+    atLeast: number;
+} | {
+    kind: 'recentTimeoutHits';
+    window: number;
+    atLeast: number;
+    thresholdRatio?: number;
+} | {
+    kind: 'avgReflectionQualityBelow';
+    window: number;
+    threshold: number;
+    minSamples: number;
+} | {
+    kind: 'lowQualityReflectionCount';
+    window: number;
+    maxQuality: number;
+    atLeast: number;
+} | {
+    kind: 'consecutiveErrorsAtLeast';
+    count: number;
+} | {
+    kind: 'lastRunOlderThanMs';
+    ms: number;
+} | {
+    kind: 'lastRunWithinMs';
+    ms: number;
+} | {
+    kind: 'noRecentRuns';
+} | {
+    kind: 'modelContains';
+    substring: string;
+} | {
+    kind: 'effectiveModelContains';
+    substring: string;
+} | {
+    kind: 'recentSuccessCountAtLeast';
+    window: number;
+    atLeast: number;
+} | {
+    kind: 'adviceFieldSet';
+    field: keyof ExecutionAdvice;
+} | {
+    kind: 'interventionStatBelow';
+    stat: 'modelUpgradeSuccessRate' | 'turnAdjustSuccessRate' | 'enrichmentSuccessRate';
+    threshold: number;
+    minSamples?: number;
+};
+/** Actions are also a closed set. */
+export type ThenAction = {
+    kind: 'bumpMaxTurns';
+    multiplier?: number;
+    baseDefault?: number;
+} | {
+    kind: 'bumpTimeoutMs';
+    multiplier?: number;
+    baseMs?: number;
+} | {
+    kind: 'setModel';
+    model: string;
+} | {
+    kind: 'appendPromptEnrichment';
+    text: string;
+} | {
+    kind: 'invokePromptEvolver';
+} | {
+    kind: 'skipWithReason';
+    reason: string;
+    reasonTemplate?: string;
+} | {
+    kind: 'escalateWithReason';
+    reason: string;
+    reasonTemplate?: string;
+} | {
+    kind: 'clearAdviceField';
+    field: 'adjustedMaxTurns' | 'adjustedModel' | 'adjustedTimeoutMs' | 'promptEnrichment';
+};
+export interface AdvisorRule {
+    schemaVersion: 1;
+    id: string;
+    description: string;
+    /** Lower runs first. Builtin priorities convention: 10, 20, ... 90; user rules at 100+ override. */
+    priority: number;
+    appliesTo?: AppliesTo;
+    /** All conditions in skipIf cause the rule to be skipped (logical OR — any match skips). */
+    skipIf?: WhenCondition[];
+    /** All conditions in `when` must be true for the rule to fire (logical AND). */
+    when: WhenCondition[];
+    /** Actions to apply when the rule fires. Applied in array order. */
+    then: ThenAction[];
+    /** If true, no further rules run when this one fires (mirrors TS `return advice` patterns like the circuit breaker). */
+    stopOnFire?: boolean;
+    /** Optional metadata for logging. */
+    log?: {
+        reason?: string;
+    };
+    /** Source path (filled by loader, not in YAML). */
+    _sourcePath?: string;
+}
+/** Built once per getExecutionAdvice call; passed to every rule. */
+export interface RuleContext {
+    job: CronJobDefinition;
+    jobName: string;
+    recentRuns: CronRunEntry[];
+    reflections: ReadonlyArray<{
+        quality: number;
+    }>;
+    consecutiveErrors: number;
+    interventionStats: {
+        modelUpgradeSuccessRate: number | null;
+        turnAdjustSuccessRate: number | null;
+        enrichmentSuccessRate: number | null;
+        sampleSize: number;
+    };
+    /** Shared mutable advice — rules read and write it. */
+    advice: ExecutionAdvice;
+    /** Current time, injectable for tests. */
+    nowMs: number;
+    /** Tier turn cap lookup (from execution-advisor.ts). */
+    tierMaxTurns: Record<number, number>;
+    /** Default standard-cron timeout. */
+    defaultTimeoutMs: number;
+    /** Hard ceiling for adjusted timeout. */
+    maxTimeoutMs: number;
+    /** Default for missing job.maxTurns. */
+    defaultMaxTurns: number;
+}
+export type RulesLoaderMode = 'off' | 'shadow' | 'primary';
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,16 @@
+/**
+ * Advisor Rule Engine — schema types.
+ *
+ * Rules are data, not code. They live as YAML files in ~/.clementine/advisor-rules/
+ * and replace the hardcoded TS rule helpers in execution-advisor.ts. Engine builtins
+ * ship in src/agent/advisor-rules/builtin/ and get copied to user-space on first init.
+ *
+ * Design constraints:
+ *   - No expression language. All `then` actions are named operations with explicit fields.
+ *     Anything more complex stays as a TS hook (then.invokeBuiltin).
+ *   - Closed-set conditions and operations. Adding a new one requires an engine update,
+ *     never an `eval()`.
+ *   - User-authored rules in user/ override engine builtins of the same id.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agent/execution-advisor.d.ts

@@ -7,7 +7,12 @@
  */
 import { CronRunLog } from '../gateway/heartbeat.js';
 import type { CronJobDefinition, ExecutionAdvice } from '../types.js';
-interface ReflectionEntry {
+export declare const TIER_MAX_TURNS: Record<number, number>;
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+export declare const MAX_TIMEOUT_MS: number;
+export declare const CIRCUIT_BREAKER_COOLDOWN_MS: number;
+export declare const DEFAULT_MAX_TURNS_FALLBACK = 5;
+export interface ReflectionEntry {
     jobName: string;
     timestamp: string;
     existence: boolean;
@@ -23,5 +28,16 @@ export declare function getExecutionAdvice(jobName: string, job: CronJobDefiniti
 export declare function checkTurnLimitHits(runs: ReturnType<CronRunLog['readRecent']>, job: CronJobDefinition, advice: ExecutionAdvice): void;
 export declare function checkReflectionQuality(reflections: ReflectionEntry[], job: CronJobDefinition, advice: ExecutionAdvice): void;
 export declare function checkTimeoutHits(runs: ReturnType<CronRunLog['readRecent']>, job: CronJobDefinition, advice: ExecutionAdvice): void;
-export {};
+export interface InterventionStats {
+    modelUpgradeSuccessRate: number | null;
+    turnAdjustSuccessRate: number | null;
+    enrichmentSuccessRate: number | null;
+    sampleSize: number;
+}
+/**
+ * Read past advisor outcomes to learn which interventions actually work
+ * for a given job. Returns null rates when insufficient data exists.
+ */
+export declare function getInterventionStats(jobName: string): InterventionStats;
+export declare function readReflections(jobName: string): ReflectionEntry[];
 //# sourceMappingURL=execution-advisor.d.ts.map

package/dist/agent/execution-advisor.js

@@ -8,18 +8,20 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import pino from 'pino';
-import { CRON_REFLECTIONS_DIR, ADVISOR_LOG_PATH } from '../config.js';
+import { ADVISOR_RULES_LOADER, CRON_REFLECTIONS_DIR, ADVISOR_LOG_PATH } from '../config.js';
 import { CronRunLog } from '../gateway/heartbeat.js';
 import { evolvePrompt } from './prompt-evolver.js';
 const logger = pino({ name: 'clementine.execution-advisor' });
+const shadowLogger = pino({ name: 'clementine.advisor-rules-shadow' });
 // ── Tier caps for maxTurns ──────────────────────────────────────────
-const TIER_MAX_TURNS = {
+export const TIER_MAX_TURNS = {
     1: 15,
     2: 50,
 };
-const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
-const MAX_TIMEOUT_MS = 20 * 60 * 1000; // 20 minutes
-const CIRCUIT_BREAKER_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour between retry probes
+export const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
+export const MAX_TIMEOUT_MS = 20 * 60 * 1000; // 20 minutes
+export const CIRCUIT_BREAKER_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour between retry probes
+export const DEFAULT_MAX_TURNS_FALLBACK = 5; // when job.maxTurns is unset
 // ── Core function ───────────────────────────────────────────────────
 export function getExecutionAdvice(jobName, job) {
     const advice = {
@@ -99,8 +101,83 @@ export function getExecutionAdvice(jobName, job) {
     catch (err) {
         logger.warn({ err, job: jobName }, 'Execution advisor error — proceeding with defaults');
     }
+    // Shadow mode: run the YAML rule engine on the same job, log any divergence
+    // from the legacy TS advice. Non-throwing — never affects the returned advice.
+    if (ADVISOR_RULES_LOADER === 'shadow') {
+        runShadowComparison(jobName, job, advice);
+    }
     return advice;
 }
+// ── Shadow-mode comparison ──────────────────────────────────────────
+let shadowInitialized = false;
+let shadowAvailable = false;
+let shadowDeps = null;
+async function ensureShadowInitialized() {
+    if (shadowInitialized)
+        return;
+    shadowInitialized = true;
+    try {
+        const [loaderMod, contextMod, engineMod] = await Promise.all([
+            import('./advisor-rules/loader.js'),
+            import('./advisor-rules/context.js'),
+            import('./advisor-rules/engine.js'),
+        ]);
+        shadowDeps = {
+            loadAdvisorRules: loaderMod.loadAdvisorRules,
+            getLoadedRules: loaderMod.getLoadedRules,
+            watchUserRulesDir: loaderMod.watchUserRulesDir,
+            buildRuleContext: contextMod.buildRuleContext,
+            applyRules: engineMod.applyRules,
+        };
+        shadowDeps.loadAdvisorRules();
+        shadowDeps.watchUserRulesDir();
+        shadowAvailable = true;
+        shadowLogger.info('Advisor rules shadow mode initialized');
+    }
+    catch (err) {
+        shadowLogger.warn({ err }, 'Failed to initialize advisor rules shadow mode');
+    }
+}
+function runShadowComparison(jobName, job, tsAdvice) {
+    // Fire-and-forget: kicks off async init the first time, then runs comparison
+    // synchronously on subsequent calls. Never throws.
+    ensureShadowInitialized()
+        .then(() => {
+        if (!shadowAvailable || !shadowDeps)
+            return;
+        try {
+            const rules = shadowDeps.getLoadedRules();
+            const ctx = shadowDeps.buildRuleContext(jobName, job);
+            const { advice: yamlAdvice, traces } = shadowDeps.applyRules(rules, ctx);
+            const diffs = diffAdvice(tsAdvice, yamlAdvice);
+            if (diffs.length > 0) {
+                shadowLogger.warn({ jobName, diffs, firedRules: traces.filter(t => t.fired).map(t => t.ruleId) }, 'Shadow advisor diverged from TS path');
+            }
+            else {
+                shadowLogger.debug({ jobName, firedRules: traces.filter(t => t.fired).map(t => t.ruleId) }, 'Shadow advisor matches TS path');
+            }
+        }
+        catch (err) {
+            shadowLogger.warn({ err, jobName }, 'Shadow advisor run failed');
+        }
+    })
+        .catch(() => { });
+}
+function diffAdvice(a, b) {
+    const fields = [
+        'adjustedMaxTurns', 'adjustedModel', 'adjustedTimeoutMs',
+        'promptEnrichment', 'shouldEscalate', 'shouldSkip',
+        'escalationReason', 'skipReason',
+    ];
+    const out = [];
+    for (const f of fields) {
+        const ta = a[f] ?? null;
+        const tb = b[f] ?? null;
+        if (ta !== tb)
+            out.push({ field: f, ts: ta, yaml: tb });
+    }
+    return out;
+}
 // ── Rule helpers ────────────────────────────────────────────────────
 export function checkTurnLimitHits(runs, job, advice) {
     // Unleashed jobs manage per-phase turns via UNLEASHED_PHASE_TURNS, not job.maxTurns.
@@ -128,7 +205,7 @@ export function checkTurnLimitHits(runs, job, advice) {
         return; // skip turn adjustment
     }
     if (turnLimitHits.length >= 2) {
-        const currentMax = job.maxTurns ?? 5;
+        const currentMax = job.maxTurns ?? DEFAULT_MAX_TURNS_FALLBACK;
         const tierCap = TIER_MAX_TURNS[job.tier] ?? TIER_MAX_TURNS[1];
         const proposed = Math.ceil(currentMax * 1.5);
         advice.adjustedMaxTurns = Math.min(proposed, tierCap);
@@ -209,7 +286,7 @@ function checkEscalation(runs, reflections, job, advice) {
  * Read past advisor outcomes to learn which interventions actually work
  * for a given job. Returns null rates when insufficient data exists.
  */
-function getInterventionStats(jobName) {
+export function getInterventionStats(jobName) {
     const stats = {
         modelUpgradeSuccessRate: null,
         turnAdjustSuccessRate: null,
@@ -255,7 +332,7 @@ function getInterventionStats(jobName) {
     return stats;
 }
 // ── Reflection file reader ──────────────────────────────────────────
-function readReflections(jobName) {
+export function readReflections(jobName) {
     try {
         const safeJob = jobName.replace(/[^a-zA-Z0-9_-]/g, '_');
         const reflPath = path.join(CRON_REFLECTIONS_DIR, `${safeJob}.jsonl`);

package/dist/config.d.ts

@@ -152,6 +152,7 @@ export declare const ADVISOR_LOG_PATH: string;
 export declare const REMOTE_ACCESS_CONFIG: string;
 export declare const STAGING_DIR: string;
 export declare const ALLOW_SOURCE_EDITS: boolean;
+export declare const ADVISOR_RULES_LOADER: 'off' | 'shadow' | 'primary';
 export declare const CLAUDE_CODE_OAUTH_TOKEN: string;
 export declare const ANTHROPIC_API_KEY: string;
 export declare const CREDENTIALS_FILE: string;

package/dist/config.js

@@ -314,6 +314,20 @@ export const ALLOW_SOURCE_EDITS = (() => {
     const raw = getEnv('CLEMENTINE_ALLOW_SOURCE_EDITS', '').toLowerCase().trim();
     return raw === '1' || raw === 'true' || raw === 'yes';
 })();
+// Advisor rule engine mode:
+//   off     — no rule loader (default, identical to pre-2a behavior)
+//   shadow  — rule engine runs alongside the legacy TS path; differences
+//             are logged but TS path's advice is what's returned.
+//   primary — rule engine is the source of truth; TS path is dead code.
+//             (Reserved for Phase 2b — not yet wired.)
+export const ADVISOR_RULES_LOADER = (() => {
+    const raw = getEnv('CLEMENTINE_ADVISOR_RULES_LOADER', '').toLowerCase().trim();
+    if (raw === 'shadow')
+        return 'shadow';
+    if (raw === 'primary')
+        return 'primary';
+    return 'off';
+})();
 // ── API ──────────────────────────────────────────────────────────────
 // Long-lived OAuth token from `clementine login` / `claude setup-token`.
 // Takes priority over ANTHROPIC_API_KEY in the SDK subprocess env.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.94",
+  "version": "1.0.95",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
     "clementine": "dist/cli/index.js"
   },
   "scripts": {
-    "build": "rm -rf dist.tmp 2>/dev/null; tsc --outDir dist.tmp && rm -rf dist && mv dist.tmp dist && chmod +x dist/cli/index.js",
+    "build:assets": "mkdir -p dist/agent/advisor-rules/builtin && (cp src/agent/advisor-rules/builtin/*.yaml dist/agent/advisor-rules/builtin/ 2>/dev/null || true)",
+    "build": "rm -rf dist.tmp 2>/dev/null; tsc --outDir dist.tmp && rm -rf dist && mv dist.tmp dist && chmod +x dist/cli/index.js && npm run build:assets",
     "prepublishOnly": "npm run build && find dist -name '*.map' -delete",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
@@ -35,6 +36,7 @@
     "falkordblite": "^0.2.0",
     "grammy": "^1.35.0",
     "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.1",
     "mailparser": "^3.7.1",
     "mammoth": "^1.8.0",
     "multer": "^2.1.1",
@@ -47,6 +49,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/express": "^5.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/mailparser": "^3.4.5",
     "@types/node": "^22.12.0",
     "@types/node-cron": "^3.0.11",