coverage gaps

the queue where "we asked, codex doesn't have it" becomes "fix or retire?"

when validate_world_element gets a non-canonical value with no fuzzy match (or a far one), the codex doesn't pretend the term is real. it logs the call and moves on.

the file

grimoires/codex-mcp/coverage-gaps.jsonl

gitignored. local-only. curator-facing. each line is one validation miss:

{"timestamp":"2026-04-30T18:42:11Z","type":"archetype","value":"Freetech","suggested":"Freetekno","distance":3,"consumer_hint":"ruggy-v06"}
{"timestamp":"2026-04-30T19:01:55Z","type":"zone","value":"sea-of-stars","suggested":null,"distance":null,"consumer_hint":"satoshi-v07"}

the cycle

1. agent calls validate_world_element with a non-canonical value
2. codex appends to coverage-gaps.jsonl
3. periodically, Gumi reads the queue
4. each entry resolves to one of:
   ✅ enrich — add to the canonical set; the claim was reasonable
   ❌ retire — invalid; teach the agent to stop using the term
   📝 alias  — colloquial pointer to an existing canonical entry

why curated, not scraped

without the gap log, two failure modes accumulate silently:

• 🪞 agents drift toward terms the codex doesn't bless, and the curator never sees which terms.
• 🌀 the codex inflates by cargo cult — "user asked, so add it" instead of reality-grounded curation.

with the gap log, the curator works from real signal: terms real consumers really asked for, with frequencies and consumer hints. the codex grows in the direction of actual narrative pressure.

composition