lazyclaw 5.1.0 → 5.3.0

package/mas/agent_turn.mjs

@@ -26,6 +26,7 @@ import * as openai from '../providers/tool_use/openai.mjs';
 import * as gemini from '../providers/tool_use/gemini.mjs';
 import * as claudeCli from '../providers/tool_use/claude_cli.mjs';
 import { put as _trajPut } from './trajectory_store.mjs';
+import { composePromptStack } from './prompt_stack.mjs';
 
 export class AgentTurnError extends Error {
   constructor(message, code) {
@@ -37,6 +38,27 @@ export class AgentTurnError extends Error {
 
 const DEFAULT_MAX_ITERATIONS = 10;
 
+// Mark the last content block in an Anthropic-shaped message array
+// with cache_control:ephemeral so the prompt-cache breakpoint advances
+// per loop iteration. Operates on the LAST message in the array (the
+// one we just appended) — if its content is an array of blocks, the
+// final block carries the marker; if it's a plain string we lift it
+// into a single text block. Mutates in place — caller owns the array.
+function _markLastContentCacheable(msgs) {
+  if (!Array.isArray(msgs) || msgs.length === 0) return;
+  const last = msgs[msgs.length - 1];
+  if (!last || typeof last !== 'object') return;
+  if (Array.isArray(last.content)) {
+    if (last.content.length === 0) return;
+    const block = last.content[last.content.length - 1];
+    if (block && typeof block === 'object') {
+      block.cache_control = { type: 'ephemeral' };
+    }
+  } else if (typeof last.content === 'string') {
+    last.content = [{ type: 'text', text: last.content, cache_control: { type: 'ephemeral' } }];
+  }
+}
+
 function adapterFor(provider) {
   switch (provider) {
     case 'anthropic':  return { ...anthropic,  toolSchemas: anthropic.toAnthropicTools };
@@ -72,13 +94,48 @@ export async function runAgentTurn({
   maxIterations = DEFAULT_MAX_ITERATIONS,
   signal,
   approve,
-  trajectoryRef,
+  // v5 (Group A — C3): trajectoryRef is OPT-OUT, not opt-in. A caller
+  // that doesn't pass one but DOES pass a configDir gets a
+  // default-stamped record so every production agent turn lands in
+  // trajectory_store. Two opt-outs exist for callers that don't want
+  // disk side effects (tool-use unit tests, sandboxed harnesses):
+  //   - set process.env.LAZYCLAW_NO_TRAJECTORY='1'
+  //   - omit configDir (legacy unit-test surface — see _maybePersistTrajectory)
+  trajectoryRef = { startedAt: Date.now() },
+  // v5 (canonical decision C5) — when true, the system slot passed to
+  // the adapter is the full 8-layer composePromptStack output instead
+  // of the bare agent.role. Default `false` for byte-stability with
+  // existing tool-use tests; callers that have NOT already pre-built
+  // the stack (e.g. the future delegation tool, direct API consumers)
+  // should opt in.
+  usePromptStack = false,
+  // Group B / C9 — prompt caching. Off by default to preserve the
+  // byte-stable adapter shape that phase 12b et al. depend on; the
+  // mention router (production caller) flips it on so every MAS turn
+  // hits the Anthropic prompt cache.
+  cache = false,
 } = {}) {
   if (!agent) throw new AgentTurnError('agent is required', 'NO_AGENT');
   const adapter = adapterFor(agent.provider);
 
   const tools = adapter.toolSchemas(listToolSchemas(agent.tools));
 
+  // Compose the layered system prompt once, up front, so every adapter
+  // round-trip in the loop sees the same string. composePromptStack
+  // returns '' on a fresh install — when it does, we fall back to
+  // agent.role so the legacy single-layer shape is preserved.
+  let systemPrompt = agent.role || '';
+  if (usePromptStack) {
+    try {
+      const stacked = composePromptStack({
+        cfgDir: configDir,
+        agent,
+        workspace: agent.workspace || '',
+      });
+      if (stacked && stacked.trim()) systemPrompt = stacked;
+    } catch { /* best-effort — never block a turn on stack composition */ }
+  }
+
   // Seed messages from prior history + the new user input. Callers
   // pass history in a provider-neutral [{role, content}] shape; the
   // adapter normalises it into its native message format (e.g. Gemini's
@@ -94,10 +151,16 @@ export async function runAgentTurn({
   const toolCalls = [];
   let iterations = 0;
   let lastText = '';
-  if (trajectoryRef && !trajectoryRef.startedAt) trajectoryRef.startedAt = Date.now();
+  if (trajectoryRef && typeof trajectoryRef === 'object' && !trajectoryRef.startedAt) trajectoryRef.startedAt = Date.now();
 
   const _maybePersistTrajectory = async (outcome) => {
+    if (process.env.LAZYCLAW_NO_TRAJECTORY === '1') return;
     if (!trajectoryRef) return;
+    // Defence-in-depth: callers that don't pass configDir (legacy unit
+    // tests of the tool-use loop) shouldn't see a side-effect on
+    // ~/.lazyclaw. The canonical post-task funnel (mas/learning.mjs)
+    // always passes configDir, so production paths still persist.
+    if (!configDir) return;
     try {
       await _trajPut({
         taskId, agentName: agent.name || 'agent',
@@ -122,8 +185,8 @@ export async function runAgentTurn({
     if (signal?.aborted) return { text: lastText, iterations, stoppedBy: 'abort', toolCalls };
     iterations++;
     const resp = await adapter.callOnce({
-      messages, tools, model: agent.model, apiKey, system: agent.role,
-      fetchImpl, baseUrl, signal,
+      messages, tools, model: agent.model, apiKey, system: systemPrompt,
+      fetchImpl, baseUrl, signal, cache,
     });
     if (resp.text) lastText = resp.text;
 
@@ -136,7 +199,17 @@ export async function runAgentTurn({
     // tool_result messages correlate, then run each tool and append the
     // adapter-shaped tool-result entries (one for Anthropic, N for
     // OpenAI, …).
-    messages.push(...adapter.assistantTurnMessages(resp));
+    // Group B / C9 — advance the prompt-cache breakpoint by marking the
+    // freshly-appended assistant + tool_result content with
+    // cache_control:ephemeral so the next iteration's prefix (which
+    // includes the previous round of tool exchanges) is itself cached.
+    // Only the LAST cache_control block in the request actually counts
+    // as the live breakpoint per Anthropic's spec — so attaching it to
+    // every iteration's latest tool turn is safe and lets the cache
+    // walk forward as the conversation grows.
+    const _newAssistant = adapter.assistantTurnMessages(resp);
+    if (cache && agent.provider === 'anthropic') _markLastContentCacheable(_newAssistant);
+    messages.push(..._newAssistant);
     const results = [];
     let toolErrored = false;
     for (const call of resp.calls) {
@@ -160,7 +233,9 @@ export async function runAgentTurn({
       results.push({ id: call.id, content: result, isError: !ok });
       if (!ok) toolErrored = true;
     }
-    messages.push(...adapter.toolResultMessages(results));
+    const _newToolResult = adapter.toolResultMessages(results);
+    if (cache && agent.provider === 'anthropic') _markLastContentCacheable(_newToolResult);
+    messages.push(..._newToolResult);
 
     // We feed every tool error (denied/unknown/runtime) back to the
     // model so it can recover. Only an extraordinary error (e.g. the

package/mas/index_db.mjs

@@ -21,6 +21,26 @@ function defaultConfigDir() {
   return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
 }
 
+// m11 — when a write-through hook fails, append a structured entry to
+// <configDir>/index-failures.jsonl so `lazyclaw doctor` can surface
+// recent failures (last 24h) and the operator can rebuild before the
+// silent stale-index problem compounds. Best-effort: any error during
+// the append itself is swallowed (we don't want to spam stderr from a
+// background hook).
+function _logIndexFailure(configDir, scope, err) {
+  try {
+    fs.mkdirSync(configDir, { recursive: true });
+    const file = path.join(configDir, 'index-failures.jsonl');
+    const entry = {
+      ts: new Date().toISOString(),
+      event: 'index.write.failed',
+      scope,
+      error: String(err?.message || err || 'unknown'),
+    };
+    fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+  } catch { /* swallow — surface only via console.warn below */ }
+}
+
 function dbPath(configDir) {
   return path.join(configDir, 'index.db');
 }
@@ -131,6 +151,7 @@ export function indexSessionTurn(row, configDir = defaultConfigDir()) {
       String(row.role || ''), Number(row.ts || Date.now()),
     );
   } catch (e) {
+    _logIndexFailure(configDir, 'sessions', e);
     // eslint-disable-next-line no-console
     console.warn('[index_db] indexSessionTurn failed:', e.message);
   }
@@ -145,6 +166,7 @@ export function indexSkill(row, configDir = defaultConfigDir()) {
       String(row.group_name || ''),
     );
   } catch (e) {
+    _logIndexFailure(configDir, 'skills', e);
     // eslint-disable-next-line no-console
     console.warn('[index_db] indexSkill failed:', e.message);
   }
@@ -159,6 +181,7 @@ export function indexTrajectory(row, configDir = defaultConfigDir()) {
       String(row.outcome || ''),
     );
   } catch (e) {
+    _logIndexFailure(configDir, 'trajectories', e);
     // eslint-disable-next-line no-console
     console.warn('[index_db] indexTrajectory failed:', e.message);
   }
@@ -172,6 +195,7 @@ export function indexMemory(row, configDir = defaultConfigDir()) {
       String(row.topic || ''), String(row.kind || ''),
     );
   } catch (e) {
+    _logIndexFailure(configDir, 'memories', e);
     // eslint-disable-next-line no-console
     console.warn('[index_db] indexMemory failed:', e.message);
   }
@@ -190,21 +214,57 @@ function sanitizeFtsQuery(q) {
   return s.replace(/[-:+]/g, ' ').replace(/\s+/g, ' ').trim();
 }
 
+/**
+ * Cross-scope FTS5 recall. Content-only semantics — all UNINDEXED
+ * metadata columns (session_id, skill_name, agent, outcome, topic, …)
+ * are returned as `metadata` but NOT searchable via MATCH (m9). Use
+ * `opts.where` to post-filter on metadata equality.
+ *
+ * @param {string} query  FTS5 MATCH query. By default the query is
+ *                        sanitised: `-`, `:`, `+` rewritten to spaces
+ *                        so a bareword like "write-through" doesn't
+ *                        get parsed as NOT-through. Pass `opts.raw=true`
+ *                        to bypass sanitisation when you need real
+ *                        FTS5 operators (NOT, OR, near).
+ * @param {Object} [opts]
+ * @param {string} [opts.configDir]
+ * @param {string[]} [opts.scope]  default: all four scopes
+ * @param {number} [opts.k]        default 10, capped at 50
+ * @param {boolean} [opts.raw]     bypass sanitiseFtsQuery (power users)
+ * @param {Object} [opts.where]    metadata equality post-filter, e.g.
+ *                                 { trained_by: 'human', agent: 'reviewer' }
+ *                                 Applied after FTS5 returns hits; values
+ *                                 are coerced to string before compare.
+ */
 export function recall(query, opts = {}) {
   const t0 = process.hrtime.bigint();
   const configDir = opts.configDir || defaultConfigDir();
   const scope = opts.scope || ['sessions', 'skills', 'trajectories', 'memories'];
   const k = Math.min(Math.max(Number(opts.k) || 10, 1), 50);
   const s = _stmts(configDir);
-  const safeQuery = sanitizeFtsQuery(query);
+  const safeQuery = opts.raw ? String(query ?? '').trim() : sanitizeFtsQuery(query);
+  const whereKeys = (opts.where && typeof opts.where === 'object') ? Object.keys(opts.where) : [];
+  // Over-fetch when a where-filter is set: post-filter can drop most
+  // hits, so request 2x k from FTS5 so the final trimmed slice has
+  // enough to fill k. Capped at the FTS5-side 200 hard limit.
+  const fetchK = whereKeys.length ? Math.min(200, k * 2) : k;
   const hits = [];
   for (const sc of scope) {
     const stmt = s.queries[sc];
     if (!stmt) continue;
     try {
-      const rows = stmt.all(safeQuery, k);
+      const rows = stmt.all(safeQuery, fetchK);
       for (const r of rows) {
         const { scope: sc2, bm25, snippet, ...metadata } = r;
+        // Apply where-filter at row level — keeps the bm25 ordering
+        // intact and avoids re-fetching after sort.
+        if (whereKeys.length) {
+          let skip = false;
+          for (const wk of whereKeys) {
+            if (String(metadata[wk] ?? '') !== String(opts.where[wk])) { skip = true; break; }
+          }
+          if (skip) continue;
+        }
         hits.push({ scope: sc2, rank: hits.length, bm25, snippet, metadata });
       }
     } catch (e) {

package/mas/learning.mjs

@@ -0,0 +1,371 @@
+// mas/learning.mjs — v5.0 spec §3.6 / canonical decision C2.
+//
+// Canonical funnel for the five post-task learning triggers. Every
+// learning signal (a finished task, an active-recall miss, a periodic
+// curation pass, etc.) lands in `runLearning(trigger, ctx)` so the
+// orchestra hub has exactly one fan-out site rather than five scattered
+// `import x.synthesize`/`y.persist` call chains.
+//
+// Triggers (frozen list — caller-side enum):
+//   post-task            — a task finished successfully. Persist the
+//                          trajectory, synthesise a SKILL.md, update the
+//                          USER.md dialectic model, stamp confidence.
+//   post-failure         — a task failed. Synthesise an anti-pattern
+//                          skill so a future agent avoids the same trap.
+//   nudge                — a nudge cluster accumulated enough evidence
+//                          to be worth distilling. Phase 2 fully wires
+//                          this; v5.0.10 keeps the dispatch hook so
+//                          callers can opt in early.
+//   active-recall-miss   — a skill was recalled but failed to apply.
+//                          Decrement its confidence; archive when it
+//                          falls below the activation threshold.
+//   periodic-curation    — cron-driven skills_curator replay. Phase 2
+//                          full implementation; v5.0.10 emits a warning
+//                          and returns a no-op result so a cron entry
+//                          configured today does not crash.
+//
+// Hard contract: a single broken handler MUST NOT poison the others.
+// Each sub-routine is wrapped in its own try/catch so e.g. a missing
+// trainer api-key won't block the trajectory write.
+
+import * as trajectoryStore from './trajectory_store.mjs';
+import * as skillSynth from './skill_synth.mjs';
+import * as userModeler from './user_modeler.mjs';
+import * as confidence from './confidence.mjs';
+import * as skills from '../skills.mjs';
+import { resolveTrainer } from '../providers/registry.mjs';
+
+export const TRIGGERS = Object.freeze([
+  'post-task',
+  'post-failure',
+  'nudge',
+  'active-recall-miss',
+  'periodic-curation',
+]);
+
+export class LearningError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'LearningError';
+    this.code = code || 'LEARNING_ERR';
+  }
+}
+
+// Public entry point. Returns { trigger, results, errors }; never throws
+// for a known trigger — the caller (orchestrator microtask, mention
+// router) expects best-effort semantics. Unknown triggers return an
+// `{ error: 'UNKNOWN_TRIGGER' }` envelope so a typo in config surfaces
+// loudly without taking down the calling stream.
+export async function runLearning(trigger, ctx = {}) {
+  if (!TRIGGERS.includes(trigger)) {
+    return { trigger, error: 'UNKNOWN_TRIGGER', known: TRIGGERS.slice() };
+  }
+  const logger = typeof ctx.logger === 'function' ? ctx.logger : () => {};
+  switch (trigger) {
+    case 'post-task':           return await _runPostTask(ctx, logger);
+    case 'post-failure':        return await _runPostFailure(ctx, logger);
+    case 'nudge':               return await _runNudge(ctx, logger);
+    case 'active-recall-miss':  return await _runActiveRecallMiss(ctx, logger);
+    case 'periodic-curation':   return await _runPeriodicCuration(ctx, logger);
+    default:
+      return { trigger, error: 'UNKNOWN_TRIGGER' };
+  }
+}
+
+// ── post-task ────────────────────────────────────────────────────────
+//
+// ctx: { agent, task, configDir, cfg, transcript?, trajectoryRef?,
+//        apiKey?, baseUrl?, fetchImpl? }
+//
+// Runs four sub-routines independently:
+//   1. trajectory_store.put       — durable evidence (FTS5 mirror too).
+//   2. synthesizeSkill            — distil a reusable SKILL.md.
+//   3. updateUserModel            — Honcho-style dialectic USER.md.
+//   4. computeConfidence          — stamp on the trained skill record.
+export async function _runPostTask(ctx, logger) {
+  const errors = [];
+  const results = {};
+  const trainer = _safeResolveTrainer(ctx.cfg, ctx.agent);
+
+  // 1. trajectory_store.put
+  try {
+    const rec = _buildTrajectoryRecord(ctx, 'done');
+    // Stamp the trainer provider/model on the trajectory so a later
+    // recall + cross-CLI dampening lookup can see who synthesised the
+    // signal vs. who executed the turn (canonical decision H2).
+    rec.trainerProvider = trainer.provider || '';
+    rec.trainerModel = trainer.model || '';
+    results.trajectory = await trajectoryStore.put(rec, { configDir: ctx.configDir });
+  } catch (e) {
+    errors.push({ step: 'trajectory', error: String(e?.message || e) });
+    logger(`[learning] trajectory put failed: ${e?.message || e}\n`);
+  }
+
+  // 2. computeConfidence — pure function, no I/O. We hoist this above
+  //    synthesizeSkill so the v5 frontmatter actually gets the
+  //    confidence value (M1). Without the hoist, synthesise wrote
+  //    `confidence: null` even though the loop computed the score
+  //    afterwards.
+  try {
+    results.confidence = confidence.computeConfidence({
+      successes: 1,
+      trials: 1,
+      ageMs: 0,
+      trainerProvider: trainer.provider,
+      workerProvider: ctx.agent?.provider || trainer.provider,
+      dampenFactor: confidence.resolveDampenFactor(ctx.cfg),
+    });
+  } catch (e) {
+    errors.push({ step: 'confidence', error: String(e?.message || e) });
+  }
+
+  // 3. synthesizeSkill (best-effort — needs an agent + provider key).
+  //    All v5 frontmatter fields land here (trained_by, confidence,
+  //    trajectory_ref) so the produced SKILL.md is ready for recall +
+  //    cross-CLI dampening without a follow-up patch.
+  if (ctx.agent && ctx.task) {
+    try {
+      results.skill = await skillSynth.synthesizeSkill({
+        agent: { ...ctx.agent, provider: trainer.provider, model: trainer.model },
+        task: ctx.task,
+        apiKey: ctx.apiKey,
+        baseUrl: ctx.baseUrl,
+        fetchImpl: ctx.fetchImpl,
+        outcome: 'done',
+        trainedBy: trainer.provider,
+        trainedOnModel: trainer.model,
+        trajectoryRef: results.trajectory?.id || null,
+        confidence: results.confidence,
+      });
+      // Persist the produced SKILL.md into the shared skills/ dir so the
+      // next agent turn's recall surfaces it. installSynthesized forwards
+      // every v5 frontmatter field (see Group A — C6 fix in skill_synth).
+      if (results.skill && ctx.configDir) {
+        try {
+          results.installed = skillSynth.installSynthesized({
+            name: results.skill.name,
+            description: results.skill.description,
+            body: results.skill.body,
+            sourceTask: ctx.task.id || '',
+            createdBy: 'agent',
+            trainedBy: trainer.provider,
+            trainedOnModel: trainer.model,
+            trajectoryRef: results.trajectory?.id || null,
+            confidence: results.confidence,
+            outcome: 'done',
+          }, ctx.configDir);
+        } catch (e) {
+          errors.push({ step: 'skillInstall', error: String(e?.message || e) });
+          logger(`[learning] skill install failed: ${e?.message || e}\n`);
+        }
+      }
+    } catch (e) {
+      errors.push({ step: 'skill', error: String(e?.message || e) });
+      logger(`[learning] skill synth failed: ${e?.message || e}\n`);
+    }
+  }
+
+  // 4. updateUserModel — needs session turns (any normalised
+  //    [{role, content}] list). Falls back to task.turns translated.
+  if (ctx.sessionTurns || ctx.task?.turns) {
+    try {
+      results.userModel = await userModeler.updateUserModel({
+        sessionTurns: ctx.sessionTurns || _toSessionTurns(ctx.task.turns),
+        provider: trainer.provider,
+        model: trainer.model,
+        apiKey: ctx.apiKey,
+        baseUrl: ctx.baseUrl,
+        fetchImpl: ctx.fetchImpl,
+        configDir: ctx.configDir,
+      });
+    } catch (e) {
+      errors.push({ step: 'userModel', error: String(e?.message || e) });
+      logger(`[learning] user model update failed: ${e?.message || e}\n`);
+    }
+  }
+
+  return { trigger: 'post-task', results, errors };
+}
+
+// ── post-failure ─────────────────────────────────────────────────────
+//
+// Same shape as post-task but synthesizeSkill runs with outcome:
+// 'failed' so the resulting SKILL.md is tagged anti_pattern: true and
+// grouped under 'anti-pattern'.
+export async function _runPostFailure(ctx, logger) {
+  const errors = [];
+  const results = {};
+  const trainer = _safeResolveTrainer(ctx.cfg, ctx.agent);
+
+  try {
+    const rec = _buildTrajectoryRecord(ctx, 'failed');
+    results.trajectory = await trajectoryStore.put(rec, { configDir: ctx.configDir });
+  } catch (e) {
+    errors.push({ step: 'trajectory', error: String(e?.message || e) });
+    logger(`[learning] failure trajectory put failed: ${e?.message || e}\n`);
+  }
+
+  if (ctx.agent && ctx.task) {
+    try {
+      results.skill = await skillSynth.synthesizeSkill({
+        agent: { ...ctx.agent, provider: trainer.provider, model: trainer.model },
+        task: ctx.task,
+        apiKey: ctx.apiKey,
+        baseUrl: ctx.baseUrl,
+        fetchImpl: ctx.fetchImpl,
+        outcome: 'failed',
+        trainedBy: trainer.provider,
+        trainedOnModel: trainer.model,
+        trajectoryRef: results.trajectory?.id || null,
+      });
+    } catch (e) {
+      errors.push({ step: 'skill', error: String(e?.message || e) });
+      logger(`[learning] anti-pattern synth failed: ${e?.message || e}\n`);
+    }
+  }
+
+  return { trigger: 'post-failure', results, errors };
+}
+
+// ── nudge ────────────────────────────────────────────────────────────
+//
+// A nudge cluster is a group of low-confidence signals that, taken
+// together, are worth a skill. v5.0.10 wires the dispatch path and
+// runs synthesizeSkill against the cluster's representative task; the
+// full cluster-collapse engine lands in Phase 2.
+export async function _runNudge(ctx, logger) {
+  const errors = [];
+  const results = {};
+  const cluster = ctx.cluster;
+  if (!cluster || !Array.isArray(cluster.items) || cluster.items.length === 0) {
+    return { trigger: 'nudge', results: {}, errors: [{ step: 'cluster', error: 'empty cluster' }] };
+  }
+  const trainer = _safeResolveTrainer(ctx.cfg, ctx.agent);
+  const representative = cluster.items[cluster.items.length - 1];
+  try {
+    results.skill = await skillSynth.synthesizeSkill({
+      agent: { ...(ctx.agent || {}), provider: trainer.provider, model: trainer.model },
+      task: representative,
+      apiKey: ctx.apiKey,
+      baseUrl: ctx.baseUrl,
+      fetchImpl: ctx.fetchImpl,
+      outcome: 'done',
+      trainedBy: trainer.provider,
+      trainedOnModel: trainer.model,
+    });
+  } catch (e) {
+    errors.push({ step: 'skill', error: String(e?.message || e) });
+    logger(`[learning] nudge synth failed: ${e?.message || e}\n`);
+  }
+  return { trigger: 'nudge', results, errors };
+}
+
+// ── active-recall-miss ───────────────────────────────────────────────
+//
+// A skill was loaded into context but failed to apply. Decrement its
+// confidence (frontmatter); archive (remove) the skill when confidence
+// drops below 0.3 so it stops bloating future system prompts.
+//
+// ctx: { skill: { name }, configDir, cfg, archiveThreshold? }
+export async function _runActiveRecallMiss(ctx, logger) {
+  const errors = [];
+  const results = {};
+  const name = ctx.skill?.name;
+  if (!name) {
+    return { trigger: 'active-recall-miss', results: {}, errors: [{ step: 'input', error: 'skill.name required' }] };
+  }
+  const threshold = Number.isFinite(+ctx.archiveThreshold) ? +ctx.archiveThreshold : 0.3;
+  try {
+    if (!skills.skillExists(name, ctx.configDir)) {
+      return { trigger: 'active-recall-miss', results: { skipped: 'not found' }, errors };
+    }
+    const raw = skills.loadSkill(name, ctx.configDir);
+    const { meta, body } = skills.parseFrontmatter(raw);
+    const priorConf = Number(meta.confidence);
+    const baseConf = Number.isFinite(priorConf) ? priorConf : 0.5;
+    const nextConf = Math.max(0, baseConf - 0.1);
+    if (nextConf < threshold) {
+      skills.removeSkill(name, ctx.configDir);
+      results.action = 'archived';
+      results.priorConfidence = baseConf;
+      results.nextConfidence = nextConf;
+    } else {
+      // Re-emit the file with the decremented confidence. We rebuild
+      // through assembleSkillDoc so the frontmatter stays canonical.
+      const updated = skillSynth.assembleSkillDoc({
+        name,
+        description: meta.description || '',
+        body,
+        createdBy: meta.created_by || 'agent',
+        sourceTask: meta.source_task || '',
+        version: Number(meta.version) || 1,
+        trainedBy: meta.trained_by || null,
+        trainedOnModel: meta.trained_on_model || null,
+        trajectoryRef: meta.trajectory_ref || null,
+        confidence: nextConf,
+        outcome: meta.anti_pattern === true || meta.anti_pattern === 'true' ? 'failed' : 'done',
+        group: meta.group || null,
+      });
+      skills.installSkill(name, updated, ctx.configDir);
+      results.action = 'decremented';
+      results.priorConfidence = baseConf;
+      results.nextConfidence = nextConf;
+    }
+  } catch (e) {
+    errors.push({ step: 'decrement', error: String(e?.message || e) });
+    logger(`[learning] active-recall-miss handler failed: ${e?.message || e}\n`);
+  }
+  return { trigger: 'active-recall-miss', results, errors };
+}
+
+// ── periodic-curation ────────────────────────────────────────────────
+//
+// Phase 2 full implementation. v5.0.10 emits a structured warning so a
+// cron entry created today returns a stable shape and operators can see
+// the hook fired without blowing up.
+export async function _runPeriodicCuration(_ctx, logger) {
+  logger('[learning] periodic-curation is a Phase 2 hook — no-op for now.\n');
+  return { trigger: 'periodic-curation', results: { stub: true }, errors: [] };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+function _safeResolveTrainer(cfg, agent) {
+  try {
+    return resolveTrainer(cfg || { provider: agent?.provider, model: agent?.model });
+  } catch {
+    return { provider: agent?.provider || '', model: agent?.model || '' };
+  }
+}
+
+function _toSessionTurns(turns) {
+  if (!Array.isArray(turns)) return [];
+  return turns.map((t) => ({
+    role: t.agent === 'user' ? 'user' : 'assistant',
+    content: String(t.text || ''),
+  }));
+}
+
+function _buildTrajectoryRecord(ctx, outcome) {
+  const task = ctx.task || {};
+  const agent = ctx.agent || {};
+  const turns = Array.isArray(task.turns) ? task.turns : [];
+  return {
+    taskId: task.id || '',
+    agentName: agent.name || 'agent',
+    workerProvider: agent.provider || '',
+    workerModel: agent.model || '',
+    startedAt: ctx.trajectoryRef?.startedAt || Date.now(),
+    endedAt: Date.now(),
+    systemPrompt: agent.role || '',
+    userMessages: turns.filter(t => t.agent === 'user').map(t => String(t.text || '')),
+    turns: turns.map((t, i) => ({
+      turnIdx: i,
+      role: t.agent === 'user' ? 'user' : 'assistant',
+      content: String(t.text || ''),
+      toolCalls: Array.isArray(t.toolCalls) ? t.toolCalls : [],
+    })),
+    finalAnswer: turns.length ? String(turns[turns.length - 1].text || '') : '',
+    outcome,
+  };
+}