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

Control-Plane-Sprache als Architekturentscheidung festhalten: universell Englisch, kein Instanzparameter #103

New Issue
Closed
opened 2026-09-15 14:50:27 +00:00 by torben · 1 comment
torben commented 2026-09-15 14:50:27 +00:00
Owner
Copy Link
Copy Source

Entscheidung (getroffen 2026-09-15, Betreiber) - umgesetzt in 6.0.0-beta.5

Die Control-Plane-Sprache ist universell Englisch und kein Instanzparameter. Es gibt kein
control_plane_language: neben dem language: in kb/CONVENTIONS.md, und keine Ausnahme für
ein Control-Plane-Dokument, das eine Instanz nur lokal führt und nie ausliefert.

Was der Anlass war

AGENTS.md § File naming begründete die Sprachregel mit einem Vorsatz, der schmaler war als die
Regel darunter: "Every file in the table above belongs to the stack and ships to instances
that share none of this instance's language choices, so:". Das trägt nur für ausgeliefertes
Material und ließ offen, was für ein Control-Plane-Dokument gilt, das eine Instanz nur für sich
selbst schreibt - eine eigene Instruction, ein selbst angelegter Seitentyp (types/ nimmt einen
ohne Code-Änderung auf), ein weiterer Stage-Contract. Genau dort fallen Ownership und Publikum
auseinander: die Datei ist durchgängig instanzeigen, ihre Anleitungshälfte hat trotzdem einen
Agenten als Leser. Die Frage blieb aus #99 übrig.

Begründung, die jetzt festgehalten ist

  1. Die tragende Achse ist das Publikum, nicht die Ownership. Ownership war ein brauchbarer
    Stellvertreter, solange nur ausgelieferte Artefakte betrachtet wurden; der instanz-eigene
    Type-Spec widerlegt ihn. Was die Sprache entscheidet, ist wer den Satz liest.
  2. Ein zweiter Sprachschalter würde jede Regel über das Schreiben von Instructions gabeln -
    die Kosten trägt jede Datei, den Nutzen hätte ein Dokument, das ohnehin nur ein Agent liest.
  3. Ein heute instanz-lokales Control-Plane-Dokument ist der Upstream-Kandidat von morgen und
    müsste sonst erst übersetzt werden - samt der Prosa/Identifier-Grenze, die dabei verloren geht.
  4. Nichts würde die Einstellung prüfen. Eine Stoppwort-Prüfung schlägt beim absichtlich
    zitierten Vokabular an und übersieht einen sauber übersetzten Absatz.

Punkt 4 kam bei der Umsetzung dazu; die docs/-Seite nennt außerdem, was die Entscheidung wieder
aufmachen würde (Menschen als Hauptleser von instructions/, oder lokalisierte Identifier).

Akzeptanzkriterien

  • AGENTS.md § File naming: Regel 1 ruht nicht mehr auf der Auslieferungsprämisse. Der
    Vorsatz nennt die For-Spalte als Achse; Regel 1 sagt ausdrücklich, dass sie auch für ein
    nie ausgeliefertes Control-Plane-Dokument gilt und dass es keinen zweiten Sprachwert gibt.
  • kb/CONVENTIONS.md und kb/CONVENTIONS.md.template tragen denselben Satz: die
    Control-Plane-Sprache ist keine Einstellung, die diese Datei zurückhält - es ist gar keine.
  • Der Docstring von dist_cmd.instance_owned_type_stems() behauptet nicht mehr, die Sprache
    eines root: kb-Type-Specs sei Sache der Instanz. Er trennt jetzt Ownership und Sprache
    und verweist auf beide Stellen, an denen der Schnitt steht.
  • docs/language-boundaries.md trägt die Begründung: warum Englisch, warum kein Parameter,
    was die KB-Sprache weiterhin entscheidet, wo die Grenze mitten durch eine Datei läuft, und
    was die Entscheidung wieder aufmachen würde. Kein normativer Satz - die Regel bleibt in
    AGENTS.md.
  • AGENTS.mds Aufzählung der docs/-Seiten nennt die neue Seite.
  • TOC-Region per tools/wikitool docs toc --apply erzeugt, nicht von Hand.
  • tools/wikitool version bump --patch → 6.0.0-beta.5, mit ausgeschriebenem
    Changelog-Abschnitt.

