Merge feat/graph-rendering: understanding-level closed scale, label declutter disabled

src/agent/subagents/extraction.ts

@@ -118,11 +118,12 @@ const propositionSchema = z.object({
 	messages: messagesField,
 	evidence,
 	understanding: z
-		.string()
+		.enum(["solid", "shaky", "accepted", "resisted", "not yet engaged"])
 		.optional()
 		.describe(
-			'One note about THIS session\'s evidence of the learner\'s grasp of this proposition, on a named-word scale ' +
-				'("solid", "shaky", "accepted", "resisted", "not yet engaged") — no numbers, no predictions.',
+			"ONE word — the learner's grasp of this proposition in THIS session, from the fixed scale " +
+				'"solid" | "shaky" | "accepted" | "resisted" | "not yet engaged". Nothing else: no numbers, ' +
+				"no justification, no explanation.",
 		),
 });
 
@@ -180,8 +181,9 @@ quiz outcomes carry that the learner believed the wrong version.
    - One reasoning step per proposition: never a topic blob, never a sub-step.
    - "messages": the [id] tags of every message where the proposition came up — provenance, report it.
    - "aliases": verbatim phrasings this session used for the same proposition.
-   - "understanding": ONE named-word-scale note on the evidence of the learner's grasp, for this session
-     only ("solid", "shaky", "accepted", "resisted", "not yet engaged"). No numbers, no predictions.
+   - "understanding": ONE word from the fixed scale — "solid", "shaky", "accepted", "resisted", or
+     "not yet engaged" — judging the learner's grasp of the proposition in THIS session. Strictly one
+     word, no numbers, no justification, no explanation (a wrong-shaped note is rejected by the schema).
 
 2. EDGES between propositions:
    - "follows": to is DERIVABLE from from (understanding from makes understanding to achievable).
@@ -256,8 +258,9 @@ FAITHFULNESS — verify every candidate against the transcript:
   direction-swapped or speculative edges.
 - ATTRIBUTION: the QUIZ line's question must genuinely test the attributed proposition. Drop wrong
   attributions to null, or re-point them to the proposition the question actually tests.
-- UNDERSTANDING notes: verify against the quiz outcomes and the session's evidence; reword to a named-word
-  scale or drop.
+- UNDERSTANDING levels: verify against the quiz outcomes and the session's evidence; each note must be
+  exactly one word from the fixed scale ("solid", "shaky", "accepted", "resisted", "not yet engaged") —
+  reword or drop anything else. No justifications.
 
 IDENTITY — link-or-create, per proposition:
 - You see the current graph (every node: id, name, statement, aliases). For each verified proposition,

src/core/contracts/graph.ts

@@ -102,7 +102,8 @@ export interface LedgerEvent {
 	 *  understanding observations — re-emission of the same chat must never
 	 *  double-record an event. */
 	ref?: string;
-	/** The learner's quiz note — diagnostic gold (vision §1 calibration). */
+	/** The learner's quiz note (diagnostic gold), or the understanding
+	 *  LEVEL word for observations — a session-relative judgment. */
 	note?: string;
 	/** The quiz question text, when nodeId is null (later attribution input). */
 	question?: string;
@@ -138,6 +139,16 @@ export interface LedgerEvent {
 
 // ─── Extraction findings (extractor output → audit → merger input) ───────────
 
+/**
+ * The extractor's standardized per-session understanding scale (DECIDED
+ * 2026-09-08): a CLOSED named-word list — no numbers, no prose, no
+ * justifications (a justification, if the agent wants one, is dropped;
+ * it is not stored). The level is session- and extraction-run-relative
+ * judgment about the learner, shown next to its session — never a node
+ * property.
+ */
+export type UnderstandingLevel = "solid" | "shaky" | "accepted" | "resisted" | "not yet engaged";
+
 /** One proposed proposition — a node candidate (or a re-encounter of one). */
 export interface ExtractedProposition {
 	/** Extractor-local id ("p1", …) referenced by edges + attribution. */
@@ -158,11 +169,11 @@ export interface ExtractedProposition {
 	messages: string[];
 	/** Verbatim transcript quotes backing the proposition. */
 	evidence: string[];
-	/** The extractor's understanding note for this proposition IN THIS
-	 *  session — a named-word scale ("solid", "shaky", "accepted",
-	 *  "resisted"), no numbers. Joins the ledger as an observation event;
-	 *  treatment pending the state-model ideation. */
-	understanding?: string;
+	/** The extractor's understanding level for this proposition IN THIS
+	 *  session — one word from the UnderstandingLevel scale. Joins the
+	 *  ledger as an observation event (note = the level word); treatment
+	 *  pending the state-model ideation. */
+	understanding?: UnderstandingLevel;
 }
 
 /** One proposed relation between two propositions. */