torben/chemenu
1
1
Fork 0
Code Issues 26 Pull Requests Actions Packages Releases 32 Activity

ENVIRONMENT.md: festhalten, womit dieser Checkout arbeitet (Harness, Skills, MCP-Server, Connectoren, Remotes) #24

New Issue
Closed
opened 2026-08-31 20:39:42 +00:00 by torben · 1 comment
torben commented 2026-08-31 20:39:42 +00:00
Owner
Copy Link
Copy Source

Ausgangslage

USER.md beantwortet, wer die Instanz bedient, SOUL.md, wie sie klingt. Womit sie
arbeitet, beantwortet niemand: welches Harness läuft, welche Skills publiziert sind, welche
MCP-Server erreichbar sind, welche Connectoren dranhängen, wohin publish veröffentlicht, wo
CI läuft.

Das sind über Wochen konstante Werte — und trotzdem erfragt oder errät sie jede Session neu,
weil nichts sie festhält.

Vorschlag

Ein drittes Root-Dokument der Session-Ebene, ENVIRONMENT.md, mit ENVIRONMENT.md.template
als Abschnittsvorgabe. Von CLAUDE.md importiert (Claude Code), von AGENTS.md über die
Namenstabelle und einen eigenen Abschnitt erreicht (übrige Harnesses).

Drei Abgrenzungen gegen die bestehende Personalization Plane:

  • Optional. Fehlt die Datei, ist das ein gültiger Endzustand. doctor meldet
    environment: absent (optional), niemals FAIL — ein FAIL würde sie durch die Hintertür
    verpflichtend machen. Genau ein Fall wird gemeldet, als WARN: ein umbenanntes, nie
    ausgefülltes Template.
  • Gitignored. Zwei Clones sind zwei Umgebungen. Eine committete Fassung gäbe dem zweiten
    Clone Antworten, die falsch sind statt zu fehlen.
  • Kontext, keine Autorität. Beschreibt, was da ist, nicht, was erlaubt ist. Ein gelisteter
    Remote autorisiert kein git push (Invariante 5), ein gelisteter MCP-Server öffnet kein
    Gate, nichts darin ist eine Quelle nach Invariante 3. Keine Geheimnisse.

Akzeptanzkriterien

  • ENVIRONMENT.md.template liegt im Root und wird von dist export ausgeliefert; die
    ausgefüllte Fassung nie.
  • .gitignore ignoriert ENVIRONMENT.md, aber nicht ENVIRONMENT.md.template;
    docs verify prüft beide Hälften.
  • doctor hat einen environment-Check: absent → OK, ausgefüllt → OK, Sentinel →
    WARN. Nie FAIL.
  • CLAUDE.md importiert die Datei; AGENTS.md trägt Namenstabellen-Zeile und Abschnitt.
  • bootstrap.md und setup-instance.md bieten das Anlegen an, als optionalen Schritt.
  • Tests für alle drei doctor-Ausgänge, den dist export-Split und die Ignore-Kanarien.
  • MINOR-Bump (neue Fähigkeit, rückwärtskompatibel) plus Changelog-Eintrag.
