feat(runtime/coach,reflex): retrieval-augmented dispatch via learned lessons

This closes the learning loop. Lessons in knowledge.db now actually
influence behaviour:

- runtime/coach/advice.js: consult({plannedSkillId, snapshot}) reads
  knowledge.topAdvice() and returns 'override' / 'avoid' / 'proceed'.
  When a lesson says "avoid <skill>" with prefer="survive.flee" (etc.),
  the dispatcher swaps in the alternative.

- runtime/reflex.js:
  * curriculumReflex now consults advice before dispatch; on 'avoid'
    backs off the planned skill + sets wander hint; on 'override'
    dispatches the lesson's preferred alternative.
  * defendReflex (dist≤4 melee branch) consults advice too — so a
    creeper at 4m honours the starter rule "attack creeper → flee".
    Failure outcomes feed back via markApplied so confidence stays
    grounded.

SAFE_OVERRIDES whitelist contains only known runSkill targets
(survive.flee, survive.sleep, survive.eat, recovery.tunnel-out,
explore.far/wander, village.build-shelter); unknown prefers fall back
to plain 'avoid'.

7 advice tests; total suite 237 green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

runtime/coach/advice.js

@@ -0,0 +1,79 @@
+// coach/advice.js — turn knowledge.lessons into actionable dispatch overrides.
+//
+// The reflex chain calls consult() right before it would dispatch a
+// planned skill. If a high-confidence lesson in the knowledge DB says
+// "avoid that skill in this situation", we either swap in the lesson's
+// preferred alternative or back off (which the curriculum reflex
+// translates into wander / cooldown).
+//
+// This is the closing of the learning loop: post-mortem → lesson →
+// recall → behavioural change. Without this, the DB is just a log.
+
+import { isAvailable as knowledgeAvailable, topAdvice, markApplied } from "../knowledge/index.js";
+import { info } from "../log.js";
+
+// Skills we will not blindly swap into — they require their own
+// preconditions (e.g. survive.flee needs a known threat direction).
+// The dispatcher will still run runSkill on them, which performs the
+// real precondition check.
+const SAFE_OVERRIDES = new Set([
+	"survive.flee",
+	"survive.sleep",
+	"survive.eat",
+	"recovery.tunnel-out",
+	"explore.far",
+	"explore.wander",
+	"village.build-shelter",
+]);
+
+/**
+ * consult({ plannedSkillId, snapshot })
+ *   → { action: 'override'|'avoid'|'proceed', overrideSkillId?, lessonId?, lesson? }
+ *
+ * 'override'  — dispatch overrideSkillId instead of plannedSkillId
+ * 'avoid'     — don't dispatch plannedSkillId; caller falls back to wander/idle
+ * 'proceed'   — no high-confidence lesson applies; dispatch as planned
+ */
+export function consult({ plannedSkillId, snapshot } = {}) {
+	if (!knowledgeAvailable()) return PROCEED;
+	if (!plannedSkillId) return PROCEED;
+	const hostile = snapshot?.closestHostile?.name ?? snapshot?.threats?.[0]?.name ?? null;
+	const situation = snapshot?.situationHash ?? null;
+	const advice = topAdvice({
+		skill: plannedSkillId,
+		hostile,
+		situation,
+	});
+	if (!advice.lessonId) return PROCEED;
+
+	// avoid_skill matches?
+	if (advice.avoid && advice.avoid === plannedSkillId) {
+		if (advice.prefer && SAFE_OVERRIDES.has(advice.prefer)) {
+			info("coach", `advice: override ${plannedSkillId} → ${advice.prefer} (lesson #${advice.lessonId})`);
+			return {
+				action: "override",
+				overrideSkillId: advice.prefer,
+				lessonId: advice.lessonId,
+				lesson: advice.lesson,
+			};
+		}
+		info("coach", `advice: avoid ${plannedSkillId} (lesson #${advice.lessonId})`);
+		return { action: "avoid", lessonId: advice.lessonId, lesson: advice.lesson };
+	}
+	return PROCEED;
+}
+
+/**
+ * After the dispatcher runs the (possibly overridden) skill, call this
+ * with the lesson id and whether the outcome was good. Increments the
+ * lesson's applied/succeeded counters and nudges its confidence.
+ */
+export function reportOutcome({ lessonId, succeeded }) {
+	if (!lessonId) return;
+	markApplied(lessonId, { succeeded: !!succeeded });
+}
+
+const PROCEED = Object.freeze({ action: "proceed", lessonId: null, lesson: null });
+
+// Test exports
+export const __testing = { SAFE_OVERRIDES };

