torben/chemenu
1
1 Fork 0
Code Issues 35 Pull Requests Actions Packages Releases 37 Activity

Seitenvorlage je Subtyp: wikitool new scaffoldet für eine Person dieselbe Vorlage wie für eine Codebasis #117

New Issue
Closed
opened 2026-09-18 20:53:25 +00:00 by torben · 5 comments
torben commented 2026-09-18 20:53:25 +00:00
Owner
Copy link
Copy source

Stand

Abgeschlossen 2026-10-03. Gebaut und veröffentlicht als d8cb494 (8.0.0-beta.31, --minor in den 8.0.0-Kandidaten), verifiziert durch die CI-Läufe 517 und 518, beide success; lokal davor pytest 2164 passed / 3 skipped (normal und auf leerer Maschine identisch), docs verify, instructions verify. Veröffentlicht nach Freigabe der Mass-Update Gate (25 Dateien).

Abschlussprüfung (stack-close): Drei Dokumente zählten das Seitenmaterial unter types/ noch als ## Template-Block und layout:-Titel allein auf — types/type-spec.md (§ Who owns a type-spec, Prosa und Sprachtabelle), types/type-guidance.md (§ Conventions), docs/language-boundaries.md —, dazu ein Kommentar in dist_cmd. Nachgezogen als dd565d2 (8.0.0-beta.32, --patch), verifiziert durch CI-Läufe 519 und 520, beide success. INSTALL.md gegen die geänderten setup-instance.md/upgrade-instance.md gelesen: beschreibt die Übernahme von Type-Specs nicht, keine Abweichung, kein Folge-Issue. Die Abschlussprüfung lief auf Opus mit reduziertem Effort.

Problem

Eine Type-Spec trug genau einen ## Template-Block für alle Werte ihres subtype_field.
Wo ein Subtyp eine andere Seitenform braucht, scaffoldete tools/wikitool new die falsche, und
Autoren bauten die Seite danach von Hand um. Der Korpus belegte das an zwei Typen:

  • entity_type: person — die gemeinsame Vorlage in types/entity.md listet unter
    ## Kerndaten Version, Sprache/Technik und Repository, für eine Person (oder
    Organisation, die laut types/entity.guidance.md ebenfalls person ist) sinnlos.
    kb/entities/people/Vannevar Bush.md füllt ## Kerndaten deshalb mit
    Geboren/Gestorben/Nationalität, Andrej Karpathy.md ersetzt es durch ## Kernbeiträge.
  • concept_type: decision — 2 der 7 Seiten unter kb/concepts/decisions/ haben die
    Basisvorlage aus types/concept.md (Kernpunkte / Wann zu verwenden / Wann NICHT) von Hand
    durch die ADR-Form Kontext / Entscheidung / Konsequenzen / Status ersetzt.