## Ausgangslage `USER.md` beantwortet, **wer** die Instanz bedient, `SOUL.md`, **wie** sie klingt. Womit sie arbeitet, beantwortet niemand: welches Harness läuft, welche Skills publiziert sind, welche MCP-Server erreichbar sind, welche Connectoren dranhängen, wohin `publish` veröffentlicht, wo CI läuft. Das sind über Wochen konstante Werte — und trotzdem erfragt oder errät sie jede Session neu, weil nichts sie festhält. ## Vorschlag Ein drittes Root-Dokument der Session-Ebene, `ENVIRONMENT.md`, mit `ENVIRONMENT.md.template` als Abschnittsvorgabe. Von `CLAUDE.md` importiert (Claude Code), von `AGENTS.md` über die Namenstabelle und einen eigenen Abschnitt erreicht (übrige Harnesses). Drei Abgrenzungen gegen die bestehende Personalization Plane: - **Optional.** Fehlt die Datei, ist das ein gültiger Endzustand. `doctor` meldet `environment: absent (optional)`, niemals `FAIL` — ein `FAIL` würde sie durch die Hintertür verpflichtend machen. Genau ein Fall wird gemeldet, als `WARN`: ein umbenanntes, nie ausgefülltes Template. - **Gitignored.** Zwei Clones sind zwei Umgebungen. Eine committete Fassung gäbe dem zweiten Clone Antworten, die falsch sind statt zu fehlen. - **Kontext, keine Autorität.** Beschreibt, was da ist, nicht, was erlaubt ist. Ein gelisteter Remote autorisiert kein `git push` (Invariante 5), ein gelisteter MCP-Server öffnet kein Gate, nichts darin ist eine Quelle nach Invariante 3. Keine Geheimnisse. ## Akzeptanzkriterien - [ ] `ENVIRONMENT.md.template` liegt im Root und wird von `dist export` ausgeliefert; die ausgefüllte Fassung nie. - [ ] `.gitignore` ignoriert `ENVIRONMENT.md`, aber **nicht** `ENVIRONMENT.md.template`; `docs verify` prüft beide Hälften. - [ ] `doctor` hat einen `environment`-Check: absent → `OK`, ausgefüllt → `OK`, Sentinel → `WARN`. Nie `FAIL`. - [ ] `CLAUDE.md` importiert die Datei; `AGENTS.md` trägt Namenstabellen-Zeile und Abschnitt. - [ ] `bootstrap.md` und `setup-instance.md` bieten das Anlegen an, als optionalen Schritt. - [ ] Tests für alle drei `doctor`-Ausgänge, den `dist export`-Split und die Ignore-Kanarien. - [ ] MINOR-Bump (neue Fähigkeit, rückwärtskompatibel) plus Changelog-Eintrag.
torben added the prio/plannedsize/M labels 2026-08-31 20:39:53 +00:00
torben commented 2026-08-31 21:22:23 +00:00
Author
Owner
Copy Link
Copy Source

Umgesetzt in a243a4a, Stack 1.8.0.

Alle Akzeptanzkriterien erfüllt:

  • ENVIRONMENT.md.template im Root, von dist export ausgeliefert (ROOT_FILES); die
    ausgefüllte Fassung nie — sie ist zusätzlich gitignored, also doppelt ausgeschlossen.
  • .gitignore ignoriert /ENVIRONMENT.md, nicht das .template. Beide Hälften prüft
    docs verify: ENVIRONMENT.md in REQUIRED_IGNORE_CANARIES, ENVIRONMENT.md.template in
    REQUIRED_TRACKED_PATHS. Das nachlässige ENVIRONMENT.md* würde beide schlucken — genau
    das fängt der Kanarienvogel ab.
  • doctor.check_environment(): absent → OK, ausgefüllt → OK, Sentinel → WARN. Nie
    FAIL.
  • CLAUDE.md importiert @ENVIRONMENT.md; AGENTS.md hat Namenstabellen-Zeile und einen
    eigenen Abschnitt „Environment" (nötig, weil die übrigen Harnesses CLAUDE.md nicht lesen).
  • bootstrap.md Schritt 5, setup-instance.md Schritt 9 — beide optional, beide mit der
    Regel „eintragen was ablesbar ist, einmal fragen, weiß ich nicht akzeptieren, leeren
    Abschnitt löschen statt raten".
  • Tests: drei doctor-Ausgänge, der dist export-Split, die Ignore-Kanarien.
  • MINOR-Bump plus Changelog-Eintrag.

Entscheidung, die im Issue noch offen war: Import statt Link in CLAUDE.md. Was hier steht,
wird nebenbei gebraucht — beim Griff zum richtigen MCP-Server, mitten in einer Aufgabe. Eine
Session, die erst nachschlagen müsste, fragt stattdessen wieder den Nutzer, und genau das sind
die Kosten, die die Datei beseitigt. Dass ein unaufgelöster Import folgenlos bleibt, war schon
vorher so (USER.md/SOUL.md vor dem Setup); hier wird es zum Dauerzustand statt zum Übergang.

Nicht gebaut, bewusst: kein wikitool environment-Kommando zum Anlegen oder Abfragen. Die
Datei wird von Menschen und Agenten gelesen und selten geschrieben; ein Kommando dafür wäre
Maschinerie ohne Abnehmer. Das Template und zwei Instruktionsschritte reichen.

Verifiziert: 730 Tests grün, docs verify, instructions verify, lint --fail-on-error,
und der CI-Smoke-Test (Export → frische Instanz → doctor/verify/lint/migrate status)
läuft durch; doctor meldet dort environment: absent (optional).

