diff --git a/CHANGES.md b/CHANGES.md index 2897aa6..65f7320 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -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 @@ -78,6 +78,7 @@ concern - readable here, never shipped as something to parse. **Low impact** - new project: Testabdeckung fuer die required-responsibility-Ablehnung +- docs/-Nachzug: Exit 42 als Haltung, und die Adoption eines neu ausgelieferten Templates ### 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 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 diff --git a/VERSION b/VERSION index 8747287..e5533f6 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -7.0.0-beta.7 +7.0.0-beta.8 diff --git a/docs/ownership-and-templates.md b/docs/ownership-and-templates.md index 1c4257f..cd5e396 100644 --- a/docs/ownership-and-templates.md +++ b/docs/ownership-and-templates.md @@ -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 `kb//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 - 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 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 diff --git a/docs/why-gates-are-code.md b/docs/why-gates-are-code.md index dc6fb89..69fa398 100644 --- a/docs/why-gates-are-code.md +++ b/docs/why-gates-are-code.md @@ -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 underneath them: why code, and why these four mechanisms in particular. + +## 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) + + ## 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 @@ -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 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 Code beats prose for the reason above, but on its own it buys less than it looks like: a check