@caddis/cli 0.4.3 → 0.4.5

package/bundles/antigravity-plugin/CADDIS-GLOSSARY.md

@@ -0,0 +1,150 @@
+# Pipeline Glossary
+
+> **Shipped as `CADDIS-GLOSSARY.md`.** This defines CADDIS's own vocabulary — the words the
+> toolchain coined, which a user meets constantly and cannot guess from the plain word. Your
+> project's own terms belong in `.caddis/kb/GLOSSARY.md` instead; run `/caddis:glossary` to
+> build one. Two files, two subjects, deliberately different names.
+
+Canonical terms used across all agents, skills, and pipeline infrastructure.
+When writing agent instructions, skills, or documentation, use ONLY these terms.
+
+Two vocabularies live here and they are NOT interchangeable. **Core Terms** onward describe the
+agent PIPELINE (orchestrator, stages, `pipeline-state.json`). **Toolchain Terms** describe caddis
+as a distributed product (pool, mirror, export target). A word can be canonical in one and absent
+from the other; where they genuinely collide, the collision is named under Flagged ambiguities
+rather than resolved by fiat.
+
+Admission test, borrowed from `last30days-skill`'s CONCEPTS.md: a term belongs here when its
+project meaning is **distinct enough from its ordinary technical sense that a newcomer would
+misread it**. `commit` does not belong. `pool` does.
+
+---
+
+## Core Terms
+
+| Canonical Term | Definition | DO NOT USE |
+|---------------|------------|------------|
+| artefact | Any file produced by an agent as pipeline output. This is the correct spelling in all contexts — field names, prose, section headers. | artifact, deliverable, output file |
+| stage | A pipeline-level progression step (intent, prd, architect, plan, implement, tester, review, closed) | phase (for pipeline steps), step |
+| phase | A subdivision of work within a Plan (Phase 1, Phase 2…). Phases exist WITHIN the implement stage. | stage (for plan subdivisions), step |
+| chain_id | Feature tracking ID format: `FEAT-YYYY-MMDD-slug`. Links all artefacts for a feature. | feature_id, tracking_id |
+| handoff | Transfer of work from one agent to another via Orchestrator | routing (for the transfer act), delegation, dispatch, hand-off |
+| handoff payload | The `_notes.handoff_payload` object written by Orchestrator via `update_notes` MCP tool before routing to a specialist | routing context, task context |
+| evidence bundle | Anchor's structured proof-of-work document (`agent-docs/anchor-evidence-*.md`) | proof, verification report |
+| gate | A supervision checkpoint requiring approval before pipeline advances (`supervision_gates.*`) | checkpoint, approval point |
+| HARD STOP | Absolute refusal to proceed — security violation, out-of-scope request, or rogue state edit | halt, block, refuse |
+| skill | A reusable knowledge pack in `.github/skills/{category}/{name}/SKILL.md` | SKILL (when referring to the concept, not the filename) |
+| prompt | A reusable prompt file in `.github/prompts/*.prompt.md` | skill (when referring to prompt files — prompts are not skills) |
+| onboarding prompt | The project bootstrap prompt at `.github/prompts/onboarding.prompt.md` | onboarding skill |
+
+## Pipeline Modes
+
+| Term | Definition |
+|------|------------|
+| supervised | All gates require manual user approval. Default mode. |
+| assisted | Manual gates with AI guidance hints. Auto-routing between stages. |
+| autopilot | All gates auto-satisfied except `intent_approved`. Fully hands-free after intent approval. |
+
+## Result Statuses
+
+### MCP `notify_orchestrator` — `result_status` parameter
+
+| Value | Meaning | Used By |
+|-------|---------|---------|
+| `complete` | Standard stage completion | All agents |
+| `phase_complete` | Multi-phase loop — implement stays in implement for next phase | Implement agent |
+| `recovered` | Recovery after guard failure | Orchestrator (debug flow) |
+
+### Agent-Specific Result Fields
+
+| Agent | Field | Possible Values | Meaning |
+|-------|-------|-----------------|---------|
+| Tester | `tester_result.status` | `passed`, `failed` | All tests pass / any test fails |
+| Code Reviewer | `Verdict` | `approved`, `revision-requested` | Code meets standards / needs changes |
+| All agents (artefact YAML header) | `approval` | `approved`, `pending`, `revision-requested` | Artefact acceptance status |
+
+### Orchestrator Artefact Validation Guards
+
+| Guard | Checks |
+|-------|--------|
+| `artefact_exists` | File at `artefact_path` exists on disk |
+| `artefact_approved` | YAML header `approval:` field is `approved` |
+| `all_phases_done` | All implementation phases complete |
+
+## File Naming Conventions
+
+| Pattern | Example | Usage |
+|---------|---------|-------|
+| Agent file | `frontend-developer.agent.md` | Lowercase kebab-case matching `name` frontmatter field |
+| Skill file | `.github/skills/{category}/{name}/SKILL.md` | Category folder + name folder + SKILL.md |
+| Plan file | `.github/plans/{feature-slug}.md` | Feature slug from chain_id |
+| Evidence file | `agent-docs/anchor-evidence-{feature}.md` | Per-feature evidence bundle |
+| Artefact registry | `agent-docs/ARTIFACTS.md` | Single registry for all pipeline artefacts |
+| Pipeline state | `.github/pipeline-state.json` | Live pipeline state — written ONLY by MCP tools |
+
+## Pipeline State Field Ownership
+
+All writes to `pipeline-state.json` go through MCP tools. Only `stages[*].status`, `stages[*].artefact`, `stages[*].completed_at`, and `blocked_by` may be set via `editFiles`.
+
+| Field | Writer | Tool |
+|-------|--------|------|
+| `current_stage` | Pipeline runner | `notify_orchestrator` |
+| `supervision_gates[*]` | Orchestrator | `satisfy_gate` |
+| `pipeline_mode` | Orchestrator | `set_pipeline_mode` |
+| `_notes.*` | Orchestrator / agents | `update_notes` |
+| `project`, `feature`, `type` | Orchestrator | `pipeline_init` / `pipeline_reset` |
+
+## Common Conflations to Avoid
+
+| Wrong | Correct | Why |
+|-------|---------|-----|
+| "Phase 3 of the pipeline" | "The implement stage" | Phases are within a Plan; stages are pipeline-level |
+| "The artifact registry" | "The artefact registry" | British spelling is canonical (matches all field names) |
+| "Run the onboarding skill" | "Run the onboarding prompt" | `.prompt.md` files are prompts, not skills |
+| "Route to the agent" | "Hand off to the agent" | Routing is Orchestrator's internal logic; handoff is the transfer act |
+| `[Stage/Phase N]` | `[Phase N]` (within Plan) or `[Stage: implement]` (pipeline-level) | Don't conflate the two with a slash |
+
+---
+
+## Toolchain Terms
+
+caddis-the-product, as opposed to the agent pipeline above. These are the words caddis invented
+out of ordinary English, which is exactly why they need defining: a reader who guesses from the
+plain word gets them wrong. Usage counts were measured across 444 markdown files on 2026-08-29.
+
+| Canonical Term | Definition | DO NOT USE |
+|---|---|---|
+| pool | The single source of every shipped resource, living in `.github/` (skills, agents, commands, prompts). Everything a user installs is EXPORTED from the pool; nothing is authored in a bundle. Versioned independently of the CLI, and bumped only by `caddis-push` — never by hand. *(222 uses)* | bundle (for the source), library |
+| bundle | One EXPORTED copy of the pool, shaped for a single target — `dist/runtime-resources/<target>/`. A bundle is generated output; editing one is always a mistake. | pool (for a built copy) |
+| export target | A named consumer in `.github/runtime-targets.json` — claude, antigravity, antigravity-plugin, codex, copilot, plus `-extras` variants. Each takes a different subset and layout from the same pool. | platform, host (for a target) |
+| mirror | The public repo `saajunaid/caddis-plugin`, refreshed by `caddis-push`. The SOURCE repo is private, so the mirror is what any other machine can actually reach. | upstream, remote |
+| relay | `.caddis/relay.md` — the durable resume doc, rewritten by `/caddis:handoff` and injected at SessionStart. Machine-local and gitignored. Only changes when someone runs a handoff, so it is stale between them by design. *(168 uses)* | handoff doc, session notes |
+| session state | `.caddis/session-state.md` — auto-captured by the `Stop` hook at the end of EVERY turn. Distinct from the relay: current without anyone deciding to make it current, and it holds no agreed next step. | relay (they are different files with different guarantees) |
+| drift | A gap between what a consumer HAS installed and what the pool currently ships. `caddis status` reports it per agent. Not code drift, not schema drift. *(160 uses)* | staleness, lag |
+| live-fire | Driving a real binary end to end rather than asserting against a manifest. Coined because three defects in one month passed every test and still gave a human a broken install: the tests asked "does the export match the manifest", never "would this work". An export target is not trusted until it has been live-fired once. | smoke test, integration test, manual test |
+| parking-lot | `.caddis/parking-lot/` — the ONE register of future work. It exists because future work previously scattered to nine places and no session could answer "what is left". Items carry `severity` and `status`; the backlog IS the plan when no plan is active. *(41 uses)* | backlog file, TODO list, icebox |
+| model lane | A named provider route reached by its own binary — `claude-oss`, `claude-glm`, `claude-deepseek` — all speaking the Anthropic protocol. A lane is a route, not a model. | provider, backend, endpoint |
+| core / extras | The two shipping tiers. Core is an EXPLICIT allowlist in `.github/runtime-targets.json`; anything not named there lands in extras. A skill defaults to extras, so placement is a decision, never an accident. | tier 1 / tier 2, full / lite |
+| harness | The agent runtime that loads caddis — Claude Code, agy, Codex, Copilot. caddis is agent-agnostic; "the harness" without a name means whichever one is running. *(135 uses)* | client, IDE, platform |
+
+## Flagged ambiguities
+
+Named rather than resolved. Pretending the vocabulary is clean is how a glossary starts lying.
+
+- **`gate` is overloaded, badly.** Core Terms defines it as a supervision checkpoint requiring
+  approval. That is one of at least twelve senses in live use: *exit gate* (20), *quality gate*
+  (9), *evidence gate* (5), *decision gate* (3), plus pre-publish, handover and privacy gates —
+  none of which involve pipeline supervision. The word appears 1019 times across 168 files.
+  **Prefer the full two-word term everywhere**; a bare "gate" is ambiguous and the reader cannot
+  tell which one you meant.
+
+- **`artefact` vs `artifact`.** Core Terms makes `artefact` canonical, and for pipeline outputs it
+  is. But the toolchain's own code says `artifact_root` and "artifact dir" (17 uses in
+  `scripts/setup_project_ai.py` alone), and those are API names that cannot be respelled without
+  a breaking change. So: **artefact** in pipeline prose and field names; **artifact dir /
+  `artifact_root`** when naming the `.caddis/` directory mechanism. Do not "fix" one into the other.
+
+- **`skill` means two things across harnesses.** In the pool it is
+  `.github/skills/<category>/<name>/SKILL.md`. But agy CONVERTS commands into skills at install
+  time, so `/caddis:catchup` ships as a command and arrives as an agy skill. A skill count that
+  disagrees between two agents is usually this, not a bug.

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.88",
+  "version": "1.3.91",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/scripts/caddis_glossary.py

