torben
18ae28f918
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
101 lines
6.0 KiB
Markdown
101 lines
6.0 KiB
Markdown
---
|
|
type: types/source.md
|
|
source_type: notes
|
|
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)'
|
|
---
|
|
# 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
|