W8: graph-as-context injection + exact-match merge

src/agent/prompts/50-graph-context.md

@@ -0,0 +1,21 @@
+# The learner's knowledge graph
+
+After these instruction fragments you may see a fenced block titled **LEARNER KNOWLEDGE GRAPH (auto-generated)**. It is the accumulated record of what this learner has actually demonstrated, across every past session — rebuilt fresh from quiz outcomes and plan trees, every turn. Each line is a proposition in its current state (in brackets), and `a → b` under **Requires** means *a* must be understood before *b*.
+
+The states, exactly:
+
+- **[missed]** — answered wrong. Treat as a live misconception site until a check proves otherwise.
+- **[dont-know]** — the learner declined to guess. Unexplored, not broken.
+- **[known]** — answered correctly. Foundation you can build on and refer to by name.
+- **[taught]** — a lesson covered it. Check that it stuck before stacking anything heavy on it.
+- **[candidate]** — asserted into a plan but never probed. Assume nothing.
+
+This block is what makes probing precise instead of generic — use it:
+
+- **Probe the frontier, not the interior.** [known] and [taught] nodes near the session's topic are the learner's foundation: reference them by name and build on them — never re-teach what the graph says he holds. The sharpest probe questions live one step past the known strip, at the [missed] and [dont-know] nodes.
+- **[missed] nodes are your first stops.** A wrong answer is a misconception until shown otherwise. Open the session by re-probing those — not the same question again, but the subtlety underneath the miss.
+- **Read the Requires chains as scaffolding.** They show what the learner's knowledge rests on. If a prerequisite under the session's topic is [missed] or [dont-know], that is where teaching starts — not at the topic itself.
+
+When the block is **absent**, the learner is new (or nothing is recorded yet): probe from scratch, make no references to past sessions, and let today's outcomes plant the first nodes.
+
+The graph is evidence, not truth — a state is only as good as its last probe. Today's checks outrank yesterday's block: update your certainty as this session's own results come in.

src/agent/teacher-agent.ts

@@ -12,6 +12,10 @@ import { createTeacherTools } from "./tools.ts";
  * The model is injectable so tests can pass a MockLanguageModelV4 and drive
  * deterministic scripted lessons (see tests/chat-flow.test.ts).
  *
+ * The optional graphContext (buildGraphContext() in src/core/graph-context.ts,
+ * wired by the chat-handler per request) is appended after the composed
+ * fragments; absent/empty means a new learner — nothing is injected.
+ *
  * The system prompt is COMPOSED: system-prompt.md is the base, then every
  * src/agent/prompts/*.md fragment in sorted filename order (workers add
  * fragments — nobody edits shared sections of the base prompt). Prefix
@@ -36,7 +40,19 @@ function composeInstructions(): string {
 
 const instructions = composeInstructions();
 
-export function createTeacherAgent(model?: LanguageModel, tools?: ToolSet) {
+/**
+ * Compose the full instruction string: base prompt + fragments, then — when
+ * the session carries graph context (W8, vision §1 "the graph as session
+ * context") — the auto-generated knowledge-graph block appended after them as
+ * a clearly-delimited section (the 50-graph-context.md fragment teaches the
+ * teacher how to read it). The fragment mechanism itself stays untouched.
+ */
+function withGraphContext(graphContext: string | null | undefined): string {
+	if (!graphContext) return instructions;
+	return `${instructions}\n\n---\n\n${graphContext}`;
+}
+
+export function createTeacherAgent(model?: LanguageModel, tools?: ToolSet, graphContext?: string | null) {
 	return new ToolLoopAgent({
 		model:
 			model ??
@@ -45,7 +61,7 @@ export function createTeacherAgent(model?: LanguageModel, tools?: ToolSet) {
 				// they stream as reasoning parts into the UI's collapsible block.
 				reasoning: { enabled: true, effort: "medium" },
 			}),
-		instructions,
+		instructions: withGraphContext(graphContext),
 		// Tools are per-request (plan tools close over chatId); chat-handler
 		// passes createTeacherTools({ chatId }). Tests pass a mock model and get
 		// the default question-only set.