torben/chemenu
1
1
Fork 0
Code Issues 26 Pull Requests Actions Packages Releases 32 Activity

feat: Prosa ist kein Identifier - Link-Taxonomie als Enum, generierte Regionen mit Markern (4.0.0)
CI / verify (push) Successful in 55s
Details
Release / release (push) Successful in 38s
Details

Browse Source 
Files changed:
- .gitea/workflows/ci.yml
- AGENTS.md
- CHANGES.md
- VERSION
- instructions/CONTRACT.md
- instructions/link-taxonomy.md
- instructions/migrations/4.0.0-link-taxonomy.md
- instructions/setup-instance.md
- kb/CONTRACT.md
- kb/CONVENTIONS.md
- kb/CONVENTIONS.md.template
- kb/comparisons/COLLECTION.md
- kb/concepts/COLLECTION.md
- kb/entities/COLLECTION.md
- kb/sources/COLLECTION.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/blocks.py
- tools/chemenu/cli.py
- tools/chemenu/commands/cite_cmd.py
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/links_cmd.py
- tools/chemenu/commands/migrate_cmd.py
- tools/chemenu/commands/new_page.py
- tools/chemenu/commands/page_ops.py
- tools/chemenu/commands/run_budget.py
- tools/chemenu/commands/xref.py
- tools/chemenu/conventions.py
- tools/chemenu/corpus_diff.py
- tools/chemenu/frontmatter_io.py
- tools/chemenu/kb_collections.py
- tools/chemenu/kb_state.py
- tools/chemenu/links.py
- tools/chemenu/lint_core.py
- tools/chemenu/provenance.py
- tools/chemenu/sections.py
- tools/chemenu/tests/conftest.py
- tools/chemenu/tests/test_blocks.py
- tools/chemenu/tests/test_cite_cmd.py
- tools/chemenu/tests/test_conventions.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_doctor.py
- tools/chemenu/tests/test_migrate_cmd.py
- tools/chemenu/tests/test_new_page.py
- tools/chemenu/tests/test_pipeline_l0.py
- tools/chemenu/tests/test_types_cmd.py
- tools/chemenu/tests/test_xref.py
- types/concept.schema.yaml
- types/entity.md
- types/entity.schema.yaml
- types/instruction.schema.yaml
- types/type-spec.md
- work/link-taxonomy-migration/README.md
- work/link-taxonomy-migration/plan.md
This commit is contained in:
Torben Nehmer
2026-09-02 18:39:22 +02:00
parent 502971d147
commit 177c7e9ce8
56 changed files with 2692 additions and 750 deletions
Download Patch File Download Diff File Expand all files Collapse all files
instructions/CONTRACT.md
+22 -2
View File
@@ -65,11 +65,31 @@ catalogue of authoring profiles an instance may adopt into its own `kb/CONVENTIO
## `instructions/migrations/`
A content migration is a Manual instruction with two extra frontmatter fields
A content migration is a Manual instruction with three extra frontmatter fields
(`types/instruction.schema.yaml`): `migrates_to:`, the stack version whose content shape it
produces, and `migration_kind:` (`mechanical` | `assisted`). It lives at
produces; `migration_kind:` (`mechanical` | `assisted`); and `obligation:`
(`required` | `offered`, default `required`). It lives at
`instructions/migrations/<version>-<slug>.md`.
`migration_kind:` and `obligation:` are **two axes, not one**. The first says how the work is
carried out, the second whether it has to happen at all:
| `obligation:` | Means | `migrate status` |
|---|---|---|
| `required` | The content must reach the new shape or it no longer fits the machinery | Counted as outstanding; `migrate done` advances `kb_version` through it, in chain order |
| `offered` | A file the instance owns still works as it is, and the stack proposes a better default | Listed separately, never blocks, no ordering rule. `migrate done` records it in the applied ledger and leaves `kb_version` where it is |
Keeping them apart is what stops `migrate status` crying wolf: an instance nagged about an
improvement it declined stops reading the nag that means its content no longer fits its
machinery. And because taking an offer deliberately does not move the version, the **applied
ledger** - not `kb_version` - is what makes an offer stop being offered; without that record
there is no way to tell a taken offer from an ignored one.
An `offered` migration is what makes an instance-owned file upgradeable at all. `dist export`
records a sha256 per shipped file in `.wikitool-release.json`, so `migrate status` can say which
of those files the instance edited and which it merely received - the first have to be
reconciled by a person, the second can simply be copied over.
The tier fits exactly: a migration must never be picked up implicitly - it rewrites the corpus -
and it is referenced by nothing, because `tools/wikitool migrate status` finds it by reading the
directory and comparing `migrates_to:` against this instance's `kb_version`. That is also why
instructions/link-taxonomy.md
+199
View File
@@ -0,0 +1,199 @@
---
type: types/instruction.md
name: link-taxonomy
description: The link-label catalogue - every relationship label a page may declare in related:, grouped by register, with the reader need each one names. A palette to authorise from in a COLLECTION.md, never binding on its own.
manual: true
---
# Pick a link label
**This page is a palette, not an enum.** It lists every label this stack ships with and what
each one asserts. What a page may actually *use* is decided by its own collection: each
`kb/<name>/COLLECTION.md` authorises a subset per destination, and `wikitool lint` checks
`related:` against that authorisation rather than against this file. A collection that
authorises six labels has six, however long this list gets.
A label is an **identifier, not prose**. It is written into `related:` as a machine value and
rendered verbatim into the page body, so it is never translated - not in a German wiki, not in
any other. Which words a page is *written* in stays [kb/CONVENTIONS.md](../kb/CONVENTIONS.md)'s;
this is not one of them.
## The invariant every label obeys
Every label completes, with the page carrying the link as the grammatical subject:
> `[source] <label> [target]`
The page containing the link asserts something **about** the target. `Hermes depends-on
PostgreSQL` reads correctly on Hermes' page; the same fact written on PostgreSQL's page is a
different label (`required-by`), not the same one pointing back. Omitted helper verbs ("is",
"a") are fine where they do not reverse the endpoints.
This is Commonplace's ADR-058, adopted wholesale, and it is what makes a label checkable rather
than a matter of taste: read the sentence out loud, and if it says the opposite of what you
meant, the label is wrong.
## Direction is authored, never mirrored
Each direction is a separate decision. A link back from the target is welcome when it
independently helps a reader *there* - and unnecessary when it does not. **Do not add a reverse
edge merely to mirror the first one.** The inbound view is rendered from the graph by
`index rebuild` and `search`, so a reader landing on the target sees what points at it whether
or not anyone wrote a second edge.
That is why most labels below have no inverse. Only two pairs do, because in each the reverse
direction is a genuine primary statement someone would write on its own: `depends-on` /
`required-by` and `runs-on` / `hosts`.
## When to run
Adding or changing a `related:` entry, authorising labels in a `COLLECTION.md`, or judging
whether a relationship is worth naming as a formal edge at all.
## Steps
1. **Decide whether this is an edge.** Not every mention is one. An edge is a reader aid: it
says *follow this if you need X*. A subject mentioned once in passing is prose with a
`[[wikilink]]`, not a declared relationship. Over-declaring is how a graph becomes a list of
everything adjacent to everything.
2. **Say the sentence.** `[this page] <label> [that page]`. If it reads backwards, you want the
other page to carry the edge, or a different label.
3. **Pick from the register that fits the pair**, below. Prefer the most specific label that is
true; fall back outward only when nothing fits.
4. **Check the collection authorises it** for that destination -
`kb/<name>/COLLECTION.md`'s `outbound:` block. If the label you want is not authorised and
should be, that is a collection-contract change, made deliberately, not a lint error to
route around.
5. **Write it with the tool**, never by hand:
```bash
tools/wikitool xref add --a "<This Page>" --b "<That Page>" --rel <label>
```
## The catalogue
### Operational
Concrete things and how they stand to one another - the register this instance runs on. Mostly
entity to entity.
| label | inverse | asserts |
|---|---|---|
| `depends-on` | `required-by` | cannot function without the target |
| `required-by` | `depends-on` | the target cannot function without this |
| `runs-on` | `hosts` | executes on the target as its substrate |
| `hosts` | `runs-on` | provides the substrate the target executes on |
| `uses` | — | employs the target at runtime, but survives without it |
| `produces` | — | emits the target as an artifact or data |
| `consumes` | — | reads the target as an artifact or data |
| `maintains` | — | carries the upkeep of the target |
| `owns` | — | is accountable for the target's existence and decisions |
`uses` versus `depends-on` is the distinction worth keeping sharp: if removing the target breaks
this thing, it is `depends-on`. `owns` versus `maintains`: accountability versus labour, and
they are often different people.
### Realization
How an idea becomes a running thing. Usually concept to entity or the reverse.
| label | asserts |
|---|---|
| `implements` | is a concrete realization of the target |
| `operationalized-from` | is the prescriptive form of the target's theory |
| `mechanism` | is the mechanism by which the target works |
| `procedure` | is the procedure for carrying out the target |
| `applies-when` | applies under the condition the target describes |
| `operates-on` | acts upon the target as its subject matter |
| `invokes` | calls the target as a step within itself |
### Conceptual
Inference and comparison between ideas.
| label | asserts |
|---|---|
| `extends` | develops the target's argument further |
| `grounds` | provides the basis the target rests on |
| `rests-on` | takes the target as its premise |
| `enables` | is the operational prerequisite that makes the target possible |
| `precondition` | must hold before the target applies |
| `exemplifies` | is an instance of the general claim the target makes |
| `abstracted-from` | generalizes from the target |
| `contrasts` | differs from the target in a way worth reading both for |
| `compares-with` | is weighed against the target on shared dimensions |
| `contradicts` | asserts something the target denies |
| `composition` | is composed of the target |
| `part-of` | is a component of the target |
`grounds` / `rests-on` is a genuine pair and both directions are primary statements; they are
listed separately rather than as inverses because either page may legitimately carry only its
own side.
### Lineage
Where something came from, and what replaced it.
| label | asserts |
|---|---|
| `supersedes` | replaces the target, which is now historical |
| `derived-from` | was produced from the target |
| `adapted-from` | was reworked from the target for a different purpose |
| `defined-in` | takes its definition from the target |
A superseded page is never deleted or rewritten - see the collection contract for
`kb/concepts/`.
### Evidence
The provenance register. Distinct from `sources:` and `[^cite-id]`, which are the *mechanical*
provenance path: these two are authored claims about how strongly something is backed.
| label | asserts |
|---|---|
| `evidenced-by` | is supported by the target as evidence |
| `is-evidence-for` | serves as evidence for the target's claim |
### Universal
| label | asserts |
|---|---|
| `see-also` | nothing more specific applies, and a reader here would still want the target |
**`see-also` is the last resort and should stay rare.** A collection where it is the commonest
label has a vocabulary problem, not a lot of loosely related pages. The previous vocabulary's
`verwandt mit` was exactly that, and it is the reason this catalogue exists.
## Extending it
Adding a label is a line of data, never a code change:
1. Add a row here, in the register it belongs to, with the sentence it completes.
2. Authorise it in the `COLLECTION.md` of every collection that may use it.
The registers are advisory groupings for readers, not a schema - nothing checks that a label is
used only within its register. Invent an intra-collection label the work needs and propose it
here afterwards; the architecture is deliberately loose, because the link theory is still
developing.
## Decision points
- **Two labels both fit?** Take the more specific one. If they are equally specific and mean
different things, the relationship is probably two edges.
- **The relationship reads better from the other page?** Write it there. Nothing is lost - the
inbound view renders it here.
- **You want a reverse edge for navigation?** You do not need one. That is what the rendered
inbound view is for, and it is complete in a way an authored mirror never was.
- **Nothing fits at all?** Use `see-also` and say so in the commit, or propose a label. Do not
stretch a label whose sentence reads false - a wrong edge is worse than a weak one, because
it is machine-readable and will be believed.
## Scope
Covers labels on `related:` edges between pages. Says nothing about `sources:` (the provenance
field, unlabelled by construction), `[^cite-id]` footnotes
([kb/CONTRACT.md](../kb/CONTRACT.md#provenance-and-citation)), or `tags:` (search keys, not
relationships).
instructions/migrations/4.0.0-link-taxonomy.md
+146
View File
@@ -0,0 +1,146 @@
---
type: types/instruction.md
name: 4.0.0-link-taxonomy
description: Move every relationship from free-text prose in a body bullet to a labelled edge in related:, and every tool-owned body region from heading-matching to a marker pair.
manual: true
migrates_to: 4.0.0
migration_kind: assisted
obligation: required
---
# Move relationships into the data, and generated regions behind markers (4.0.0)
Until 4.0.0 the stack used **prose as an identifier** in three places, and each one cost
something measurable:
| Was the identifier | Cost |
|---|---|
| A section's heading text (`## Beziehungen`) | The KB language was a compiler constant, and the region's *end* was a guess. Content sitting after it was silently deleted on eight pages |
| A relationship label in a body bullet (`- **hängt ab von:**`) | Nothing could check the vocabulary, so it drifted to **152 distinct labels** across 337 bullets against thirteen that were documented |
| The reciprocal half of every edge | `xref add` mirrored every link, which made per-collection label authorisation impossible and filled `## Siehe auch` with 555 unlabelled bullets, 353 of them provably redundant |
4.0.0 replaces all three. A region is delimited by a marker pair and rendered from frontmatter;
a label is a machine value in `related:`, drawn from a catalogue and authorised per destination
by the source collection; an edge is authored in one direction and the inbound view is computed.
**This one touches pages.** Unlike 3.0.0 it is not a contract reshuffle: every `related:` entry
and every tool-owned body region changes. It is `assisted` because there is no mapping table -
mapping free-text German onto a 35-label catalogue is a judgment call per edge, and a large
minority of the old labels are reverse directions that under the new model are not stored at all.
## When to run
After installing 4.0.0 over an instance on 3.x. `tools/wikitool migrate status` names it, and
`lint` reports `unlabelled_edges` for every unconverted edge - that count reaching zero is how
you know the run is finished.
**Nothing breaks while it is outstanding.** Unlabelled edges and undelimited regions are read,
not rejected: `links.py` treats a bare title as an edge whose label is not declared yet, and
`provenance.split_cite_block` falls back to the pre-marker layout. That is deliberate - a corpus
has to stay readable while it is being converted - and it is why the two lint findings are
advisory until step 6 promotes them.
## Steps
1. **Rewrite `kb/CONVENTIONS.md`'s `sections:` block.** Three slots become two, because the
See Also region is gone:
```yaml
sections:
links: <your heading for declared relationships>
footnotes: <your heading for citation definitions>
```
Delete `section_aliases:` if you have one - nothing matches on heading text any more, so
there is nothing to alias. The heading is now a *rendering* value: changing it re-renders
the words above each region on the next write and can no longer split a page.
2. **Add an `outbound:` block to every `kb/<name>/COLLECTION.md`.** Which labels a page may use,
per destination collection, with `any` as a wildcard:
```yaml
outbound:
entities: [depends-on, runs-on, uses, see-also]
concepts: [implements, see-also]
```
The catalogue to draw from is [link-taxonomy.md](../link-taxonomy.md); the four contracts in
the origin repo are worked examples. **The source collection decides** - that is what makes a
35-label palette usable, and it is why the reverse edge can no longer be written
automatically. A destination you do not list authorises nothing, which is a real answer.
3. **Fix your page type-spec templates.** If you adopted the 3.0.0 templates, they contain
`## {section.relationships}` and `## {section.see_also}`. Those variables no longer exist and
would be written into new pages literally. **Delete both sections from the `## Template`
block** - a template must not scaffold a tool-owned region at all: it is generated between
markers on the first `xref add` / `cite add` and re-rendered on every write.
4. **Convert the corpus**, following [migrate-corpus.md](../migrate-corpus.md). Cut it into
units sized against the iteration budget; the origin repo used four, ~45 pages each. Per page:
- For each labelled bullet under the old relationships heading: say the sentence
`[this page] <label> [target]` and pick the catalogue label that makes it true. If it only
reads true **backwards**, the edge belongs on the other page - move it there rather than
inventing an inverse label the catalogue does not have.
- For each bare `- [[X]]` bullet under the old See Also heading: drop it if a labelled edge
already connects the pair. Otherwise decide - a real label, or dropped with the reason
recorded. **Do not convert them to `see-also` in bulk.** That is the one shortcut this
migration explicitly refuses: it would start the new taxonomy with most of its edges on its
weakest label, which is the sediment the change exists to remove.
- Write edges with `tools/wikitool xref add --a "<A>" --b "<B>" --rel <label>`, never by
hand. The body region is rendered from `related:`; editing inside a marker pair is
overwritten without warning.
- `cite sync` converts a page's old footnote block into a marked region in passing.
5. **Check each unit mechanically before anything else:**
```bash
tools/wikitool migrate verify --from <pre-migration rev> --path kb/<area> --fail-on-error
```
It compares wikilink and citation **counts**, footnote definitions, H1, structural
frontmatter, and - new in 4.0.0 - the **count of marker pairs per region**. A dropped marker
is otherwise silent: the region becomes ordinary prose and the next write appends a second
one beside it.
6. **Record it, then tighten the checks:**
```bash
tools/wikitool lint # unlabelled_edges and unauthorised_labels must be 0
tools/wikitool migrate done 4.0.0 --pages <N>
```
Only once `lint` reports zero of both is the run finished. The two findings are advisory
during the window and become hard errors afterwards - the same path
`legacy_citation_markers` took after the citation migration.
## How to tell a migrated page from an unmigrated one
Its `related:` entries are `- <label>: <title>` rather than bare titles, and its relationship
and footnote sections sit between `<!-- wikitool:links -->` / `<!-- wikitool:footnotes -->`
marker pairs. `tools/wikitool links show --page "<Title>"` prints `unlabelled` for every edge
still waiting, and `lint`'s `unlabelled_edges` count is the corpus-wide version of the same
question.
## Decision points
- **A label you want is not in the catalogue?** Add it - a row in `link-taxonomy.md` and an
entry in the authorising `COLLECTION.md`. No code change is involved, and the registers are
advisory groupings rather than a schema. Do not stretch a label whose sentence reads false: a
wrong edge is worse than a weak one, because it is machine-readable and will be believed.
- **`related:` holds an entry with no body bullet to derive a label from?** Expected - the
origin repo found 480 edges against 337 bullets, because frontmatter and body had already
drifted apart while the label lived only in prose. Read the page and decide; that drift is
itself part of what this migration repairs.
- **A page loses its last inbound edge?** The orphan check will now report it, and that is the
check working: directional edges mean a page nothing points at is genuinely unreachable, where
the old mirrored model always manufactured a back-link. Either something should point at it,
or it is reached through the catalog and that is fine.
- **Tempted to keep writing reverse edges for navigation?** Do not. `links show` computes the
inbound view, and the rendered bullet on the asserting page is an ordinary `[[wikilink]]`, so
a backlink panel in an editor already shows it.
## Scope
The corpus under `kb/`, plus the three instance-owned declarations in steps 1-3. It does not
touch `raw/`, and it learns nothing new: the same knowledge is restated in a form that can be
checked. Installing the 4.0.0 machinery itself is `INSTALL.md`'s and must have happened first.
instructions/setup-instance.md
+19 -6
View File
@@ -68,17 +68,23 @@ bereit für den ersten `Ingest`.
Ablauf:
1. Die Collection-Contracts übernehmen - vier Kopien, keine Frage an den Nutzer, denn was
dort steht ist unabhängig von der Sprache brauchbar:
1. Die Collection-Contracts **und die Page-Type-Specs** übernehmen - Kopien, keine Frage an
den Nutzer, denn was dort steht ist als Ausgangspunkt unabhängig von der Sprache brauchbar:
```bash
for template in kb/*/COLLECTION.md.template; do
for template in kb/*/COLLECTION.md.template types/*.template; do
cp "$template" "${template%.template}"
done
```
Die `.template`-Dateien bleiben liegen; sie sind die Vorlage für den nächsten Export.
Unter `types/` betrifft das genau die Type-Specs mit `root: kb` - `entity`, `concept`,
`source`, `comparison` - samt ihrer `.schema.yaml`. Sie beschreiben Seiten, die *diese*
Instanz schreibt, also gehören sie ihr: Prosa, Template und Sprache dürfen umgeschrieben
werden. `instruction`, `lint-report` und `type-spec` beschreiben Stack-Artefakte und
kommen unverändert.
2. Den Nutzer nach der KB-Sprache fragen. `kb/CONVENTIONS.md.template` ist auf **Englisch**
voreingestellt; [kb-profiles.md](kb-profiles.md) hält daneben ein vollständiges
deutsches Profil bereit, und dessen Volltext ist die `kb/CONVENTIONS.md` des Quell-Repos.
@@ -99,9 +105,16 @@ bereit für den ersten `Ingest`.
Migration jeder vorhandenen Seite (`section_aliases:` trägt die alten Namen, siehe
[migrate-corpus.md](migrate-corpus.md)).
**Nichts davon liegt unter `tools/` oder `types/`.** Der Compiler liest die Abschnittsnamen
aus `kb/CONVENTIONS.md`, und die vier Page-Type-Templates setzen sie über
`{section.…}`-Variablen ein - eine anderssprachige Instanz ändert dort keine Datei.
**Nichts davon liegt in einer Stack-Datei.** Der Compiler liest die Abschnittsnamen aus
`kb/CONVENTIONS.md`; die vier Page-Type-Specs gehören ab Schritt 1 dieser Instanz. Eine
anderssprachige Instanz übersetzt sie einfach - das ist kein lokaler Patch an etwas
Ausgeliefertem mehr, sondern Arbeit an den eigenen Dateien, und ein Upgrade nimmt sie ihr
nicht wieder weg.
Was der Stack von `types/` überhaupt noch verlangt, ist eine Zeile: es muss einen Type-Spec
mit `name: source` geben, dessen Schema `raw_files` fordert. Daran hängt der gesamte
`raw/`→`kb/`-Provenance-Pfad (`sources coverage`, `[^cite-id]`-Auflösung, `kb/provenance.md`),
und `docs verify` prüft genau das - nicht mehr.
Unverändert bleibt in jedem Fall die Regel, die dem Stack gehört: **jede Zeile einer Seite
ist Prosa oder Identifier, und nur Prosa wird übersetzt** ([kb/CONTRACT.md § Language and