core/docs/decisions/ADR-0067-cross-pack-teaching-chains.md

ADR-0067 — Cross-pack teaching chains (Plan Phase 4)

Status: Accepted Date: 2026-05-18 Author: Shay Phase: Plan Phase 4 (multi-domain composition) Builds on: ADR-0052 / ADR-0063 / ADR-0064 / ADR-0066

---

Context

ADR-0064 introduced the cross-pack teaching corpora registry but deliberately kept each corpus 1:1 bound to a single ratified pack. Chains whose subject + object resolved to different packs were dropped at load time. The structural rationale was sound for v1: keep the per-pack DAGs ratified before adding cross-domain edges.

Phases 1–3 satisfied that prerequisite:

• 3 ratified content packs live on the default runtime (cognition v1 + relations v1/v2).
• 36 reviewed in-pack chains across three corpora.
• NARRATIVE + EXAMPLE composers in place — ready to consume multi-corpus chain sets.

The articulation wall now lives in the gap between domains. The system has nothing to say when an operator asks:

> Why does family exist?
> Does identity require family?
> Does understanding require parent?

These prompts reference a relations-pack lemma and a cognition-pack lemma in the same chain. No single-pack corpus can ground them; an edge that crosses packs is required.

---

Decision

Introduce a deliberately narrow cross-pack chain shape. Each chain explicitly carries two pack-residency fields:

{
  "chain_id": "cause_family_grounds_identity",
  "subject": "family",
  "intent": "cause",
  "connective": "grounds",
  "object": "identity",
  "subject_pack_id": "en_core_relations_v1",
  "object_pack_id": "en_core_cognition_v1",
  ...
}

The loader verifies per-chain residency: the subject must resolve in its declared subject pack, and the object must resolve in its declared object pack. Same-pack entries are rejected (they belong in the in-pack corpus).

Files

chat/cross_pack_grounding.py                                  NEW
teaching/cross_pack_chains/cross_pack_chains_v1.jsonl         NEW (5 chains)
chat/runtime.py                                               wired cross-pack fall-through
chat/narrative_surface.py                                     aggregates cross-pack chains
chat/example_surface.py                                       aggregates cross-pack reverse chains
tests/test_cross_pack_chains.py                               NEW (31 tests)
docs/decisions/ADR-0067-cross-pack-teaching-chains.md         NEW (this file)

Surface format

"{X} — cross-pack-grounded ({corpus_id}: {subject_pack_id} × {object_pack_id}):
 {dX1}; {dX2}. {X} {conn} {Y} ({dY1}). No session evidence yet."

Both pack ids are exposed in the tag so the audit trail and operator debugger can see which domains the chain crosses without parsing the chain body.

Resolution order

In chat/runtime.py for CAUSE/VERIFICATION:

1. teaching_grounded_surface_composed (when composed_surface=True) OR teaching_grounded_surface — in-pack chain index (_all_chains_index across all single-pack corpora).
2. cross_pack_grounded_surface — fall-through when no in-pack chain resolves the (subject, intent). [ADR-0067]
3. Fall through to OOV invitation if the subject is unknown to any mounted pack.

The cross-pack composer is the fall-through only: when an in-pack chain exists on the same (subject, intent), the in-pack composer wins. This preserves the cognition-lane byte-identity invariant.

NARRATIVE and EXAMPLE aggregation

Both multi-clause composers (ADR-0066) now walk cross-pack chains in addition to in-pack ones:

• narrative_surface.py calls cross_pack_chains_for_subject(X) and appends those chains into the dedup-and-sort pipeline.
• example_surface.py calls cross_pack_chains_for_object(X) similarly.

The corpus tag widens from (cognition_chains_v1) to (cognition_chains_v1 + cross_pack_chains_v1) whenever any cross-pack clause contributes. Stable lexicographic ordering — no behaviour change on subjects with no cross-pack chains.

Seed corpus

teaching/cross_pack_chains/cross_pack_chains_v1.jsonl ships with 5 hand-authored, reviewed chains:

chain_id	direction
cause_family_grounds_identity	relations → cognition
cause_parent_grounds_understanding	relations → cognition
cause_family_supports_memory	relations → cognition
verification_identity_requires_family	cognition → relations
verification_understanding_requires_parent	cognition → relations

All connectives are whitelisted in generate.semantic_templates._PREDICATE_HUMANIZE.

---

Consequences

Capability unlocked

Prompt	Pre-ADR-0067	Post-ADR-0067
"Does identity require family?"	OOV invitation	identity requires family (cross-pack)
"Does understanding require parent?"	OOV invitation	understanding requires parent (cross-pack)
"Tell me about family"	1 clause (in-pack)	3 clauses (in-pack + 2 cross-pack)
"Give me an example of memory"	1 example	2 examples (in-pack recall + cross-pack family supports)

Live verification

> Does identity require family?
  [teaching] identity — cross-pack-grounded
  (cross_pack_chains_v1: en_core_cognition_v1 × en_core_relations_v1):
  cognition.identity; identity.stable. identity requires family
  (kinship.unit). No session evidence yet.

> Tell me about family.
  [teaching] family — narrative-grounded
  (cross_pack_chains_v1 + relations_chains_v1): kinship.unit;
  social.group.kin. family grounds identity (cognition.identity);
  family grounds parent (kinship.ascendant.direct); family supports
  memory (cognition.memory). No session evidence yet.

> Give me an example of memory.
  [teaching] memory — example-grounded
  (cognition_chains_v1 + cross_pack_chains_v1): cognition.memory.
  Example: family supports memory; recall reveals memory. No session
  evidence yet.

Cognition lane — byte-identical

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

The cross-pack composer fires only as a fall-through. All cognition- lane prompts (which exercise in-pack chains) follow the unchanged path.

---

Trust boundaries

• Strict per-chain pack residency. A chain declares subject_pack_id and object_pack_id explicitly; the loader verifies each lemma against its named pack. Skewed entries drop silently with no surface impact.
• Anti-leakage: cross-pack chains must actually cross packs. Entries where subject_pack_id == object_pack_id are rejected as corpus-misfilings.
• No prose generation. Every visible non-template token in the surface is a lemma, a pack semantic_domains atom, or a whitelisted connective from humanize_predicate.
• No new mutation surface. ADR-0027 / ADR-0057 doctrine preserved: corpus appends go through accept_proposal (or supersede_chain) and nowhere else. This module is read-only.
• In-pack precedence. Cross-pack chains never override an in-pack chain on the same (subject, intent) — the cognition- lane byte-identity invariant depends on this.
• Supersession honoured. Cross-pack chains support superseded_by (ADR-0055 Phase A) — retired entries drop from the active view, history preserved on disk.

---

Verification

tests/test_cross_pack_chains.py                              31 passed
Curated lanes (all green):
  smoke 67 / cognition 121 / teaching 17 / packs 6 / runtime 19
Cognition eval byte-identical (public + holdout).
Full lane: 2096 passed, 2 skipped, 0 failed.

---

Future ADRs unlocked

• Cross-pack supersede CLI. Today core teaching supersede is in-pack only. A cross-pack supersede needs to validate the new chain's residency against the same (subject_pack_id, object_pack_id) pair as the retired chain.
• Cross-pack proposals via core teaching propose. Today proposals target the in-pack corpus only. Extending to cross-pack needs the proposal schema to carry both pack ids and the replay- equivalence gate to handle multi-corpus surface diffs.
• Cross-pack composed surface (ADR-0062 generalisation). Chain- of-chains across packs (e.g. family grounds identity, which grounds knowledge) would compose a relations seed → cognition intermediate → cognition tail. Needs the composer to dispatch on per-chain object_pack_id for follow-up lookup.
• Three-pack chains. Today cross-pack is binary (subject_pack × object_pack). N-ary chains crossing 3+ packs would need a different schema; out of scope until a third content-bearing pack ratifies.