feat: Prosa ist kein Identifier - Link-Taxonomie als Enum, generierte Regionen mit Markern (4.0.0)
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:
@@ -0,0 +1,88 @@
|
||||
# Workshop: link-taxonomy-migration
|
||||
|
||||
- **Run key:** `link-taxonomy-migration` (this directory's name - there is no other identifier)
|
||||
- **Input:** none - this run is not an ingest
|
||||
- **Started:** 2026-09-02
|
||||
- **Session id form:** `WIKITOOL_SESSION_ID="link-taxonomy-migration/u<N>"`, one per unit
|
||||
- **Issue:** Gitea #40, sections *Label werden Enum* and *Toolgeführte Blöcke*
|
||||
|
||||
## Goal
|
||||
|
||||
Move every relationship in `kb/` from free-text German prose in a body bullet to a machine
|
||||
value in `related:`, and every tool-owned body region from heading-matching to a marker pair.
|
||||
Afterwards the compiler contains no heading text and no relationship label, and `lint` can
|
||||
enforce the vocabulary because there is one.
|
||||
|
||||
## Why this is `assisted` and not `mechanical`
|
||||
|
||||
Measured on 2026-09-02, against the corpus rather than against the documentation:
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Pages | 180 |
|
||||
| Distinct relationship labels in body bullets | **152** |
|
||||
| Labelled bullets | 337 |
|
||||
| Labels occurring exactly once | 102 |
|
||||
| Top 20 labels cover | 167 of 337 |
|
||||
| Bare `- [[X]]` bullets under `## Siehe auch` | 555 |
|
||||
| ...of those, provably redundant (a labelled edge already exists) | 353 |
|
||||
| ...of those, the only connection between the two pages | **202**, across 63 target pages |
|
||||
|
||||
`kb/CONVENTIONS.md` documents thirteen labels. Nothing ever checked that, and the corpus does
|
||||
not follow it - so there is no mapping table to apply, and roughly 539 edges need a judgment
|
||||
call each. A large minority are reverse directions (`Verwendet von` 20x, `implementiert durch`,
|
||||
`Ersetzt durch`), which under authored directional edges are exactly the edges that stop being
|
||||
stored and start being rendered.
|
||||
|
||||
Rejected alternative, recorded so it is not re-proposed: map the top 20 mechanically and set
|
||||
everything else to `see-also`. That would start the new taxonomy with ~370 of ~539 edges on its
|
||||
weakest label - the `verwandt mit` sediment this whole change exists to end, re-created as the
|
||||
documented initial state.
|
||||
|
||||
## Closes when
|
||||
|
||||
Every unit in `plan.md` is published, and:
|
||||
|
||||
- `wikitool lint` reports zero unlabelled edges and zero labels outside the authorising
|
||||
collection's `outbound:` block
|
||||
- `wikitool migrate verify --from <pre-migration rev>` reports no wikilink or citation count
|
||||
change, and no unbalanced marker
|
||||
- `wikitool migrate done 4.0.0 --pages <N>` has run
|
||||
|
||||
## Checklist
|
||||
|
||||
- [x] u0 mechanism - taxonomy, `links.py`, `blocks.py`, `xref` rewrite, lint checks,
|
||||
`links show` for the inbound view, deletion of the matching layer. No page touched.
|
||||
- [ ] u1 `kb/entities/` (systems, tools, technologies)
|
||||
- [ ] u2 `kb/entities/` (projects, people) + `kb/comparisons/`
|
||||
- [ ] u3 `kb/concepts/`
|
||||
- [ ] u4 `kb/sources/`
|
||||
- [ ] u5 close-out - `migrate done`, version bump, `CHANGES.md`, workshop close
|
||||
|
||||
## Measured after u0
|
||||
|
||||
`lint` against the corpus, with the machinery in place and no page touched:
|
||||
|
||||
| Finding | Count |
|
||||
|---|---|
|
||||
| `unlabelled_edges` | **480** - every `related:` entry, since none carries a label yet |
|
||||
| `unauthorised_labels` | 0 - nothing declares a label at all, so nothing can be unauthorised |
|
||||
| `malformed_edges` | 0 |
|
||||
| `unbalanced_markers` | 0 |
|
||||
| `orphan_pages` | 1 (`GRUB`, pre-existing) |
|
||||
| `broken_links`, `dangling_frontmatter_refs`, `schema_validation_errors` | 0 |
|
||||
|
||||
480 is the number u1-u4 have to bring to zero. It is larger than the 337 labelled body bullets
|
||||
because `related:` also holds entries whose bullet was lost or never written - which is itself a
|
||||
finding: the frontmatter and the body had already drifted apart under the old model, and nothing
|
||||
could see it while the label lived only in the prose.
|
||||
|
||||
## Open decisions
|
||||
|
||||
- **Settled 2026-09-02:** edges are directional; the reverse edge is authored only when it is a
|
||||
primary statement on its own page. The inbound view is rendered, not stored.
|
||||
- **Settled 2026-09-02:** the 353 provably-redundant `## Siehe auch` edges are dropped
|
||||
mechanically. The 202 that are the only connection get a real label each, or are dropped with
|
||||
a reason - never converted to `see-also` in bulk.
|
||||
- **Settled 2026-09-02:** labels are not localized. `- **depends-on:** [[Hermes]]` is what a
|
||||
German page carries.
|
||||
Reference in New Issue
Block a user