Vor diesem Paket gab es keinen Mechanismus dafür: TypeResolver.extract_template nahm den
ersten ```markdown-Block im Body der Type-Spec, einziger Aufrufer war
tools/chemenu/commands/new_page.py. Bestehende Seiten wurden durch dieses Paket nicht umgebaut.

Herkunft: Das Issue entstand 2026-09-18 für den damaligen Subtyp entity_type: project.
Dieser Anlass war erledigt — #122 hat den Wert in codebase umbenannt, #123 hat dem Vorhaben
einen eigenen Typ types/project.md mit eigener Vorlage gegeben (#119 D17).

Nebenbefund, gleiche Dateien: types/entity.md (description:) und
types/entity.guidance.md sprachen noch von „projects" bzw. „a software project" — veraltet
seit #122. In diesem Paket auf „codebases"/„a codebase" korrigiert.

Entscheidungen

E1 — Weiterführen. Betreiber 2026-10-03. Die Mechanik ist allgemein, der Bedarf an zwei
Typen belegt.

E2 — Mechanismus: eine flache Datei je Subtyp-Vorlage, types/<typ>.<subtyp-wert>.md.
Betreiber 2026-10-03 („getrennte Template-Files je Ausprägung … übersichtlicher, leichter zu
handhaben, das File muss nicht zerpflückt werden"; flach statt Unterverzeichnis: „Mache
entity.person.md").

  • Die Datei ist das Scaffold: reines Markdown, kein Frontmatter, kein Fence. Ihr Name ist
    die einzige Deklaration — keine zweite Stelle nennt denselben Subtyp.
  • Die Basisvorlage bleibt der ## Template-Block in der Type-Spec. Damit scaffoldet jede
    bereits adoptierte Type-Spec jeder Instanz unverändert.
  • Fortsetzung des Schnitts, den types/<name>.guidance.md schon gemacht hat
    (docs/ownership-and-templates.md § „Where the file boundary used to strain"): eine Datei je
    Publikum. Eine Subtyp-Vorlage ist reines Seitenmaterial in der KB-Sprache.
  • Verworfen: layout.<subtyp>.template: mit Vorlagentext als YAML-Blockstring
    (Seitentext im Frontmatter, Quoting-Fallen, zwei Formen für dieselbe Sache); derselbe Schlüssel
    als Zeiger auf einen Body-Abschnitt (wiederholt die Überschrift, zwei Stellen laufen
    auseinander); Body-Abschnitte ## Template: <wert> (zerpflückt die Type-Spec, mischt weiter
    zwei Publika in einer Datei); types/<typ>/<wert>.md im Unterverzeichnis (Betreiber: flach).
    Eigener Typ je Subtyp war nie eine Option für person (#119 D20).

E3 — Umfang: Mechanik + zwei Beispielvorlagen + eine Interview-Instruction. Betreiber
2026-10-03 („1–2 Beispiele mitliefern und eine manual: true-Instruction mit einem Interview,
das nach nötigen Subvorlagen schaut und beim Anlegen hilft").

E4 — Kein Migrationsdokument. Keine Seite ändert sich, jede adoptierte Type-Spec
funktioniert unverändert. Eine bestehende Instanz bekommt die Beispiele über den normalen Weg:
dist upgrade legt types/entity.person.md.template neben sie, dist adopt übernimmt es. Ein
obligation: offered-Dokument wie 6.0.0-type-guidance-split.md ist nicht nötig, weil keine
adoptierte Datei geändert werden muss — die neue Vorlage ist eine eigene Datei.

Umsetzungsentscheidungen (stack-build)

Im Bau getroffen, innerhalb von E2; keine davon öffnete das Design neu.

  • U1 — Eine Namensregel für alle Aufrufer. type_resolver.split_subtype_template_name(name)
    entscheidet allein nach der Form <stem>.<wert>.md (Wert ≠ guidance, ein Segment ohne Punkt),
    ob eine Datei eine Subtyp-Vorlage ist. toc, dist_cmd._owned_type_stem und docs verify
    fragen alle diese Funktion — eine fehlerhafte Vorlage wird also überall gleich eingeordnet, und
    docs verify meldet sie.
  • U2 — Dritte Prüfung in docs verify: eine Subtyp-Vorlage mit Frontmatter ist ein Fehler.
    Folgt aus E2 („kein Frontmatter"): new liest die Datei als Klartext, ein Frontmatter-Block
    landete als Text in jeder Seite.
  • U3 — new validiert das Frontmatter, bevor es die Vorlage wählt. Der Subtypwert benennt
    eine Datei unter types/, also hat er das Schema-Enum passiert, bevor er so benutzt wird.
    Zusätzlich lehnt TypeResolver.subtype_template_path jeden Wert ab, der kein Dateinamen-Segment
    sein kann.
  • U4 — types describe zeigt Subtyp-Vorlagen nicht. Nicht verlangt und nicht gebaut;
    types/type-spec.md § Anatomy sagt, dass nur new sie liest. Wird es gebraucht, ist das ein
    eigenes Issue.
  • U5 — README.md mitgezogen (Baum unter types/, Zeile „Templates" unter IT-Specific
    Features), zusätzlich zur Doku-Liste unten.

Spezifikation (umgesetzt)

Auflösung

  • Eine Datei unter types/ ist eine Subtyp-Vorlage, wenn ihr Name <stem>.<rest>.md ist
    und <rest> nicht guidance ist (U1). Ob types/<stem>.md eine Type-Spec mit
    subtype_field ist, prüft docs verify. <stem> endet am ersten Punkt (Typnamen erfüllen
    ^[a-z][a-z0-9-]*$, enthalten also nie einen).
  • new nimmt types/<stem>.<wert>.md, wobei <wert> der Wert des subtype_field im gebauten
    Frontmatter ist, wenn die Datei existiert; sonst den ## Template-Block wie bisher (gleiche
    Extraktionsregel, unverändert). Umgesetzt als TypeResolver.page_template(spec, wert).
  • Ganze Ersetzung, kein Mischen. Die Subtyp-Vorlage ersetzt die Basis vollständig. Dieselben
    Template-Variablen und Filter (types/type-spec.md § Template variables).
  • guidance ist reserviert. types/<stem>.guidance.md ist immer die Guidance-Datei; der
    Subtypwert guidance kann keine Datei-Vorlage haben. types/type-spec.md sagt das.
  • Eine Subtyp-Vorlage hat kein Frontmatter und wird deshalb von
    TypeResolver.list_type_specs() nicht als Type-Spec gezählt.

Prüfung (docs verify, check_subtype_templates)

Fehler, mit Datei und Wert im Text:

  • types/<stem>.<rest>.md, <rest> ≠ guidance, und types/<stem>.md ist keine Type-Spec
    oder hat kein subtype_field (verwaiste Vorlage).
  • <rest> ist kein Wert, den das Schema für das subtype_field zulässt (Tippfehler → tote
    Vorlage). Ohne Enum keine Prüfung.
  • Die Datei trägt Frontmatter (U2).

TOC

Subtyp-Vorlagen sind vom TOC-Scope (toc.target_files) ausgenommen, unabhängig von ihrer Länge.
Invariante: keine Datei, die new als Scaffold liest, enthält je einen wikitool:toc-Marker.

Eigentum und Auslieferung

Subtyp-Vorlagen sind Seitenmaterial einer root: kb-Type-Spec, gehören also der Instanz und
werden wie ihre Type-Spec nur als .template ausgeliefert.

Stelle Änderung
dist_cmd._owned_type_stem erkennt <stem>.<rest>.md (≠ .guidance.md) als zum Typ <stem> gehörig
dist_cmd._plan_types benennt sie damit in types/<stem>.<rest>.md.template um
dist_cmd.find_leaks meldet eine solche Datei ohne .template im Export als Leck
dist_cmd.adoptable_templates schon abgedeckt (types/*.template, flach) — im Test bestätigt
instructions/upgrade-instance.md Schritt 5 nennt die neue Form: übernehmen mit dist adopt oder liegen lassen; beides gültig

Invariante für die Auslieferung: kein Export enthält eine Subtyp-Vorlage unter ihrem
unsuffixierten Namen, und kein dist upgrade schreibt je auf eine adoptierte Subtyp-Vorlage
(dist upgrade schreibt nur, was der neue Stamp listet; Test über _write_candidates).

Beispielvorlagen (deutsch, Seitenmaterial)

  • types/entity.person.md: Titel · **Typ:** · Beschreibung · Kerndaten (Rolle, Zugehörigkeit,
    Wirkungszeitraum — je „falls zutreffend") · Beiträge · Historie.
  • types/concept.decision.md: Titel · **Typ:** · Definition · Kontext · Entscheidung ·
    Alternativen · Konsequenzen · Status.
  • Beide tragen keine tool-eigene Region.

Interview-Instruction instructions/subtype-templates.md

manual: true — von keinem Skill und nicht aus AGENTS.md verlinkt; erwähnt aus
instructions/evolve-subtypes.md (neuer Schritt 5), instructions/setup-instance.md
(Schritt 4.1, als spätere Frage), instructions/upgrade-instance.md (Schritt 5) und
types/type-spec.md. Englisch. Ablauf: Typen/Werte auflisten → Seiten je Wert gegen ihre
Vorlage halten → ≥3-Seiten-Schwelle → ausgeliefertes .template als Ausgangspunkt anbieten →
je Kandidat dem Nutzer vorlegen → schreiben bzw. dist adopt, dann docs verify → bestehende
Seiten nicht umbauen.

Akzeptanzkriterien

Alle erfüllt mit d8cb494, verifiziert durch CI-Läufe 517 und 518; die Doku-Nachträge der
Abschlussprüfung mit dd565d2, CI-Läufe 519 und 520.

  • tools/wikitool new entity --name X --set entity_type=person erzeugt eine Seite ohne
    Version, Sprache/Technik und Repository, deren Body types/entity.person.md
    entspricht (Variablen ersetzt). — test_new_person_scaffolds_the_person_template
  • tools/wikitool new concept --name X --set concept_type=decision erzeugt eine Seite, deren
    Body types/concept.decision.md entspricht. — test_new_decision_scaffolds_the_decision_template
  • Jeder Subtyp ohne eigene Vorlagendatei, und jeder Typ ohne subtype_field, erzeugt
    byte-identisches Scaffold wie vor der Änderung     — geprüft für alle Typen unter types/.
    — test_every_shipped_type_scaffolds_its_base_template_where_no_subtype_file_exists
  • TypeResolver.list_type_specs() liefert dieselbe Menge wie vor der Änderung.
    — test_list_type_specs_counts_no_subtype_template
  • docs verify schlägt fehl für eine verwaiste Subtyp-Vorlage und für eine mit einem Wert
    außerhalb des Enums; der Fehlertext nennt Datei und Wert. types/<stem>.guidance.md löst
    keinen der beiden aus. — test_docs_verify.py (4 Tests)
  • Eine Subtyp-Vorlage über 100 Zeilen bekommt keine TOC-Region, und docs verify verlangt
    keine. — test_target_files_leaves_out_subtype_templates
  • dist export-Plan: types/entity.person.md.template und
    types/concept.decision.md.template sind enthalten, die unsuffixierten Namen nicht;
    find_leaks meldet eine untergeschobene unsuffixierte Subtyp-Vorlage.
    — test_this_repos_export_plan_carries_both_example_subtype_templates,
    test_subtype_template_ships_only_as_template_and_upgrade_never_writes_it,
    test_find_leaks_catches_one_instance_own_data[types/entity.person.md]
  • dist adopt ohne Pfad bietet die .template an und übernimmt sie byte-identisch.
    — test_adopt_without_a_path_copies_every_collection_and_type_template
  • pytest deckt alle obigen Fälle ab.
  • instructions/subtype-templates.md existiert mit manual: true, ist von keinem Skill und
    nicht aus AGENTS.md verlinkt, wird aus evolve-subtypes.md und setup-instance.md
    erwähnt und nennt die ≥3-Seiten-Schwelle; instructions verify grün.
  • types/entity.md und types/entity.guidance.md sprechen nicht mehr von „projects".
  • Doku nachgezogen: AGENTS.md § File naming (Zeile types/<name>.<subtype>.md),
    types/type-spec.md (§ Anatomy, § Template variables, § Who owns a type-spec samt
    Sprachtabelle), types/type-guidance.md, instructions/upgrade-instance.md Schritt 5,
    docs/ownership-and-templates.md § „The consequence in practice",
    docs/language-boundaries.md, cli_contract-Datensätze von new, docs verify,
    docs toc, dist export, dist adopt (und damit tools/CONTRACT.md), README.md (U5).
  • tools/wikitool docs verify und tools/wikitool instructions verify grün.

Versionsteil

Gelandet im offenen Kandidaten 8.0.0: --minor → 8.0.0-beta.31 (max-wins hielt den
Kandidaten bei 8.0.0; kein zweites --breaking), Abschluss-Nachtrag --patch →
8.0.0-beta.32. Kein Migrationsdokument (E4). Damit vor dem Release von 8.0.0 gelandet, wie
vorausgesetzt.

Für sich genommen gegen instructions/dev/version-parts.md:

  • Vorwärts: neue Maschinerie über eine Instanz kopiert → keine Subtyp-Vorlagendatei vorhanden
    (sie kommen nur als .template), jede Type-Spec scaffoldet byte-identisch. Kein Handgriff.
  • Rückwärts: eine Instanz, die types/entity.person.md adoptiert hat, setzt die alte Maschine
    zurück → alte new ignoriert die Datei (Basisvorlage). Ob ein alter docs verify die Datei
    ablehnt, wurde nicht geprüft — innerhalb des 8.0.0-Kandidaten ohne Folge, weil keine Instanz
    eine Vorversion dieses Kandidaten erhält.

Sprache

Subtyp-Vorlagen sind Seitenmaterial, also in der KB-Sprache (kb/CONVENTIONS.md language:,
hier deutsch); Dateinamen und Subtypwerte sind Identifier. Die neue Instruction und alle
Ergänzungen an Contracts, AGENTS.md und docs/ sind Control Plane, also englisch.

Berührte Dateien

  • tools/chemenu/type_resolver.py (split_subtype_template_name, subtype_template_path,
    page_template)
  • tools/chemenu/commands/new_page.py (Subtypwert durchreichen, Datensatz)
  • tools/chemenu/commands/docs_verify.py (check_subtype_templates, Datensätze docs verify
    und docs toc)
  • tools/chemenu/toc.py (Subtyp-Vorlagen aus dem Scope)
  • tools/chemenu/commands/dist_cmd.py (_owned_type_stem, Doku _plan_types, find_leaks,
    Datensätze dist export/dist adopt)
  • types/entity.person.md, types/concept.decision.md (neu)
  • types/entity.md (description:), types/entity.guidance.md, types/type-spec.md,
    types/type-guidance.md
  • instructions/subtype-templates.md (neu), instructions/evolve-subtypes.md,
    instructions/setup-instance.md, instructions/upgrade-instance.md
  • AGENTS.md § File naming, docs/ownership-and-templates.md, docs/language-boundaries.md,
    README.md
  • tools/CONTRACT.md (generiert)
  • Tests: test_type_resolver.py, test_new_page.py, test_docs_verify.py, test_toc.py,
    test_dist_cmd.py
  • CHANGES.md über version bump

Abhängigkeit

Keine. #119 ist abgeschlossen; #118 (Beteiligungs-Label) ist unabhängig.

## Stand **Abgeschlossen 2026-10-03.** Gebaut und veröffentlicht als `d8cb494` (`8.0.0-beta.31`, `--minor` in den 8.0.0-Kandidaten), verifiziert durch die CI-Läufe [517](https://gitea.nehmer.net/torben/chemenu/actions/runs/517) und [518](https://gitea.nehmer.net/torben/chemenu/actions/runs/518), beide `success`; lokal davor `pytest` 2164 passed / 3 skipped (normal und auf leerer Maschine identisch), `docs verify`, `instructions verify`. Veröffentlicht nach Freigabe der Mass-Update Gate (25 Dateien). **Abschlussprüfung (stack-close):** Drei Dokumente zählten das Seitenmaterial unter `types/` noch als `## Template`-Block und `layout:`-Titel allein auf — `types/type-spec.md` (§ Who owns a type-spec, Prosa und Sprachtabelle), `types/type-guidance.md` (§ Conventions), `docs/language-boundaries.md` —, dazu ein Kommentar in `dist_cmd`. Nachgezogen als `dd565d2` (`8.0.0-beta.32`, `--patch`), verifiziert durch CI-Läufe [519](https://gitea.nehmer.net/torben/chemenu/actions/runs/519) und [520](https://gitea.nehmer.net/torben/chemenu/actions/runs/520), beide `success`. `INSTALL.md` gegen die geänderten `setup-instance.md`/`upgrade-instance.md` gelesen: beschreibt die Übernahme von Type-Specs nicht, keine Abweichung, kein Folge-Issue. Die Abschlussprüfung lief auf Opus mit reduziertem Effort. ## Problem Eine Type-Spec trug genau **einen** `## Template`-Block für alle Werte ihres `subtype_field`. Wo ein Subtyp eine andere Seitenform braucht, scaffoldete `tools/wikitool new` die falsche, und Autoren bauten die Seite danach von Hand um. Der Korpus belegte das an zwei Typen: - **`entity_type: person`** — die gemeinsame Vorlage in `types/entity.md` listet unter `## Kerndaten` `Version`, `Sprache/Technik` und `Repository`, für eine Person (oder Organisation, die laut `types/entity.guidance.md` ebenfalls `person` ist) sinnlos. `kb/entities/people/Vannevar Bush.md` füllt `## Kerndaten` deshalb mit Geboren/Gestorben/Nationalität, `Andrej Karpathy.md` ersetzt es durch `## Kernbeiträge`. - **`concept_type: decision`** — 2 der 7 Seiten unter `kb/concepts/decisions/` haben die Basisvorlage aus `types/concept.md` (Kernpunkte / Wann zu verwenden / Wann NICHT) von Hand durch die ADR-Form Kontext / Entscheidung / Konsequenzen / Status ersetzt. Vor diesem Paket gab es keinen Mechanismus dafür: `TypeResolver.extract_template` nahm den ersten ```` ```markdown ````-Block im Body der Type-Spec, einziger Aufrufer war `tools/chemenu/commands/new_page.py`. Bestehende Seiten wurden durch dieses Paket nicht umgebaut. **Herkunft:** Das Issue entstand 2026-09-18 für den damaligen Subtyp `entity_type: project`. Dieser Anlass war erledigt — #122 hat den Wert in `codebase` umbenannt, #123 hat dem Vorhaben einen eigenen Typ `types/project.md` mit eigener Vorlage gegeben (#119 D17). **Nebenbefund, gleiche Dateien:** `types/entity.md` (`description:`) und `types/entity.guidance.md` sprachen noch von „projects" bzw. „a software project" — veraltet seit #122. In diesem Paket auf „codebases"/„a codebase" korrigiert. ## Entscheidungen **E1 — Weiterführen.** Betreiber 2026-10-03. Die Mechanik ist allgemein, der Bedarf an zwei Typen belegt. **E2 — Mechanismus: eine flache Datei je Subtyp-Vorlage, `types/<typ>.<subtyp-wert>.md`.** Betreiber 2026-10-03 („getrennte Template-Files je Ausprägung … übersichtlicher, leichter zu handhaben, das File muss nicht zerpflückt werden"; flach statt Unterverzeichnis: „Mache `entity.person.md`"). - Die Datei **ist** das Scaffold: reines Markdown, kein Frontmatter, kein Fence. Ihr Name ist die einzige Deklaration — keine zweite Stelle nennt denselben Subtyp. - Die Basisvorlage bleibt der `## Template`-Block in der Type-Spec. Damit scaffoldet jede bereits adoptierte Type-Spec jeder Instanz unverändert. - Fortsetzung des Schnitts, den `types/<name>.guidance.md` schon gemacht hat (`docs/ownership-and-templates.md` § „Where the file boundary used to strain"): eine Datei je Publikum. Eine Subtyp-Vorlage ist reines Seitenmaterial in der KB-Sprache. - **Verworfen:** `layout.<subtyp>.template:` mit Vorlagentext als YAML-Blockstring (Seitentext im Frontmatter, Quoting-Fallen, zwei Formen für dieselbe Sache); derselbe Schlüssel als Zeiger auf einen Body-Abschnitt (wiederholt die Überschrift, zwei Stellen laufen auseinander); Body-Abschnitte `## Template: <wert>` (zerpflückt die Type-Spec, mischt weiter zwei Publika in einer Datei); `types/<typ>/<wert>.md` im Unterverzeichnis (Betreiber: flach). Eigener Typ je Subtyp war nie eine Option für `person` (#119 D20). **E3 — Umfang: Mechanik + zwei Beispielvorlagen + eine Interview-Instruction.** Betreiber 2026-10-03 („1–2 Beispiele mitliefern und eine `manual: true`-Instruction mit einem Interview, das nach nötigen Subvorlagen schaut und beim Anlegen hilft"). **E4 — Kein Migrationsdokument.** Keine Seite ändert sich, jede adoptierte Type-Spec funktioniert unverändert. Eine bestehende Instanz bekommt die Beispiele über den normalen Weg: `dist upgrade` legt `types/entity.person.md.template` neben sie, `dist adopt` übernimmt es. Ein `obligation: offered`-Dokument wie `6.0.0-type-guidance-split.md` ist nicht nötig, weil keine adoptierte Datei geändert werden muss — die neue Vorlage ist eine eigene Datei. ## Umsetzungsentscheidungen (stack-build) Im Bau getroffen, innerhalb von E2; keine davon öffnete das Design neu. - **U1 — Eine Namensregel für alle Aufrufer.** `type_resolver.split_subtype_template_name(name)` entscheidet allein nach der Form `<stem>.<wert>.md` (Wert ≠ `guidance`, ein Segment ohne Punkt), ob eine Datei eine Subtyp-Vorlage ist. `toc`, `dist_cmd._owned_type_stem` und `docs verify` fragen alle diese Funktion — eine fehlerhafte Vorlage wird also überall gleich eingeordnet, und `docs verify` meldet sie. - **U2 — Dritte Prüfung in `docs verify`: eine Subtyp-Vorlage mit Frontmatter ist ein Fehler.** Folgt aus E2 („kein Frontmatter"): `new` liest die Datei als Klartext, ein Frontmatter-Block landete als Text in jeder Seite. - **U3 — `new` validiert das Frontmatter, bevor es die Vorlage wählt.** Der Subtypwert benennt eine Datei unter `types/`, also hat er das Schema-Enum passiert, bevor er so benutzt wird. Zusätzlich lehnt `TypeResolver.subtype_template_path` jeden Wert ab, der kein Dateinamen-Segment sein kann. - **U4 — `types describe` zeigt Subtyp-Vorlagen nicht.** Nicht verlangt und nicht gebaut; `types/type-spec.md` § Anatomy sagt, dass nur `new` sie liest. Wird es gebraucht, ist das ein eigenes Issue. - **U5 — `README.md` mitgezogen** (Baum unter `types/`, Zeile „Templates" unter IT-Specific Features), zusätzlich zur Doku-Liste unten. ## Spezifikation (umgesetzt) ### Auflösung - Eine Datei unter `types/` ist eine **Subtyp-Vorlage**, wenn ihr Name `<stem>.<rest>.md` ist und `<rest>` nicht `guidance` ist (U1). Ob `types/<stem>.md` eine Type-Spec mit `subtype_field` ist, prüft `docs verify`. `<stem>` endet am ersten Punkt (Typnamen erfüllen `^[a-z][a-z0-9-]*$`, enthalten also nie einen). - `new` nimmt `types/<stem>.<wert>.md`, wobei `<wert>` der Wert des `subtype_field` im gebauten Frontmatter ist, wenn die Datei existiert; sonst den `## Template`-Block wie bisher (gleiche Extraktionsregel, unverändert). Umgesetzt als `TypeResolver.page_template(spec, wert)`. - **Ganze Ersetzung, kein Mischen.** Die Subtyp-Vorlage ersetzt die Basis vollständig. Dieselben Template-Variablen und Filter (`types/type-spec.md` § Template variables). - **`guidance` ist reserviert.** `types/<stem>.guidance.md` ist immer die Guidance-Datei; der Subtypwert `guidance` kann keine Datei-Vorlage haben. `types/type-spec.md` sagt das. - Eine Subtyp-Vorlage hat kein Frontmatter und wird deshalb von `TypeResolver.list_type_specs()` nicht als Type-Spec gezählt. ### Prüfung (`docs verify`, `check_subtype_templates`) Fehler, mit Datei und Wert im Text: - `types/<stem>.<rest>.md`, `<rest>` ≠ `guidance`, und `types/<stem>.md` ist keine Type-Spec **oder** hat kein `subtype_field` (verwaiste Vorlage). - `<rest>` ist kein Wert, den das Schema für das `subtype_field` zulässt (Tippfehler → tote Vorlage). Ohne Enum keine Prüfung. - Die Datei trägt Frontmatter (U2). ### TOC Subtyp-Vorlagen sind vom TOC-Scope (`toc.target_files`) ausgenommen, unabhängig von ihrer Länge. Invariante: keine Datei, die `new` als Scaffold liest, enthält je einen `wikitool:toc`-Marker. ### Eigentum und Auslieferung Subtyp-Vorlagen sind Seitenmaterial einer `root: kb`-Type-Spec, gehören also der Instanz und werden wie ihre Type-Spec nur als `.template` ausgeliefert. | Stelle | Änderung | |---|---| | `dist_cmd._owned_type_stem` | erkennt `<stem>.<rest>.md` (≠ `.guidance.md`) als zum Typ `<stem>` gehörig | | `dist_cmd._plan_types` | benennt sie damit in `types/<stem>.<rest>.md.template` um | | `dist_cmd.find_leaks` | meldet eine solche Datei ohne `.template` im Export als Leck | | `dist_cmd.adoptable_templates` | schon abgedeckt (`types/*.template`, flach) — im Test bestätigt | | `instructions/upgrade-instance.md` Schritt 5 | nennt die neue Form: übernehmen mit `dist adopt` oder liegen lassen; beides gültig | Invariante für die Auslieferung: **kein Export enthält eine Subtyp-Vorlage unter ihrem unsuffixierten Namen, und kein `dist upgrade` schreibt je auf eine adoptierte Subtyp-Vorlage** (`dist upgrade` schreibt nur, was der neue Stamp listet; Test über `_write_candidates`). ### Beispielvorlagen (deutsch, Seitenmaterial) - `types/entity.person.md`: Titel · `**Typ:**` · Beschreibung · Kerndaten (Rolle, Zugehörigkeit, Wirkungszeitraum — je „falls zutreffend") · Beiträge · Historie. - `types/concept.decision.md`: Titel · `**Typ:**` · Definition · Kontext · Entscheidung · Alternativen · Konsequenzen · Status. - Beide tragen keine tool-eigene Region. ### Interview-Instruction `instructions/subtype-templates.md` `manual: true` — von keinem Skill und nicht aus `AGENTS.md` verlinkt; erwähnt aus `instructions/evolve-subtypes.md` (neuer Schritt 5), `instructions/setup-instance.md` (Schritt 4.1, als spätere Frage), `instructions/upgrade-instance.md` (Schritt 5) und `types/type-spec.md`. Englisch. Ablauf: Typen/Werte auflisten → Seiten je Wert gegen ihre Vorlage halten → ≥3-Seiten-Schwelle → ausgeliefertes `.template` als Ausgangspunkt anbieten → je Kandidat dem Nutzer vorlegen → schreiben bzw. `dist adopt`, dann `docs verify` → bestehende Seiten nicht umbauen. ## Akzeptanzkriterien Alle erfüllt mit `d8cb494`, verifiziert durch CI-Läufe 517 und 518; die Doku-Nachträge der Abschlussprüfung mit `dd565d2`, CI-Läufe 519 und 520. - [x] `tools/wikitool new entity --name X --set entity_type=person` erzeugt eine Seite ohne `Version`, `Sprache/Technik` und `Repository`, deren Body `types/entity.person.md` entspricht (Variablen ersetzt). — `test_new_person_scaffolds_the_person_template` - [x] `tools/wikitool new concept --name X --set concept_type=decision` erzeugt eine Seite, deren Body `types/concept.decision.md` entspricht. — `test_new_decision_scaffolds_the_decision_template` - [x] **Jeder Subtyp ohne eigene Vorlagendatei, und jeder Typ ohne `subtype_field`, erzeugt byte-identisches Scaffold wie vor der Änderung** — geprüft für alle Typen unter `types/`. — `test_every_shipped_type_scaffolds_its_base_template_where_no_subtype_file_exists` - [x] `TypeResolver.list_type_specs()` liefert dieselbe Menge wie vor der Änderung. — `test_list_type_specs_counts_no_subtype_template` - [x] `docs verify` schlägt fehl für eine verwaiste Subtyp-Vorlage und für eine mit einem Wert außerhalb des Enums; der Fehlertext nennt Datei und Wert. `types/<stem>.guidance.md` löst keinen der beiden aus. — `test_docs_verify.py` (4 Tests) - [x] Eine Subtyp-Vorlage über 100 Zeilen bekommt keine TOC-Region, und `docs verify` verlangt keine. — `test_target_files_leaves_out_subtype_templates` - [x] `dist export`-Plan: `types/entity.person.md.template` und `types/concept.decision.md.template` sind enthalten, die unsuffixierten Namen nicht; `find_leaks` meldet eine untergeschobene unsuffixierte Subtyp-Vorlage. — `test_this_repos_export_plan_carries_both_example_subtype_templates`, `test_subtype_template_ships_only_as_template_and_upgrade_never_writes_it`, `test_find_leaks_catches_one_instance_own_data[types/entity.person.md]` - [x] `dist adopt` ohne Pfad bietet die `.template` an und übernimmt sie byte-identisch. — `test_adopt_without_a_path_copies_every_collection_and_type_template` - [x] `pytest` deckt alle obigen Fälle ab. - [x] `instructions/subtype-templates.md` existiert mit `manual: true`, ist von keinem Skill und nicht aus `AGENTS.md` verlinkt, wird aus `evolve-subtypes.md` und `setup-instance.md` erwähnt und nennt die ≥3-Seiten-Schwelle; `instructions verify` grün. - [x] `types/entity.md` und `types/entity.guidance.md` sprechen nicht mehr von „projects". - [x] Doku nachgezogen: `AGENTS.md` § File naming (Zeile `types/<name>.<subtype>.md`), `types/type-spec.md` (§ Anatomy, § Template variables, § Who owns a type-spec samt Sprachtabelle), `types/type-guidance.md`, `instructions/upgrade-instance.md` Schritt 5, `docs/ownership-and-templates.md` § „The consequence in practice", `docs/language-boundaries.md`, `cli_contract`-Datensätze von `new`, `docs verify`, `docs toc`, `dist export`, `dist adopt` (und damit `tools/CONTRACT.md`), `README.md` (U5). - [x] `tools/wikitool docs verify` und `tools/wikitool instructions verify` grün. ## Versionsteil Gelandet im offenen Kandidaten **`8.0.0`**: `--minor` → `8.0.0-beta.31` (max-wins hielt den Kandidaten bei 8.0.0; kein zweites `--breaking`), Abschluss-Nachtrag `--patch` → `8.0.0-beta.32`. Kein Migrationsdokument (E4). Damit vor dem Release von 8.0.0 gelandet, wie vorausgesetzt. Für sich genommen gegen `instructions/dev/version-parts.md`: - *Vorwärts:* neue Maschinerie über eine Instanz kopiert → keine Subtyp-Vorlagendatei vorhanden (sie kommen nur als `.template`), jede Type-Spec scaffoldet byte-identisch. Kein Handgriff. - *Rückwärts:* eine Instanz, die `types/entity.person.md` adoptiert hat, setzt die alte Maschine zurück → alte `new` ignoriert die Datei (Basisvorlage). Ob ein alter `docs verify` die Datei ablehnt, wurde nicht geprüft — innerhalb des 8.0.0-Kandidaten ohne Folge, weil keine Instanz eine Vorversion dieses Kandidaten erhält. ## Sprache Subtyp-Vorlagen sind Seitenmaterial, also in der KB-Sprache (`kb/CONVENTIONS.md` `language:`, hier deutsch); Dateinamen und Subtypwerte sind Identifier. Die neue Instruction und alle Ergänzungen an Contracts, `AGENTS.md` und `docs/` sind Control Plane, also englisch. ## Berührte Dateien - `tools/chemenu/type_resolver.py` (`split_subtype_template_name`, `subtype_template_path`, `page_template`) - `tools/chemenu/commands/new_page.py` (Subtypwert durchreichen, Datensatz) - `tools/chemenu/commands/docs_verify.py` (`check_subtype_templates`, Datensätze `docs verify` und `docs toc`) - `tools/chemenu/toc.py` (Subtyp-Vorlagen aus dem Scope) - `tools/chemenu/commands/dist_cmd.py` (`_owned_type_stem`, Doku `_plan_types`, `find_leaks`, Datensätze `dist export`/`dist adopt`) - `types/entity.person.md`, `types/concept.decision.md` (neu) - `types/entity.md` (`description:`), `types/entity.guidance.md`, `types/type-spec.md`, `types/type-guidance.md` - `instructions/subtype-templates.md` (neu), `instructions/evolve-subtypes.md`, `instructions/setup-instance.md`, `instructions/upgrade-instance.md` - `AGENTS.md` § File naming, `docs/ownership-and-templates.md`, `docs/language-boundaries.md`, `README.md` - `tools/CONTRACT.md` (generiert) - Tests: `test_type_resolver.py`, `test_new_page.py`, `test_docs_verify.py`, `test_toc.py`, `test_dist_cmd.py` - `CHANGES.md` über `version bump` ## Abhängigkeit Keine. #119 ist abgeschlossen; #118 (Beteiligungs-Label) ist unabhängig.
torben added the prio/plannedsize/Marea/kbkind/decision labels 2026-09-18 20:53:25 +00:00
torben changed title from Seitenvorlage je Subtyp: `wikitool new` scaffoldet für ein Projekt dieselbe Vorlage wie für eine Person to Seitenvorlage je Subtyp: `wikitool new` scaffoldet für eine Person dieselbe Vorlage wie für eine Codebasis 2026-10-03 09:44:54 +00:00
torben commented 2026-10-03 09:44:54 +00:00
Author
Owner
Copy link
Copy source

