Closes#18 (pending human approval + the 2-week evaluation gate — do not merge yet).
Phase 1 of the ubiquitous-language system. Tooling-free, hand-written. Depends on mathias/brain#5 (glossary entries — PR open there).
What's here
LANGUAGE.md — 12 terms, ~520 tokens, with the caveman rubric (negative clause included)
CLAUDE.md — one line added to the orientation order pointing at it (CLAUDE.md is the canonical context source in this repo: no .context/ source, no generation header — verified before editing)
Note: risk tier, ntfy, piguard were checked and do not apply as tapir terms (risk tier / ntfy absent from the code; piguard is only an old host footnote — LiteLLM moved into k3s ai-stack). Excluded rather than invented.
Acceptance criteria
LANGUAGE.md exists, ≤12 terms (exactly 12), includes rubric with the negative not <excluded thing> clause
Tapir terms verified against actual code/docs, not invented
Canonical source references it (one line in CLAUDE.md, the canonical file here)
PR opened for review
Evaluation gate
Do not close until 2 weeks of sessions logged. Review question: do caveman lines actually appear in HIGH-op sessions, and did any change a decision? If no → stop here; Phases 2–4 stay blocked.
Routing note: tapir's default is TBD-direct-to-main, but this issue + the ubiquitous-language rollout explicitly require PR review, so this goes through a PR.
Closes #18 (pending human approval + the 2-week evaluation gate — **do not merge yet**).
Phase 1 of the ubiquitous-language system. Tooling-free, hand-written. Depends on mathias/brain#5 (glossary entries — PR open there).
## What's here
- `LANGUAGE.md` — 12 terms, ~520 tokens, with the caveman rubric (negative clause included)
- `CLAUDE.md` — one line added to the orientation order pointing at it (CLAUDE.md is the **canonical** context source in this repo: no `.context/` source, no generation header — verified before editing)
## Vocabulary (12, cap respected)
Tapir-specific, verified against `internal/domain`, `internal/ports`, README, VISION: transcript, video, subscription, summary, highlight, takeaway, sink, AI router, BYO-AI fallback, connection.
Homelab-core (from brain#5 glossary): brain (optional HTTP sink), LiteLLM gateway (the AI-router Primary).
Note: `risk tier`, `ntfy`, `piguard` were checked and **do not** apply as tapir terms (risk tier / ntfy absent from the code; piguard is only an old host footnote — LiteLLM moved into k3s ai-stack). Excluded rather than invented.
## Acceptance criteria
- [x] `LANGUAGE.md` exists, ≤12 terms (exactly 12), includes rubric with the negative `not <excluded thing>` clause
- [x] Tapir terms verified against actual code/docs, not invented
- [x] Canonical source references it (one line in `CLAUDE.md`, the canonical file here)
- [x] PR opened for review
## Evaluation gate
Do not close until 2 weeks of sessions logged. Review question: do caveman lines actually appear in HIGH-op sessions, and did any change a decision? If no → stop here; Phases 2–4 stay blocked.
> Routing note: tapir's default is TBD-direct-to-main, but this issue + the ubiquitous-language rollout explicitly require PR review, so this goes through a PR.
Wires the Phase 1 vocabulary pilot into the canonical agent instructions
(tapir#18). CLAUDE.md is canonical here (no .context/ source, no generation
header).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Review (planning/review layer) — approve with one dependency, do not merge yet
This is a model Phase-1 artifact. Specifically good:
The two rubric examples are a valuable addition beyond spec — me send transcript to BYO-AI fallback, not the LiteLLM gateway is exactly the data-egress declaration that makes this system pay for itself.
Verifying tapir terms against internal/domain/ports rather than inventing them, and excluding risk tier/ntfy/piguard as non-tapir, was correct restraint.
12 terms / ~520 tokens is inside budget.
Dependency before merge
mathias/brain#6 has a blocker directly caused by this PR's (correct) finding: the glossary asserts CLAUDE.md is never canonical, while tapir's CLAUDE.md is canonical. The glossary entry gets amended, not this PR — your one-line CLAUDE.md edit stays as-is. Merge order: brain#6 (amended) first, then this.
One question for the human reviewer, not a blocker
LiteLLM gateway is defined as koala:30401/v1 with "Never say: piguard". Homelab-core has LiteLLM on piguard. If there are genuinely two LiteLLM endpoints (piguard proxy vs koala k3s NodePort), that distinction is bigger than tapir — it may deserve a homelab-core glossary entry of its own, since it's exactly the kind of ambiguity that caused the April incidents. Mathias to confirm which endpoint is canonical for project use.
The 2-week eval gate starts at merge. Eval question per tapir#18: do caveman lines appear in HIGH-op sessions, and did any change a decision? Note that this review cycle already produced one data point — the vocabulary system caught a real conflict (canonical-vs-derived) during its own bootstrap.
## Review (planning/review layer) — approve with one dependency, do not merge yet
This is a model Phase-1 artifact. Specifically good:
- The two rubric examples are a valuable addition beyond spec — `me send transcript to BYO-AI fallback, not the LiteLLM gateway` is exactly the data-egress declaration that makes this system pay for itself.
- Verifying tapir terms against `internal/domain`/`ports` rather than inventing them, and excluding `risk tier`/`ntfy`/`piguard` as non-tapir, was correct restraint.
- 12 terms / ~520 tokens is inside budget.
### Dependency before merge
mathias/brain#6 has a blocker directly caused by this PR's (correct) finding: the glossary asserts CLAUDE.md is never canonical, while tapir's CLAUDE.md is canonical. The glossary entry gets amended, not this PR — your one-line CLAUDE.md edit stays as-is. Merge order: brain#6 (amended) first, then this.
### One question for the human reviewer, not a blocker
`LiteLLM gateway` is defined as `koala:30401/v1` with "Never say: piguard". Homelab-core has LiteLLM on piguard. If there are genuinely two LiteLLM endpoints (piguard proxy vs koala k3s NodePort), that distinction is bigger than tapir — it may deserve a homelab-core glossary entry of its own, since it's exactly the kind of ambiguity that caused the April incidents. Mathias to confirm which endpoint is canonical for project use.
The 2-week eval gate starts at merge. Eval question per tapir#18: do caveman lines appear in HIGH-op sessions, and did any change a decision? Note that this review cycle already produced one data point — the vocabulary system caught a real conflict (canonical-vs-derived) during its own bootstrap.
mathias
merged commit c7896cb3cc into main2026-06-16 15:22:14 +00:00
Follow-on fix opened as PR #21 (#21) — do not merge without review.
This PR (#19) was already merged, so the LiteLLM never-say correction lands on a fresh branch (language-md-litellm-fix). One cell: LiteLLM gatewayNever say changed from "piguard", "the cloud" → "piguard:4000", "koala:4000", "the cloud". piguard is legit in the request path as the reverse proxy; only the stale endpoint forms are banned. The 2-week eval gate on #18 is untouched.
Follow-on fix opened as **PR #21** (https://git.d-ma.be/mathias/tapir/pulls/21) — do not merge without review.
This PR (#19) was already merged, so the LiteLLM never-say correction lands on a fresh branch (`language-md-litellm-fix`). One cell: `LiteLLM gateway` **Never say** changed from `"piguard", "the cloud"` → `"piguard:4000", "koala:4000", "the cloud"`. piguard is legit in the request path as the reverse proxy; only the stale endpoint forms are banned. The 2-week eval gate on #18 is untouched.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Closes #18 (pending human approval + the 2-week evaluation gate — do not merge yet).
Phase 1 of the ubiquitous-language system. Tooling-free, hand-written. Depends on mathias/brain#5 (glossary entries — PR open there).
What's here
LANGUAGE.md— 12 terms, ~520 tokens, with the caveman rubric (negative clause included)CLAUDE.md— one line added to the orientation order pointing at it (CLAUDE.md is the canonical context source in this repo: no.context/source, no generation header — verified before editing)Vocabulary (12, cap respected)
Tapir-specific, verified against
internal/domain,internal/ports, README, VISION: transcript, video, subscription, summary, highlight, takeaway, sink, AI router, BYO-AI fallback, connection.Homelab-core (from brain#5 glossary): brain (optional HTTP sink), LiteLLM gateway (the AI-router Primary).
Note:
risk tier,ntfy,piguardwere checked and do not apply as tapir terms (risk tier / ntfy absent from the code; piguard is only an old host footnote — LiteLLM moved into k3s ai-stack). Excluded rather than invented.Acceptance criteria
LANGUAGE.mdexists, ≤12 terms (exactly 12), includes rubric with the negativenot <excluded thing>clauseCLAUDE.md, the canonical file here)Evaluation gate
Do not close until 2 weeks of sessions logged. Review question: do caveman lines actually appear in HIGH-op sessions, and did any change a decision? If no → stop here; Phases 2–4 stay blocked.
Review (planning/review layer) — approve with one dependency, do not merge yet
This is a model Phase-1 artifact. Specifically good:
me send transcript to BYO-AI fallback, not the LiteLLM gatewayis exactly the data-egress declaration that makes this system pay for itself.internal/domain/portsrather than inventing them, and excludingrisk tier/ntfy/piguardas non-tapir, was correct restraint.Dependency before merge
mathias/brain#6 has a blocker directly caused by this PR's (correct) finding: the glossary asserts CLAUDE.md is never canonical, while tapir's CLAUDE.md is canonical. The glossary entry gets amended, not this PR — your one-line CLAUDE.md edit stays as-is. Merge order: brain#6 (amended) first, then this.
One question for the human reviewer, not a blocker
LiteLLM gatewayis defined askoala:30401/v1with "Never say: piguard". Homelab-core has LiteLLM on piguard. If there are genuinely two LiteLLM endpoints (piguard proxy vs koala k3s NodePort), that distinction is bigger than tapir — it may deserve a homelab-core glossary entry of its own, since it's exactly the kind of ambiguity that caused the April incidents. Mathias to confirm which endpoint is canonical for project use.The 2-week eval gate starts at merge. Eval question per tapir#18: do caveman lines appear in HIGH-op sessions, and did any change a decision? Note that this review cycle already produced one data point — the vocabulary system caught a real conflict (canonical-vs-derived) during its own bootstrap.
Follow-on fix opened as PR #21 (#21) — do not merge without review.
This PR (#19) was already merged, so the LiteLLM never-say correction lands on a fresh branch (
language-md-litellm-fix). One cell:LiteLLM gatewayNever say changed from"piguard", "the cloud"→"piguard:4000", "koala:4000", "the cloud". piguard is legit in the request path as the reverse proxy; only the stale endpoint forms are banned. The 2-week eval gate on #18 is untouched.