@@ -0,0 +1,268 @@
+"""caddis_glossary — propose the words a project INVENTED, so they can be defined once.
+
+WHY. Every project coins vocabulary out of ordinary English, and those are the worst words in
+the codebase: a reader who guesses from the plain word gets them wrong and never knows. caddis
+itself coined `pool`, `relay`, `drift`, `parking-lot`, `live-fire` — and its own glossary went
+five and a half months without mentioning any of them, because nothing measured the gap.
+
+WHAT THIS DOES AND DOES NOT DO. It PROPOSES candidates by measurement. It never writes a
+definition, because a definition is domain knowledge that only a person or a model reading the
+code can supply. A file of correct words with empty meanings is worse than no file: it looks
+authoritative and teaches nothing. `/caddis:glossary` is the half that writes the meanings.
+
+    python caddis_glossary.py                  # propose candidates, ranked
+    python caddis_glossary.py --check          # exit 1 if a proposed term has no entry
+    python caddis_glossary.py --scaffold       # create the file if it is missing
+
+HOW A CANDIDATE IS CHOSEN. Frequency alone is useless — "the file" beats every real term. A
+word is a candidate when it is COMMON IN THIS REPO but is not ordinary technical English. The
+stop-list below is the load-bearing part, and it is deliberately generous: a false positive
+costs a human three seconds to ignore, while a false negative leaves a coined word undefined
+forever, which is the failure being fixed.
+
+ACCURACY, MEASURED. On a normal application repo it is good: run against `docket` it proposed
+`board`, `lane`, `card`, `gate` — that project's actual coined vocabulary, top of the list. On a
+HARNESS repo full of documentation ABOUT agents it is noisier, because words like `protocol` and
+`intent` are both ordinary English and genuinely overloaded here. It is a suggester, not an
+oracle; a human or the model decides what earns an entry.
+
+Stdlib only, cross-platform, and it never raises on a bad file — it is run by a command and by
+a gate, and a traceback from either is worse than a missing suggestion.
+"""
+from __future__ import annotations
+
+import argparse
+import collections
+import os
+import re
+import sys
+
+# ── what a project's own vocabulary lives in ────────────────────────────────────────────
+DOC_GLOBS = (".md",)
+SKIP_DIRS = {
+    ".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__",
+    ".mypy_cache", ".pytest_cache", "vendor", "site-packages", ".next", "target",
+    # Vendored and reference material is someone ELSE'S vocabulary. Without these, caddis's
+    # own run proposed `aws4` (33 files) and `mxgraph` (11) out of bundled AWS and draw-io
+    # reference docs — words no caddis reader will ever meet.
+    "references", "assets", "fixtures", ".archive", "archive", "examples", "sample",
+    "samples", "third_party", "vendored", "node_modules", "bundles", "runtime-resources",
+}
+
+# Ordinary technical English. A word here is never proposed, however often it appears.
+# Longer than it looks necessary on purpose: the cost of a false positive is a human ignoring
+# one line; the cost of a false negative is a coined word nobody ever defines.
+COMMON = {
+    # english scaffolding
+    "the", "and", "for", "with", "that", "this", "from", "into", "than", "then", "when",
+    "where", "which", "what", "who", "why", "how", "not", "but", "all", "any", "each",
+    "one", "two", "only", "also", "more", "most", "less", "some", "such", "same", "other",
+    "its", "it's", "you", "your", "our", "their", "they", "them", "has", "have", "had",
+    "was", "were", "been", "being", "are", "can", "will", "would", "should", "must", "may",
+    "does", "did", "done", "doing", "use", "used", "using", "make", "made", "get", "got",
+    "see", "read", "write", "run", "runs", "running", "ran", "set", "put", "take", "give",
+    "new", "old", "first", "last", "next", "now", "here", "there", "before", "after",
+    "over", "under", "out", "off", "own", "per", "via", "yes", "no", "if", "in", "on", "of",
+    "to", "at", "by", "as", "is", "be", "or", "so", "up", "do", "an", "a",
+    # ordinary software vocabulary — predictable from the word itself
+    "file", "files", "path", "paths", "dir", "directory", "folder", "code", "line", "lines",
+    "test", "tests", "testing", "error", "errors", "bug", "fix", "fixed", "build", "built",
+    "commit", "commits", "branch", "merge", "push", "pull", "repo", "repository", "git",
+    "api", "cli", "url", "http", "https", "json", "yaml", "toml", "html", "css", "sql",
+    "user", "users", "name", "names", "value", "values", "key", "keys", "type", "types",
+    "list", "lists", "table", "tables", "row", "rows", "column", "field", "fields",
+    "function", "method", "class", "module", "package", "library", "script", "scripts",
+    "server", "client", "request", "response", "data", "input", "output", "config",
+    "version", "release", "install", "update", "delete", "create", "add", "remove",
+    "return", "returns", "call", "calls", "check", "checks", "log", "logs", "note", "notes",
+    "step", "steps", "case", "cases", "example", "default", "option", "options", "flag",
+    "flags", "command", "commands", "tool", "tools", "agent", "agents", "model", "models",
+    "session", "sessions", "context", "prompt", "prompts", "token", "tokens", "cache",
+    "state", "status", "result", "results", "change", "changes", "work", "works", "time",
+    "does", "doc", "docs", "document", "section", "page", "text", "content", "format",
+    "project", "projects", "team", "user", "system", "service", "process", "task", "tasks",
+    "issue", "issues", "problem", "solution", "reason", "cause", "point", "part", "way",
+    "thing", "things", "need", "needs", "want", "know", "like", "just", "even", "still",
+    "never", "always", "every", "both", "because", "while", "since", "about", "against",
+    # added after the first real run proposed all of these — ordinary in any codebase
+    "skill", "skills", "plan", "plans", "phase", "phases", "design", "designs", "review",
+    "reviews", "mode", "modes", "pattern", "patterns", "implementation", "reference",
+    "description", "descriptions", "workflow", "workflows", "feature", "features",
+    "component", "components", "interface", "structure", "approach", "detail", "details",
+    "requirement", "requirements", "specification", "architecture", "instructions",
+    "guidelines", "standard", "standards", "best", "practice", "practices", "overview",
+    "summary", "report", "reports", "action", "actions", "level", "levels", "order",
+    "number", "count", "size", "start", "stop", "begin", "end", "open", "close", "load",
+    "save", "store", "fetch", "send", "receive", "handle", "handles", "support", "supports",
+    "references", "security", "scope", "verification", "react", "python", "typescript",
+}
+
+_WORD = re.compile(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*", re.I)
+
+# A term must appear at least this often, in at least this many files, to be proposed.
+# One mention is a passing usage; a coined term earns its definition by recurring.
+MIN_USES = 12
+MIN_FILES = 3
+MAX_SUGGESTIONS = 25
+# A coined term is specific, so in a LARGE corpus it shows up in a minority of files. Measured:
+# `description` appeared in 2112 of ~2500 caddis docs and outranked every real term.
+#
+# But this rule INVERTS on a small repo. Applied unconditionally it deleted docket's four best
+# candidates — `board`, `lane`, `card`, `docket` — because in a 50-file repo the core vocabulary
+# genuinely is in most files. So it only engages once there are enough files for "share" to
+# mean anything.
+MAX_FILE_SHARE = 0.25
+SHARE_RULE_MIN_CORPUS = 200
+
+
+def _doc_files(root: str) -> list[str]:
+    found = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".venv")]
+        for n in filenames:
+            if n.endswith(DOC_GLOBS):
+                found.append(os.path.join(dirpath, n))
+    return found
+
+
+def glossary_path(root: str) -> str:
+    """`.caddis/kb/GLOSSARY.md` — beside the KB, which is where reference docs live."""
+    return os.path.join(root, ".caddis", "kb", "GLOSSARY.md")
+
+
+def defined_terms(path: str) -> set[str]:
+    """Canonical terms are the first cell of each markdown table row."""
+    if not os.path.isfile(path):
+        return set()
+    terms = set()
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if not line.startswith("|"):
+                    continue
+                cells = [c.strip() for c in line.strip().strip("|").split("|")]
+                if len(cells) < 2 or not cells[0] or set(cells[0]) <= {"-", ":", " "}:
+                    continue
+                head = cells[0].strip("`*").lower()
+                if head in {"term", "canonical term", "word"}:
+                    continue
+                terms.add(head)
+    except OSError:
+        return set()
+    return terms
+
+
+def propose(root: str) -> list[tuple[str, int, int]]:
+    """Return [(term, uses, files)] — words this repo says often that plain English does not."""
+    uses: collections.Counter = collections.Counter()
+    files: dict[str, set] = collections.defaultdict(set)
+    for f in _doc_files(root):
+        try:
+            text = open(f, encoding="utf-8", errors="replace").read().lower()
+        except OSError:
+            continue
+        # Strip fenced code and inline code: identifiers are not project vocabulary.
+        text = re.sub(r"```.*?```", " ", text, flags=re.S)
+        text = re.sub(r"`[^`]*`", " ", text)
+        for w in _WORD.findall(text):
+            if len(w) < 4 or w in COMMON:
+                continue
+            uses[w] += 1
+            files[w].add(f)
+    total = max(1, len(_doc_files(root)))
+    out = [
+        (w, n, len(files[w]))
+        for w, n in uses.items()
+        if n >= MIN_USES
+        and len(files[w]) >= MIN_FILES
+        and (total < SHARE_RULE_MIN_CORPUS or (len(files[w]) / total) <= MAX_FILE_SHARE)
+    ]
+    out.sort(key=lambda r: (-r[1], r[0]))
+    return out
+
+
+TEMPLATE = """# Glossary
+
+The words this project invented out of ordinary English, defined once.
+
+**Admission test:** a term belongs here when its meaning in this project is *distinct enough
+from its ordinary technical sense that a newcomer would misread it*. `commit` does not belong.
+A word this team uses in its own way does.
+
+Proposed by `caddis_glossary.py`, which measures which words this repo says often that plain
+English does not. It cannot write the definitions — run `/caddis:glossary` and the model will
+draft them from the actual code, or write them yourself.
+
+| Term | Definition | DO NOT USE |
+|---|---|---|
+| _example_ | Replace this row. A definition should say what the word means HERE, and why the ordinary reading is wrong. | the synonyms that cause confusion |
+
+## Flagged ambiguities
+
+Name the words that are still overloaded rather than pretending the vocabulary is clean. A
+glossary that hides its own dirt starts lying. Delete this section only when there is genuinely
+nothing to flag.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--root", default=os.getcwd())
+    ap.add_argument("--check", action="store_true",
+                    help="exit 1 if a proposed term has no entry")
+    ap.add_argument("--scaffold", action="store_true",
+                    help="write the glossary template if it does not exist")
+    args = ap.parse_args(argv)
+
+    root = os.path.abspath(args.root)
+    path = glossary_path(root)
+
+    if args.scaffold:
+        if os.path.isfile(path):
+            print("[glossary] present — kept: %s" % os.path.relpath(path, root))
+        else:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w", encoding="utf-8", newline="\n") as fh:
+                fh.write(TEMPLATE)
+            print("[glossary] wrote %s" % os.path.relpath(path, root))
+        return 0
+
+    candidates = propose(root)
+    defined = defined_terms(path)
+    missing = [(w, n, f) for w, n, f in candidates if w not in defined]
+
+    if args.check:
+        # Advisory by design. A project may legitimately decide a frequent word needs no
+        # definition, and a gate that cannot be satisfied gets bypassed rather than obeyed.
+        if not os.path.isfile(path):
+            print("[glossary] no %s — run with --scaffold" % os.path.relpath(path, root))
+            return 0
+        if missing:
+            print("[glossary] %d frequent term(s) with no entry:" % len(missing))
+            for w, n, f in missing[:MAX_SUGGESTIONS]:
+                print("    %-24s %4d uses in %d files" % (w, n, f))
+            print("  Define them, or leave them — this is advisory. `/caddis:glossary` drafts them.")
+            return 1
+        print("[glossary] every frequent term is defined (%d entries)" % len(defined))
+        return 0
+
+    if not candidates:
+        print("[glossary] no candidates — too few docs, or nothing recurs enough.")
+        return 0
+    print("Candidate vocabulary for %s" % root)
+    print("  (>= %d uses across >= %d files, ordinary English excluded)\n" % (MIN_USES, MIN_FILES))
+    print("  %-26s %6s %6s  %s" % ("TERM", "USES", "FILES", "DEFINED?"))
+    for w, n, f in candidates[:MAX_SUGGESTIONS]:
+        print("  %-26s %6d %6d  %s" % (w, n, f, "yes" if w in defined else "-- no --"))
+    if missing:
+        print("\n  %d undefined. Run `/caddis:glossary` to draft definitions from the code."
+              % len(missing))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # pragma: no cover — a suggester must never break a caller
+        print("[glossary] skipped: %s" % exc)
+        sys.exit(0)

package/bundles/antigravity-plugin/scripts/setup_project_ai.py

@@ -902,6 +902,39 @@ memory.jsonl
 """
 
 