Changelog: Prämisse gegen den Baum korrigiert - project ist seit #122/#123 kein Entity-Subtyp mehr, die Projektvorlage existiert als eigener Typ; Titel und Akzeptanzkriterien auf person umgestellt. Mechanismus neu bewertet: A in A1 (Frontmatter, wäre --major) und A2 (Body-Abschnitte ## Template: <wert>, --minor) geteilt, Empfehlung A2. Drei offene Betreiberfragen F1-F3. Nebenbefund: veraltetes „projects" in types/entity.md/entity.guidance.md aufgenommen.

**Changelog:** Prämisse gegen den Baum korrigiert - `project` ist seit #122/#123 kein Entity-Subtyp mehr, die Projektvorlage existiert als eigener Typ; Titel und Akzeptanzkriterien auf `person` umgestellt. Mechanismus neu bewertet: A in A1 (Frontmatter, wäre `--major`) und A2 (Body-Abschnitte `## Template: <wert>`, `--minor`) geteilt, Empfehlung A2. Drei offene Betreiberfragen F1-F3. Nebenbefund: veraltetes „projects" in `types/entity.md`/`entity.guidance.md` aufgenommen.
torben commented 2026-10-03 09:57:47 +00:00
Author
Owner
Copy link
Copy source

Changelog: F1 entschieden (weiterführen). F3 neu gefasst nach Betreibervorgabe: zwei Beispielvorlagen (person, concept_type: decision, beide am Korpus belegt), Interview-Instruction subtype-templates.md (manual: true, ≥3-Seiten-Schwelle), angebotenes Upgrade 8.0.0-subtype-templates.md. Versionsabschnitt korrigiert: Kandidat 8.0.0 ist bereits major, das --major-Argument gegen A1 entfällt; F2 bleibt offen als reine Formfrage.

