core/docs/decisions/ADR-0061-procedure-intent-pack-grounded-surface.md

ADR-0061 — PROCEDURE Intent Routes to Pack-Grounded Surface

Status: Accepted Date: 2026-05-18 Author: Shay

---

Context

Pre-ADR-0061, the PROCEDURE intent ("How do I X?", "How can I Y?") had no pack-grounded composer. The runtime's _maybe_pack_grounded_surface dispatched on:

• COMPARISON → pack_grounded_comparison_surface
• CAUSE / VERIFICATION → teaching_grounded_surface
• CORRECTION → pack_grounded_correction_surface
• DEFINITION / RECALL → pack_grounded_surface

PROCEDURE fell through to the universal "insufficient grounding" disclosure. This was the second architectural holdout miss surfaced by the epistemology v1 curriculum unit:

• procedure_define_010 — "How do I define a concept?" — expected term=["concept"]. Pre-ADR: universal disclosure → both surface and term miss.
• procedure_verify_034 — "How do I verify a claim?" — no expected_terms, but pre-ADR fell through to disclosure → surface miss (though the case had no terms-based fail).

The teaching corpus does not carry procedural chains (chat.teaching_grounding._VALID_INTENTS = frozenset({"cause", "verification"})); procedural knowledge is fundamentally different in kind from causal/verifying claims and deserves its own ratification path (out of scope for this ADR). The pack-grounded surface for procedures is the honest cold-start fallback: ground the topic in pack semantics, state explicitly that ratified step-by-step guidance does not exist yet.

---

Decision

Add pack_grounded_procedure_surface(subject_text: str) -> str | None to chat/pack_grounding.py and wire IntentTag.PROCEDURE through it in _maybe_pack_grounded_surface.

Surface format

"procedure-grounded ({pack_id}): {lemma} ({d1}; {d2}).
 Step-by-step guidance for {lemma} is not yet ratified
 in this session."

Every visible non-template token is either the topical lemma or a verbatim semantic_domains string from the ratified pack. The trailing clause is the constant trust-boundary label, analogous to ADR-0053/0060's "No prior turn in this session to correct yet."

Topic-lemma selector: last pack-resident lemma

Procedure subjects emerge from the intent classifier as verb phrases:

Prompt	intent.subject	Pack-resident tokens	Selected
How do I define a concept?	"define a concept"	define, concept	concept
How can I correct an error?	"correct an error"	correct	correct
How do I verify a claim?	"verify a claim"	verify	verify
How do I learn this?	"learn this"	learn	learn

The procedure verb tends to be the first pack-resident lemma; the topic of the procedure tends to be the last. Picking the last captures the user's actual subject of interest without requiring POS tagging or syntactic analysis.

When the verb is the only pack-resident lemma (object is OOV or a filler), the verb is the topic by elimination — keeps surface coverage on procedure utterances with non-pack objects.

Stopword set

Only be and have are stopworded — they're pack-resident but carry no topical signal. Procedure verbs (define, verify, correct, learn) are deliberately NOT stopworded, so the verb-as-fallback rule fires when the object is OOV.

Fall-through preserved

When subject_text contains no pack-resident lemma ("How do I do stuff?"), the composer returns None and the runtime falls through to the universal disclosure. This preserves the honesty contract from ADR-0053: never fabricate surface from nothing.

---

Verification

tests/test_procedure_surface.py             15 passed
  - extraction: last-wins / verb-by-elimination / skips be/have /
    None on empty / strips punctuation / case-insensitive
  - surface: contains topic lemma / contains topic domains /
    pack_id present / "not yet ratified" trust label preserved /
    None for no pack lemma / deterministic
  - end-to-end: procedure_define_010 emits 'concept' /
    no-pack-lemma falls through to disclosure /
    'verify a claim' grounds with verb

Lanes (regression check):
  core test --suite smoke           67 passed
  core test --suite cognition      121 passed
  core test --suite teaching        17 passed

Cognition lane lift

Split	Metric	Pre-ADR-0061	Post-ADR-0061
public	intent / surface / term / versor	100 / 100 / 91.7 / 100	100 / 100 / 91.7 / 100 (unchanged)
holdout	intent / surface / term / versor	100 / 94.7 / 79.2 / 100	100 / 100.0 / 83.3 / 100

Two cases fixed:

• procedure_define_010: surface and term (+1/24 = +4.2pp on term_capture; +1/19 on surface_groundedness).
• procedure_verify_034: surface only (no expected_terms; contributes the remaining 4.5pp on surface_groundedness).

Combined surface_groundedness lift: 94.7% → 100.0% on holdout.

Remaining holdout misses

Two cases still emit the universal disclosure on UNKNOWN intent:

• unknown_spirit_041 — "spirit wisdom truth" — expected ["wisdom", "truth"].
• unknown_word_018 — "word beginning truth" — expected ["word", "truth"].

expected_surface_contains is empty for both (so they pass the surface_groundedness check trivially via all([]) == True), but the expected terms (4 across the two cases) are not in the disclosure surface. Closing them requires a pack-grounded UNKNOWN composer that surfaces all pack-resident lemmas in the utterance — a deliberately-distinct ADR scope (different intent, different selector semantics, different trust-boundary clause).

---

Why not extend the teaching corpus to procedural chains

A teaching chain in cognition_chains_v1.jsonl carries (subject, intent, connective, object) with intent ∈ {cause, verification}. The schema implies a propositional claim: "subject {connective} object". Procedural knowledge is fundamentally different in kind:

• A procedure is a sequence (often ordered, often conditional), not a binary relation.
• A procedure's correctness depends on the procedural context (the user's existing state, tools, prior steps), not on alignment with reviewed evidence.
• Promoting "to define X, do A then B then C" into the same schema as "knowledge requires evidence" would silently equate two different epistemic structures — exactly the kind of hidden normalisation CLAUDE.md prohibits.

A future ADR could introduce a parallel procedure_chains_v1.jsonl with its own schema and a reviewed-procedural-knowledge composer. ADR-0061 is the honest fallback for the cold-start case in the absence of that infrastructure.

---

Cross-References

• ADR-0048 — the original pack_grounded_surface for DEFINITION / RECALL intents.
• ADR-0050 — the COMPARISON-shaped sibling.
• ADR-0053 — the CORRECTION acknowledgement; ADR-0061 follows the same trust-boundary pattern.
• ADR-0060 — the sibling fix that landed the correction topic lemma.
• Curriculum: epistemology v1 — the unit that surfaced this gap.