Render Glossary Observations from InvocationPayload (gstack / host agents)
Who is this for (1)
- Stakeholder Persona: AI Collaboration Agent — Written for the AI Collaboration Agent reader.
Render Glossary Observations from InvocationPayload
When Spec Kitty’s invocation executor processes a request it runs a fast inline
glossary conflict scan (the glossary chokepoint) and attaches the result to
InvocationPayload as glossary_observations. Host agents — including gstack
and any custom orchestrator — must implement the rendering contract described
below.
Payload Structure
InvocationPayload.to_dict() returns a dict that includes "glossary_observations":
{ "invocation_id": "01HXYZ...", "profile_id": "implementer", "action": "implement", "governance_context_text": "...", "governance_context_hash": "a3f1b2c4", "governance_context_available": true, "router_confidence": null, "glossary_observations": { "matched_urns": ["glossary:d93244e7"], "high_severity": [], "all_conflicts": [], "tokens_checked": 12, "duration_ms": 3.2, "error_msg": null }}The glossary_observations dict is produced by
GlossaryObservationBundle.to_dict().
Rendering Contract
Clean invocation (all_conflicts empty, error_msg null)
No glossary notice is needed. Deliver governance context to the model as normal.
Low-severity conflicts only (all_conflicts non-empty, high_severity empty)
Optionally surface a low-priority advisory notice. No blocking is required. Example (surfaced below the governance context):
[GLOSSARY ADVISORY] Minor terminology ambiguity detected. Review if relevant.High-severity conflicts (high_severity non-empty)
Prepend an inline warning before the governance context delivered to the model. This ensures the model receives the warning in its context window before acting.
Example format:
[GLOSSARY WARNING] The following terms carry HIGH-severity semantic conflicts: • lane (glossary:d93244e7) — ambiguous_scope Candidate senses: "execution lane (WP routing)" | "git branch lane (worktree)"
Review these terms carefully before proceeding.---[Governance context follows]Error during scan (error_msg non-null)
Log the warning internally. Do not block the invocation. The glossary scan degraded gracefully and the rest of the payload is valid.
Example log line:
[WARN] glossary chokepoint error for invocation 01HXYZ...: <error_msg value>Trail Behavior
A glossary_checked event is appended to the Tier 1 JSONL trail only when
all_conflicts is non-empty OR error_msg is non-null. Clean invocations
produce no glossary_checked line.
Readers that encounter "event": "glossary_checked" in a trail file and do not
recognize the event type may safely skip it.
See Trail Model — Glossary Check Event for the full event schema.