**Changelog:** F1 entschieden (weiterführen). F3 neu gefasst nach Betreibervorgabe: zwei Beispielvorlagen (`person`, `concept_type: decision`, beide am Korpus belegt), Interview-Instruction `subtype-templates.md` (`manual: true`, ≥3-Seiten-Schwelle), angebotenes Upgrade `8.0.0-subtype-templates.md`. Versionsabschnitt korrigiert: Kandidat 8.0.0 ist bereits major, das `--major`-Argument gegen A1 entfällt; F2 bleibt offen als reine Formfrage.
torben added size/Lkind/build and removed size/Mkind/decision labels 2026-10-03 10:37:42 +00:00
torben commented 2026-10-03 10:37:42 +00:00
Author
Owner
Copy link
Copy source

Changelog: F2 entschieden (Betreiber): eine flache Datei je Subtyp-Vorlage, types/<typ>.<wert>.md; A1 (Frontmatter), A2 (Body-Abschnitte) und Unterverzeichnis verworfen. Neu aus der Prüfung gegen den Baum: guidance als Subtypwert reserviert, Subtyp-Vorlagen aus dem TOC-Scope von toc.py (sonst landet eine TOC-Region im Scaffold), Auslieferung als .template über dist_cmd._owned_type_stem/_plan_types/find_leaks. Angebotenes Migrationsdokument gestrichen (E4) - dist upgrade/dist adopt tragen die Beispiele. Versionsteil: --minor in den offenen 8.0.0-Kandidaten. Relabel: kind/decision → kind/build (alle Fragen entschieden), size/M → size/L (Auslieferungsseite, AGENTS.md, vier Instructions).

