types/: Seiten-Type-Spec-Anleitungsprosa in stackeigene guidance-Datei ausgelagert (schliesst #104)
CI / verify (push) Failing after 43s
Release / release (push) Successful in 34s

Files changed:
- AGENTS.md
- CHANGES.md
- VERSION
- docs/ownership-and-templates.md
- instructions/migrations/6.0.0-type-guidance-split.md
- instructions/setup-instance.md
- tools/CONTRACT.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/types_cmd.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_dist_upgrade.py
- tools/chemenu/tests/test_type_resolver.py
- tools/chemenu/tests/test_types_cmd.py
- tools/chemenu/type_resolver.py
- tools/chemenu/types_core.py
- types/comparison.guidance.md
- types/comparison.md
- types/concept.guidance.md
- types/concept.md
- types/entity.guidance.md
- types/entity.md
- types/source.guidance.md
- types/source.md
- types/type-guidance.md
- types/type-guidance.schema.yaml
- types/type-spec.md
This commit is contained in:
2026-09-15 18:23:38 +02:00
parent 90ce41964f
commit d49513bda6
26 changed files with 789 additions and 238 deletions
+63
View File
@@ -0,0 +1,63 @@
---
type: types/type-guidance.md
name: source
description: When to write a source page instead of a neighboring type, and how to write a conforming one - capture-field, provenance and not-extracted rules that hold regardless of which source_type values this instance chose
---
# Source Guidance
`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.
## When to use
- 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
## Authoring guidance
- `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, is a call this instance's own collection contract makes - see `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:` on this type): 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
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.
- 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.
---
Relevant Notes:
- 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