diff --git a/CHANGES.md b/CHANGES.md index a3f2caa..c91b31c 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse. --- -## 6.0.0-beta.3 - 2026-09-15 - TOC-Scope auf types/ und docs/ erweitert, Sprachregeln zentralisiert, --breaking akkumuliert +## 6.0.0-beta.4 - 2026-09-15 - types/type-spec.md: Ownership und Sprache getrennt benannt (Nachzug zu #99) **Author:** Torben Nehmer @@ -80,6 +80,7 @@ concern - readable here, never shipped as something to parse. **Low impact** - gates.md/session-setup.md: die Budget-Ausnahme von version regrade haengt an der Aufrufform +- types/type-spec.md: Ownership und Sprache getrennt benannt (Nachzug zu #99) ### gates.md/session-setup.md: die Budget-Ausnahme von version regrade haengt an der Aufrufform @@ -212,6 +213,23 @@ Nebenbefund, den die Scope-Erweiterung sofort aufgedeckt hat: `docs/version-mode jeder ausgelieferten Instanz ein toter Link. Jetzt ein Klartextpfad mit dem Satz, warum er keiner ist. +### types/type-spec.md: Ownership und Sprache getrennt benannt (Nachzug zu #99) + +`types/type-spec.md` sagte weiterhin, Prosa, `## Template`-Body **und Sprache** eines +Seiten-Type-Specs gehoerten der Instanz, die bei anderer KB-Sprache "einfach die Datei +uebersetzt" - genau das Gegenteil des Schnitts, den der Bump davor ausgeliefert hat. Aufgefallen +in der Schlussphase, beim Nachdenken darueber, welche Sprachregel fuer einen *instanz-eigenen* +neuen Seitentyp gilt. + +Der Abschnitt trennt die zwei Fragen jetzt: Ownership sagt, wer eine Zeile aendern darf, die +Sprache folgt davon unabhaengig dem Publikum der Zeile - Anleitungsprosa an einen Agenten ist +Control Plane und englisch, `## Template`-Body und `layout:`-Titel sind Seitentext in der +KB-Sprache, Feldnamen und Enum-Werte sind Identifier und werden nie uebersetzt. Als Tabelle, weil +der Schnitt mitten durch eine Datei laeuft und eine Aufzaehlung im Fliesstext ihn genau deshalb +nicht haelt. Der Satz bindet ausdruecklich auch einen Type-Spec, den eine Instanz sich selbst +schreibt: der ist zwar durchgaengig instanzeigen, aber seine Anleitungshaelfte hat trotzdem einen +Agenten als Leser. + --- ## 5.1.0 - 2026-09-12 - changelog: Kandidaten-Eintrag nach Impact gruppiert, version regrade zur Nachkorrektur, version release verlangt eine Zusammenfassung diff --git a/VERSION b/VERSION index 63e1ef2..09e55f8 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -6.0.0-beta.3 +6.0.0-beta.4 diff --git a/types/type-spec.md b/types/type-spec.md index 2618df4..a79168b 100644 --- a/types/type-spec.md +++ b/types/type-spec.md @@ -67,12 +67,27 @@ frontmatter before anyone drew it: | `root: kb` (`entity`, `concept`, `source`, `comparison`) | A page **this instance** writes | The instance | `types/.md.template` plus its `.schema.yaml.template`, adopted by a rename | | `root: repo` (`instruction`), no `base_dir` (`lint-report`), and `type-spec` itself | A stack artifact | The stack | Verbatim | -A page type-spec's prose, its `## Template` body and its language are therefore the instance's -to rewrite — an instance writing its pages in another language simply translates the file, and +A page type-spec's prose and its `## Template` body are therefore the instance's to rewrite, and an upgrade does not take that back. Improvements to a shipped default reach it as an *offered* migration ([instructions/CONTRACT.md](../instructions/CONTRACT.md#instructionsmigrations)), never by overwriting. +**Ownership and language are not the same question here**, and this is the one file in the tree +where they come apart. Owning the file means the instance may rewrite any of it; the language it +writes in still follows what the line is *for*, per +[AGENTS.md § File naming](../AGENTS.md#file-naming): + +| Part of a page type-spec | Audience | Language | +|---|---|---| +| Authoring guidance, frontmatter table, when to use / not to use | An agent writing a page | The control plane's — English | +| The `## Template` body, and the `layout:` titles that head a catalog section | The page itself | The instance's KB language (`kb/CONVENTIONS.md` `language:`) | +| Field names, enum values, `dir:` values, `type:` paths | The machine | Neither — identifiers, never translated | + +That is the same prose/identifier cut [kb/CONTRACT.md](../kb/CONTRACT.md#language-and-identifiers) +makes *inside* a page, applied one level up. It binds a type-spec an instance writes for itself +exactly as it binds the four shipped ones: a new page type is instance-owned end to end, which +settles who may change it, not which language each half is written in. + **What the stack still requires of the type layer is one line.** There must be a type-spec declaring `name: source` whose schema requires `raw_files:` — the whole `raw/` → `kb/` provenance path (`sources coverage`, `[^cite-id]` resolution, `kb/provenance.md`) asks @@ -175,7 +190,7 @@ replace anyway. See `tools/chemenu/blocks.py`. | Frontmatter fields, enums, defaults, required-ness | Provenance and citation mechanics | Quality goal and tone | | Directory placement and title prefix | Linking mechanics and the orphan check | Naming conventions | | Body skeleton (template) | The prose/identifier rule | Relationship vocabulary | -| When to use / not use this type | — | The KB language and its section-heading names | +| When to use / not use this type | — | The KB language value, and its section-heading names | If a rule would be identical for every type *and* every instance, it belongs in `kb/CONTRACT.md`. If every instance would answer it differently, it belongs in