runtime/coach/advice.test.js

@@ -0,0 +1,97 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { initKnowledge, record } from "../knowledge/index.js";
+import { __resetForTests, isAvailable, closeStore } from "../knowledge/store.js";
+import { consult, reportOutcome, __testing } from "./advice.js";
+
+const { SAFE_OVERRIDES } = __testing;
+
+async function bootstrap() {
+	__resetForTests();
+	const tmp = mkdtempSync(join(tmpdir(), "pepa-advice-test-"));
+	await initKnowledge({ stateDir: tmp });
+	return tmp;
+}
+
+function cleanup(tmp) {
+	closeStore();
+	try { rmSync(tmp, { recursive: true, force: true }); } catch {}
+}
+
+test("consult: returns proceed when knowledge disabled", () => {
+	__resetForTests();
+	const res = consult({ plannedSkillId: "gather.logs", snapshot: {} });
+	assert.equal(res.action, "proceed");
+});
+
+test("consult: returns proceed when no relevant lesson", async () => {
+	const tmp = await bootstrap();
+	if (!isAvailable()) { cleanup(tmp); return; }
+	const res = consult({ plannedSkillId: "gather.unknown-skill", snapshot: {} });
+	assert.equal(res.action, "proceed");
+	cleanup(tmp);
+});
+
+test("consult: starter creeper rule routes attack → survive.flee", async () => {
+	const tmp = await bootstrap();
+	if (!isAvailable()) { cleanup(tmp); return; }
+	const res = consult({
+		plannedSkillId: "attack creeper",
+		snapshot: { closestHostile: { name: "creeper", distance: 4 } },
+	});
+	assert.equal(res.action, "override");
+	assert.equal(res.overrideSkillId, "survive.flee");
+	assert.ok(res.lessonId);
+	assert.ok(res.lesson);
+	cleanup(tmp);
+});
+
+test("consult: avoid lesson without prefer → 'avoid' action", async () => {
+	const tmp = await bootstrap();
+	if (!isAvailable()) { cleanup(tmp); return; }
+	record({
+		text: "Don't gather.stone — confirmed flaky.",
+		category: "pathing",
+		triggerSkill: "gather.stone",
+		avoidSkill: "gather.stone",
+		preferSkill: null,
+		confidence: 0.9,
+		source: "test",
+	});
+	const res = consult({ plannedSkillId: "gather.stone", snapshot: {} });
+	assert.equal(res.action, "avoid");
+	assert.ok(res.lessonId);
+	cleanup(tmp);
+});
+
+test("consult: prefer outside SAFE_OVERRIDES set → falls to avoid", async () => {
+	const tmp = await bootstrap();
+	if (!isAvailable()) { cleanup(tmp); return; }
+	record({
+		text: "test fallback",
+		category: "combat",
+		triggerSkill: "gather.logs",
+		avoidSkill: "gather.logs",
+		preferSkill: "non.standard.skill",
+		confidence: 0.9,
+		source: "test",
+	});
+	const res = consult({ plannedSkillId: "gather.logs", snapshot: {} });
+	assert.equal(res.action, "avoid", "unsafe prefer falls back to avoid, not override");
+	cleanup(tmp);
+});
+
+test("reportOutcome: no-op without lessonId", () => {
+	reportOutcome({ lessonId: null });
+	assert.ok(true);
+});
+
+test("SAFE_OVERRIDES: only contains known reflex skills", () => {
+	for (const id of SAFE_OVERRIDES) {
+		assert.ok(typeof id === "string" && id.includes("."), `${id} looks like a real skill id`);
+	}
+});