chemenu/kb/sources/Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31.md

type, source_type, author, raw_files, source_language, date, tags, entities, concepts, summary

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

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

• Gitea-Issue #24 angelegt (prio/2, size/M) und nach der Umsetzung geschlossen
• 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.mds 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