+GLOSSARY_TEMPLATE = """\
+# Glossary
+
+The words this project invented out of ordinary English, defined once.
+
+**Admission test:** a term belongs here when its meaning in this project is *distinct
+enough from its ordinary technical sense that a newcomer would misread it*. `commit` does
+not belong. A word this team uses in its own way does.
+
+To find candidates, run the measurer. It ranks the words this repo says often that plain
+English does not, and marks which already have an entry:
+
+    python <caddis>/scripts/caddis_glossary.py
+
+It cannot write the definitions - only a person or the model reading the code can say what
+a coined word MEANS here. Run `/caddis:glossary` to have them drafted, or write them.
+
+This file is for YOUR project's vocabulary. caddis's own coined words - pool, relay, drift,
+export target - are defined separately in `CADDIS-GLOSSARY.md` at the plugin root, which also
+serves as a worked example of what a good entry looks like. Do not copy those terms in here.
+
+| Term | Definition | DO NOT USE |
+|---|---|---|
+| _example_ | Replace this row. Say what the word means HERE, and why the ordinary reading is wrong. | the synonyms that cause confusion |
+
+## Flagged ambiguities
+
+Name the words that are still overloaded rather than pretending the vocabulary is clean. A
+glossary that hides its own dirt starts lying. Delete this section only when there is
+genuinely nothing to flag.
+"""
+
+
 ARTIFACT_CONFIG_EXAMPLE = """\
 # caddis per-repo configuration — a documented template.
 #
@@ -1198,6 +1231,20 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
             em.parent.mkdir(parents=True, exist_ok=True)
             em.write_text(ENVIRONMENT_MAP_TEMPLATE, encoding="utf-8")
         notes.append(f"scaffold: wrote {label}/kb/environment-map.md")
+    # A vocabulary stub, seeded but never auto-filled. `caddis_glossary.py` can measure
+    # which words a repo coined, but only a person or the model reading the code can say
+    # what they MEAN - and a file of correct words with empty meanings looks authoritative
+    # while teaching nothing. The stub carries the admission test so whoever fills it in
+    # knows what qualifies.
+    gl = root / "kb" / "GLOSSARY.md"
+    if gl.exists():
+        notes.append(f"scaffold: {label}/kb/GLOSSARY.md present - kept")
+    else:
+        if not dry:
+            gl.parent.mkdir(parents=True, exist_ok=True)
+            gl.write_text(GLOSSARY_TEMPLATE, encoding="utf-8")
+        notes.append(f"scaffold: wrote {label}/kb/GLOSSARY.md (run /caddis:glossary to fill it)")
+
     gi = root / ".gitignore"
     if gi.exists():
         # APPEND what is missing rather than keeping the file frozen. The old behaviour was

package/bundles/antigravity-plugin/skills/_registry.md

@@ -76,6 +76,7 @@
 | Feature Plan | `feature-plan/` | Create a phased, TDD-structured implementation plan that acts as the durable spine for multi-session work |
 | Gate Preflight | `gate-preflight/` | Deterministic headless preflight — validates a plan against the actual codebase, self-contained (never depends on a skill activating) |
 | Gate Review | `gate-review/` | Deterministic headless code review — adversarial diff review, self-contained (never depends on a skill activating) |
+| Glossary | `glossary/` | Define the words this project invented, in one place — .caddis/kb/GLOSSARY.md |
 | Handoff | `handoff/` | End-of-session handoff — capture exact state so the next session resumes with zero re-discovery |
 | Implement | `implement/` | Headless plan executor — implement an approved plan phase-by-phase on the current feature branch, TDD-first, committing per phase |
 | Kb | `kb/` | Rebuild the KB index (.caddis/kb/DOC-MAP.md) — create it if missing, index un-indexed notes, report dangling links |

package/bundles/antigravity-plugin/skills/glossary/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: glossary
+description: Define the words this project invented, in one place — .caddis/kb/GLOSSARY.md
+---
+
+# /glossary — define what this project coined
+
+Every project invents vocabulary out of ordinary English, and those are the most dangerous words
+in the codebase: a reader who guesses from the plain word gets it wrong and never finds out.
+caddis itself coined `pool`, `relay`, `drift`, `parking-lot` — and its own glossary went five and
+a half months without mentioning any of them, because nothing measured the gap.
+
+Your job is the half a script cannot do: **write what the words mean here.**
+
+## Step 1 — get the candidates
+
+```
+python <caddis-plugin-root>/scripts/caddis_glossary.py
+```
+
+It ranks the words this repo says often that plain English does not, and marks which already
+have an entry. `--scaffold` creates `.caddis/kb/GLOSSARY.md` if it is missing.
+
+It is a **suggester, not an oracle**. It is good on an application repo — run against a kanban
+tool it proposed `board`, `lane`, `card` at the top — and noisier on a repo whose docs are ABOUT
+software, where words like `protocol` are both ordinary and genuinely overloaded. Expect to
+discard some suggestions. That is the intended cost: a false positive wastes three seconds, a
+missing term stays undefined forever.
+
+If the script is not available, read the repo yourself and look for the same thing.
+
+## Step 2 — apply the admission test to each candidate
+
+A term belongs **only if its meaning here is distinct enough from its ordinary technical sense
+that a newcomer would misread it.**
+
+- `commit`, `branch`, `endpoint` — **no**. The ordinary meaning is correct.
+- A word the team bent to its own purpose — **yes**. That is the whole point.
+
+Discard the rest without comment. A padded glossary is skimmed and then ignored.
+
+## Step 3 — write each definition from the CODE, not from the word
+
+Read where the term is actually used before defining it. A definition that restates the word
+teaches nothing, and a wrong one is worse than a gap because it is believed.
+
+Each row gets three things:
+
+| Column | What goes in it |
+|---|---|
+| **Term** | The canonical spelling. Pick one and stop using the others. |
+| **Definition** | What it means HERE, and — where it helps — why the ordinary reading misleads. Say the thing a newcomer would get wrong. |
+| **DO NOT USE** | The synonyms actually causing confusion in this repo. Leave blank rather than inventing some. |
+
+**A worked example ships with caddis.** `CADDIS-GLOSSARY.md` at the plugin root defines caddis's
+own coined vocabulary the same way — read a few entries before writing yours. It is caddis's
+words, not this project's: never copy its terms into a project glossary.
+
+Good: *"pool — the single source of every shipped resource, in `.github/`. Everything installed is EXPORTED from it; nothing is authored in a bundle."*
+
+Bad: *"pool — a pool of resources."*
+
+## Step 4 — flag what is still dirty
+
+Fill the **Flagged ambiguities** section with the words that remain overloaded. This is the part
+people skip and it is the most valuable part, because a glossary that hides its own dirt starts
+lying.
+
+Look for a term used in several incompatible senses. In caddis, `gate` is defined as one thing
+and used as at least twelve — exit gate, quality gate, evidence gate, privacy gate. The honest
+move is to name the overload and recommend the two-word form, not to pick a winner by fiat.
+
+Also flag a term whose canonical spelling the code itself contradicts. Do not "fix" either side
+when both are load-bearing; document the split and where each applies.
+
+## Step 5 — report
+
+Say how many terms you added, how many candidates you rejected and roughly why, and what you
+flagged as ambiguous. If you found nothing worth adding, say that — it is a real answer, and
+better than padding the file to look productive.
+
+## Keeping it honest
+
+Re-run `caddis_glossary.py --check` later. It exits 1 when a frequent term has no entry. It is
+**advisory**: a project may reasonably decide a common word needs no definition, and a gate that
+cannot be satisfied gets bypassed rather than obeyed.
+
+Do not enforce the DO-NOT-USE column by grepping. Most banned synonyms are ordinary English —
+"step", "block", "refuse" — and a check that cries wolf gets deleted, leaving no check at all.

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.88",
+  "poolVersion": "1.3.91",
   "bundles": {
-    "antigravity-plugin": "1.3.88",
+    "antigravity-plugin": "1.3.91",
     "antigravity-plugin-extras": "1.3.28",
     "codex": "unknown"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",