docs: Exit 42 als Haltung und die Adoption eines neuen Templates nachgezogen (#119)
Files changed: - CHANGES.md - VERSION - docs/ownership-and-templates.md - docs/why-gates-are-code.md
This commit is contained in:
1 parent
1d695f6536
commit
8ed8c6f5d9
4 files changed
+65
-3
No files matched your search
@@ -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/<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
|
||||
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
|
||||
|
||||
@@ -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.
|
||||
|
||||
<!-- 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
|
||||
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user