Pilot of the ubiquitous-language system in one real repo. tapir is the pilot because it has active development (v0.16.0 work) and a clear domain vocabulary. This phase is deliberately tooling-free: a hand-written LANGUAGE.md to validate that caveman declarations against an explicit vocabulary actually help, before we invest in generation tooling (hyperguild langgen).
Depends on: mathias/brain#5 (glossary entries must exist first — tapir's terms derive from them).
Spec
Create LANGUAGE.md in repo root, hand-written, this format:
# Vocabulary (hand-written pilot 2026-06 — will be generated by langgen in Phase 2)
| Term | Means | Never say |
|---|---|---|
| <term> | <agent definition from brain glossary> | <rejected aliases> |
## Caveman rubric
Before any HIGH/CRITICAL operation, output one line:
`caveman: me <verb> <object>, not <excluded thing>`
Valid iff: (1) only vocabulary terms + plain verbs, (2) a stranger could identify
the exact operation, (3) names one thing explicitly NOT being done.
Include homelab-core terms relevant to tapir (e.g. brain as optional sink, piguard/LiteLLM routing) plus tapir-specific terms (e.g. subscription, summary, highlight, takeaway, BYO-AI fallback — verify actual domain terms against the codebase and README).
Hard cap: 12 terms total. Token budget for the whole file: ~600 tokens.
Add one line to CLAUDE.md (or AGENT.md if that is canonical here): "Read LANGUAGE.md. Apply the caveman rubric before destructive operations."
Acceptance criteria
LANGUAGE.md exists, ≤12 terms, includes the rubric with the negative clause (point 3)
Tapir-specific terms verified against actual code/docs, not invented
CLAUDE.md/AGENT.md references it (one line, edit the canonical source per the derived-context rule)
PR opened for review
Evaluation gate (do not close until)
2 weeks of sessions logged. Question to answer at review: do caveman lines actually appear in HIGH-op sessions, and did any of them change a decision? If no → stop here, Phases 2–4 stay blocked.
## Context
Pilot of the ubiquitous-language system in one real repo. tapir is the pilot because it has active development (v0.16.0 work) and a clear domain vocabulary. This phase is deliberately tooling-free: a hand-written `LANGUAGE.md` to validate that caveman declarations against an explicit vocabulary actually help, before we invest in generation tooling (hyperguild langgen).
Depends on: mathias/brain#5 (glossary entries must exist first — tapir's terms derive from them).
## Spec
1. Create `LANGUAGE.md` in repo root, hand-written, this format:
```markdown
# Vocabulary (hand-written pilot 2026-06 — will be generated by langgen in Phase 2)
| Term | Means | Never say |
|---|---|---|
| <term> | <agent definition from brain glossary> | <rejected aliases> |
## Caveman rubric
Before any HIGH/CRITICAL operation, output one line:
`caveman: me <verb> <object>, not <excluded thing>`
Valid iff: (1) only vocabulary terms + plain verbs, (2) a stranger could identify
the exact operation, (3) names one thing explicitly NOT being done.
```
2. Include homelab-core terms relevant to tapir (e.g. `brain` as optional sink, `piguard`/LiteLLM routing) plus tapir-specific terms (e.g. subscription, summary, highlight, takeaway, BYO-AI fallback — verify actual domain terms against the codebase and README).
3. Hard cap: 12 terms total. Token budget for the whole file: ~600 tokens.
4. Add one line to `CLAUDE.md` (or `AGENT.md` if that is canonical here): "Read LANGUAGE.md. Apply the caveman rubric before destructive operations."
## Acceptance criteria
- [ ] `LANGUAGE.md` exists, ≤12 terms, includes the rubric with the negative clause (point 3)
- [ ] Tapir-specific terms verified against actual code/docs, not invented
- [ ] CLAUDE.md/AGENT.md references it (one line, edit the canonical source per the derived-context rule)
- [ ] PR opened for review
## Evaluation gate (do not close until)
2 weeks of sessions logged. Question to answer at review: do caveman lines actually appear in HIGH-op sessions, and did any of them change a decision? If no → stop here, Phases 2–4 stay blocked.
LANGUAGE.md: 12 terms (~520 tokens) + caveman rubric with the not <excluded thing> negative clause. Tapir terms verified against internal/domain/ports/README/VISION; homelab-core terms (brain sink, LiteLLM gateway) derived from brain#5.
risk tier/ntfy/piguard checked and excluded — not real tapir terms (absent from code, or stale host footnote), not invented.
CLAUDE.md (canonical here — no .context/ source, no gen header) gets one orientation line pointing at it. Depends on brain#5 PR #6.
**PR opened — do not merge yet (2-week eval gate):** https://gitea.d-ma.be/mathias/tapir/pulls/19
- `LANGUAGE.md`: 12 terms (~520 tokens) + caveman rubric with the `not <excluded thing>` negative clause. Tapir terms verified against `internal/domain`/`ports`/README/VISION; homelab-core terms (brain sink, LiteLLM gateway) derived from brain#5.
- `risk tier`/`ntfy`/`piguard` checked and excluded — not real tapir terms (absent from code, or stale host footnote), not invented.
- `CLAUDE.md` (canonical here — no `.context/` source, no gen header) gets one orientation line pointing at it. Depends on brain#5 PR #6.
PR #19 merged to main (2026-06-16). Issue intentionally kept open — the merge auto-closed it; reopened per the evaluation gate.
Eval clock starts now: 2 weeks of logged sessions → review ~2026-06-30. Close only after answering: did caveman lines actually appear in HIGH/CRITICAL-op sessions, and did any change a decision? If no → stop here; Phases 2–4 stay blocked.
PR #19 merged to `main` (2026-06-16). **Issue intentionally kept open** — the merge auto-closed it; reopened per the evaluation gate.
Eval clock starts now: 2 weeks of logged sessions → review ~**2026-06-30**. Close only after answering: did caveman lines actually appear in HIGH/CRITICAL-op sessions, and did any change a decision? If no → stop here; Phases 2–4 stay blocked.
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.
Context
Pilot of the ubiquitous-language system in one real repo. tapir is the pilot because it has active development (v0.16.0 work) and a clear domain vocabulary. This phase is deliberately tooling-free: a hand-written
LANGUAGE.mdto validate that caveman declarations against an explicit vocabulary actually help, before we invest in generation tooling (hyperguild langgen).Depends on: mathias/brain#5 (glossary entries must exist first — tapir's terms derive from them).
Spec
LANGUAGE.mdin repo root, hand-written, this format:brainas optional sink,piguard/LiteLLM routing) plus tapir-specific terms (e.g. subscription, summary, highlight, takeaway, BYO-AI fallback — verify actual domain terms against the codebase and README).CLAUDE.md(orAGENT.mdif that is canonical here): "Read LANGUAGE.md. Apply the caveman rubric before destructive operations."Acceptance criteria
LANGUAGE.mdexists, ≤12 terms, includes the rubric with the negative clause (point 3)Evaluation gate (do not close until)
2 weeks of sessions logged. Question to answer at review: do caveman lines actually appear in HIGH-op sessions, and did any of them change a decision? If no → stop here, Phases 2–4 stay blocked.
PR opened — do not merge yet (2-week eval gate): https://gitea.d-ma.be/mathias/tapir/pulls/19
LANGUAGE.md: 12 terms (~520 tokens) + caveman rubric with thenot <excluded thing>negative clause. Tapir terms verified againstinternal/domain/ports/README/VISION; homelab-core terms (brain sink, LiteLLM gateway) derived from brain#5.risk tier/ntfy/piguardchecked and excluded — not real tapir terms (absent from code, or stale host footnote), not invented.CLAUDE.md(canonical here — no.context/source, no gen header) gets one orientation line pointing at it. Depends on brain#5 PR #6.PR #19 merged to
main(2026-06-16). Issue intentionally kept open — the merge auto-closed it; reopened per the evaluation gate.Eval clock starts now: 2 weeks of logged sessions → review ~2026-06-30. Close only after answering: did caveman lines actually appear in HIGH/CRITICAL-op sessions, and did any change a decision? If no → stop here; Phases 2–4 stay blocked.