Umgesetzt in `a243a4a`, Stack **1.8.0**. Alle Akzeptanzkriterien erfüllt: - `ENVIRONMENT.md.template` im Root, von `dist export` ausgeliefert (`ROOT_FILES`); die ausgefüllte Fassung nie — sie ist zusätzlich gitignored, also doppelt ausgeschlossen. - `.gitignore` ignoriert `/ENVIRONMENT.md`, nicht das `.template`. Beide Hälften prüft `docs verify`: `ENVIRONMENT.md` in `REQUIRED_IGNORE_CANARIES`, `ENVIRONMENT.md.template` in `REQUIRED_TRACKED_PATHS`. Das nachlässige `ENVIRONMENT.md*` würde beide schlucken — genau das fängt der Kanarienvogel ab. - `doctor.check_environment()`: absent → `OK`, ausgefüllt → `OK`, Sentinel → `WARN`. Nie `FAIL`. - `CLAUDE.md` importiert `@ENVIRONMENT.md`; `AGENTS.md` hat Namenstabellen-Zeile und einen eigenen Abschnitt „Environment" (nötig, weil die übrigen Harnesses `CLAUDE.md` nicht lesen). - `bootstrap.md` Schritt 5, `setup-instance.md` Schritt 9 — beide optional, beide mit der Regel „eintragen was ablesbar ist, einmal fragen, `weiß ich nicht` akzeptieren, leeren Abschnitt löschen statt raten". - Tests: drei `doctor`-Ausgänge, der `dist export`-Split, die Ignore-Kanarien. - MINOR-Bump plus Changelog-Eintrag. **Entscheidung, die im Issue noch offen war: Import statt Link in `CLAUDE.md`.** Was hier steht, wird nebenbei gebraucht — beim Griff zum richtigen MCP-Server, mitten in einer Aufgabe. Eine Session, die erst nachschlagen müsste, fragt stattdessen wieder den Nutzer, und genau das sind die Kosten, die die Datei beseitigt. Dass ein unaufgelöster Import folgenlos bleibt, war schon vorher so (`USER.md`/`SOUL.md` vor dem Setup); hier wird es zum Dauerzustand statt zum Übergang. **Nicht gebaut, bewusst:** kein `wikitool environment`-Kommando zum Anlegen oder Abfragen. Die Datei wird von Menschen und Agenten gelesen und selten geschrieben; ein Kommando dafür wäre Maschinerie ohne Abnehmer. Das Template und zwei Instruktionsschritte reichen. **Verifiziert:** 730 Tests grün, `docs verify`, `instructions verify`, `lint --fail-on-error`, und der CI-Smoke-Test (Export → frische Instanz → `doctor`/`verify`/`lint`/`migrate status`) läuft durch; `doctor` meldet dort `environment: absent (optional)`.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/corpus
Betrifft Demo-/Testbett-Frage, Inhalt und Umfang von kb/
 area/distribution
Betrifft Auslieferung, Upgrade, Versionierung einer Instanz
 area/kb
Betrifft kb/-Schema, Contract, Confidence, Lint, Wissensbasis
 area/process
Betrifft den Entwicklungsprozess selbst, nicht den Stack als Artefakt
 area/workflow
Betrifft Git, Merge, Branching, Publish, PRs
 kind/build
Spezifiziert, wartet nur noch auf Umsetzungszeit
 kind/decision
Wartet auf eine Betreiberentscheidung
 kind/defect
Befund: Doku und Realitaet, oder zwei Dokus, widersprechen sich
 prio/blocking
Blockiert oder beschaedigt laufende Arbeit - als naechstes
 prio/planned
Traegt bald Zinsen - eingeplant
 prio/waiting
Sinnvoll, wartet auf einen Ausloeser
 size/L
Mehrere Sitzungen oder offene Designfragen vor dem ersten Commit
 size/M
Mehrere Dateien, Contract- oder Instruction-Aenderung, eigener Testaufwand
 size/S
Eine Sitzung, ein Publish, klar umrissener Schnitt
 status/blocked
Wartet auf ein anderes, noch offenes Issue - nicht eigenstaendig bearbeitbar
 status/incoming
Vom Menschen angelegte Anforderung, unvollständig, muss durch den Stack komplettiert werden.
 status/unconfirmed
Gemeldeter Verdacht, noch nicht gegen tatsaechliches Verhalten geprueft - size/prio vorlaeufig
No Label prio/planned size/M
Milestone
No items
No Milestone
Assignees
Clear assignees
torben
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#24
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?