core/docs/decisions/ADR-0066-turn-level-composition.md

ADR-0066 — Turn-level composition (Plan Phase 3)

Status: Accepted Date: 2026-05-18 Author: Shay Phase: Plan Phase 3 (turn-level composition — the articulation gap) Builds on: ADR-0048 / ADR-0052 / ADR-0062 / ADR-0064 / ADR-0065

---

Context

Phases 1 + 2 closed two flywheels: the chain-gap and OOV-gap signal streams. The vocabulary and corpus axes both grow under operator review. But surfaces still felt mechanical — each turn was freshly minted from primitives, never referenced backward.

Three intents were missing from the runtime:

1. Thread anaphora — "As we just established, X reveals Y, and on this turn..." Conversation reads as a thread, not a series of independent grounded surfaces.
2. NARRATIVE — "Tell me about X." A multi-clause composer that surfaces everything the system has reviewed about X, across every registered corpus.
3. EXAMPLE — "Give me an example of X." The converse of NARRATIVE: surfaces chains where X is the object, inverting the typical chain access pattern.

Phase 3 adds all three deterministically — no prose generation, no content synthesis.

---

Decision

P3.1 — Session-thread context (chat/thread_context.py)

A bounded FIFO of TurnSummary records, owned by ChatRuntime. Each turn appends one summary (intent_tag, subject, grounding_source, chain_id, corpus_id) via the runtime's internal _push_thread_summary. The cold-start path classifies intent up-front unconditionally so the summary captures the subject even when no sink is attached (previously gated on sink attachment — now gated only on gate_decision.source == "empty_vault" + English output).

Default capacity 8 (MAX_THREAD_TURNS). Oldest summaries evict in FIFO order. Frozen TurnSummary dataclass; never mutated post-push.

P3.2 — Anaphora composer (chat/anaphora.py)

thread_anaphora_prefix(ctx, subject, intent_name, source) → str | None. Returns a deterministic backreference when:

• The current turn is pack/teaching grounded.
• A prior pack/teaching turn on the same subject exists in the thread context.
• The prior turn's intent differs from the current intent (same-intent revisits are redundant; the prior turn IS the current surface modulo vault drift).

Prefix shapes (structural-fields-only, no prose):

(Recalling turn N: chain <chain_id>.)            # prior was teaching
(Recalling turn N: <subject> grounded pack.)     # prior was pack

Opt-in via RuntimeConfig.thread_anaphora=False. Default off preserves every pre-P3.2 surface byte-identically.

P3.3 — NARRATIVE intent (chat/narrative_surface.py)

New IntentTag.NARRATIVE. Classifier patterns:

^tell\s+me\s+about\s+
^describe\s+
^what\s+(?:can|do)\s+you\s+(?:say|know)\s+about\s+

Registered BEFORE ^what\s+(?:is|are)\s+ so the more specific patterns win.

Composer: narrative_grounded_surface(subject_lemma, max_clauses=4). Walks every reviewed chain rooted on X across all registered teaching corpora, dedupes by (connective, object), sorts by (intent, connective, object) for replay stability, emits up to max_clauses clauses.

Surface format:

"{X} — narrative-grounded ({corpus_ids}): {dX1}; {dX2}.
 {X} {conn1} {O1} ({dO1}); {X} {conn2} {O2} ({dO2}). No session
 evidence yet."

Tagged grounding_source="teaching" — narrative surfaces are reviewed-corpus content, same provenance tier as teaching_grounded_surface.

P3.4 — EXAMPLE intent (chat/example_surface.py)

New IntentTag.EXAMPLE. Classifier patterns:

^(?:give|show)\s+(?:me\s+)?an?\s+(?:example|instance)\s+of\s+
^example\s+of\s+

Composer: example_grounded_surface(object_lemma, max_examples=3). Reverse-chain access: walks chains where X is the object, not the subject. Dedupes by subject. Sorts by (intent, subject, connective).

Surface format:

"{X} — example-grounded ({corpus_ids}): {dX1}; {dX2}.
 Example: {subject1} {conn1} {X}; {subject2} {conn2} {X}. No
 session evidence yet."

Cross-cutting