Zusätzlich behoben (in der Umsetzung gefunden)

  • AGENTS.md sagte "Four pages exist today" über ein Verzeichnis mit fünf Seiten.
    docs/model-and-effort-selection.md fehlte in der Liste - absichtlich, weil ein Link von dort
    die Claude-Code-eigene Entscheidung in die anderen drei Harnesses laden würde, aber ohne dass
    der Satz das sagte. Er zählt jetzt, was von AGENTS.md aus verlinkt ist, und benennt die
    sechste Seite samt Grund.
  • docs/ownership-and-templates.md § "Where the file boundary strains" verweist für die
    Sprachachse auf die neue Seite und hält fest, dass der Rest der Seite nur von Ownership handelt.

Verifiziert

tools/wikitool docs verify (50 Referenzdateien, TOCs aktuell, alle Links auflösend),
tools/wikitool instructions verify (22 Instructions, 7 Skills, 14 publizierte Kopien
identisch), pytest in tools/ mit 1253 grünen Tests. Publiziert als f350999
(6.0.0-beta.5, 7 Dateien) und 90ce419 (docs-Querverweis, ohne Bump - docs/ liegt außerhalb
des CI-Version-Gates).

Nicht in diesem Paket

Der Dateischnitt des Seiten-Type-Specs (Anleitung stackeigen, Seitenmaterial instanzeigen) steht
als #104. Die Entscheidung hier gilt unabhängig davon, wie #104 ausgeht: sie sagt, in welcher
Sprache jede Hälfte geschrieben ist, nicht in welcher Datei sie liegt.

## Entscheidung (getroffen 2026-09-15, Betreiber) - umgesetzt in 6.0.0-beta.5 Die Control-Plane-Sprache ist **universell Englisch** und **kein Instanzparameter**. Es gibt kein `control_plane_language:` neben dem `language:` in `kb/CONVENTIONS.md`, und keine Ausnahme für ein Control-Plane-Dokument, das eine Instanz nur lokal führt und nie ausliefert. ## Was der Anlass war `AGENTS.md` § File naming begründete die Sprachregel mit einem Vorsatz, der schmaler war als die Regel darunter: "Every file in the table above belongs to the stack and **ships to instances** that share none of this instance's language choices, so:". Das trägt nur für ausgeliefertes Material und ließ offen, was für ein Control-Plane-Dokument gilt, das eine Instanz nur für sich selbst schreibt - eine eigene Instruction, ein selbst angelegter Seitentyp (`types/` nimmt einen ohne Code-Änderung auf), ein weiterer Stage-Contract. Genau dort fallen Ownership und Publikum auseinander: die Datei ist durchgängig instanzeigen, ihre Anleitungshälfte hat trotzdem einen Agenten als Leser. Die Frage blieb aus #99 übrig. ## Begründung, die jetzt festgehalten ist 1. **Die tragende Achse ist das Publikum, nicht die Ownership.** Ownership war ein brauchbarer Stellvertreter, solange nur ausgelieferte Artefakte betrachtet wurden; der instanz-eigene Type-Spec widerlegt ihn. Was die Sprache entscheidet, ist wer den Satz liest. 2. **Ein zweiter Sprachschalter würde jede Regel über das Schreiben von Instructions gabeln** - die Kosten trägt jede Datei, den Nutzen hätte ein Dokument, das ohnehin nur ein Agent liest. 3. **Ein heute instanz-lokales Control-Plane-Dokument ist der Upstream-Kandidat von morgen** und müsste sonst erst übersetzt werden - samt der Prosa/Identifier-Grenze, die dabei verloren geht. 4. **Nichts würde die Einstellung prüfen.** Eine Stoppwort-Prüfung schlägt beim absichtlich zitierten Vokabular an und übersieht einen sauber übersetzten Absatz. Punkt 4 kam bei der Umsetzung dazu; die `docs/`-Seite nennt außerdem, was die Entscheidung wieder aufmachen würde (Menschen als Hauptleser von `instructions/`, oder lokalisierte Identifier). ## Akzeptanzkriterien - [x] `AGENTS.md` § File naming: Regel 1 ruht nicht mehr auf der Auslieferungsprämisse. Der Vorsatz nennt die *For*-Spalte als Achse; Regel 1 sagt ausdrücklich, dass sie auch für ein nie ausgeliefertes Control-Plane-Dokument gilt und dass es keinen zweiten Sprachwert gibt. - [x] `kb/CONVENTIONS.md` **und** `kb/CONVENTIONS.md.template` tragen denselben Satz: die Control-Plane-Sprache ist keine Einstellung, die diese Datei zurückhält - es ist gar keine. - [x] Der Docstring von `dist_cmd.instance_owned_type_stems()` behauptet nicht mehr, die Sprache eines `root: kb`-Type-Specs sei Sache der Instanz. Er trennt jetzt Ownership und Sprache und verweist auf beide Stellen, an denen der Schnitt steht. - [x] `docs/language-boundaries.md` trägt die Begründung: warum Englisch, warum kein Parameter, was die KB-Sprache weiterhin entscheidet, wo die Grenze mitten durch eine Datei läuft, und was die Entscheidung wieder aufmachen würde. Kein normativer Satz - die Regel bleibt in `AGENTS.md`. - [x] `AGENTS.md`s Aufzählung der `docs/`-Seiten nennt die neue Seite. - [x] TOC-Region per `tools/wikitool docs toc --apply` erzeugt, nicht von Hand. - [x] `tools/wikitool version bump --patch` → `6.0.0-beta.5`, mit ausgeschriebenem Changelog-Abschnitt. ## Zusätzlich behoben (in der Umsetzung gefunden) - `AGENTS.md` sagte "Four pages exist today" über ein Verzeichnis mit fünf Seiten. `docs/model-and-effort-selection.md` fehlte in der Liste - absichtlich, weil ein Link von dort die Claude-Code-eigene Entscheidung in die anderen drei Harnesses laden würde, aber ohne dass der Satz das sagte. Er zählt jetzt, was von `AGENTS.md` aus verlinkt ist, und benennt die sechste Seite samt Grund. - `docs/ownership-and-templates.md` § "Where the file boundary strains" verweist für die Sprachachse auf die neue Seite und hält fest, dass der Rest der Seite nur von Ownership handelt. ## Verifiziert `tools/wikitool docs verify` (50 Referenzdateien, TOCs aktuell, alle Links auflösend), `tools/wikitool instructions verify` (22 Instructions, 7 Skills, 14 publizierte Kopien identisch), `pytest` in `tools/` mit 1253 grünen Tests. Publiziert als `f350999` (6.0.0-beta.5, 7 Dateien) und `90ce419` (docs-Querverweis, ohne Bump - `docs/` liegt außerhalb des CI-Version-Gates). ## Nicht in diesem Paket Der Dateischnitt des Seiten-Type-Specs (Anleitung stackeigen, Seitenmaterial instanzeigen) steht als #104. Die Entscheidung hier gilt unabhängig davon, wie #104 ausgeht: sie sagt, in welcher Sprache jede Hälfte geschrieben ist, nicht in welcher Datei sie liegt.
torben added the area/processkind/buildprio/plannedsize/S labels 2026-09-15 14:51:41 +00:00
torben commented 2026-09-15 15:01:31 +00:00
Author
Owner
Copy Link
Copy Source

