diff --git a/CHANGES.md b/CHANGES.md index 06fdab0..0bb9026 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,12 +59,13 @@ concern - readable here, never shipped as something to parse. --- -## 6.1.0-beta.1 - 2026-09-16 - Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md +## 6.1.0-beta.2 - 2026-09-16 - Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form **Author:** Torben Nehmer - Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md +- Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form ### Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md @@ -121,6 +122,57 @@ Kein Grenzuebertritt: eine neue Instruktionsdatei und ein geaenderter Meldungste Richtungen ein Drop-in. Eine Instanz, die zurueckgeht, behaelt die Datei als ueberzaehlige Datei, und nichts liest sie automatisch - `manual: true` heisst genau das. +### Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form + +`instructions/migrations/6.0.0-type-guidance-split.md` verlangte in seinem Verifikationsschritt, +die Ausgabe von `types describe ` muesse *"read the same as it did before this migration"* - +ohne dass ein Schritt davor dieses Vorher festhielt. Eine Pruefung gegen einen Zustand, den +niemand aufgeschrieben hat, faellt auf das Gedaechtnis des Ausfuehrenden zurueck, und bei ueber +150 Zeilen Ausgabe je Typ ist das keins. Der getracete 6.0.0-Lauf hat entsprechend durch +`| head -250` und `| tail -80` geprueft und *"structurally identical to before"* geurteilt; was +das uebersah, lag in der Mitte der `source`-Ausgabe. Das Dokument schreibt die Ausgabe jetzt in +einem eigenen Schritt **vor** der Aenderung in eine Datei und diffed hinterher, mit +`grep -c '^## Authoring guidance'` als Ein-Zahl-Probe: zwei Koepfe sind richtig - einen setzt +`types describe` selbst, einen bringt die Guidance-Datei mit. + +Als generisches Muster steht dasselbe jetzt in `instructions/migrate-corpus.md` § "Writing the +migration document", weil es nicht an diesem einen Dokument haengt: `migrate verify` traegt seine +Baseline im letzten Commit, ob jemand daran denkt oder nicht - eine Migration an der Maschinerie +statt an `kb/` hat gar keine, und genau dort entsteht die Behauptung, die sich nicht widerlegen +laesst. + +Zweiter Fehler im selben Dokument: der Beispielverweis auf `types/entity.md` zeigt in einer +ausgelieferten Instanz auf die beim Setup adoptierte Kopie - also auf genau den Vorher-Zustand, +den der Schritt entfernen laesst. Der Nachher-Zustand liegt dort unter +`types/entity.md.template`, und im Ursprungs-Repo existiert diese Datei ueberhaupt nicht: +`dist export` re-keyt `types/.md` erst beim Export. Der Satz konnte in einer Instanz also +nicht bloss unguenstig sein, er konnte dort nie stimmen. Dazu sagt der Schritt jetzt die Sprache +des Pointer-Absatzes - englisch, weil Anleitungsprosa an einen Agenten Control Plane ist, +unabhaengig davon, wem die Datei gehoert - und dass das auch fuer behaltene lokale Prosa gilt: +die wird uebersetzt, nicht umbenannt. Die Tabelle dazu wird verlinkt statt kopiert +(`types/type-spec.md` § "Who owns a type-spec"), und ein behaltener Abschnitt bekommt einen +eigenen Namen statt der Ueberschrift, die `types describe` schon selbst setzt. + +Derselbe Defekt eine Ebene hoeher, gefunden beim Nachmessen: `types/source.md` trug hier im +Ursprungs-Repo noch einen Rest-Abschnitt `## Authoring guidance` mit einem einzigen Bullet, der +die `title_prefix`-Frontmatter wiederholte - `types describe source` gab drei Koepfe aus, die +anderen drei Typen zwei. Die Sprachzentralisierung hat den Abschnitt uebersetzt, der +Guidance-Split den Rest der Prosa ausgelagert und diesen Bullet stehenlassen. Die Datei wird beim +Export zu `types/source.md.template`, also haette ihn jede neu aufgesetzte Instanz mit adoptiert. +Entfernt, geprueft mit genau dem Muster, das der Schritt oben jetzt vorschreibt: Vorher-Datei, +Diff, vier entfernte Zeilen und sonst nichts, alle vier Typen komponieren jetzt mit zwei Koepfen. + +Verifiziert: `docs verify` (73 ausgelieferte Dokumente, 58 Referenzdateien), +`instructions verify` (23 Instruktionen, 7 Skills) und 1276 Tests gruen. Kein neuer Test: die +Aenderung ist Prosa in zwei Instruktionen und ein entfernter Abschnitt aus einem Type-Spec - +was hier mechanisch pruefbar waere, prueft `docs verify` bereits als Type-Spec gegen sein Schema. + +Kein Grenzuebertritt: in beide Richtungen ein Drop-in. Die Korrektur gilt denen, die noch +upgraden - eine Instanz, die das Angebot bereits genommen hat, liest das Dokument nicht noch +einmal. Fuer sie lohnt der eine Befehl, mit dem der Schaden hier gefunden wurde: +`grep -c '^## Authoring guidance'` ueber `types describe ` fuer alle vier Typen, drei +bedeutet einen Rest-Abschnitt im eigenen Type-Spec. + --- ## 6.0.1 - 2026-09-16 - docs toc/verify erreichen die .template-Form einer Referenzdatei diff --git a/VERSION b/VERSION index acd0499..c56d949 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -6.1.0-beta.1 +6.1.0-beta.2 diff --git a/instructions/migrate-corpus.md b/instructions/migrate-corpus.md index 7972651..2cff4fd 100644 --- a/instructions/migrate-corpus.md +++ b/instructions/migrate-corpus.md @@ -120,6 +120,16 @@ Write it for a reader who has the new machinery and the old content, and who is changed, which pages are affected, how to tell a migrated page from an unmigrated one, and what `migrate verify` should report when it is done. +**A verification step names its own baseline, and does it in an earlier step.** Where the +document asks that something "read the same as before" - a composed `types describe` answer, a +rendered index, any command's output - it says what to capture, where to put it, and at which +point, so the check is a `diff` rather than a memory. Step 4's `migrate verify` needs none of +that: its baseline is the last commit, which git holds whether or not anyone thought to keep it. +A migration that changes machinery rather than `kb/` pages has no such baseline, and that is +exactly where the unfalsifiable version has already slipped through - the 6.0.0 type-guidance +split asked for output that "must read the same", named nothing to compare it against, and a +stray section in the middle of one type-spec survived a check made in good faith. + **Baseline: 1.0.0.** Migrations that predate it - the type-system move, the `confidence_base` backfill, the German section headings, the translation itself - have no documents and will not get any. An instance older than that is re-exported, not migrated. diff --git a/instructions/migrations/6.0.0-type-guidance-split.md b/instructions/migrations/6.0.0-type-guidance-split.md index 4f9f537..2c7bb75 100644 --- a/instructions/migrations/6.0.0-type-guidance-split.md +++ b/instructions/migrations/6.0.0-type-guidance-split.md @@ -56,7 +56,7 @@ upgrade(s) available"; taking it is not gated on anything else being current. shipped default.** Compare the type-spec's current prose (everything outside `## Frontmatter` and `## Template`) against the corresponding `types/.guidance.md`: - - **Unchanged, or changed only in ways this instance is happy to lose:** proceed to step 3 + - **Unchanged, or changed only in ways this instance is happy to lose:** proceed to step 4 directly - the new guidance file already carries the improved version. - **Locally edited in a way worth keeping** (a house style note, an extra rule specific to this corpus): that edit has to move somewhere before the old prose is dropped. Either fold @@ -65,28 +65,69 @@ upgrade(s) available"; taking it is not gated on anything else being current. instead of adding `guidance:` at all - both are legitimate; declining the stack default for one type is not an error. -3. **Add `guidance: types/.guidance.md` to the type-spec's frontmatter** - by hand, the same +3. **Write down what `types describe` answers today, before changing anything.** Step 6 checks + that the composed answer still reads the same, and that is only a check if the "before" was + recorded somewhere other than your memory: + + ```bash + tools/wikitool types describe > /tmp/-before.txt + ``` + + The whole output, per type-spec you are about to touch. Reading it through `head` or `tail` + instead is how a difference in the middle of a 150-line answer survives the check - and a + stray section in the middle of one type-spec is exactly what this step exists to catch. + +4. **Add `guidance: types/.guidance.md` to the type-spec's frontmatter** - by hand, the same way any other type-spec frontmatter field is written (a type-spec is machinery, not a `kb/` page, so this is not a `wikitool touch` call). Do not remove `## Frontmatter` or `## Template`; only the generic prose around them is what the guidance file now carries. -4. **Delete the now-duplicated prose from the type-spec**, keeping the H1, a short pointer to the - guidance file (`types/entity.md`'s own current text is the worked example), `## Frontmatter` - and `## Template`. Where step 2 found a local edit worth keeping and it lives in the - type-spec's own body rather than a private guidance file, leave that part exactly where it is. +5. **Delete the now-duplicated prose from the type-spec**, keeping the H1, a short pointer to the + guidance file, `## Frontmatter` and `## Template`. Where step 2 found a local edit worth + keeping and it lives in the type-spec's own body rather than a private guidance file, leave + that part exactly where it is. -5. **Verify:** + **The worked example is `types/.md.template`, not `types/.md`.** The latter is the + copy this instance adopted at setup - it is the file you are editing, so it still shows the + before-state. The `.template` beside it ships verbatim with every release and already carries + the after-state: H1, pointer paragraph, and `guidance:` in the frontmatter. Read it for the + shape; do not copy it wholesale, because its `## Frontmatter` and `## Template` are the + stack's defaults and yours are yours. + + **The pointer paragraph is written in English**, like the H1 above it. It is authoring prose + addressed to an agent, so it belongs to the control plane whether or not this instance owns + the file it sits in - and so does any prose you keep beside it. A local note written in this + instance's KB language before that rule existed is therefore translated, not relabelled: + an English heading over a body in another language is the half-done version of this step. + [types/type-spec.md](../../types/type-spec.md#who-owns-a-type-spec) has the part-by-part + table; `## Frontmatter` and `## Template` are untouched by this migration either way. + + **Do not head a kept note `## Authoring guidance`.** `types describe` sets that heading itself + and inlines the guidance file beneath it, which brings its own - so a third one out of the + type-spec's body reads as a duplicated section in the composed answer. Give a local note a + name of its own. + +6. **Verify against the file from step 3:** ```bash - tools/wikitool types describe + tools/wikitool types describe > /tmp/-after.txt + diff /tmp/-before.txt /tmp/-after.txt ``` - The output must read the same as it did before this migration - the guidance prose composed - ahead of the type-spec's own body, in one answer. A diff against the pre-migration output of - the same command, restricted to wording, is expected only where step 2 found something to - drop or fold in; the structure (frontmatter fields, template block) must be byte-identical. + The two must read the same - the guidance prose composed ahead of the type-spec's own body, + in one answer. Wording differences are expected only where step 2 found something to drop or + fold in; the structure (frontmatter fields, template block) must be byte-identical, and a + heading that stands in the "after" but not in the "before" means prose was renamed where it + should have been removed. One number catches the most likely version of that: -6. **Record it:** + ```bash + grep -c '^## Authoring guidance' /tmp/-after.txt + ``` + + Two is correct - the one `types describe` sets, and the one the guidance file brings. Three + means the type-spec's own body still carries a section of that name (step 5). + +7. **Record it:** ```bash tools/wikitool migrate done 6.0.0 --pages 0 diff --git a/types/source.md b/types/source.md index 747a20d..54d86d8 100644 --- a/types/source.md +++ b/types/source.md @@ -44,10 +44,6 @@ how to write a conforming page is [types/source.guidance.md](source.guidance.md) | `concepts` | No | Titles of the concepts mentioned in this source | | `summary` | Yes | One-liner for `kb/index.md` | -## Authoring guidance - -- The title starts with "Source - ", followed by the name of the source - ## Template The block below is page material, so it is written in this instance's KB language