mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

langgen: generate LANGUAGE.md from brain glossary at session start (Phase 2 — GATED) #40

New Issue
Open
opened 2026-06-12 20:39:40 +00:00 by mathias · 0 comments
mathias commented 2026-06-12 20:39:40 +00:00
Owner
Copy Link
Copy Source

Context

Phase 2 of the ubiquitous-language system. langgen generates LANGUAGE.md from the brain glossary wing, replacing the hand-written pilot file (mathias/tapir#18). Pull-based: runs at session start / bootstrap, never push/webhook. LANGUAGE.md is a derived file per the canonical-vs-derived context rule — never hand-edited after this lands.

GATED — do not start until: the brain glossary has changed ≥2 times after Phase 0, proving regeneration is a real need. Check with the human before picking this up.

Spec

Go binary in tools/langgen/, ~150 LOC target.

langgen --project tapir --glossary <path-to-brain-repo>/wiki/glossary --out LANGUAGE.md

Behavior:

  1. Read glossary entries as local files (brain syncs via Syncthing/git — no network dependency, must work offline for Crush sessions with no cloud egress).
  2. Select entries where status: active AND (scope: homelab-core OR scope: project:<project>).
  3. Collision = exit 1 with a clear message if the same term exists in both selected scopes. No merge logic, no precedence.
  4. Emit LANGUAGE.md: header stamp generated: <date> from glossary@<git-sha>, term table (term / agent definition / never-say from aliases_rejected), caveman rubric footer (rubric text lives in tools/langgen/rubric.md, embedded via go:embed).
  5. Warn (stderr) above 20 terms — F1 glossary-bloat canary. Hard token budget ~600 tokens for output.

Acceptance criteria

  • Binary builds with stdlib + a YAML frontmatter parser only
  • Collision test, scope-filter test, status-filter test, bloat-warning test
  • Sha stamp verified against glossary repo HEAD
  • Wired into hyperguild session bootstrap (regenerate on session start)
  • tapir's hand-written LANGUAGE.md replaced by generated output in a follow-up PR, diff reviewed by human

Out of scope

Vocabulary drift detection (ai-sessions Phase 4), ntfy integration (Phase 3), any push/webhook mechanism.

## Context Phase 2 of the ubiquitous-language system. `langgen` generates `LANGUAGE.md` from the brain glossary wing, replacing the hand-written pilot file (mathias/tapir#18). Pull-based: runs at session start / bootstrap, never push/webhook. LANGUAGE.md is a derived file per the canonical-vs-derived context rule — never hand-edited after this lands. **GATED — do not start until:** the brain glossary has changed ≥2 times after Phase 0, proving regeneration is a real need. Check with the human before picking this up. ## Spec Go binary in `tools/langgen/`, ~150 LOC target. ``` langgen --project tapir --glossary <path-to-brain-repo>/wiki/glossary --out LANGUAGE.md ``` Behavior: 1. Read glossary entries as local files (brain syncs via Syncthing/git — no network dependency, must work offline for Crush sessions with no cloud egress). 2. Select entries where `status: active` AND (`scope: homelab-core` OR `scope: project:<project>`). 3. **Collision = exit 1** with a clear message if the same `term` exists in both selected scopes. No merge logic, no precedence. 4. Emit LANGUAGE.md: header stamp `generated: <date> from glossary@<git-sha>`, term table (term / agent definition / never-say from aliases_rejected), caveman rubric footer (rubric text lives in `tools/langgen/rubric.md`, embedded via go:embed). 5. Warn (stderr) above 20 terms — F1 glossary-bloat canary. Hard token budget ~600 tokens for output. ## Acceptance criteria - [ ] Binary builds with stdlib + a YAML frontmatter parser only - [ ] Collision test, scope-filter test, status-filter test, bloat-warning test - [ ] Sha stamp verified against glossary repo HEAD - [ ] Wired into hyperguild session bootstrap (regenerate on session start) - [ ] tapir's hand-written LANGUAGE.md replaced by generated output in a follow-up PR, diff reviewed by human ## Out of scope Vocabulary drift detection (ai-sessions Phase 4), ntfy integration (Phase 3), any push/webhook mechanism.
mathias added the risk/lowsize/stype/feat labels 2026-08-27 05:25:41 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels risk/low size/s type/feat
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#40