**Changelog:** F2 entschieden (Betreiber): eine flache Datei je Subtyp-Vorlage, `types/<typ>.<wert>.md`; A1 (Frontmatter), A2 (Body-Abschnitte) und Unterverzeichnis verworfen. Neu aus der Prüfung gegen den Baum: `guidance` als Subtypwert reserviert, Subtyp-Vorlagen aus dem TOC-Scope von `toc.py` (sonst landet eine TOC-Region im Scaffold), Auslieferung als `.template` über `dist_cmd._owned_type_stem`/`_plan_types`/`find_leaks`. Angebotenes Migrationsdokument gestrichen (E4) - `dist upgrade`/`dist adopt` tragen die Beispiele. Versionsteil: `--minor` in den offenen 8.0.0-Kandidaten. Relabel: `kind/decision` → `kind/build` (alle Fragen entschieden), `size/M` → `size/L` (Auslieferungsseite, `AGENTS.md`, vier Instructions).
torben commented 2026-10-03 14:07:13 +00:00
Author
Owner
Copy link
Copy source

Changelog: Gebaut und veröffentlicht als d8cb494 (8.0.0-beta.31, --minor), CI-Läufe 517/518 grün; alle Akzeptanzkriterien abgehakt, je mit dem Test, der sie prüft. Neu: § Umsetzungsentscheidungen U1–U5 – eine gemeinsame Namensregel (split_subtype_template_name), dritte docs verify-Prüfung auf Frontmatter, Validierung vor der Vorlagenwahl, types describe bewusst unverändert, README.md mitgezogen. Spezifikation auf die gebauten Funktionsnamen nachgezogen; „Stand" ersetzt den Bau-Hinweis.

