domain-glossary

domain-glossary

Source-grounded domain glossaries in Obsidian — every entry cites a verifiable code symbol, and every citation is drift-checked.

Why

Static CONTEXT.md / GLOSSARY.md files rot. A term defined against Foo::bar() in 2024 becomes a lie once the symbol is renamed, moved, or deleted, and nobody notices until an agent quotes it back at you.

This plugin keeps glossary entries in Obsidian (per-domain, not per-repo), requires every entry to cite a stable artifact (symbol name first, file path fallback), and provides a drift-check pass that classifies every citation as RESOLVED, RELOCATED, or UNRESOLVED.

How it works

1. Look up on demand. When the agent encounters an unfamiliar acronym or project-specific term in a registered repo, it auto-invokes the skill, resolves the cwd to a domain via domain-glossary.local.md, reads that domain's glossary file, and answers grounded — no manual @-includes, no CLAUDE.md edits.
2. Seed candidate terms from four sources: claude-mem observations, git commit message corpora, local symbol definitions (GitNexus CLI when available, grep fallback otherwise), and in-repo documentation (READMEs, docs/**, Python docstrings).
3. Confirm each candidate with the user before writing — the agent never writes uncited entries.
4. Store accepted entries in an Obsidian domain glossary (<vault>/<Domain>/glossary.md).
5. Drift-check on demand: walk every citation, resolve it against the cited repo, report status.
6. Mirror (optional) the canonical vault file to a repo docs/glossary.md with a provenance header.

Current Status

• Storage: Obsidian-first, with optional repo mirror.
• Scope: per-domain glossary files.
• First target: Altamira / mtf-builder.
• Exposure: public personal v0.1 tooling; not marketplace-ready.
• Citation key: symbol-name primary, file-path fallback.

Evaluation Status

Phase 4/5 produced retrospective proxy evidence only: no measured token savings, no proxy time-to-root-cause improvement, and a small reviewer-observed preference for glossary-loaded PR language.

Because token-scope was not available in the trial shell, this repository does not claim measured token savings yet. See docs/evaluations/2026-05-08-phase4-ab-trial.md for the caveats and next validation step.

Commands

Command	What it does
(no command — auto-invoke)	When the agent meets a term it can't ground, it invokes the skill, resolves the active repo's domain, and reads the matching glossary before answering.
/domain-glossary	Identify the current domain and list available subcommands.
/domain-glossary seed <domain>	Run the four seed scripts and merge candidates for review.
/domain-glossary drift-check <glossary.md>	Resolve every citation in the glossary and report drift.
drift-check-all.sh [--config <path>] [--json]	Walk every domain in domain-glossary.local.md and aggregate counts. Exit status = drift count.
drift-check-on-commit.sh	Async post-commit hook. Returns in ~10–70 ms, runs drift-check-all in a detached subshell under a 30 s hard timeout, and overwrites $CEO_VAULT/CEO/alerts/glossary-drift.md as a state file.

Scripts

All scripts live under skills/domain-glossary/scripts/ and can be run directly without invoking the slash command.

Script	Purpose
drift-check.sh [--repo name=path] [--json] <glossary.md>	Resolve citations, emit RESOLVED / RELOCATED / UNRESOLVED.
drift-check-all.sh [--config <path>] [--json]	Drift-check every domain in domain-glossary.local.md, summary at the end. Repo aliases are derived from the basename of each registered repo path.
drift-check-on-commit.sh	Async post-commit wrapper. See docs/playbooks/glossary-drift.md.
seed-from-claude-mem.sh --project <p> --query <q>	Candidate terms from claude-mem SQLite (~/.claude-mem/claude-mem.db).
seed-from-commits.sh --repo <path> [--since <date>]	Candidate terms by phrase frequency in git log.
seed-from-gitnexus.sh --repo <path> --repo-name <alias>	Candidate terms from symbol definitions (GitNexus when present, grep fallback).
seed-from-docs.sh --repo <path> --repo-name <alias>	Candidate terms from READMEs, docs/**, module READMEs, and Python module/class docstrings.
resolve-domain.sh [cwd]	Resolve the current working directory to <domain>\t<glossary-path> via domain-glossary.local.md (with git-worktree fallback). Used by the skill's lookup operation.
render-repo-mirror.sh --source <vault.md> --dest <repo/docs/glossary.md>	Copy vault glossary to a repo mirror with provenance header.

Citation forms

Drift-check accepts three citation shapes inside a glossary entry:

**Citation:** `symbol_name` in `repo:path/to/file.py`
**Citation:** `repo:path/to/file.py:42`
**Citation:** [[Altamira/some-note]]