torben
00220f8b07
Files changed: - kb/index.md - kb/log.md - kb/sources/analyses/Source - Copilot Skill Restructure Instructions.md - kb/sources/analyses/Source - LLM Improvements Codex Analysis.md - kb/sources/analyses/Source - LLM Improvements Production Agent Gaps 2026.md - kb/sources/analyses/Source - LLM Improvements Sonnet Analysis.md - kb/sources/articles/Source - AMD Powermanagement CPU.md - kb/sources/articles/Source - LLM Wiki Pattern.md - kb/sources/articles/Source - LLM Wiki v2.md - kb/sources/documents/Source - qmd - GitHub Repository.md - kb/sources/notes/Source - Arch Linux Cheat Sheet.md - kb/sources/notes/Source - Docker Cheatsheet.md - kb/sources/notes/Source - Wine.md - kb/sources/trackers/Source - Gitea Issue 41 - Issue Management and Label Scheme 2026-09-02.md - kb/sources/trackers/Source - Gitea Issues 62-63 - status-incoming Label Introduction 2026-09-04.md - kb/sources/transcripts/Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04.md - kb/sources/transcripts/Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - Nightly Drift-Check Workflow and doctor's Bootstrap Gap Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31.md - kb/sources/transcripts/Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30.md - kb/sources/transcripts/Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31.md - kb/sources/transcripts/Source - MCP Read Server Implementation Session 2026-09-02.md - kb/sources/transcripts/Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01.md - kb/sources/transcripts/Source - Public Release, Corpus Purge and History Squash Session 2026-09-01.md - kb/sources/transcripts/Source - Publish-Remote Gate and Issue Triage Session 2026-09-01.md - kb/sources/transcripts/Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md - work/backfill-capture-fields/README.md - work/backfill-capture-fields/plan.md
103 lines
6.0 KiB
Markdown
103 lines
6.0 KiB
Markdown
---
|
|
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
|