**Changelog:** Gebaut und veröffentlicht als `d8cb494` (`8.0.0-beta.31`, `--minor`), CI-Läufe 517/518 grün; alle Akzeptanzkriterien abgehakt, je mit dem Test, der sie prüft. Neu: § Umsetzungsentscheidungen U1–U5 – eine gemeinsame Namensregel (`split_subtype_template_name`), dritte `docs verify`-Prüfung auf Frontmatter, Validierung vor der Vorlagenwahl, `types describe` bewusst unverändert, `README.md` mitgezogen. Spezifikation auf die gebauten Funktionsnamen nachgezogen; „Stand" ersetzt den Bau-Hinweis.
torben commented 2026-10-03 15:17:10 +00:00
Author
Owner
Copy link
Copy source

Changelog: Abschlussprüfung: types/type-spec.md, types/type-guidance.md und docs/language-boundaries.md nannten Subtyp-Vorlagen nicht als Seitenmaterial – nachgezogen als dd565d2 (8.0.0-beta.32), CI 519/520 grün. INSTALL.md gegen die geänderten Installations-Instructions gelesen, keine Abweichung. Body in den Endzustand gebracht (Stand, Versionsteil als gelandet, Doku-Liste ergänzt); Issue geschlossen.

**Changelog:** Abschlussprüfung: `types/type-spec.md`, `types/type-guidance.md` und `docs/language-boundaries.md` nannten Subtyp-Vorlagen nicht als Seitenmaterial – nachgezogen als `dd565d2` (`8.0.0-beta.32`), CI 519/520 grün. `INSTALL.md` gegen die geänderten Installations-Instructions gelesen, keine Abweichung. Body in den Endzustand gebracht (Stand, Versionsteil als gelandet, Doku-Liste ergänzt); Issue geschlossen.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
area/corpus
Betrifft Demo-/Testbett-Frage, Inhalt und Umfang von kb/
 area/distribution
