learnharness/docs/probe-teach-split.md

The probe→teach agent split & plan-movement semantics

Shared understanding reached 2026-09-11 (user + master session). This is the convergence record — the decided design, with reasoning. It is not a task list; implementation waves are planned against it.

---

1. Two agents, one conversation

Probing and teaching are structurally so different that they get separate agents: separate system prompts and separate tool sets, each fully fleshed-out with a major focus on its own phase. The split extracts more system-instruction alignment: neither agent carries the other phase's bulk (neither needs the specifics — each gets only a brief summary of the other's philosophy so they share a view of the whole process).

• The prober runs the probing phase: quiz + ask_user_question + probe_done. Its quiz is a different tool (different schema: no nodeId field at all) under the same name, so the model is never shown a field it must not use. No plan tools, no jobs, no demos.
• The teacher runs everything from planning onward: full tool set (teach quiz with nodeId, plan_init, jobs, demos). Constructed the moment the transcript carries a probe_done.
• The swap happens between probing and planning — the planning phase needs full knowledge of how teaching is done, so the teacher agent starts at planning.
• They share the message history. No fresh start: the history holds subtleties an assessment summary would lose. History tool parts are content, not live schemas — the teacher reads the prober's quiz calls as past conversation; the one foreign tool (probe_done) reads as a concluded past action, and even a hypothetical re-call degrades to a returned tool-error (the return-to-agent doctrine).
• Invisible to the user: same chat, same record, same UI. The agents are constructed per-request by the same composition root; "which agent" is a construction branch, not a handoff.

2. probe_done — the seam tool

The prober concludes explicitly:

• Server-side tool. Input: the learner assessment. Output: ok/error.
• Refuses while a question is open ("resolve the open question first") — same doctrine as nodeId validation.
• Refuses a second conclusion (idempotent: the probe concludes once).
• The assessment is the tool call's input, so it streams to the learner live and is durable in the transcript by the tool result itself. A dedicated assessment card/viewer comes later (UI).
• Assessment shape (v1, refine later): a list of dependency strands + a free-form read of the learner's edge on each. The probe was already a binary search per strand the lesson depends on; the assessment formalizes exactly that. Optional overall summary.
• Side effect: it queues the handoff. When the prober's turn ends, the wake pipeline (the same machinery that delivers sub-agent results and abort steers) fires a server-side turn with a handoff steer — the teacher is constructed (probe_done is in the transcript) and authors the plan. The learner experiences assessment → plan as one continuous flow. If the wake is lost (crash window), the next client message still constructs the teacher — the transcript is the source of truth.

3. nodeId semantics — position, not completion

The old contract read a correct answer on a tagged check as "node done." That is the wrong signal and is abolished. The new contract:

nodeId on a quiz means: "this question is about this node." Nothing else. It is a position signal, never a completion signal.

• Current node = the node referenced by the most recent tagged quiz call (the call, not the result — any state counts).
• Visited = every node that appeared in an earlier tagged quiz call. Sticky, monotonic. There is no done ledger and no done bookkeeping of any kind — everything is inferred from the session history. The stored tree carries structure only (the author-once protocol taken to its conclusion: currentNodeId/doneNodeIds are removed from the tree).
• A node spans multiple turns and multiple checks naturally. Several questions may tag the same node — the map stays put. The teacher moving to a new node is the teacher's judgment that the previous one is finished, regardless of individual check outcomes (a failed check followed by a re-teach and a move-on is still a visited node).
• Failed checks move nothing. Results no longer feed derivation at all.
• Untagged checks are legal ad-hoc checks — they don't move the map (quick comprehension checks don't need nodes). Not every check needs a node. The prompt stresses tagging when teaching a map node: an untagged stream leaves the map frozen (lost signal).
• No fallback current. Before the first tagged check nothing is current. No derived-from-prereqs guess.
• Present-but-invalid ids are still rejected at the call boundary (existing validation, return-to-agent retry).
• Visualization: current node gets a special highlight; visited nodes render visible (not grayed); upcoming nodes gray out. "Where have we been, where are we."

4. Phases — explicit events, no occupancy derivation

The phase chain is event-driven:

probe (prober) — probe_done → planning (teacher) — plan_init presents the plan → accept → teach (teacher)

• The broken derived-occupancy seam (phase-of-tree via currentNodeId nothing ever sets — the stuck-on-plan bug) is replaced, not patched.
• Interim rule until the accept-plan UI lands: a successful plan_init marks plan→teach. (The accept gate is designed but deferred — §7.)
• The session picker phase derives from transcript markers the same way.

5. No global-graph context in sessions (for now)

Both agents run fully standalone — no knowledge-graph injection into either prompt. The graph-as-session-context idea (W8) is shelved until there's a considered design for what it should actually feed. The global knowledge graph remains what the extraction pipeline builds; nothing in lesson prompts reads it.

6. The plan UI: persistent DAG window (direction)

The injected-blocks approach is superseded: the plan should live in a persistent DAG window in the conversation view (like the background- processes dock): always present, zoomed on the current node, auto-moving as the lesson advances; click → full plan (the existing popup survives as the expanded view). Exact layout/design is refined in the UI session.

Interim until that wave: the full plan block still renders in the flow at plan authoring (plan presentation moment; statuses are accurate at that instant) and remains the popup's entry point. The neighborhood-block machinery (frozen fragments) is retired — snapshots can't represent live-derived movement.

7. Deferred / later waves (designed, not now)

• Accept-plan UI — when the teacher presents the plan, the composer changes to a formal accept control (two send buttons: green accept-plan / continue; red decline) — first plan_init only, never re-authorings. That acceptance is the explicit planning→teach signal. Ideated in the UI session.
• Assessment viewer — the strand assessments displayed to the learner as a proper card (data already durable in the transcript).
• Model / thinking control — currently hardcoded per role in config.ts MODELS. The split gives natural MODELS.prober / MODELS.teacher entries; runtime control comes after.
• Graph context, properly designed — what the global graph should feed into sessions (§5).

8. No backwards compatibility — ever

Legacy sessions are not supported. At major pivots the testing data is wiped and re-grown from new testing. No compat shims, no legacy marker fallbacks, no migration of old trees. probe_done is the only teacher construction key; sessions without it are prober sessions (dead legacy data is garbage to be wiped, not accommodated).

---

Diagnosis context (why this pivot)

The 2026-09-11 user testing round (Nietzsche + Lacan sessions, minimal- effort GLM) exposed: (1) the teacher never tagged nodeId — every quiz in both sessions was untagged, so nothing ever derived; (2) the phase system structurally could not leave "plan" — phaseOfTree read currentNodeId, which the author-once protocol never sets, so no session could reach "teach"; (3) with result-derived "done," one passed check would have falsely finished a node. Model-compliance issues (untagged checks, free-text correctAnswer) are expected to shrink with higher thinking budgets and runtime model control — but the semantics had to be right first. Model mistakes are good test material: they exercise the return-to-agent validation loops.