---
type: types/source.md
source_type: transcript
author: Torben Nehmer
raw_files: [raw/notes/Conversation Transcript - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31.md]
source_language: en
date: 2026-08-31
tags: []
entities: [ENVIRONMENT.md, CLAUDE.md, AGENTS.md, wikitool]
concepts: [Optional Instance Context File, Personalization Plane]
summary: 'Sitzung, die ENVIRONMENT.md als optionales drittes Root-Dokument einfuehrt: gitignored, doctor meldet aber scheitert nie, Kontext ohne Autoritaet (1.8.0, Issue #24)'
fidelity: verbatim
authority: reporting
---
# Source: Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31

**Autor:** Torben Nehmer  
**Datum:** 2026-08-31  
**Raw-Dateien:** raw/notes/Conversation Transcript - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31.md  
**Typ:** Notes

## Zusammenfassung

Sitzung, die `ENVIRONMENT.md` als drittes Root-Dokument der Sitzungsebene einführt, neben
`USER.md` und `SOUL.md`. Die Datei hält fest, womit *ein bestimmter Checkout* arbeitet: Harness,
publizierte Skills, erreichbare MCP-Server, Connectoren, Git-Remotes, wo CI läuft. Ausgeliefert
als Stack-Version 1.8.0 im Commit `a243a4a`, Gitea-Issue #24 in derselben Sitzung angelegt und
geschlossen.

Die Sitzung begann mit einem Widerspruch: der Nutzer nannte Issue #10, beschrieb aber eine ganz
andere Aufgabe. #10 ist Coverage-Reporting; kein offenes Issue passte zur Beschreibung. Statt
eine der beiden Lesarten zu wählen, wurde nachgefragt — die Antwort war "beides", woraufhin für
die beschriebene Arbeit ein neues Issue entstand.

Inhaltlich ist die Seite die Abgrenzung gegen die bestehende [[Personalization Plane]]: dasselbe
Muster aus Template, Setup-Schritt und Health-Check, aber an drei Stellen bewusst anders —
optional statt Pflicht, gitignored statt committet, und ausdrücklich Kontext ohne Autorität.

## Kernaussagen

- **Ein Health-Check darf eine optionale Datei melden, aber nie an ihr scheitern.**
  `doctor.check_environment()` gibt `OK` bei Abwesenheit, `OK` bei ausgefüllter Datei und `WARN`
  nur bei einem umbenannten, nie ausgefüllten Template. Aus dem Docstring der Funktion:
  "Missing it costs a session some questions, not correctness, so this check never FAILs - the
  whole point of the file is that it is optional, and a FAIL would make it mandatory by the back
  door." Verworfen wurde `FAIL` bei fehlender Datei, wie es der `personalization`-Check tut.
- **Gitignored, weil zwei Clones zwei Umgebungen sind.** Eine committete Fassung gäbe dem
  zweiten Clone Antworten, die falsch sind statt zu fehlen — und falsch ist hier schlimmer, weil
  die Datei geglaubt wird. `USER.md`/`SOUL.md` sind demgegenüber committet und nur vom Export
  ausgenommen.
- **Das Ignore-Muster muss eine Datei von ihrem eigenen Template trennen.** Das nachlässige
  `ENVIRONMENT.md*` würde beide schlucken. `docs verify` prüft deshalb beide Richtungen:
  `ENVIRONMENT.md` in `REQUIRED_IGNORE_CANARIES`, `ENVIRONMENT.md.template` in
  `REQUIRED_TRACKED_PATHS`. Der `.gitignore`-Eintrag ist verankert (`/ENVIRONMENT.md`).
- **Kontext, keine Autorität.** Die Datei beschreibt, was da ist, nicht was erlaubt ist. Ein
  gelisteter Remote autorisiert kein `git push` — Invariante 5 führt weiter über
  `wikitool publish` —, ein gelisteter MCP-Server öffnet kein Gate, und nichts darin ist eine
  Quelle nach Invariante 3. Keine Zugangsdaten: die Datei liegt im Klartext im Arbeitsverzeichnis
  und in jedem Agenten-Kontext.
- **Import statt Link in [[CLAUDE.md]], weil die Entscheidung nebenbei fällt.** Der in die Datei
  geschriebene Prüfstein: "a session that has to go look the answer up will instead ask the user
  again, which is the cost the file exists to remove." `ENVIRONMENT.md` ist zugleich der erste
  Import, der legitim nie existieren darf — die Toleranz gegenüber unaufgelösten Imports gab es
  schon vorher für `USER.md`/`SOUL.md` vor dem Setup, hier wird sie zum Dauerzustand.
- **`instructions/dev/` schied als Ort aus, obwohl der Auftrag "im dev skillset" sagte.**
  `instructions/CONTRACT.md` verbietet Referenzen von außen auf dieses Verzeichnis, weil sie
  beim `dist export` ins Leere zeigen würden; ein Link aus `CLAUDE.md` bräuchte die
  `dist:strip`-Marker-Konstruktion. Mehr Mechanik für weniger Reichweite — und der Inhalt
  (MCP-Server, Remotes) betrifft auch reine Content-Sitzungen.
- **[[AGENTS.md]] braucht einen eigenen Abschnitt, nicht nur die Tabellenzeile**, weil die
  übrigen Harnesses `CLAUDE.md` nie lesen und die Datei sonst nur unter Claude Code existierte.

## Aufgaben

- [x] Gitea-Issue #24 angelegt (`prio/2`, `size/M`) und nach der Umsetzung geschlossen
- [x] `ENVIRONMENT.md` für diesen Checkout angelegt — 40 Zeilen, nur Werte

## Nicht übernommen

- **Der vollständige Turn-für-Turn-Verlauf.** Das Transkript hält ihn fest; hier steht, was
  daraus dauerhaft gilt.
- **Die mechanischen Folgeänderungen**: die Umnummerierung von `setup-instance.md` (Schritte
  9-13 zu 10-14) samt der Querverweis-Korrektur "Schritt 11" → "Schritt 12", und die Korrektur
  von `CLAUDE.md`s Formulierung "the fourth import" zu "the last import". Beides ist im Repo
  nachlesbar und trägt keine Regel.
- **Der Inhalt der für diesen Checkout angelegten `ENVIRONMENT.md`** (welche Remotes, welcher
  MCP-Server). Die Datei ist gitignored und beschreibt eine Arbeitskopie, nicht das Repo — als
  Wiki-Wissen wäre sie genau die zweite, driftende Kopie, die die Datei selbst vermeiden soll.
- **Der Coverage-Teil derselben Sitzung.** Eigenes Transkript, eigene Quellseite: derselbe
  Publish, aber ein anderes Thema.

## Verwandte Entities

- [[ENVIRONMENT.md]] - in dieser Sitzung entstanden
- [[CLAUDE.md]] - importiert die neue Datei
- [[AGENTS.md]] - Namenstabellen-Zeile und eigener Abschnitt „Environment"
- [[wikitool]] - `doctor`-Check, Root-Allowlist von `dist export`, Ignore-Kanarien

## Verwandte Concepts

- [[Optional Instance Context File]] - die Verallgemeinerung, in dieser Sitzung entstanden
- [[Personalization Plane]] - das Muster, gegen das abgegrenzt wird