• NARRATIVE + EXAMPLE both fall through to the OOV invitation (P2.1) when the subject is unknown — same gradient discipline as Phase 2.
• Both composers consult the cross-corpus aggregator from ADR-0064; no new ratification required.
• No new pack mutation. No new corpus. Phase 3 is pure surface + thread-state work over the Phase 1/2 substrate.

---

Consequences

Capability unlocked

Intent	Pre-Phase-3	Post-Phase-3
"Tell me about X"	universal disclosure	multi-clause narrative across corpora
"Give me an example of X"	universal disclosure	reverse-chain example surface
Subject-anaphora across turns	none	opt-in deterministic backreference

Live verification

> Tell me about truth.
  [teaching] truth — narrative-grounded (cognition_chains_v1):
  cognition.truth; logos.core. truth grounds knowledge (cognition.knowledge);
  truth requires evidence (cognition.evidence). No session evidence yet.

> Give me an example of knowledge.
  [teaching] knowledge — example-grounded (cognition_chains_v1):
  cognition.knowledge. Example: truth grounds knowledge;
  understanding requires knowledge; evidence grounds knowledge.
  No session evidence yet.

> Tell me about mother.
  [teaching] mother — narrative-grounded (relations_chains_v2):
  kinship.parent.female; kinship.parent. mother precedes daughter
  (kinship.child.female). No session evidence yet.

# With thread_anaphora=True, after a teaching turn on "light":
> What is light?
  [pack] (Recalling turn 0: chain cause_light_reveals_truth.)
  light — pack-grounded (en_core_cognition_v1):
  cognition.illumination; logos.core; perception.clarity.

Cognition lane: byte-identical

Phase 3 is additive — every existing intent classifier rule and composer behaviour preserved.

public:  intent 100% / surface 100% / term 91.7% / closure 100%
holdout: intent 100% / surface 100% / term 83.3% / closure 100%

---

Trust boundaries

• No prose generation. The anaphora prefix is structural fields only (turn_index + chain_id or grounding tier). NARRATIVE and EXAMPLE composers emit only pack atoms, chain content, and fixed template strings.
• No new mutation surfaces. Phase 3 reads the reviewed corpora; it never writes.
• Anaphora is opt-in. Default thread_anaphora=False keeps surfaces byte-identical to pre-P3.2.
• Bounded. Thread context capped at 8 turns; NARRATIVE capped at 4 clauses; EXAMPLE capped at 3 examples. All defaults configurable.

---

Files changed

chat/thread_context.py                                   NEW (~165 lines)
chat/anaphora.py                                         NEW (~90 lines)
chat/narrative_surface.py                                NEW (~165 lines)
chat/example_surface.py                                  NEW (~115 lines)
chat/oov_surface.py                                      added NARRATIVE/EXAMPLE
chat/runtime.py                                          wired all three composers + thread push
core/config.py                                           thread_anaphora flag
generate/intent.py                                       NARRATIVE / EXAMPLE enum + patterns
tests/test_thread_context.py                             NEW (20 tests)
tests/test_anaphora.py                                   NEW (12 tests)
tests/test_narrative_example_intents.py                  NEW (30 tests)
docs/decisions/ADR-0066-turn-level-composition.md        NEW (this file)
docs/decisions/README.md                                 ADR-0066 index entry

---

Verification

tests/test_thread_context.py                             20 passed
tests/test_anaphora.py                                   12 passed
tests/test_narrative_example_intents.py                  30 passed
Curated lanes (all green):
  smoke 67 / cognition 121 / teaching 17 / packs 6 / runtime 19 / algebra 132
Cognition eval byte-identical.

---

Future ADRs unlocked

• Anaphora on the walk path. Today thread anaphora fires only when both turns are pack/teaching tier. Extending to vault-path turns (the typical mid-session surface) needs a parallel hook in the walk return path. Natural follow-up.
• Multi-intent NARRATIVE composition. Current NARRATIVE walks one corpus dimension. Future work: extend composed-surface (ADR-0062) to operate on the NARRATIVE clause set, producing "narrative-of-narratives" surfaces.
• EXAMPLE with hypothetical counterexamples. Today EXAMPLE surfaces only positive corpus chains. Future: when the corpus contains contradicting/superseded chains, EXAMPLE can show contrast.