docs: Exit 42 als Haltung und die Adoption eines neuen Templates nachgezogen (#119)
CI / verify (push) Successful in 48s
Release / release (push) Successful in 36s

Files changed:
- CHANGES.md
- VERSION
- docs/ownership-and-templates.md
- docs/why-gates-are-code.md
This commit is contained in:
torben committed 2026-09-20 10:14:36 +02:00
1 parent 1d695f6536
commit 8ed8c6f5d9
4 files changed
+65 -3

No files matched your search

+23 -1
View File
@@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse.
--- ---
## 7.0.0-beta.7 - 2026-09-20 - Doku-Nachzug zu #119: die Verpflichtungsschicht erreicht Installation, Setup und docs/ ## 7.0.0-beta.8 - 2026-09-20 - docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates
**Author:** Torben Nehmer **Author:** Torben Nehmer
@@ -78,6 +78,7 @@ concern - readable here, never shipped as something to parse.
**Low impact** **Low impact**
- new project: Testabdeckung fuer die required-responsibility-Ablehnung - new project: Testabdeckung fuer die required-responsibility-Ablehnung
- docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates
<!-- /wikitool:bumps --> <!-- /wikitool:bumps -->
### Typ `project` und Collection `kb/gtd/`: das Vorhaben als eigene Seitenart ### Typ `project` und Collection `kb/gtd/`: das Vorhaben als eigene Seitenart
@@ -268,6 +269,27 @@ Seitentyp oder eine neue Collection (Type-Spec/`COLLECTION.md` + `kb/CONTRACT.md
Adoptionspfade). Die Zeile zur `docs/`-Begruendung sagt jetzt zusaetzlich, dass eine Entscheidung Adoptionspfade). Die Zeile zur `docs/`-Begruendung sagt jetzt zusaetzlich, dass eine Entscheidung
ohne Seite die eigentliche Luecke ist, weil Begruendungen aus einem Issue nie ausgeliefert werden. ohne Seite die eigentliche Luecke ist, weil Begruendungen aus einem Issue nie ausgeliefert werden.
### docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates
Die Abschlusspruefung dieses Kandidaten (`stack-close` Schritt 3) hat zwei `docs/`-Seiten gefunden,
deren Begruendung die Pakete #124/#126 bzw. #123 verschoben hatten, ohne dass jemand sie nachzog -
beide unpruefbar, weil eine `docs/`-Seite per Konstruktion keinen normativen Satz traegt.
- **`docs/why-gates-are-code.md` kannte Exit 42 nur als Gate.** Die Seite oeffnet mit „vier harte
Grenzen", und seit #124/#126 verlaesst `HumanInterventionRequired` denselben Code, ohne eine
fuenfte Gate zu sein. Neuer Abschnitt „Exit 42 is a posture, and it outgrew the gates": die vier
Gates teilen eine *Weigerung* (die Operation waere moeglich, das Werkzeug fuehrt sie
unbesehen nicht aus), der neue Fall ist das Gegenteil (die Operation ist gar nicht moeglich, kein
Token koennte das aendern) - gemeinsam ist beiden nur, was der Exit-Code tatsaechlich sagt:
anhalten, einem Menschen zeigen, nichts umgehen. Dazu die verworfene Alternative, die Luecke in
der Instruction-Schicht zu beschreiben - genau die Prosa-Regel, gegen die diese Seite argumentiert.
- **`docs/ownership-and-templates.md` beschrieb die `.template`-Kategorie nur von innen.** „Wird
von einem Upgrade nie geschrieben" stimmt weiterhin fuer eine bereits adoptierte Datei; der Fall,
dass ein Release ein Template fuer einen Typ liefert, den die Instanz noch *gar nicht* hat, stand
nirgends - und genau der ist seit #123 der Grenzuebertritt. Die Kategorie nennt ihn jetzt als die
eine Gestalt, in der „das Upgrade schreibt diese Datei nie" zu Arbeit wird, mit Verweis auf den
Schritt in `upgrade-instance.md`, den Stack 7.0.0-beta.7 dort angelegt hat.
--- ---
## 6.2.0 - 2026-09-19 - Entity-Subtyp project nach codebase umbenannt ## 6.2.0 - 2026-09-19 - Entity-Subtyp project nach codebase umbenannt
+1 -1
View File
@@ -1 +1 @@
7.0.0-beta.7 7.0.0-beta.8
+9 -1
View File
@@ -149,7 +149,15 @@ becomes visible once an upgrade is a command rather than a hand-run copy:
- **`.template`-sourced files** - `USER.md`, `SOUL.md`, `kb/CONVENTIONS.md`, each - **`.template`-sourced files** - `USER.md`, `SOUL.md`, `kb/CONVENTIONS.md`, each
`kb/<name>/COLLECTION.md`, `ENVIRONMENT.md`, the `root: kb` type-specs - are never written by `kb/<name>/COLLECTION.md`, `ENVIRONMENT.md`, the `root: kb` type-specs - are never written by
an upgrade at all. The distribution ships only the `.template` beside them, so the filled file an upgrade at all. The distribution ships only the `.template` beside them, so the filled file
is out of reach by construction rather than by a rule someone has to remember. is out of reach by construction rather than by a rule someone has to remember. The same
property has a second face on the way in: when a release ships a `.template` for a type or
collection the instance does not have *yet*, the upgrade writes the template and stops - it
cannot write the filled file without deciding the instance's own language and wording for it.
Adoption is therefore an act the instance performs, and where the stack *requires* that type
(the `source` idiom, and `project` since 7.0.0) an upgrade that skips it leaves a tree
`docs verify` refuses. That is the ownership boundary working rather than a gap in it, but it
is the one shape in which "the upgrade never writes this file" turns into work somebody has to
do; `instructions/upgrade-instance.md` carries the step.
- **Seeded-once files** - `.wikitool-kb.json`, `CHANGES.md`, `kb/log.md`, `raw/.gitkeep` - are - **Seeded-once files** - `.wikitool-kb.json`, `CHANGES.md`, `kb/log.md`, `raw/.gitkeep` - are
written into a *new* instance by `dist export` and belong to the instance from then on. They written into a *new* instance by `dist export` and belong to the instance from then on. They
are the awkward category: they sit in the release stamp's file list like any other shipped are the awkward category: they sit in the release stamp's file list like any other shipped
+32
View File
@@ -7,6 +7,16 @@ one trips, are in [AGENTS.md § Gates](../AGENTS.md#gates) and
[instructions/gates.md](../instructions/gates.md). This page is only about the design choice [instructions/gates.md](../instructions/gates.md). This page is only about the design choice
underneath them: why code, and why these four mechanisms in particular. underneath them: why code, and why these four mechanisms in particular.
<!-- wikitool:toc -->
## Contents
- [A suggestion an agent can talk itself past](#a-suggestion-an-agent-can-talk-itself-past)
- [Why four different mechanisms, not one](#why-four-different-mechanisms-not-one)
- [Exit 42 is a posture, and it outgrew the gates](#exit-42-is-a-posture-and-it-outgrew-the-gates)
- [A gate in code still has to be reachable](#a-gate-in-code-still-has-to-be-reachable)
- [Numbers that come from measurement, not intuition](#numbers-that-come-from-measurement-not-intuition)
<!-- /wikitool:toc -->
## A suggestion an agent can talk itself past ## A suggestion an agent can talk itself past
An instruction like "don't publish too much at once" or "don't loop forever" lives in the same An instruction like "don't publish too much at once" or "don't loop forever" lives in the same
@@ -51,6 +61,28 @@ The Iteration Budget Gate asks a fourth kind of question - not "is this instance
itself (call count, repeated identical calls), not from anything about the content of any one itself (call count, repeated identical calls), not from anything about the content of any one
call. call.
## Exit 42 is a posture, and it outgrew the gates
Those four are the named gates, and they are not the only thing that exits 42 any more. When the
task-tracker provider layer arrived, it brought a case that looks like a gate from the outside and
is not one: a provider whose API cannot create a project (Super Productivity's local REST API
reads projects but does not write them) raises `HumanInterventionRequired`, and the command prints
what a human has to do and exits 42.
Reusing the code was deliberate, and so was not calling it a fifth gate. What the four gates share
is a *refusal*: the operation was possible and the tool declined to perform it unreviewed. This is
the opposite situation - the operation is not possible at all, and no token could make it
possible. What the two have in common is only what the exit code actually communicates: **stop,
show this to a human, do not improvise a way around it.** That sentence is the whole meaning of
42 here, and it is worth more as a shared convention than as a number reserved for one mechanism.
The alternative was worse in a specific way. A provider that cannot do something could have been
described in the instruction layer instead - "if you are on this tracker, create the project by
hand first" - which is exactly the prose-shaped rule this page argues against, with the added cost
that every instruction would then have to know which provider an instance runs. The capability
gap belongs where the capability is, and reaches the session as an exit code rather than as a
paragraph it has to remember to apply.
## A gate in code still has to be reachable ## A gate in code still has to be reachable
Code beats prose for the reason above, but on its own it buys less than it looks like: a check Code beats prose for the reason above, but on its own it buys less than it looks like: a check