stack: TOC-Scope auf types/ und docs/, Sprachregeln nach AGENTS.md zentralisiert, alle Templates auf Control-Plane-Sprache, --breaking akkumuliert (schliesst #99)

Files changed: - AGENTS.md - CHANGES.md - ENVIRONMENT.md.template - SOUL.md - SOUL.md.template - USER.md.template - VERSION - docs/ownership-and-templates.md - docs/version-model.md - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - instructions/setup-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/concepts/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/chemenu/commands/types_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/toc.py - tools/chemenu/version.py - types/comparison.md - types/concept.md - types/entity.md - types/lint-report.md - types/source.md
2026-09-15 16:21:02 +02:00
parent c0dc2129bb
commit c64479fe02
31 changed files with 1093 additions and 603 deletions
@@ -1,7 +1,7 @@
 ---
 type: types/type-spec.md
 name: source
-description: Strukturierter Typ für Source-Seiten, die eingelesenes Rohmaterial erfassen und zusammenfassen
+description: Structured type for source pages that record and summarize ingested raw material
 schema: types/source.schema.yaml
 subtype_field: source_type
 base_dir: sources
@@ -20,71 +20,85 @@ layout:

 # Source

-`source` ist der Typ für Seiten, die eingelesenes Rohmaterial zusammenfassen und katalogisieren. Source-Seiten sind die Brücke zwischen der `raw/`-Schicht (unveränderliche Quelldateien) und der `kb/`-Schicht (kompiliertes Wissen). Eine Source-Seite steht für **eine logische Quelle**, die mehrere Raw-Dateien umfassen kann.
+`source` is the type for pages that summarize and catalogue ingested raw material. Source pages are the bridge between the `raw/` layer (immutable source files) and the `kb/` layer (compiled knowledge). One source page stands for **one logical source**, which may span several raw files.

-## Wann zu verwenden
+<!-- wikitool:toc -->
+## Contents

- Zusammenfassung eines einzelnen externen Artikels, Dokuments oder einer Spezifikation
- Erfassung mehrerer zusammengehöriger Notizen oder Gesprächsprotokolle als eine Quelle
- Dokumentation eines eingelesenen PDFs, Handbuchs oder sonstigen Dokuments
- Festhalten von Informationen zu einem Bild oder Diagramm
+- [When to use](#when-to-use)
+- [When NOT to use](#when-not-to-use)
+- [Frontmatter](#frontmatter)
+- [Authoring guidance](#authoring-guidance)
+- [Not Extracted](#not-extracted)
+- [Template](#template)
+<!-- /wikitool:toc -->

-## Wann NICHT zu verwenden
+## When to use

- Für kompiliertes Wissen (dann `entity` oder `concept`)
- Für vergleichende Analysen (dann `comparison`)
- Für originären Wiki-Inhalt, der nicht aus Rohmaterial abgeleitet ist
+- Summarizing a single external article, document or specification
+- Recording several related notes or meeting records as one source
+- Documenting an ingested PDF, manual or other document
+- Capturing information about an image or a diagram
+
+## When NOT to use
+
+- For compiled knowledge (use `entity` or `concept`)
+- For comparative analyses (use `comparison`)
+- For original wiki content not derived from raw material

 ## Frontmatter

-| Feld | Pflicht | Verwendung |
+| Field | Required | Use |
 |---|---:|---|
-| `type` | Ja | `types/source.md` |
-| `source_type` | Ja | Eines von: transcript, analysis, article, document, notes, tracker, unclassified - kein Default, siehe unten |
-| `author` | Ja | Urheber des Quellmaterials |
-| `raw_files` | Ja | Raw-Dateipfade, die diese Quelle **besitzt** - siehe "Eine Raw-Datei, ein Besitzer" unten |
-| `fidelity` | Ja (im Werkzeug, nicht im Schema) | Wie treu die *Erfassung* ist: `verbatim`, `published`, `secondhand`, `nontextual` - Capture-Feld, siehe unten |
-| `authority` | Ja (im Werkzeug, nicht im Schema) | Was das Material über seinen *Gegenstand* behaupten darf: `normative`, `reporting`, `opinion` - Capture-Feld, siehe unten |
-| `source_url` | Nein | Ursprungs-URL bei externen Quellen |
-| `source_language` | Nein | ISO-639-1-Code der Sprache des Rohmaterials, z. B. `de`, `en`, `fr` |
-| `date` | Ja | Veröffentlichungs- oder Erstellungsdatum (YYYY-MM-DD) |
-| `tags` | Nein | Navigations-Tags zur Kategorisierung |
-| `entities` | Nein | Titel der in dieser Quelle erwähnten Entities |
-| `concepts` | Nein | Titel der in dieser Quelle erwähnten Concepts |
-| `summary` | Ja | Einzeiler für `kb/index.md` |
+| `type` | Yes | `types/source.md` |
+| `source_type` | Yes | One of: transcript, analysis, article, document, notes, tracker, unclassified - no default, see below |
+| `author` | Yes | Originator of the source material |
+| `raw_files` | Yes | Raw file paths this source **owns** - see "One raw file, one owner" below |
+| `fidelity` | Yes (in the tool, not in the schema) | How faithful the *capture* is: `verbatim`, `published`, `secondhand`, `nontextual` - a capture field, see below |
+| `authority` | Yes (in the tool, not in the schema) | What the material may claim about its *subject*: `normative`, `reporting`, `opinion` - a capture field, see below |
+| `source_url` | No | Origin URL for external sources |
+| `source_language` | No | ISO 639-1 code of the raw material's language, e.g. `de`, `en`, `fr` |
+| `date` | Yes | Publication or creation date (YYYY-MM-DD) |
+| `tags` | No | Navigation tags for categorization |
+| `entities` | No | Titles of the entities mentioned in this source |
+| `concepts` | No | Titles of the concepts mentioned in this source |
+| `summary` | Yes | One-liner for `kb/index.md` |

-## Autorenanweisungen
+## Authoring guidance

- Der Titel beginnt mit "Source - ", gefolgt vom Namen der Quelle
- `source_type` hat **keinen Default** - `wikitool new source` verweigert ohne einen expliziten Wert. Ist die Kategorie unklar, `unclassified` setzen statt zu raten; das ist ein sichtbares Katalogfach mit beratendem `lint`-Befund, kein Sammelbecken. Was `analysis` von `document` trennt und welche Area welchen Wert hält: [kb/sources/COLLECTION.md](../kb/sources/COLLECTION.md)
- `raw_files` listet jede Raw-Datei, die diese Quelle abdeckt (eine Source-Seite pro logischer Quelle, nicht pro Datei)
- `fidelity` und `authority` sind **Capture-Felder** (`capture_fields:` oben): am Drop-Punkt erhoben, danach nicht mehr frei änderbar. `wikitool raw accept --fidelity <wert> --authority <wert>` verweigert ohne beide; ohne `--page` druckt es stattdessen die fertige `new source --set fidelity=... --set authority=...`-Zeile, die `new source` seinerseits ohne beide Werte verweigert. `wikitool touch --set fidelity=<wert>` schreibt nur, solange das Feld fehlt - steht bereits ein Wert, verweigert es und verweist auf `raw accept --replaces` als einzigen Korrekturweg (eine korrigierte Erfassung ist eine neue Edition, keine Bearbeitung). `unknown` ist backfill-only: nur `wikitool touch` darf es schreiben, nie `raw accept` oder `new source` - dieselbe Konstruktion wie bei `source_language` für Seiten, die vor dieser Regel entstanden sind. Was die Werte bedeuten und wie sie sich unterscheiden: [raw/CONTRACT.md](../raw/CONTRACT.md#getting-a-file-in-incoming)
- Bei externen Artikeln immer `source_url` auf die Ursprungs-URL setzen
- `source_language` auf die Sprache des Rohmaterials setzen, nicht auf die der Seite
- Die Seite wird in der KB-Sprache geschrieben, unabhängig von der Sprache der Quelle; wörtliche Passagen werden im Original zitiert (`kb/CONVENTIONS.md` § "Language")
- Kernaussagen im Abschnitt Summary zusammenfassen
- Handlungsbedarf in den Abschnitt Action Items
- Bewusst Weggelassenes in den Abschnitt Not Extracted - siehe unten
- Erwähnte Entities und Concepts unter Related Entities/Concepts verlinken
+- The title starts with "Source - ", followed by the name of the source
+- `source_type` has **no default** - `wikitool new source` refuses without an explicit value. Where the category is unclear, set `unclassified` rather than guessing; that is a visible catalog slot with an advisory `lint` finding, not a dumping ground. What separates `analysis` from `document`, and which area holds which value: [kb/sources/COLLECTION.md](../kb/sources/COLLECTION.md)
+- `raw_files` lists every raw file this source covers (one source page per logical source, not per file)
+- `fidelity` and `authority` are **capture fields** (`capture_fields:` above): recorded at the drop point and not freely changeable afterwards. `wikitool raw accept --fidelity <value> --authority <value>` refuses without both; without `--page` it instead prints the ready-made `new source --set fidelity=... --set authority=...` line, which `new source` in turn refuses without both values. `wikitool touch --set fidelity=<value>` only writes while the field is absent - where a value already stands, it refuses and points at `raw accept --replaces` as the one correction path (a corrected capture is a new edition, not an edit). `unknown` is backfill-only: only `wikitool touch` may write it, never `raw accept` or `new source` - the same construction as `source_language` uses for pages that predate this rule. What the values mean and how they differ: [raw/CONTRACT.md](../raw/CONTRACT.md#getting-a-file-in-incoming)
+- For external articles, always set `source_url` to the origin URL
+- Set `source_language` to the raw material's language, not the page's
+- The page is written in the KB language, whatever language the source is in; verbatim passages are quoted in the original (`kb/CONVENTIONS.md` § "Language")
+- Summarize the key claims in the summary section
+- Put anything actionable in the action items section
+- Put deliberate omissions in the not-extracted section - see below
+- Link the entities and concepts mentioned under related entities/concepts

 ## Not Extracted

-Die Entscheidung, dass Material *nicht* übernommen werden soll, ist nicht rekonstruierbar: nichts
-im Repository kann sie neu herleiten, und `sources coverage` weiß nur, ob eine Raw-Datei von
-irgendeiner Source-Seite beansprucht wird - nie, ob jemand über ihren Inhalt entschieden hat.
-Bleibt das unaufgeschrieben, wird dieselbe Quelle bei jedem späteren Durchgang neu verhandelt.
+The decision that material should *not* be taken over cannot be reconstructed: nothing in the
+repository can re-derive it, and `sources coverage` only knows whether a raw file is claimed by
+some source page - never whether anyone decided about its contents. Left unwritten, the same
+source is renegotiated on every later pass.

- Jede bewusste Auslassung mit **Begründung** festhalten, nicht nur mit Dateinamen.
- Pflicht, wenn der Ingest über `instructions/ingest-large-tree.md` lief - auf beiden Achsen:
-  beim Tree-Ingest hält der Abschnitt fest, was aus dem Baum nicht übernommen wurde, bei einer
-  thematisch breiten Einzelquelle, welche genannten Gegenstände keine eigene Seite bekommen
-  haben und warum. Optional bei einer einzelnen kleinen Datei - aber ein leerer Abschnitt ist
-  immer noch besser als ein fehlender.
- Gehört auf die Source-Seite, nicht in `kb/log.md`: es ist eine Aussage über *diese* Quelle,
-  und das Log ist chronologisch, nicht quellenbezogen.
+- Record every deliberate omission with a **reason**, not just a filename.
+- Mandatory where the ingest ran through `instructions/ingest-large-tree.md` - on both axes: for
+  a tree ingest the section records what was not taken from the tree; for a thematically broad
+  single source, which named subjects got no page of their own, and why. Optional for a single
+  small file - but an empty section still beats a missing one.
+- Belongs on the source page, not in `kb/log.md`: it is a statement about *this* source, and the
+  log is chronological rather than per-source.

 ## Template

+The block below is page material, so it is written in this instance's KB language
+(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
+become the headings of every page `wikitool new source` scaffolds.
+
 ```markdown
 # Source: {name}

@@ -121,24 +135,18 @@ TODO: 2-3 Absätze zu den Kernaussagen des Quellmaterials.
 {concepts|bullets}
 ```

-`# Source:` bleibt als Präfix stehen - es spiegelt den `title_prefix` und damit den Titel, unter
-dem die Seite verlinkt und zitiert wird. Der Wert hinter `**Typ:**` bleibt der englische
-Enum-Wert. Fügt `wikitool cite` ein Zitat hinzu, entsteht am Seitenende der toolgeführte
-Fußnoten-Block; wie er heißt, entscheidet die Instanz in `kb/CONVENTIONS.md` (`sections:`).
+`# Source:` stays as a prefix - it mirrors the `title_prefix` and with it the title the page is
+linked and cited under. The value behind `**Typ:**` stays the English enum value. When
+`wikitool cite` adds a citation, the tool-managed footnote block appears at the end of the page;
+what it is called is the instance's decision in `kb/CONVENTIONS.md` (`sections:`).

 ---

-Ergänzende Hinweise:
+Additional notes:

- Source-Seiten sind der maßgebliche Katalog dessen, was an Rohmaterial eingelesen wurde
- **Eine Raw-Datei, ein Besitzer.** Eine Raw-Datei steht in genau einem `raw_files:` - diese Seite ist dafür verantwortlich, sie zusammengefasst zu halten. Beliebig viele Seiten dürfen sie per `[^cite-id]` **zitieren**; ein Zitat ist Wiederverwendung, `raw_files:` ist eine Wartungszuständigkeit. Bei zwei Anspruchstellern ist undefiniert, welche Seite bei einer Änderung der Raw-Datei nachgezogen werden muss - dann verrotten beide still
- Source-Seiten machen Wissen bis zum ursprünglichen Rohmaterial rückverfolgbar
- `raw_files:` enthält konkrete existierende Dateipfade, nie Verzeichnisse
- Eine `raw_files:`-Liste jenseits von etwa 15 Einträgen zeigt an, dass der Schnitt zu grob war -
-  die Quelle hätte per `instructions/ingest-large-tree.md` in mehrere Source-Seiten geteilt
-  werden müssen
- `entities:` plus `concepts:` jenseits von etwa 20 Einträgen ist das Gegenstück auf der anderen
-  Achse: nicht zu wenig geschnitten, sondern zu viel auf einmal kompiliert. Geteilt wird eine
-  solche Quelle nicht - eine Raw-Datei hat einen Besitzer -, sie hätte den Extract-Pass aus
-  `instructions/ingest-large-tree.md` § "A broad source is not cut" gebraucht, damit nicht jeder
-  genannte Gegenstand eine Seite bekommt
+- Source pages are the authoritative catalogue of what raw material has been ingested
+- **One raw file, one owner.** A raw file appears in exactly one `raw_files:` - that page is responsible for keeping it summarized. Any number of pages may **cite** it via `[^cite-id]`; a citation is reuse, `raw_files:` is a maintenance responsibility. With two claimants it is undefined which page has to be brought up to date when the raw file changes - and then both rot quietly
+- Source pages make knowledge traceable back to the original raw material
+- `raw_files:` holds concrete existing file paths, never directories
+- A `raw_files:` list beyond roughly 15 entries indicates the cut was too coarse - the source should have been split into several source pages via `instructions/ingest-large-tree.md`
+- `entities:` plus `concepts:` beyond roughly 20 entries is the counterpart on the other axis: not cut too little, but compiled too much at once. Such a source is not split - a raw file has one owner - it needed the extract pass from `instructions/ingest-large-tree.md` § "A broad source is not cut", so that not every named subject gets a page