W5: probe/teach phases — divider + collapsed teach checks

components/artifacts/plan-divider.tsx

@@ -1,9 +1,29 @@
-import type { ArtifactPartProps } from "@/src/core/contracts";
+import type { ArtifactPartProps, PlanToolResult } from "@/src/core/contracts";
 
 /**
- * Phase divider rendered where plan_init lands in the transcript (W5).
- * Probe → teach transition marker per vision §2 "Two phases".
+ * The probe→teach divider (vision §2 "Two phases, clearly separated").
+ *
+ * Rendered by the artifact registry wherever the session's plan_init part
+ * sits in the transcript — the plan call IS the transition marker, so the
+ * divider marks the seam: probing above, teaching below. Deliberately quiet:
+ * a hairline rule with a small chip, never a banner.
+ *
+ * Renders null until the tool's output is available AND the init succeeded —
+ * a failed first plan_init must not mark the seam (the retry that succeeds
+ * draws the divider at its own, correct spot).
  */
-export function PlanDivider(_props: ArtifactPartProps) {
-	return null;
+export function PlanDivider({ part }: ArtifactPartProps) {
+	if (part.state !== "output-available") return null;
+	const result = part.output as PlanToolResult | undefined;
+	if (!result || result.ok !== true) return null;
+	const nodeCount = result.tree?.nodes?.length ?? 0;
+	return (
+		<div className="my-4 flex w-full items-center gap-3" data-testid="plan-divider">
+			<span className="h-px flex-1 bg-border/80" />
+			<span className="rounded-full border border-border/80 px-2.5 py-0.5 text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+				Teaching{nodeCount > 0 ? ` · ${nodeCount} node${nodeCount === 1 ? "" : "s"}` : ""}
+			</span>
+			<span className="h-px flex-1 bg-border/80" />
+		</div>
+	);
 }

components/chat.tsx

@@ -23,6 +23,7 @@ import type { TeacherUIMessage } from "@/src/agent/ui-message";
 import type { ArtifactPartProps } from "@/src/core/contracts";
 import type { QuestionAnswerData } from "@/src/core/question-core";
 import { findPendingJobCall, findPendingToolCall } from "@/src/core/pending";
+import { phaseAt } from "@/src/core/phases";
 
 /** One width for everything: transcript, cards, and the bottom blob share this column. */
 const COLUMN = "mx-auto w-full max-w-3xl px-4";
@@ -105,6 +106,14 @@ export function Chat({
 	const pending = findPendingToolCall(messages);
 	const busy = status === "submitted" || status === "streaming";
 
+	// Teach-phase check (W5, vision §2 "two phases"): a pending question that
+	// lands after plan_init starts collapsed behind a "Check your
+	// understanding" reveal button; probe-phase questions auto-open as today.
+	// A pending question can never precede plan_init in the transcript (the
+	// teacher's turn ends at the question call), so the session's current
+	// phase IS the question's phase. Pre-plan sessions: all probe — unchanged.
+	const requiresReveal = pending !== null && phaseAt(messages) === "teach";
+
 	// A tool call still streaming its input: the teacher is writing a question.
 	// Shown as a transcript shimmer, exactly like the thinking indicator.
 	const questionStreaming =
@@ -224,6 +233,7 @@ export function Chat({
 
 						<DockOverlay
 							pending={pending}
+							requiresReveal={requiresReveal}
 							composer={
 								<Composer
 									busy={busy}
@@ -264,27 +274,45 @@ export function Chat({
  */
 function DockOverlay({
 	pending,
+	requiresReveal,
 	composer,
 	onSubmitAnswer,
 }: {
 	pending: ReturnType<typeof findPendingToolCall>;
+	/** Teach-phase pending question: arrives collapsed behind the reveal button (W5). */
+	requiresReveal: boolean;
 	composer: React.ReactNode;
 	onSubmitAnswer: (output: QuestionAnswerData) => void;
 }) {
 	const { isAtBottom, scrollToBottom, scrollRef } = useStickToBottomContext();
-	const [expanded, setExpanded] = useState(true);
+	// Teach-phase mount (session reload with a pending check): the dock starts
+	// as the collapsed invitation too — the check must not pop open on reload.
+	const [expanded, setExpanded] = useState(!requiresReveal);
+	// Reveal state (W5): false until the learner clicks the invitation. While
+	// false, the scroll machine must NOT auto-expand at the bottom — the
+	// learner reads the teaching first and opens the check when ready. Once
+	// revealed, the normal collapse machine rules apply untouched.
+	const [revealed, setRevealed] = useState(false);
+	const revealPending = requiresReveal && !revealed;
 
 	const pendingId = pending?.toolCallId ?? null;
 	const initialPendingRef = useRef(pendingId);
 
 	// New question MID-SESSION: open expanded if the learner is following at
 	// the bottom (scroll to reveal it); reading history → arrive as the bar.
-	// On session mount the dock simply starts expanded at the bottom (the
-	// library's instant initial scroll positions us) — no scroll, no morph.
+	// Teach-phase checks ALWAYS arrive collapsed behind the reveal button,
+	// even at the bottom. On session mount the dock simply starts in its
+	// initial state (expanded for probe, invitation for teach) — no scroll, no
+	// morph.
 	useEffect(() => {
 		if (!pendingId || pendingId === initialPendingRef.current) return;
-		setExpanded(isAtBottom);
-		if (isAtBottom) void scrollToBottom();
+		if (requiresReveal) {
+			setRevealed(false);
+			setExpanded(false);
+		} else {
+			setExpanded(isAtBottom);
+			if (isAtBottom) void scrollToBottom();
+		}
 		// eslint-disable-next-line react-hooks/exhaustive-deps -- fire only when a NEW question lands
 	}, [pendingId]);
 
@@ -299,6 +327,10 @@ function DockOverlay({
 	expandedRef.current = expanded;
 	const pendingRef = useRef(!!pending);
 	pendingRef.current = !!pending;
+	const requiresRevealRef = useRef(requiresReveal);
+	requiresRevealRef.current = requiresReveal;
+	const revealedRef = useRef(revealed);
+	revealedRef.current = revealed;
 	const expandedHRef = useRef(0);
 	const collapsedHRef = useRef(42);
 
@@ -311,6 +343,7 @@ function DockOverlay({
 	const intentTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
 	const expandAndReveal = () => {
 		expandIntentRef.current = true;
+		setRevealed(true); // the teach-check invitation was accepted (W5)
 		setExpanded(true);
 		clearTimeout(intentTimerRef.current);
 		intentTimerRef.current = setTimeout(() => {
@@ -332,6 +365,9 @@ function DockOverlay({
 			if (expandedRef.current) {
 				if (d > delta + 64 && !expandIntentRef.current) setExpanded(false);
 			} else if (d < 16) {
+				// Teach checks stay collapsed until the learner opens them (W5): the
+				// at-bottom auto-expand would pop the form over the teaching.
+				if (requiresRevealRef.current && !revealedRef.current) return;
 				setExpanded(true);
 				void scrollToBottom();
 			}
@@ -397,6 +433,7 @@ function DockOverlay({
 									toolCallId={pending.toolCallId}
 									input={pending.input as never}
 									expanded={expanded}
+									reveal={revealPending}
 									onExpand={expandAndReveal}
 									onSubmit={onSubmitAnswer}
 								/>

components/question-dock.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useMemo, useState } from "react";
-import { ArrowDownIcon } from "lucide-react";
+import { ArrowDownIcon, ChevronRightIcon, PlayIcon } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { MessageResponse } from "@/components/ai-elements/message";
 import { cn } from "@/lib/utils";
@@ -37,14 +37,28 @@ export interface QuestionDockProps {
 	input: QuizToolInput | AskToolInput;
 	/** Collapse state, owned by the DockOverlay (it drives the shell's height morph). */
 	expanded: boolean;
+	/**
+	 * Teach-phase check awaiting its reveal (vision §2, W5): while collapsed,
+	 * the bar is the "Check your understanding" invitation instead of the
+	 * scroll-collapse strip. Owned by the DockOverlay; false once the learner
+	 * has revealed (afterwards the normal collapse machine rules apply).
+	 */
+	reveal?: boolean;
 	onExpand: () => void;
 	onSubmit: (output: QuestionAnswerData) => void;
 }
 
-export function QuestionDock({ toolName, toolCallId, input, expanded, onExpand, onSubmit }: QuestionDockProps) {
+export function QuestionDock({ toolName, toolCallId, input, expanded, reveal = false, onExpand, onSubmit }: QuestionDockProps) {
 	return (
 		<>
-			{!expanded && <QuestionDockBar toolName={toolName} question={input.question} onExpand={onExpand} />}
+			{!expanded && (
+				<QuestionDockBar
+					toolName={toolName}
+					question={input.question}
+					onExpand={onExpand}
+					variant={reveal ? "reveal" : "collapsed"}
+				/>
+			)}
 			<div className={expanded ? "dock-variant" : "invisible h-0 overflow-hidden"}>
 				<QuestionDockForm
 					toolName={toolName}
@@ -70,16 +84,42 @@ function teaserText(q: string): string {
 		.trim();
 }
 
-/** The collapsed strip: kind chip + question one-liner; click to answer. */
+/** The collapsed strip. Two species (W5): "collapsed" is the scroll minimization
+ *  (kind chip + one-liner + Answer ↓); "reveal" is the teach-check invitation —
+ *  a distinct, more inviting affordance, because it asks the learner to start
+ *  something, not to resume something. */
 export function QuestionDockBar({
 	toolName,
 	question,
 	onExpand,
+	variant = "collapsed",
 }: {
 	toolName: "quiz" | "ask_user_question";
 	question: string;
 	onExpand: () => void;
+	variant?: "collapsed" | "reveal";
 }) {
+	if (variant === "reveal") {
+		return (
+			<button
+				type="button"
+				data-testid="teach-check-reveal"
+				onClick={onExpand}
+				className="dock-variant flex w-full items-center gap-3 px-4 py-3 text-left transition-colors hover:bg-accent/40"
+			>
+				<span className="flex size-7 shrink-0 items-center justify-center rounded-full bg-primary/15 text-primary">
+					<PlayIcon className="size-3.5" />
+				</span>
+				<span className="min-w-0 flex-1">
+					<span className="block text-sm font-medium">Check your understanding</span>
+					<span className="block truncate text-xs text-muted-foreground">{teaserText(question)}</span>
+				</span>
+				<span className="flex shrink-0 items-center gap-1 text-xs font-medium text-primary">
+					Open <ChevronRightIcon className="size-3.5" />
+				</span>
+			</button>
+		);
+	}
 	return (
 		<button
 			type="button"

src/agent/prompts/30-phases.md

@@ -0,0 +1,18 @@
+# The two phases
+
+Every session has two phases, and the learner's UI marks the seam. Know which phase you're in — it changes how your questions arrive.
+
+## Probe
+
+From the first message until you call `plan_init`. Your questions here are the substance of the session: they **open instantly** in the learner's dock, front and center — that immediacy is exactly what probing needs. Ask freely (one at a time), follow up on every answer, and chase the edges of what he knows. The probe is working when the questions are getting sharper, not easier.
+
+## Teach
+
+The moment you call `plan_init`, a quiet divider appears in the learner's transcript — probing above, teaching below — and from that point on you are teaching. Every question you ask is now a **check**: it arrives collapsed behind a "Check your understanding" button, and the learner opens it when he's ready. Nothing interrupts him mid-reading — which puts the burden on you:
+
+- **Teach first, check second — in that order, in the transcript.** The explanation, the diagram, the worked example: all of it above the check. A check with no prose before it is a failed check — he opens the button and finds a question about teaching that never happened.
+- **Finish the thought before you fire.** Never call a check mid-explanation. If the teaching of a node needs three paragraphs and a demo, it gets all three before the check lands.
+- **One node, one check.** `plan_set_current` when you start teaching the node, teach it completely, then check it (`nodeId` set, so the outcome lands on the graph).
+- **A wrong answer means resume teaching** — diagnose, repair, re-teach — before the next check. The button is a gate, not a quiz-show buzzer.
+
+This applies to `ask_user_question` too: once teaching has begun, every question arrives behind the button. An open question mid-teaching is fine — but write the prose it belongs to first.

src/core/phases.ts

@@ -0,0 +1,47 @@
+/**
+ * Probe/teach phase derivation (vision §2 "Two phases, clearly separated").
+ *
+ * The session's phase is DERIVED, never stored: `plan_init` IS the transition
+ * marker — the call already fires exactly once at the seam (verified live in
+ * Gate 1), so no new agent tool exists. Phase = "probe" until the first
+ * message containing a `plan_init` tool part; from that message onward,
+ * phase = "teach". Everything after it (checks, follow-up asks) is teaching.
+ *
+ * Pure: no imports, no runtime deps — safe on server, client, and in tests.
+ */
+
+/** The two phases of a session. */
+export type Phase = "probe" | "teach";
+
+/** Minimal structural slice of a UI message — anything with typed parts. */
+export interface PhaseMessage {
+	parts: ReadonlyArray<{ type: string }>;
+}
+
+const PLAN_INIT_PART = "tool-plan_init";
+
+/**
+ * The phase at `upToIndex` (inclusive; default: the last message).
+ *
+ * Scans messages[0..upToIndex] for the FIRST message containing a
+ * `tool-plan_init` part — any part state counts (the call itself is the
+ * transition; teaching has begun even while the call's input streams). The
+ * message that contains plan_init is already teach: the divider renders
+ * exactly there, so probe content sits above it, teaching below.
+ *
+ * Boundary semantics:
+ * - no plan_init anywhere → "probe" at every index (pre-plan sessions keep
+ *   the old auto-open behavior for every question — backward compatible).
+ * - first plan_init in message i → phaseAt(m, i-1) === "probe",
+ *   phaseAt(m, i) === "teach", and every index after.
+ * - multiple plan_init parts → the FIRST wins (a re-init attempt later in
+ *   the transcript never moves the seam; the tool refuses re-init anyway).
+ */
+export function phaseAt(messages: readonly PhaseMessage[], upToIndex?: number): Phase {
+	const last = Math.min(upToIndex ?? messages.length - 1, messages.length - 1);
+	for (let i = 0; i <= last; i++) {
+		const parts = messages[i]?.parts;
+		if (parts?.some((p) => p.type === PLAN_INIT_PART)) return "teach";
+	}
+	return "probe";
+}

tests/phases.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Phase derivation (W5, vision §2 "two phases") — the probe→teach boundary.
+ *
+ * phaseAt is the pure seam-finder: plan_init IS the transition marker, so the
+ * first message containing a tool-plan_init part flips everything from it
+ * onward to "teach". The boundary cases here are the ones the UI leans on:
+ * teach checks collapse behind the reveal button, probe questions auto-open.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { phaseAt, type PhaseMessage } from "../src/core/phases.ts";
+
+/** A minimal message: just typed parts, exactly the structural slice phaseAt reads. */
+function msg(...partTypes: string[]): PhaseMessage {
+	return { parts: partTypes.map((type) => ({ type })) };
+}
+
+/** Realistic shape: full tool part objects with state fields (extra fields ignored). */
+function toolMsg(...parts: { type: string; state: string; toolCallId: string }[]): PhaseMessage {
+	return { parts };
+}
+
+describe("phaseAt", () => {
+	it("no messages → probe", () => {
+		assert.equal(phaseAt([]), "probe");
+	});
+
+	it("no plan_init anywhere → probe at every index (pre-plan sessions keep the old behavior)", () => {
+		const messages = [
+			msg("text"),
+			msg("text", "tool-quiz", "text"),
+			toolMsg({ type: "tool-quiz", state: "input-available", toolCallId: "q1" }),
+			msg("text"),
+		];
+		for (let i = 0; i < messages.length; i++) {
+			assert.equal(phaseAt(messages, i), "probe", `index ${i}`);
+		}
+		assert.equal(phaseAt(messages), "probe");
+	});
+
+	it("the boundary: probe before the plan_init message, teach from it onward", () => {
+		const messages = [
+			msg("text"), // probe chatter
+			msg("text", "tool-quiz"), // probe question
+			msg("text", "tool-plan_init", "text"), // ← the seam (divider renders here)
+			msg("text", "tool-quiz"), // a check — teach phase
+			msg("text"),
+		];
+		assert.equal(phaseAt(messages, 0), "probe");
+		assert.equal(phaseAt(messages, 1), "probe");
+		assert.equal(phaseAt(messages, 2), "teach", "the message containing plan_init is already teach");
+		assert.equal(phaseAt(messages, 3), "teach");
+		assert.equal(phaseAt(messages, 4), "teach");
+		assert.equal(phaseAt(messages), "teach", "default = current phase (last message)");
+	});
+
+	it("multiple plan_init parts → the FIRST wins (a later re-init never moves the seam)", () => {
+		const messages = [
+			msg("text"),
+			msg("tool-plan_init"), // first — the seam
+			msg("text"),
+			msg("tool-plan_init"), // a refused re-init attempt: must not matter
+			msg("text"),
+		];
+		assert.equal(phaseAt(messages, 0), "probe");
+		assert.equal(phaseAt(messages, 1), "teach");
+		assert.equal(phaseAt(messages, 2), "teach", "between the two plan_inits: already teach (first wins)");
+		assert.equal(phaseAt(messages, 3), "teach");
+	});
+
+	it("any part state counts — the call itself is the transition, even mid-stream", () => {
+		const messages = [
+			msg("text"),
+			toolMsg({ type: "tool-plan_init", state: "input-streaming", toolCallId: "p1" }),
+		];
+		assert.equal(phaseAt(messages, 1), "teach");
+	});
+
+	it("upToIndex past the end / negative → clamped, never throws", () => {
+		const messages = [msg("tool-plan_init")];
+		assert.equal(phaseAt(messages, 99), "teach");
+		assert.equal(phaseAt(messages, -1), "probe", "empty scan range → probe");
+		assert.equal(phaseAt([]), "probe");
+	});
+});

tests/render-cards.test.tsx

@@ -18,6 +18,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { MessageResponse } from "../components/ai-elements/message.tsx";
 import { QuestionDock } from "../components/question-dock.tsx";
 import { AnsweredCard } from "../components/answered-card.tsx";
+import { PlanDivider } from "../components/artifacts/plan-divider.tsx";
 import { buildAnswer, coerceCorrectAnswer, normalizeOptions, resolveCorrect, type QuestionData } from "../src/core/question-core.ts";
 
 const quizInput = {
@@ -171,4 +172,92 @@ describe("math rendering (streamdown + KaTeX)", () => {
 		);
 		assert.ok(answeredHtml.includes("katex"), "answered card: option/explanation math renders");
 	});
+});
+
+describe("teach-check reveal (W5 phase separation)", () => {
+	// The collapsed dock renders the bar AND the hidden form (it stays mounted
+	// so a half-made selection survives) — assertions target the bar species.
+	it("teach-phase check collapses into the invitation bar, not the scroll bar", () => {
+		const html = renderToStaticMarkup(
+				<QuestionDock
+					toolName="quiz"
+					toolCallId="t1"
+					input={quizInput as never}
+					expanded={false}
+					reveal
+					onExpand={() => {}}
+					onSubmit={() => {}}
+				/>,
+		);
+		assert.ok(html.includes('data-testid="teach-check-reveal"'), "invitation affordance present");
+		assert.match(html, /Check your understanding/);
+		assert.match(html, /Which planet is closest/, "question teaser invites, not minimizes");
+		assert.match(html, /Open/, "a clear reveal action");
 	});
+
+	it("probe questions keep the plain collapsed bar (no invitation copy)", () => {
+		const html = renderToStaticMarkup(
+				<QuestionDock
+					toolName="quiz"
+					toolCallId="q1"
+					input={quizInput as never}
+					expanded={false}
+					onExpand={() => {}}
+					onSubmit={() => {}}
+				/>,
+		);
+		assert.ok(html.includes('data-testid="question-dock-bar"'), "the scroll-collapse strip");
+		assert.ok(!html.includes("Check your understanding"), "no invitation copy outside teach phase");
+		assert.match(html, /Answer/, "the strip keeps its Answer affordance");
+	});
+
+	it("after the reveal, the teach check renders the full form (probe default, unchanged)", () => {
+		// Post-click: expanded=true — exactly today's dock. The probe auto-open
+		// path renders the identical form; this is also the regression pin for it.
+		const html = renderDock({ toolName: "quiz", toolCallId: "t1", input: quizInput as never });
+		assert.ok(html.includes('data-testid="question-dock"'), "the form is the dock's content once expanded");
+		assert.match(html, /Submit answer/);
+	});
+});
+
+describe("PlanDivider (the probe→teach seam)", () => {
+	const tree = {
+		nodes: [
+			{ id: "a", title: "A" },
+			{ id: "b", title: "B" },
+			{ id: "c", title: "C" },
+		],
+		edges: [{ from: "a", to: "b" }],
+		currentNodeId: null,
+		doneNodeIds: [],
+		version: 1,
+	};
+
+	it("renders the quiet divider with the node count once output-available", () => {
+		const html = renderToStaticMarkup(
+				<PlanDivider part={{ type: "tool-plan_init", state: "output-available", toolCallId: "p1", output: { ok: true, tree } }} />,
+		);
+		assert.ok(html.includes('data-testid="plan-divider"'));
+		assert.match(html, /Teaching/);
+		assert.match(html, /3 nodes/, "node count from the output tree");
+		assert.ok(!html.includes("banner"), "never a loud banner");
+	});
+
+	it("renders null while the tool streams and on a failed init", () => {
+		const streaming = renderToStaticMarkup(
+				<PlanDivider part={{ type: "tool-plan_init", state: "input-streaming", toolCallId: "p1" }} />,
+		);
+		assert.equal(streaming, "", "null while input-streaming");
+		const failed = renderToStaticMarkup(
+				<PlanDivider
+					part={{
+						type: "tool-plan_init",
+						state: "output-available",
+						toolCallId: "p1",
+						output: { ok: false, error: "Tree already initialized", tree },
+					}}
+				/>,
+		);
+		assert.equal(failed, "", "a refused re-init must not draw a second seam");
+	});
+});