wikitool new instruction schreibt das Migrationsfeld obligation: required in jede neue Instruktion #109

New Issue

2026-09-16T12:16:00Z

torben commented

2026-09-16 12:16:00 +00:00

Beobachtung

tools/wikitool new instruction --name "<name>" erzeugt (Stand 6.1.0-beta.1):

---
type: types/instruction.md
name: <name>
description: 'TODO: add description'
obligation: required
---

obligation: ist aber ein Migrationsfeld. instructions/CONTRACT.md
§ instructions/migrations/ fuehrt es als eines von drei Feldern, die eine Migration
zusaetzlich traegt (migrates_to:, migration_kind:, obligation:), und
types/instruction.schema.yaml beschreibt es woertlich als "Whether the migration must run at
all". Eine gewoehnliche Instruktion ist keine Migration und hat nichts, was laufen muesste.

Gegenprobe im Baum: ausser der frisch scaffoldeten Datei traegt das Feld nur
instructions/migrations/4.0.0-link-taxonomy.md und
instructions/migrations/6.0.0-type-guidance-split.md - also genau die zwei Migrationsdokumente.
Keine der 20 anderen Instruktionen hat es.

Warum es zaehlt

Nichts bricht: migrate status baut die Kette aus migrates_to:, nicht aus obligation:, und
das Feld ist schemakonform. Der Schaden ist Lesbarkeit an einer Stelle, an der der Stack sonst
sehr genau ist - eine neue Instruktion behauptet in ihrer Frontmatter eine Eigenschaft aus einem
anderen Konzept, und wer das Schema nicht daneben legt, liest es als bedeutungstragend. Beim
Anlegen von instructions/upgrade-instance.md ist das Feld genau so aufgefallen und von Hand
wieder entfernt worden; das naechste Mal bleibt es vielleicht stehen.

Vermutete Ursache (nicht verifiziert): das Scaffold materialisiert Schema-Defaults, und
obligation: hat als einziges der Migrationsfelder einen (default: required).

Akzeptanzkriterien

tools/wikitool new instruction --name "x" erzeugt eine Frontmatter ohne obligation:.
tools/wikitool new erzeugt ein Migrationsdokument weiterhin mit den drei Feldern, sofern
es das heute tut - andernfalls ist dokumentiert, dass eine Migration von Hand ergaenzt wird.
Ein Test deckt die Frontmatter des Scaffolds ab, damit ein spaeter hinzukommender
Schema-Default nicht still wieder einwandert.
docs verify, instructions verify und pytest ohne neue Befunde.

Abgrenzung

Nur das Scaffold. Ob obligation: im Schema einen Default haben soll, ist eine eigene Frage -
instructions/CONTRACT.md beschreibt required ausdruecklich als den Default fuer Migrationen,
und dort ist er richtig.

Gefunden beim Anlegen der Instruktion aus #108.

## Beobachtung `tools/wikitool new instruction --name "<name>"` erzeugt (Stand `6.1.0-beta.1`): ```yaml --- type: types/instruction.md name: <name> description: 'TODO: add description' obligation: required --- ``` `obligation:` ist aber ein **Migrationsfeld**. `instructions/CONTRACT.md` § `instructions/migrations/` fuehrt es als eines von drei Feldern, die eine Migration zusaetzlich traegt (`migrates_to:`, `migration_kind:`, `obligation:`), und `types/instruction.schema.yaml` beschreibt es woertlich als *"Whether the migration must run at all"*. Eine gewoehnliche Instruktion ist keine Migration und hat nichts, was laufen muesste. Gegenprobe im Baum: ausser der frisch scaffoldeten Datei traegt das Feld **nur** `instructions/migrations/4.0.0-link-taxonomy.md` und `instructions/migrations/6.0.0-type-guidance-split.md` - also genau die zwei Migrationsdokumente. Keine der 20 anderen Instruktionen hat es. ## Warum es zaehlt Nichts bricht: `migrate status` baut die Kette aus `migrates_to:`, nicht aus `obligation:`, und das Feld ist schemakonform. Der Schaden ist Lesbarkeit an einer Stelle, an der der Stack sonst sehr genau ist - eine neue Instruktion behauptet in ihrer Frontmatter eine Eigenschaft aus einem anderen Konzept, und wer das Schema nicht daneben legt, liest es als bedeutungstragend. Beim Anlegen von `instructions/upgrade-instance.md` ist das Feld genau so aufgefallen und von Hand wieder entfernt worden; das naechste Mal bleibt es vielleicht stehen. Vermutete Ursache (nicht verifiziert): das Scaffold materialisiert Schema-Defaults, und `obligation:` hat als einziges der Migrationsfelder einen (`default: required`). ## Akzeptanzkriterien - [ ] `tools/wikitool new instruction --name "x"` erzeugt eine Frontmatter ohne `obligation:`. - [ ] `tools/wikitool new` erzeugt ein Migrationsdokument weiterhin mit den drei Feldern, sofern es das heute tut - andernfalls ist dokumentiert, dass eine Migration von Hand ergaenzt wird. - [ ] Ein Test deckt die Frontmatter des Scaffolds ab, damit ein spaeter hinzukommender Schema-Default nicht still wieder einwandert. - [ ] `docs verify`, `instructions verify` und `pytest` ohne neue Befunde. ## Abgrenzung Nur das Scaffold. Ob `obligation:` im Schema einen Default haben soll, ist eine eigene Frage - `instructions/CONTRACT.md` beschreibt `required` ausdruecklich als den Default fuer Migrationen, und dort ist er richtig. Gefunden beim Anlegen der Instruktion aus #108.

torben added the prio/planned size/S area/process kind/defect labels 2026-09-16 12:16:00 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: torben/chemenu#109