Changelog: Abgeschlossen in 6.0.0-beta.5 (f350999, 90ce419). Alle sieben
Akzeptanzkriterien abgehakt; Begründungspunkt 4 ("nichts würde die Einstellung prüfen") ist bei
der Umsetzung dazugekommen. Zwei Nebenbefunde neu im Body: die falsche Seitenzählung in
AGENTS.md samt der absichtlichen Auslassung von docs/model-and-effort-selection.md, und der
Querverweis aus docs/ownership-and-templates.md. Verifizierte Läufe und Commits benannt.

Modelle dieser Sitzung: Opus 5 in allen drei Phasen - Entscheidung und Issue-Zuschnitt,
Umsetzung, Abschluss. Der stack-dev-Modellwechsel wurde bewusst nicht angeboten: das Paket
hatte keine mechanische Mitte (bis auf einen Docstring reine Prosa in ungeprüftem Gebiet).

**Changelog:** Abgeschlossen in `6.0.0-beta.5` (`f350999`, `90ce419`). Alle sieben Akzeptanzkriterien abgehakt; Begründungspunkt 4 ("nichts würde die Einstellung prüfen") ist bei der Umsetzung dazugekommen. Zwei Nebenbefunde neu im Body: die falsche Seitenzählung in `AGENTS.md` samt der absichtlichen Auslassung von `docs/model-and-effort-selection.md`, und der Querverweis aus `docs/ownership-and-templates.md`. Verifizierte Läufe und Commits benannt. **Modelle dieser Sitzung:** Opus 5 in allen drei Phasen - Entscheidung und Issue-Zuschnitt, Umsetzung, Abschluss. Der `stack-dev`-Modellwechsel wurde bewusst nicht angeboten: das Paket hatte keine mechanische Mitte (bis auf einen Docstring reine Prosa in ungeprüftem Gebiet).
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 area/process kind/build prio/planned size/S
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#103
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?