Betrifft Auslieferung, Upgrade, Versionierung einer Instanz
 area/kb
Betrifft kb/-Schema, Contract, Confidence, Lint, Wissensbasis
 area/process
Betrifft den Entwicklungsprozess selbst, nicht den Stack als Artefakt
 area/workflow
Betrifft Git, Merge, Branching, Publish, PRs
 kind/build
Spezifiziert, wartet nur noch auf Umsetzungszeit
 kind/decision
Wartet auf eine Betreiberentscheidung
 kind/defect
Befund: Doku und Realitaet, oder zwei Dokus, widersprechen sich
 prio/blocking
Blockiert oder beschaedigt laufende Arbeit - als naechstes
 prio/planned
Traegt bald Zinsen - eingeplant
 prio/waiting
Sinnvoll, wartet auf einen Ausloeser
 size/L
Mehrere Sitzungen oder offene Designfragen vor dem ersten Commit
 size/M
Mehrere Dateien, Contract- oder Instruction-Aenderung, eigener Testaufwand
 size/S
Eine Sitzung, ein Publish, klar umrissener Schnitt
 status/blocked
Wartet auf ein anderes, noch offenes Issue - nicht eigenstaendig bearbeitbar
 status/incoming
Vom Menschen angelegte Anforderung, unvollständig, muss durch den Stack komplettiert werden.
 status/unconfirmed
Gemeldeter Verdacht, noch nicht gegen tatsaechliches Verhalten geprueft - size/prio vorlaeufig
No labels area/kb kind/build prio/planned size/L
Milestone
No items
No Milestone
Assignees
Clear assignees
torben
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#117