# Plan: link-taxonomy-migration

One unit is one session id and one `publish`, sized against the 60-call iteration budget.
Per-page cost here is roughly `1 touch` + the edges on it; the corpus-wide commands
(`index rebuild`, `sources rebuild-index`, `log append`, `publish` twice for the gate) are
per unit, not per page. That puts the ceiling near 45 pages and the target at 40.

| # | Unit | Pages | Job | Done when |
|---|------|------:|-----|-----------|
| u0 | mechanism | 0 | Taxonomy catalogue, `links.py`, `blocks.py`, `outbound:` in every `COLLECTION.md`, `xref` rewritten to one directional edge, lint checks, `links show` for the inbound view, `migrate verify` marker invariant, deletion of `sections.py` and the matching layer | Suite green; `lint` reports the corpus's unlabelled edges as findings rather than crashing |
| u1 | `kb/entities/systems`, `tools`, `technologies` | ~45 | Label every edge, drop redundant see-also, wrap markers | `migrate verify --path kb/entities --fail-on-error` clean |
| u2 | `kb/entities/projects`, `people`, `kb/comparisons` | ~40 | as u1 | as u1 |
| u3 | `kb/concepts` | ~45 | as u1 | `migrate verify --path kb/concepts --fail-on-error` clean |
| u4 | `kb/sources` | ~50 | as u1, plus `entities:`/`concepts:` on source pages | `migrate verify --path kb/sources --fail-on-error` clean |
| u5 | close-out | 0 | `migrate done 4.0.0`, `version bump --major`, `CHANGES.md` body, promote nothing, close workshop | `docs verify` + `lint --fail-on-error` green, workshop deleted |

Unit boundaries are written down here *before* the run so that publishing several units
together stays a planned batch rather than a way around a Mass-Update Gate refusal - see
`instructions/gates.md`.

## Per-page procedure

1. Read the page's `## Beziehungen` and `## Siehe auch` blocks.
2. For each labelled bullet: say the sentence `[this page] <label> [target]`. Pick the catalogue
   label that makes it true. If it only reads true backwards, the edge belongs on the other
   page - move it, do not invert the label into something the catalogue does not have.
3. For each bare `## Siehe auch` bullet: drop it if a labelled edge already connects the pair
   (the tooling lists these). Otherwise decide - a real label, or dropped with the reason
   recorded in the unit's notes.
4. Write the edges with `xref add --rel`, never by hand.
5. The body blocks are then *generated*: no hand-editing inside a marker pair.

## Vocabulary carried between units

`glossary.md` in this directory. A mapping decided in u1 and re-decided in u3 is the failure the
file exists to prevent - add to it **before** dispatching the next unit.

## Deliberately excluded from this run

- **Commonplace's articulation test and the `connect` report workflow.** They change how ingest
  proposes links, not how links are stored. Separate question, separate issue.
- **Promoting the lint checks to hard errors.** During this run an unlabelled edge is a finding,
  because that is precisely the migration window `.wikitool-kb.json` exists to represent. The
  promotion is a later version's change, once the corpus can pass it.
- **`sources:` and `[^cite-id]`.** The provenance path is unlabelled by construction and is not
  part of the link taxonomy.
- **Any change to page prose.** This run restates relationships in a new form; it learns
  nothing new, and a body edit outside a marker pair is out of scope.