types/: Seiten-Type-Spec-Anleitungsprosa in stackeigene guidance-Datei ausgelagert (schliesst #104)
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:
@@ -0,0 +1,41 @@
|
||||
---
|
||||
type: types/type-guidance.md
|
||||
name: comparison
|
||||
description: When to write a comparison page instead of a neighboring type, and how to write a conforming one - structure and analysis rules that hold regardless of what this instance is comparing
|
||||
---
|
||||
|
||||
# Comparison Guidance
|
||||
|
||||
`comparison` is the type for pages that set several entities, tools, technologies or approaches
|
||||
systematically against one another along fixed criteria. Comparison pages support decisions and
|
||||
make the trade-offs between alternatives visible.
|
||||
|
||||
## When to use
|
||||
|
||||
- Comparing several technologies or frameworks for a concrete purpose
|
||||
- Analysing the advantages and disadvantages of different tools or libraries
|
||||
- Evaluating alternative ways of solving a problem
|
||||
- Documenting a decision process with several options examined
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For documenting a single entity or concept (use `entity` or `concept` respectively)
|
||||
- For summaries of source material (use `source`)
|
||||
- For pages covering a single subject rather than comparing several
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- A title that names the comparison (e.g. "Go vs Rust", "Kubernetes vs Docker Swarm"); it follows the established names of the subjects compared, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- State clearly what is being compared and why
|
||||
- Use a comparison table with the criteria as rows
|
||||
- An analysis that evaluates the table rather than repeating it
|
||||
- A recommendation wherever one can be justified
|
||||
|
||||
---
|
||||
|
||||
Relevant Notes:
|
||||
|
||||
- Comparison pages support technology selection and architecture decisions
|
||||
- The entities compared should all exist as wiki pages
|
||||
- The criteria should fit the decision at hand
|
||||
- A comparison stays focused on one concrete purpose or decision context
|
||||
+5
-31
@@ -5,24 +5,15 @@ description: Structured type for comparison pages that set several entities or a
|
||||
schema: types/comparison.schema.yaml
|
||||
base_dir: comparisons
|
||||
page_ref_fields: [entities, related]
|
||||
guidance: types/comparison.guidance.md
|
||||
---
|
||||
|
||||
# Comparison
|
||||
|
||||
`comparison` is the type for pages that set several entities, tools, technologies or approaches systematically against one another along fixed criteria. Comparison pages support decisions and make the trade-offs between alternatives visible.
|
||||
|
||||
## When to use
|
||||
|
||||
- Comparing several technologies or frameworks for a concrete purpose
|
||||
- Analysing the advantages and disadvantages of different tools or libraries
|
||||
- Evaluating alternative ways of solving a problem
|
||||
- Documenting a decision process with several options examined
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For documenting a single entity or concept (use `entity` or `concept` respectively)
|
||||
- For summaries of source material (use `source`)
|
||||
- For pages covering a single subject rather than comparing several
|
||||
This instance's configuration for the `comparison` type: its frontmatter fields as this schema
|
||||
requires them, and the page skeleton `wikitool new comparison` scaffolds. When to use this type
|
||||
and how to write a conforming page is [types/comparison.guidance.md](comparison.guidance.md) -
|
||||
`tools/wikitool types describe comparison` composes both into one answer.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
@@ -35,14 +26,6 @@ page_ref_fields: [entities, related]
|
||||
| `related` | No | Declared outbound edges - one `compares-with` edge per subject, written by `wikitool xref add` |
|
||||
| `summary` | Yes | One-liner for `kb/index.md` |
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- A title that names the comparison (e.g. "Go vs Rust", "Kubernetes vs Docker Swarm"); it follows the established names of the subjects compared, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- State clearly what is being compared and why
|
||||
- Use a comparison table with the criteria as rows
|
||||
- An analysis that evaluates the table rather than repeating it
|
||||
- A recommendation wherever one can be justified
|
||||
|
||||
## Template
|
||||
|
||||
The block below is page material, so it is written in this instance's KB language
|
||||
@@ -75,12 +58,3 @@ TODO: Falls möglich - was wann und für wen zu verwenden ist. Unter welchen Ums
|
||||
convention, and the page title itself (`Go vs Rust`) does not carry it. When `wikitool xref` adds
|
||||
a relationship, the tool-managed cross-reference section appears; what it is called is the
|
||||
instance's decision in `kb/CONVENTIONS.md` (`sections:`).
|
||||
|
||||
---
|
||||
|
||||
Additional notes:
|
||||
|
||||
- Comparison pages support technology selection and architecture decisions
|
||||
- The entities compared should all exist as wiki pages
|
||||
- The criteria should fit the decision at hand
|
||||
- A comparison stays focused on one concrete purpose or decision context
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
type: types/type-guidance.md
|
||||
name: concept
|
||||
description: When to write a concept page instead of a neighboring type, and how to write a conforming one - citation, linking and register rules that hold regardless of which concept_type values this instance chose
|
||||
---
|
||||
|
||||
# Concept Guidance
|
||||
|
||||
`concept` is the type for abstract ideas, methodologies, patterns and architectural decisions.
|
||||
Concepts provide the theoretical and methodological ground that entities implement or follow.
|
||||
|
||||
## When to use
|
||||
|
||||
- Documenting an architectural pattern or design approach
|
||||
- Explaining a design pattern or a programming methodology
|
||||
- Describing a communication protocol or standard
|
||||
- Recording a workflow or process that recurs across projects
|
||||
- Documenting an architectural decision (ADR) or design decision
|
||||
- Analysing a recurring problem and its solutions
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For concrete things such as projects, systems or tools (use `entity`)
|
||||
- For source documents or ingested material (use `source`)
|
||||
- For comparative analyses of concrete subjects (use `comparison`)
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- The title is the concept's canonical name and follows the established term of art, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- Open with a clear definition: what the concept is
|
||||
- Give examples wherever they carry the understanding
|
||||
- Link to the entities that implement or use the concept
|
||||
- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
|
||||
- Wikipedia register: factual, neutral, no marketing language
|
||||
|
||||
---
|
||||
|
||||
Relevant Notes:
|
||||
|
||||
- Concept pages carry the wiki's theoretical underpinning
|
||||
- Each concept type stands for a different category of abstract knowledge
|
||||
- Concepts should be linked to from the entities that implement or use them
|
||||
+5
-44
@@ -6,6 +6,7 @@ schema: types/concept.schema.yaml
|
||||
subtype_field: concept_type
|
||||
base_dir: concepts
|
||||
page_ref_fields: [related, sources]
|
||||
guidance: types/concept.guidance.md
|
||||
layout:
|
||||
architecture: {dir: architectures, title: Architekturen}
|
||||
pattern: {dir: patterns, title: Muster}
|
||||
@@ -17,32 +18,10 @@ layout:
|
||||
|
||||
# Concept
|
||||
|
||||
`concept` is the type for abstract ideas, methodologies, patterns and architectural decisions. Concepts provide the theoretical and methodological ground that entities implement or follow.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to use](#when-to-use)
|
||||
- [When NOT to use](#when-not-to-use)
|
||||
- [Frontmatter](#frontmatter)
|
||||
- [Authoring guidance](#authoring-guidance)
|
||||
- [Template](#template)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to use
|
||||
|
||||
- Documenting an architectural pattern or design approach
|
||||
- Explaining a design pattern or a programming methodology
|
||||
- Describing a communication protocol or standard
|
||||
- Recording a workflow or process that recurs across projects
|
||||
- Documenting an architectural decision (ADR) or design decision
|
||||
- Analysing a recurring problem and its solutions
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For concrete things such as projects, systems or tools (use `entity`)
|
||||
- For source documents or ingested material (use `source`)
|
||||
- For comparative analyses of concrete subjects (use `comparison`)
|
||||
This instance's configuration for the `concept` type: its frontmatter fields as this schema
|
||||
requires them, and the page skeleton `wikitool new concept` scaffolds. When to use this type and
|
||||
how to write a conforming page is [types/concept.guidance.md](concept.guidance.md) -
|
||||
`tools/wikitool types describe concept` composes both into one answer.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
@@ -58,16 +37,6 @@ layout:
|
||||
| `provenance` | Yes | sourced, general or mixed |
|
||||
| `summary` | Yes | One-liner for `kb/index.md` |
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- The title is the concept's canonical name and follows the established term of art, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- Open with a clear definition: what the concept is
|
||||
- Give examples wherever they carry the understanding
|
||||
- Link to the entities that implement or use the concept
|
||||
- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
|
||||
- Wikipedia register: factual, neutral, no marketing language
|
||||
|
||||
## Template
|
||||
|
||||
The block below is page material, so it is written in this instance's KB language
|
||||
@@ -112,11 +81,3 @@ The value behind `**Typ:**` stays the English enum value - that is what `search
|
||||
on. When `wikitool xref` adds a relationship, the two tool-managed sections for relationships and
|
||||
cross-references appear as well; what they are called is the instance's decision in
|
||||
`kb/CONVENTIONS.md` (`sections:`).
|
||||
|
||||
---
|
||||
|
||||
Additional notes:
|
||||
|
||||
- Concept pages carry the wiki's theoretical underpinning
|
||||
- Each concept type stands for a different category of abstract knowledge
|
||||
- Concepts should be linked to from the entities that implement or use them
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
type: types/type-guidance.md
|
||||
name: entity
|
||||
description: When to write an entity page instead of a neighboring type, and how to write a conforming one - citation, linking and register rules that hold regardless of which entity_type values this instance chose
|
||||
---
|
||||
|
||||
# Entity Guidance
|
||||
|
||||
`entity` is the type for concrete things: projects, systems, tools, technologies or people.
|
||||
Entities are the primary building blocks of the knowledge graph.
|
||||
|
||||
## When to use
|
||||
|
||||
- Representing a software project, an initiative or a piece of work
|
||||
- Documenting a running system, service or infrastructure component
|
||||
- Describing a CLI tool, utility or software library
|
||||
- Recording information about a language, a framework or a protocol
|
||||
- Documenting a person, a team or an organization
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For abstract concepts, patterns or methodologies (use `concept`)
|
||||
- For source documents or ingested material (use `source`)
|
||||
- For comparative analyses (use `comparison`)
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- The title is the entity's canonical name and follows the subject's established designation, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- The main description goes near the top
|
||||
- Link to related entities and concepts wherever relationships exist
|
||||
- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
|
||||
- Wikipedia register: factual, neutral, no marketing language
|
||||
|
||||
---
|
||||
|
||||
Relevant Notes:
|
||||
|
||||
- Entity pages form the concrete inventory of the knowledge base
|
||||
- Every entity type (project, system, tool and so on) is a variant of this base type
|
||||
- The relationships between entities carry the knowledge graph's interconnection
|
||||
+5
-42
@@ -6,6 +6,7 @@ schema: types/entity.schema.yaml
|
||||
subtype_field: entity_type
|
||||
base_dir: entities
|
||||
page_ref_fields: [related, sources]
|
||||
guidance: types/entity.guidance.md
|
||||
layout:
|
||||
project: {dir: projects, title: Projekte}
|
||||
system: {dir: systems, title: Systeme}
|
||||
@@ -16,31 +17,10 @@ layout:
|
||||
|
||||
# Entity
|
||||
|
||||
`entity` is the type for concrete things: projects, systems, tools, technologies or people. Entities are the primary building blocks of the knowledge graph.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to use](#when-to-use)
|
||||
- [When NOT to use](#when-not-to-use)
|
||||
- [Frontmatter](#frontmatter)
|
||||
- [Authoring guidance](#authoring-guidance)
|
||||
- [Template](#template)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to use
|
||||
|
||||
- Representing a software project, an initiative or a piece of work
|
||||
- Documenting a running system, service or infrastructure component
|
||||
- Describing a CLI tool, utility or software library
|
||||
- Recording information about a language, a framework or a protocol
|
||||
- Documenting a person, a team or an organization
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For abstract concepts, patterns or methodologies (use `concept`)
|
||||
- For source documents or ingested material (use `source`)
|
||||
- For comparative analyses (use `comparison`)
|
||||
This instance's configuration for the `entity` type: its frontmatter fields as this schema
|
||||
requires them, and the page skeleton `wikitool new entity` scaffolds. When to use this type and
|
||||
how to write a conforming page is [types/entity.guidance.md](entity.guidance.md) -
|
||||
`tools/wikitool types describe entity` composes both into one answer.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
@@ -56,15 +36,6 @@ layout:
|
||||
| `provenance` | Yes | sourced, general or mixed |
|
||||
| `summary` | Yes | One-liner for `kb/index.md` |
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- The title is the entity's canonical name and follows the subject's established designation, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- The main description goes near the top
|
||||
- Link to related entities and concepts wherever relationships exist
|
||||
- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
|
||||
- Wikipedia register: factual, neutral, no marketing language
|
||||
|
||||
## Template
|
||||
|
||||
The block below is page material, so it is written in this instance's KB language
|
||||
@@ -102,11 +73,3 @@ The relationships section is deliberately **not** in the template: it is a gener
|
||||
`wikitool xref` creates between markers on the first edge entry and re-renders from `related:`.
|
||||
An author never writes into it. The value behind `**Typ:**` stays the English enum value - that is
|
||||
what `search --field` filters on.
|
||||
|
||||
---
|
||||
|
||||
Additional notes:
|
||||
|
||||
- Entity pages form the concrete inventory of the knowledge base
|
||||
- Every entity type (project, system, tool and so on) is a variant of this base type
|
||||
- The relationships between entities carry the knowledge graph's interconnection
|
||||
|
||||
@@ -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
|
||||
+5
-61
@@ -8,6 +8,7 @@ base_dir: sources
|
||||
title_prefix: "Source - "
|
||||
page_ref_fields: [entities, concepts]
|
||||
capture_fields: [fidelity, authority]
|
||||
guidance: types/source.guidance.md
|
||||
layout:
|
||||
transcript: {dir: transcripts, title: Transkripte}
|
||||
analysis: {dir: analyses, title: Analysen}
|
||||
@@ -20,31 +21,10 @@ layout:
|
||||
|
||||
# Source
|
||||
|
||||
`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.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [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 -->
|
||||
|
||||
## 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
|
||||
This instance's configuration for the `source` type: its frontmatter fields as this schema
|
||||
requires them, and the page skeleton `wikitool new source` scaffolds. When to use this type and
|
||||
how to write a conforming page is [types/source.guidance.md](source.guidance.md) -
|
||||
`tools/wikitool types describe source` composes both into one answer.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
@@ -67,31 +47,6 @@ layout:
|
||||
## Authoring guidance
|
||||
|
||||
- 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
|
||||
|
||||
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.
|
||||
|
||||
## Template
|
||||
|
||||
@@ -139,14 +94,3 @@ TODO: 2-3 Absätze zu den Kernaussagen des Quellmaterials.
|
||||
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:`).
|
||||
|
||||
---
|
||||
|
||||
Additional 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
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
type: types/type-spec.md
|
||||
name: type-guidance
|
||||
description: "Stack-owned authoring prose for a root:kb page type - the machine-independent half a type-spec's optional guidance: field links to"
|
||||
schema: types/type-guidance.schema.yaml
|
||||
---
|
||||
|
||||
# Type Guidance
|
||||
|
||||
`type-guidance` describes the shape of one `types/<name>.guidance.md` file: the stack-owned half
|
||||
of a `root: kb` page type's contract. A page type-spec ([types/type-spec.md](type-spec.md) §
|
||||
"Who owns a type-spec") splits at the audience line - what an agent needs to know to write a
|
||||
conforming page, versus what this instance's schema and template concretely are - and a guidance
|
||||
file is the machine-independent half of that split, linked from the type-spec it documents via
|
||||
that file's own `guidance:` frontmatter field.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Writing or improving the generic authoring rules for a `root: kb` type: when to choose it, when
|
||||
not to, and mechanism-level advice that holds regardless of which enum values, directory names
|
||||
or template text this instance chose - citation mechanics, provenance rules, what a conforming
|
||||
page does or does not claim
|
||||
- Anything a later stack release would want every adopting instance to receive automatically,
|
||||
the way a fix to `tools/` already does
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Enum values, `layout:` titles, directory names or template text. Those name *this* instance's
|
||||
choices and stay in the type-spec itself - the file `guidance:` points *from*, never the one it
|
||||
points *to*
|
||||
- A type an instance writes entirely for itself. `guidance:` is optional; a type-spec that omits
|
||||
it is described from its own body alone, exactly as every type-spec worked before this type
|
||||
existed
|
||||
|
||||
## Frontmatter
|
||||
|
||||
| Field | Required | Use |
|
||||
|---|---:|---|
|
||||
| `type` | Yes | `types/type-guidance.md` |
|
||||
| `name` | Yes | The page type this documents, e.g. `entity` - matches that type-spec's own `name:` |
|
||||
| `description` | Yes | Retrieval description for this guidance document |
|
||||
|
||||
## Conventions
|
||||
|
||||
- Linked from the type-spec it documents via that file's `guidance:` frontmatter field - a
|
||||
repo-relative path, resolved the same way `schema:` is
|
||||
- `tools/wikitool types describe <name>` composes both halves into one answer; an agent asking
|
||||
for a type's contract never needs to know it comes from two files
|
||||
- Written in the control plane's English ([AGENTS.md](../AGENTS.md) § File naming), like a
|
||||
type-spec's own authoring prose - only the type-spec's `## Template` block and its `layout:`
|
||||
titles are page material
|
||||
|
||||
---
|
||||
|
||||
Relevant Notes:
|
||||
|
||||
- Ships verbatim with every distribution; the type-spec it documents ships only as a `.template`
|
||||
where `root: kb` - see `docs/ownership-and-templates.md` § "Where the file boundary used to
|
||||
strain"
|
||||
- No `## Template` section here: a guidance file's body is prose an author reads, not a body
|
||||
structure `wikitool new` would scaffold. `type-guidance` declares no `base_dir:` for the same
|
||||
reason `lint-report` does, and `wikitool new type-guidance` refuses for the same reason
|
||||
- An instance that adopted its type-specs before this type existed sees nothing change until it
|
||||
takes the offered migration that adds `guidance:` to each one - see
|
||||
`instructions/migrations/` for the document
|
||||
@@ -0,0 +1,23 @@
|
||||
# YAML Schema for type-guidance documents
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
const: "types/type-guidance.md"
|
||||
description: Must reference the type-guidance type-spec
|
||||
name:
|
||||
type: string
|
||||
description: >-
|
||||
The page type this guidance documents, e.g. 'entity' - matches that
|
||||
type-spec's own `name:` field
|
||||
minLength: 1
|
||||
pattern: "^[a-z][a-z0-9-]*$"
|
||||
description:
|
||||
type: string
|
||||
description: Retrieval description for this guidance document
|
||||
minLength: 10
|
||||
required:
|
||||
- type
|
||||
- name
|
||||
- description
|
||||
additionalProperties: false
|
||||
+37
-18
@@ -33,6 +33,7 @@ A type-spec doc is the authoring and validation contract for one Chemenu artifac
|
||||
- `description`: retrieval description for the type contract.
|
||||
- `schema`: repo-relative path to the `.schema.yaml` file that validates artifacts of this type, or `null` when the type has no schema.
|
||||
- `subtype_field` (optional): the frontmatter field name on instances of this type that carries a subtype/category (e.g. `entity_type`), or omitted if this type has no such field.
|
||||
- `guidance` (optional): repo-relative path to a `types/type-guidance.md`-shaped document holding this type's stack-owned authoring prose - see § "Anatomy of a type" below. Meaningful only on a `root: kb` type-spec; omit for a type an instance writes entirely for itself.
|
||||
|
||||
## Validation Contract
|
||||
|
||||
@@ -65,28 +66,41 @@ frontmatter before anyone drew it:
|
||||
| Type-spec | Describes | Owned by | Ships as |
|
||||
|---|---|---|---|
|
||||
| `root: kb` (`entity`, `concept`, `source`, `comparison`) | A page **this instance** writes | The instance | `types/<name>.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 |
|
||||
| `root: repo` (`instruction`), no `base_dir` (`lint-report`), and `type-spec`/`type-guidance` themselves | A stack artifact | The stack | Verbatim |
|
||||
|
||||
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.
|
||||
A page type-spec's frontmatter configuration and its `## Template` body are therefore the
|
||||
instance's to rewrite, and an upgrade does not take that back. Its generic authoring prose is the
|
||||
opposite: where the type-spec declares `guidance:`, that prose lives in a separate, stack-owned
|
||||
`types/<name>.guidance.md` (§ "Anatomy of a type" below) that ships verbatim and is overwritten
|
||||
by an upgrade like any other machinery file - the type-spec it documents does not have to be
|
||||
re-adopted, or even touched, for that improvement to arrive. A type-spec that declares no
|
||||
`guidance:` (a type an instance writes entirely for itself) has no stack half to receive; it is
|
||||
described from its own body alone, exactly as every type-spec worked before this split existed.
|
||||
An *existing* instance that adopted its type-specs before `guidance:` existed takes this as an
|
||||
*offered* migration ([instructions/CONTRACT.md](../instructions/CONTRACT.md#instructionsmigrations))
|
||||
rather than something an upgrade applies on its own - see `instructions/migrations/` for the
|
||||
document.
|
||||
|
||||
**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):
|
||||
**Ownership and language still do not line up with each other**, and that stays true even though
|
||||
the authoring prose now has its own file rather than sharing one with the template. Owning the
|
||||
type-spec means the instance may rewrite its frontmatter and its `## Template` body; a guidance
|
||||
file it links is never the instance's to rewrite at all - it is the stack's, the same way
|
||||
`tools/CONTRACT.md` is. What each part is *written in* still follows what the line is *for*, per
|
||||
[AGENTS.md § File naming](../AGENTS.md#file-naming), independent of which file it lives in or who
|
||||
owns that file:
|
||||
|
||||
| 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 |
|
||||
| Part of a `root: kb` type's contract | Lives in | Audience | Language |
|
||||
|---|---|---|---|
|
||||
| When to use / not to use, authoring guidance | The `guidance:` file, where declared | An agent writing a page | The control plane's — English |
|
||||
| The frontmatter table documenting this instance's own fields | The type-spec itself | An agent writing a page | The control plane's — English |
|
||||
| The `## Template` body, and the `layout:` titles that head a catalog section | The type-spec itself | The page itself | The instance's KB language (`kb/CONVENTIONS.md` `language:`) |
|
||||
| Field names, enum values, `dir:` values, `type:` paths | Either file's frontmatter | 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.
|
||||
settles who may change it, not which language each half is written in - and it may declare its
|
||||
own `guidance:` file if it wants the same shape, though nothing requires it to.
|
||||
|
||||
**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/`
|
||||
@@ -102,14 +116,19 @@ Python. Adding a type must require no code change.
|
||||
|
||||
### Anatomy of a type
|
||||
|
||||
Each type is two files:
|
||||
Each type is at least two files, and a `root: kb` type may be three:
|
||||
|
||||
| File | Owns |
|
||||
|------|------|
|
||||
| `types/<name>.md` | The authoring contract: when to use the type, when not to, guidance, and the `## Template` block used to scaffold new pages |
|
||||
| `types/<name>.md` | This instance's configuration: its frontmatter fields as this schema requires them, and the `## Template` block used to scaffold new pages. For a type with no `guidance:` (below), its own prose also carries the authoring contract - when to use the type, when not to |
|
||||
| `types/<name>.schema.yaml` | The machine-checkable half: fields, types, enums, defaults, required-ness, `additionalProperties: false` |
|
||||
| `types/<name>.guidance.md` (optional, `root: kb` only) | The stack-owned authoring contract: when to use the type, when not to, and mechanism-level advice that holds regardless of this instance's own enum values or template text - linked from the type-spec's own `guidance:` field. `types/type-guidance.md` is its contract |
|
||||
|
||||
This file is the self-referential root contract that both are validated against.
|
||||
This file is the self-referential root contract every type-spec is validated against, and
|
||||
`type-guidance.md` is validated against it the same way `lint-report.md` is - itself a
|
||||
non-instantiable, contract-only type. `tools/wikitool types describe <name>` composes all of a
|
||||
type's files into one answer regardless of how many there are; an agent asking for a type's
|
||||
contract never needs to know it came from more than one file.
|
||||
|
||||
### Placement frontmatter
|
||||
|
||||
|
||||
Reference in New Issue
Block a user