Doku-Hälfte zu 4.7.0: redundant_see_also in tools/CONTRACT.md und wiki-lint, xref-remove-Falle benannt (4.7.1, #49)

Files changed:
- CHANGES.md
- VERSION
- instructions/wiki-lint/SKILL.md
- tools/CONTRACT.md

.gitea/workflows/release.yml

@@ -102,11 +102,32 @@ jobs:
       - name: Release notes from CHANGES.md
         # `version notes` fails when the changelog has no entry for this
         # version, which is the last place that mistake can still be caught.
+        #
+        # The footer below settles Gitea #47's second side-finding: a release
+        # note is written once, at tag time, and a later correction to
+        # CHANGES.md never reaches it - `gitea-mcp` has no release-edit method,
+        # and delete-and-recreate would destroy the attached tarball assets that
+        # INSTALL.md and `version check` point at. That happened for real to
+        # v4.4.0, whose note carried a fact that the corpus had already
+        # corrected. Rather than build a correction path for a text nobody can
+        # edit, the snapshot says it is one and names where the maintained
+        # version lives. A stale note then costs a reader one click instead of
+        # a wrong belief. Appended here rather than inside `version notes`,
+        # which is a general-purpose extractor whose other callers (a local
+        # preview, a pipe) should not inherit a release-page footer.
         if: steps.version.outputs.skip != 'true'
         run: |
           set -eu
           tools/wikitool docs verify
           tools/wikitool version notes > /tmp/release-notes.md
+          cat >> /tmp/release-notes.md <<'EOF'
+
+          ---
+
+          *This note is a snapshot of the `CHANGES.md` entry as it stood when the tag was cut, and
+          is never edited afterwards. The maintained version of this text - including any later
+          correction - is the entry for this version in `CHANGES.md` in the repository.*
+          EOF
           cat /tmp/release-notes.md
 
       - name: Build the distribution tarball

CHANGES.md

@@ -35,6 +35,285 @@ dev-checkout concern - readable here, never shipped as something to parse.
 
 ---
 
+## 4.7.1 - 2026-09-04 - redundant_see_also in tools/CONTRACT.md und wiki-lint dokumentiert; xref-remove-Falle benannt
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- redundant_see_also in tools/CONTRACT.md und wiki-lint; xref-remove-Falle beim Aufräumen benannt
+<!-- /wikitool:bumps -->
+
+Die Doku-Hälfte von `4.7.0`, beim Abschluss nachgezogen. Der Befund war ausgeliefert, aber
+`tools/CONTRACT.md`s `lint`-Zeile zählt die Befunde auf und kannte ihn nicht - eine Instanz hätte
+eine Sektion im Report gefunden, die ihr Contract nicht erklärt. `docs verify` prüft, dass die
+Kommandotabelle existiert, nie was in einer Zeile steht; genau die Lücke, für die AGENTS.md
+„a stack change is not finished until the human docs describe it" geschrieben ist.
+
+**Die eigentliche Änderung ist aber die Warnung in `wiki-lint`**, und sie ist keine Prosa-Politur.
+Der neue Befund liest sich wie etwas, das Schritt 7 („repariere, was mechanisch ist") abräumt, und
+der naheliegende Griff wäre `xref remove` - das die Referenz **beidseitig** löscht. Angewandt auf
+`Wine see-also Wine GE` neben `Wine GE depends-on Wine` hätte das die schwache *und* die
+spezifische Kante entfernt, und das Paar sagte danach gar nichts mehr. Ein Befund, dessen
+offensichtliche Reparatur Daten zerstört, ist schlechter als kein Befund: Schritt 1 nennt die
+Falle jetzt beim Namen und verweist auf `xref add` (fasst nur die Quellseite an) oder aufs
+Berichten. Dieselbe Asymmetrie hat in #30 schon einmal Daten gekostet.
+
+---
+
+## 4.7.0 - 2026-09-04 - Link-Katalog: authored, alternative-to, addresses; entity→entity-Lineage; Lint-Befund gegen redundante see-also
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- Link-Katalog: authored, alternative-to, addresses; Lint-Befund gegen redundante see-also
+<!-- /wikitool:bumps -->
+
+Drei neue Label, zwei geschlossene Autorisierungslücken und ein Lint-Befund - ausgelöst von der
+anstehenden ersten produktiven Instanz. Katalog und `COLLECTION.md` gehen über `dist export` in
+jede neue Instanz; was hier fehlt, fehlt dort ab Tag eins, und nachträglich ist eine
+Katalogerweiterung eine Korpus-Migration statt einer Datenzeile. Gitea #43 und #49.
+
+**Die Messung, die den Zuschnitt bestimmt hat.** Die 180 `see-also`-Kanten des Korpus zerfallen
+exakt in drei Klassen: 57 (32 %) sind Spiegel einer bereits typisierten Gegenkante, 70 (39 %)
+sind wechselseitige `see-also`-Paare, 53 (29 %) stehen einseitig. Die erste Klasse ist kein
+Vokabularproblem - `Wine see-also Wine GE` steht neben `Wine GE depends-on Wine`, `RAG see-also
+NotebookLM` neben `NotebookLM implements RAG`. Der Katalog war für ein Drittel der Fälle längst
+ausreichend; es hat sie nur nichts gemeldet. Genau dafür ist der Lint-Befund unten da, und er ist
+der Grund, warum diese Version mehr ist als zwei Katalogzeilen.
+
+**`authored`** (operationales Register). „hat das Ziel als einmaligen Akt geschaffen." Der Katalog
+kannte fortlaufende Rechenschaft (`owns`) und fortlaufende Arbeit (`maintains`), aber nicht den
+historischen Ursprung - Urheberschaft stand im Korpus deshalb in vier unvereinbaren Formen
+nebeneinander: `source.author` als Freitext, `owns`, `see-also` und ein Prosa-Bullet. Eine davon
+war sachlich falsch: `Vannevar Bush owns Memex` behauptet laufende Rechenschaft für einen 1974
+Verstorbenen, und eine falsche maschinenlesbare Kante ist schlechter als eine schwache, weil sie
+geglaubt wird. Geschrieben wird das Label auf der Entity-Seite (`Andrej Karpathy authored LLM
+Wiki Pattern`) - die Gegenrichtung `authored-by` auf der Concept-Seite hätte `xref remove`
+gebraucht, das beidseitig abräumt, statt `xref add`, das relabelt. Vier Kanten im Korpus
+umgestellt, keine verloren.
+
+**`alternative-to`** (operationales Register, selbst-dual). „erfüllt denselben Zweck wie das Ziel,
+so dass ein Leser, der zwischen beiden wählt, beide will." Belegt durch rund 30 Paare, darunter
+die sieben Agent-CLIs, die untereinander *ausschließlich* `see-also` tragen - keine einzige
+typisierte Kante. Abgegrenzt gegen `contrasts` (behauptet einen lesenswerten Unterschied) und
+`compares-with` (wiegt auf benannten Dimensionen ab und führt in dieser Instanz auf eine
+`kb/comparisons/`-Seite): zwei Agent-CLIs sind austauschbar, zwei gegensätzliche Entwurfsprinzipien
+sind es nicht.
+
+Der Katalog sagt jetzt ausdrücklich, dass ein selbst-duales Label **einmal pro Paar** geschrieben
+wird. Ohne diesen Satz wäre aus einer 22-Kanten-`see-also`-Clique eine 22-Kanten-
+`alternative-to`-Clique geworden und nichts gewonnen: sieben austauschbare Werkzeuge sind 21
+Paare, beidseitig deklariert 42 Kanten, von denen die zweiten 21 nichts sagen.
+
+**`addresses`** (konzeptionelles Register). „ist eine Antwort auf das Problem, das das Ziel
+beschreibt." `types/concept.md` deklariert `problem` und `decision` als eigene Subtypen, und der
+Katalog hatte kein Label, das eine Entscheidung mit dem Problem verbindet, das sie löst - eine
+Collection konnte ein Problem benennen und nie sagen, was dagegen unternommen wurde. Abgegrenzt
+gegen `rests-on`, das das Ziel als *Prämisse* nimmt statt als zu lösendes Problem. Im Korpus nur
+vier belegte Paare, also dünn nach dem sonst geltenden „erst der Anwendungsfall"-Maßstab; die
+Ausnahme ist bewusst und gilt dem Auslieferungszeitpunkt, der die Kosten umdreht.
+
+**Zwei Autorisierungslücken entity→entity.** `kb/entities/COLLECTION.md` erlaubte bisher keine
+Lineage zwischen zwei Entities - ein Fork, eine Neuimplementierung, ein Nachbau war nicht
+ausdrückbar; `derived-from` und `adapted-from` sind jetzt freigegeben. Ebenso `implements`, für
+eine Entity, die eine als Entity geführte Konvention umsetzt. Ein autorisiertes Label ohne
+Live-Nutzung ist ausdrücklich in Ordnung (`instructions/dev/corpus-policy.md`).
+
+**Lint-Befund `redundant_see_also`.** Meldet eine `see-also`-Kante, deren Gegenrichtung bereits
+ein typisiertes Label trägt. Gegen den Korpus dieser Instanz meldet er genau die gemessenen 57.
+**Advisory, nicht hart**, aus zwei Gründen zugleich: eine schwache Kante neben einer spezifischen
+ist redundant, nicht kaputt - und der Befund kommt lange nach den Korpora, die er beurteilt, also
+würde eine harte Einstufung jede bestehende Instanz mit dem Upgrade rot schalten, das ihn
+ausliefert. Anders als `unlabelled_edges` ist er auch nicht migrations-gegatet: es gibt keine
+Version, ab der die Redundanz zum Fehler wird, nur einen Sweep, zu dem jemand kommt oder nicht.
+
+`links.SEE_ALSO` ist damit das einzige Katalog-Label, das das Werkzeug beim Namen kennt. Das ist
+eine begründete Ausnahme, keine Aufweichung: `see-also` ist der erklärte letzte Ausweg des
+Katalogs und behauptet nur, dass nichts Besseres passte - was der einzige Grund ist, warum `lint`
+eine Kante als *schwächer als* eine andere über demselben Paar beurteilen kann. Alles andere am
+Vokabular bleibt in `instructions/link-taxonomy.md` und den `outbound:`-Blöcken.
+
+**Nicht dabei, bewusst.** Der Sweep der 180 bestehenden Kanten (#48) - diese Version ändert außer
+den vier Urheberschaftskanten keine Korpus-Kante. Verworfen wurden außerdem `variant-of` (die
+Wine-Forks tragen bereits `depends-on Wine`), `implemented-by` (Spiegel von `implements`, den die
+Inbound-View rendert), `sibling-of` für die Concept-Cliquen (Über-Verlinkung, kein fehlendes Wort)
+und `builds-on` (Vokabularkollision mit `extends`/`derived-from`/`adapted-from`).
+
+---
+
+## 4.6.1 - 2026-09-04 - DEVELOPMENT.md im Kommandotabellen-Check, selbstbeschriftete Release-Notes, Prosa-Korrekturen (#47 Block 3)
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- DEVELOPMENT.md im Kommandotabellen-Check, selbstbeschriftete Release-Notes, Prosa-Korrekturen (#47 Block 3)
+<!-- /wikitool:bumps -->
+
+Block 3 aus #47 - die beiden Nebenbefunde entschieden und umgesetzt - plus drei Prosa-Korrekturen
+an `4.6.0`, die eine Bewertung des eigenen Ergebnisses gefunden hat.
+
+**`DEVELOPMENT.md` gehört in `docs_verify.STAGE_READMES`** (entschieden: ja). Das Gegenargument
+bei der Aufnahme war, die Liste führe bisher nur ausgelieferte Dokumente, und `DEVELOPMENT.md`
+wird von `dist_cmd.ROOT_FILES` bewusst nicht ausgeliefert. Beim Hinsehen löst es sich auf:
+`check_readmes_have_no_command_table` überspringt eine Datei, die nicht existiert. In einer
+ausgelieferten Instanz ist der Eintrag damit schlicht wirkungslos, im Entwicklungs-Checkout - dem
+einzigen Ort, an dem die Datei existiert und also driften kann - greift er. Dafür spricht der
+Anlass: genau diese Datei trug einmal eine Tabelle, die für jeden Verify-Befehl ein zweites Mal
+beschrieb, was er prüft, und sie musste von Hand entfernt werden, weil nichts sie mit etwas
+verglich. Zwei Tests: einer, der die Tabelle in `DEVELOPMENT.md` meldet, und einer, der
+festhält, dass eine fehlende gelistete Datei übersprungen und nicht als Fund gemeldet wird - der
+Instanz-Fall, an dem die Entscheidung hing. Der Konstantenname ist jetzt enger als sein Inhalt;
+das steht als Kommentar daneben, statt eine Umbenennung durch zwei Aufrufstellen zu ziehen.
+
+**Veröffentlichte Release-Notes veralten weiter - sie sagen es jetzt selbst** (entschieden:
+Schnappschuss akzeptieren, statt einen Korrekturweg zu bauen). Eine nach dem Tag korrigierte
+`CHANGES.md` erreicht die Release-Seite nicht: `gitea-mcp` kennt kein Release-Edit, und
+Löschen-und-neu-Anlegen würde die angehängten Tarball-Assets vernichten, auf die `INSTALL.md` und
+`version check` zeigen. Bei `v4.4.0` ist das real eingetreten. Statt eines Korrekturwegs für einen
+Text, den niemand editieren kann, trägt der Schnappschuss jetzt eine Fußzeile, die sagt, dass er
+einer ist und wo die gepflegte Fassung liegt - eine veraltete Notiz kostet einen Leser damit einen
+Klick statt einer falschen Überzeugung. Angehängt in `release.yml` und nicht in `version notes`:
+das Kommando ist ein allgemeiner Extraktor, dessen andere Aufrufer (lokale Vorschau, eine Pipe)
+keine Release-Seiten-Fußzeile erben sollen. `.gitea/`-Änderung, also ohne eigenen Bump-Anspruch -
+sie fährt hier mit.
+
+**Drei Prosa-Korrekturen an `4.6.0`.** Der `4.6.0`-Eintrag und der Docstring von
+`touches_stack_machinery` behaupteten, das Prädikat prüfe „denselben Pfad-Umfang, den der
+CI-Versions-Gate selbst verwendet". Das stimmt nicht: CI matcht `[^/]+/CONTRACT\.md$`, also genau
+eine Pfadebene, das Prädikat matcht `CONTRACT.md` in jeder Tiefe. Folgenlos im Verhalten - ein
+Über-Match druckt eine Zeile zu viel, nie eine zu wenig -, aber es war eine behauptete Äquivalenz,
+die keine ist, geschrieben in genau der ungeprüften Prosa-Phase, um die #47 sich dreht. Docstring
+und `tools/CONTRACT.md` benennen die Differenz jetzt und begründen sie (bei einer Erinnerung ist
+Über-Matchen die richtige Richtung). Drittens: `stack-close` beschrieb den eigenen Skill-Schnitt
+zu stark („es gibt keinen nächsten Schritt mehr, an dem vorbei zu rutschen wäre"). Wahr für die
+*Prozedur*, die nicht mehr im Kontext steht; nicht wahr für den *Auslöser* - `stack-dev`s „invoke
+it now" ist weiterhin ein Satz, und die `publish`-Notiz nennt den Skill bewusst nicht beim Namen.
+Zwei der drei Kettenglieder bleiben Selbstdisziplin. Der Skill sagt das jetzt selbst, statt sich
+als Garantie zu verkaufen, die er nicht ist.
+
+Verifiziert: `tools/wikitool docs verify`, `tools/wikitool instructions verify`,
+`.venv/bin/python -m pytest -q` (969 passed, 2 davon neu), `release.yml` gegen den YAML-Parser
+und das Heredoc als Trockenlauf gegen eine Beispiel-Notiz.
+
+---
+
+## 4.6.0 - 2026-09-04 - stack-dev/stack-close skill split, publish stack-machinery note, model-selection fix (#47 Block 2)
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- stack-dev/stack-close skill split, publish stack-machinery note, model-selection fix (#47 Block 2)
+<!-- /wikitool:bumps -->
+
+Block 2 aus #47 (Vorschlag E, am 2026-09-04 entschieden): die ungeprüfte Schlussphase einer
+Stack-Sitzung - Issue-Body-Rewrite, `docs/`-Veralterung, Changelog-Prosa - hatte bisher keinen
+eigenen Haltepunkt, sondern einen Prosa-Break in `stack-dev` Schritt 6. Der ist zweimal
+hintereinander verschluckt worden (#42, #30), beide Male mit echtem Fund im nachgeholten
+Durchgang. Ein dritter Prosa-Haltepunkt hätte dieselbe Wette verloren, die
+`docs/why-gates-are-code.md` für Gates schon verliert - also keine Prosa-Lösung mehr, sondern ein
+struktureller Schnitt.
+
+**Neuer Skill `stack-close`**, dev-only wie `stack-dev`. `stack-dev` endet nach `tools/wikitool
+publish` mit einem Stop statt mit einem sechsten Schritt; die Schlussphase existiert nur noch als
+eigener Skill, den eine Sitzung aufrufen muss - es gibt keinen „nächsten Schritt" mehr, an dem
+vorbei sie rutschen könnte. `stack-close` trägt drei Dinge: den Modell-Rückwechsel-Hinweis (wie
+zuvor), die Body-Rewrite-Disziplin aus `issue-tracking.md` Schritte 2-3 und 7, und neu die
+**Handover-Pflicht über die ganze Sitzung**: benannt wird das Modell für Design/Versionsstelle
+(Schritt 3), für die mechanische Mitte, und für diese Schlussphase - alle drei, auch wenn sie
+identisch sind. Eine Handover-Zeile, die nur eine billige Schlussphase meldet, schweigt genau
+dann, wenn die ebenso ungeprüfte Design-Phase auch billig lief und niemand dort gewechselt hat.
+
+Ein Agenten-Zuschnitt (Schlussphase als eigener Subagent mit eigenem Modell) wurde geprüft und
+verworfen: ein Fork erbt in Claude Code zwingend das Elternmodell, ein frischer Subagent den
+Sitzungskontext nicht - die Kombination, die der Zuschnitt bräuchte, gibt es nicht, und selbst
+wenn: der Input der Schlussphase *ist* das akkumulierte Sitzungswissen, das ein kalter Agent aus
+Diff und Issue neu ableiten müsste. Volle Begründung im Body von #47.
+
+**`instructions/claude-code-model-selection.md` korrigiert**, im dist-strip-Block: die
+Übersicht „stack-dev Schritt 3 und 6" ist falsch geworden, seit Schritt 6 nicht mehr existiert.
+Sie benennt jetzt beide Haltepunkte an ihrem tatsächlichen Ort - Schritt 3 in `stack-dev`,
+der zweite am Anfang von `stack-close`.
+
+**`stack-dev` Schritt 3 ehrlicher formuliert** (Vorschlag C): nicht mehr „ab hier alles
+mechanisch", sondern mit benannter Ausnahme - Changelog-Prosa (Schritt 4), eine berührte
+`docs/`-Seite, neue Menschendoku, der Prosa-Anteil einer Instruction. Dazu die Einschränkung aus
+#30: „durch Tests abgedeckt" gilt nur für das, was die Tests *treffen* - zwei
+datenvernichtende Bugs in `upstream merge` liefen an einem grünen `pytest`/`docs
+verify`/`instructions verify`/CI vorbei, weil kein Test den Fall traf, nicht weil ein
+schwächeres Modell schlechteren Code für den getesteten Fall geschrieben hätte.
+
+**Neu: `tools/wikitool publish` selbst erinnert an die Phasengrenze.** Berührt das Changeset
+`tools/`, `types/`, `instructions/`, `AGENTS.md` oder ein `<stage>/CONTRACT.md` - derselbe
+Umfang, den ein Versions-Bump selbst abdeckt -, druckt `publish` nach der Erfolgsmeldung eine
+Zeile, dass die folgende Phase von keinem der drei Checks abgedeckt ist. Kein Gate, keine
+Änderung am Exit-Code, für eine gewöhnliche Content-Publish stumm; harness- und
+instanzneutral formuliert, ohne jede Erwähnung eines Trackers, weil `publish` von jedem
+Skill genutzt wird, nicht nur von `stack-dev`. `git_publish.touches_stack_machinery()` plus
+vier neue Tests (`test_git_publish.py`): zwei für die reine Klassifikationsfunktion
+(positiv/negativ), zwei Integrationstests gegen einen echten Publish - die Notiz erscheint genau
+einmal bei einer `instructions/`-Änderung und bleibt aus bei einer gewöhnlichen `kb/`-Änderung.
+`tools/CONTRACT.md`s `publish`-Zeile trägt die Kurzfassung, absichtlich ohne den Dateinamen
+`version-parts.md` zu nennen - die Datei liegt unter `instructions/dev/` und würde in einer
+ausgelieferten Instanz ins Leere zeigen, während `tools/CONTRACT.md` selbst ausgeliefert wird.
+
+Verifiziert: `tools/wikitool instructions sync` (7 Skills, `stack-close` neu), `tools/wikitool
+docs verify`, `tools/wikitool instructions verify`, `.venv/bin/python -m pytest -q` (967
+passed, 4 davon neu).
+
+#47 bleibt offen für Block 3 (`DEVELOPMENT.md` in `STAGE_READMES`, veraltete Release-Notes).
+
+---
+
+## 4.5.1 - 2026-09-04 - issue-tracking - destructive-step invariants, comment-vs-body authority, rename sweep
+
+**Author:** Torben Nehmer
+
+<!-- wikitool:bumps -->
+- issue-tracking - destructive-step invariants, comment-vs-body authority, rename sweep
+<!-- /wikitool:bumps -->
+
+Block 1 aus #47 (gemeinsam mit #29): drei Ergänzungen an
+`instructions/dev/issue-tracking.md`, ausgelöst durch zwei Fehlerklassen, die
+in derselben Sitzung am Stack aufgetreten waren.
+
+- **Schritt 1** trägt jetzt, dass destruktive Schritte im Body die Invariante
+  nennen müssen, die sie nicht verletzen dürfen, und dass ein
+  Akzeptanzkriterium eine prüfbare Eigenschaft ist, keine Tätigkeit. Auslöser
+  war #30: der Body schrieb wörtlich "Arbeitsverzeichnis entfernen" für den
+  `upstream merge`-Ablauf, und genau das wurde zum datenvernichtenden Bug -
+  ein `shutil.rmtree` auf eine Stage mit gitignorierten, nicht
+  rekonstruierbaren Daten.
+- **Schritt 2** trägt jetzt die Lesesicht auf Body und Kommentare, die es
+  bisher nur aus Autorensicht gab: der Body ist der Stand, Kommentare sind
+  Historie; ein erkennbar veralteter Body wird richtiggestellt statt
+  umgangen; widersprüchliche Kommentare werden nach Beleg aufgelöst, nicht
+  nach Datum. Auslöser war ebenfalls #30 (ein Kommentar empfahl das Gegenteil
+  dessen, was der Body später festlegte) und #10 (ein seit Tagen veralteter
+  Body gegen drei widersprechende Kommentare, zwei davon sich selbst
+  widersprechend).
+- Neuer Abschnitt **"Renames and other decay in the tracker"** nach Schritt 7:
+  ein Rename ist erst fertig, wenn auch die offenen Issues nachgezogen sind,
+  weil `wikitool` diesen Tracker nicht kennt und nicht kennenlernen soll. Mit
+  der Wegweiser-vs-Beleg-Unterscheidung aus #29 und dem Hinweis, dass auch
+  verschwundene `kb/`-Seiten und private Infrastrukturangaben Issue-Texte
+  altern lassen. Ein neuer Trigger in "When to run" verweist darauf.
+
+Keine der drei Ergänzungen verschiebt die bestehende Nummerierung der
+Schritte 1-7 - die Querverweise darauf (u. a. aus
+`instructions/dev/stack-dev/SKILL.md` auf Schritt 7, aus
+`kb/concepts/Issue Label Scheme.md` auf Schritt 2) bleiben also gültig, ohne
+angefasst zu werden.
+
+Verifiziert: `tools/wikitool instructions verify`, `tools/wikitool docs
+verify`, beide grün (Prosa-only, kein Interface geändert, PATCH).
+
+#47 bleibt offen (Block 2: der Skill-Schnitt aus Vorschlag E; Block 3: die
+beiden Nebenbefunde). #29 bleibt ebenfalls offen: dieser Block deckte nur den
+Regelabsatz, nicht den noch ausstehenden Pfad-Durchgang durch #4, #5, #15,
+#21, #16, #26 - der war nicht Teil des Auftrags für diesen Block.
+
+---
+
 ## 4.5.0 - 2026-09-04 - Beide Update-Wege in Code: upstream merge fuer Clones, dist upgrade fuer Tarball-Instanzen
 
 **Author:** Torben Nehmer

DEVELOPMENT.md

@@ -92,6 +92,9 @@ gegen einen Commit. `.gitea/workflows/release.yml` ist Schritt 6 oben.
 Der `stack-dev`-Skill (`instructions/dev/`, nur in diesem Ursprungs-Repo vorhanden) fasst die
 Regeln für eine Sitzung, die den Stack selbst statt Wiki-Inhalt bearbeitet: wann
 Quellenbindung nicht gilt, wo Design endet und die mechanische Phase beginnt (mit dem
-Modellwechsel-Hinweis), und dass Issue-Abschluss ein Body-Rewrite ist, kein Kommentar. Siehe
+Modellwechsel-Hinweis), und endet mit dem Publish. Die Schlussphase - Issue-Body als Rewrite
+statt Kommentar, `docs/`-Veralterung, die Modell-Handover-Zeile über die ganze Sitzung - liegt
+seit `4.6.0` in einem eigenen Folge-Skill, `stack-close`, den `stack-dev` an dieser Stelle
+übergibt statt sie als weiteren eigenen Schritt zu führen. Siehe
 [instructions/dev/issue-tracking.md](instructions/dev/issue-tracking.md) für den
 Issue-Tracker selbst.

INSTALL.md

@@ -195,6 +195,20 @@ dem sich jede Instanz mitten im Upgrade befindet.
    tools/wikitool dist upgrade <tarball-oder-verzeichnis> --dry-run
    ```
 
+   **Beim ersten Sprung auf `4.5.0` oder höher gibt es dieses Kommando in der Instanz noch
+   nicht** - es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball
+   verwenden, gegen die alte Instanz gerichtet:
+
+   ```bash
+   tar -xzf chemenu-stack-<version>.tar.gz
+   CHEMENU_ROOT="$PWD" chemenu-stack-<version>/tools/wikitool \
+     dist upgrade chemenu-stack-<version>.tar.gz --dry-run
+   ```
+
+   `CHEMENU_ROOT` sagt dem Paket, auf welchen Korpus es zeigen soll (siehe § Konfiguration);
+   ohne die Variable würde es den entpackten Tarball selbst für die Instanz halten. Ab dem
+   zweiten Upgrade trägt die Instanz das Kommando selbst und die kurze Form oben genügt.
+
    Klassifiziert jede Datei aus dem `files`-Block der neuen `.wikitool-release.json`:
    unverändert seit der Installation, lokal verändert oder gelöscht, neu im Release, oder aus dem
    Release entfallen - und druckt die Migrationskette, die nach dem Tausch aussteht, ohne sie

VERSION

@@ -1 +1 @@
-4.5.0
+4.7.1

instructions/claude-code-model-selection.md

@@ -74,8 +74,12 @@ to *make*, not a setting to apply.
    switch at the moment the phase changes - once, without arguing about it, and never as a reason
    to stop work that is already underway.
 <!-- dist:strip-start -->
-   In this repo those moments are named: the `stack-dev` skill breaks for them at its steps 3
+   In this repo those moments are named, one per skill rather than both in one: `stack-dev`'s own
-   (design settled, work turns mechanical) and 6 (publish done, the unchecked tail begins).
+   step 3 breaks for the first (design settled, work turns mechanical), and `stack-dev` itself
+   ends at the publish rather than asking the same session to break out of its own momentum a
+   second time. The second switch lives at the opening of `stack-close`, the skill `stack-dev`
+   hands off to once the publish succeeds (the unchecked tail begins) - a session has to invoke
+   it to reach that step at all, which is the point: nothing left to skip past mid-flow.
 <!-- dist:strip-end -->
 
 2. **Pick a spawned subagent's model by what it does**, via the `Agent` tool's `model:`

instructions/dev/issue-tracking.md

@@ -34,6 +34,8 @@ issues at that URL, which is exactly why `dist export` excludes
   moved.
 - Closing one: the body is rewritten to its final state first, and only then
   closed (step 7).
+- A rename or move ships: sweep the open issues for text that assumed the old
+  name or path (§ Renames and other decay in the tracker).
 
 ## Steps
 
@@ -42,6 +44,26 @@ issues at that URL, which is exactly why `dist export` excludes
    specific files or commands involved. An issue that only makes sense to
    whoever wrote it is a note, and notes were the problem.
 
+   **Destructive steps carry the invariant they must not violate.** A body
+   that prescribes a mechanism gets built as prescribed - including its
+   bugs. Where a step deletes, overwrites, resets or moves, name the
+   property that must still hold afterwards, not only the command that gets
+   there. "Remove the working directory, then `git checkout HEAD --
+   <stage>`" is a mechanism; "the content stages must afterwards match
+   `HEAD` exactly, without any untracked or ignored file being touched" is
+   the same instruction plus its test - a build instruction and an
+   acceptance criterion at once, so the defect surfaces while the test is
+   written rather than in review afterwards. #30's `upstream merge` body
+   wrote the mechanism and got exactly that bug: a working-directory removal
+   that took a stage's gitignored, unrecoverable data with it.
+
+   **An acceptance criterion states a checkable property, not an activity.**
+   "Implement X" is done when someone says so; "after `upstream merge`,
+   `reports/` still holds every file it held before" is done when it is
+   true. This is not a ban on imperative steps - a numbered procedure can
+   still produce a correct control flow, and that is its merit - it binds
+   the destructive steps, and every box in the criteria list.
+
 2. **The body is the working state, not a historical first post - keep it
    current as you go.** It is this stack's plan file: the same thing a harness's
    own plan document is, and it is maintained the same way. Not written once,
@@ -73,6 +95,32 @@ issues at that URL, which is exactly why `dist export` excludes
    Body rewrites and comments are an LLM session's job. A human normally
    touches only labels and metadata directly.
 
+   **Reading an issue, the body is the state and comments are history.** A
+   session picking an issue up reads the body as the spec; comments are read
+   for provenance - why something was decided, what was tried - never as
+   the current instruction. A recommendation in a comment can be older than
+   the body's decision and read just as convincingly: on #30 an earlier
+   comment recommended a smaller, `verify`-only command, while the body had
+   since settled on building the full `merge` command. A session trusting
+   the comment would have built the wrong thing, with a plausible
+   justification out of this repo's own tracker.
+
+   **A body that is demonstrably wrong is corrected first, not worked
+   around.** "Body beats comment" is a rule of precedence, not a licence to
+   execute a stale spec. Where a comment or the tree proves a claim in the
+   body false, the body is rewritten before the work starts - the rewrite
+   above is the fix; leaning on the comments as the "real" state is not.
+   #10 is the case: its body claimed coverage had never been measured while
+   three comments carried a percentage, a statement count and a CI run
+   number.
+
+   **Where two comments contradict each other, evidence decides, not
+   recency.** On #10, one comment showed a retrieved artifact with zero
+   items on a finished run - the report was not actually retrievable - and
+   a later comment declared the same criterion met without re-checking. The
+   later comment is not the newer truth, only the unchecked one. Resolve it
+   into the body with the evidence named, or mark the point open.
+
 3. **Comment a changelog, never a copy.** A body rewrite gets one short comment
    naming only what changed against the previous state - what is new, what is
    gone, what was corrected. Do not snapshot the old body into a comment: a full
@@ -180,6 +228,27 @@ issues at that URL, which is exactly why `dist export` excludes
    shipped. Nothing mechanical catches it (see below), which is why it is a step
    rather than a habit.
 
+## Renames and other decay in the tracker
+
+A rename is not finished when the tree is green. Renaming a package, a path,
+a command, a flag or the repository itself moves text that lives outside the
+working tree, and the open issues are the largest such text. Nothing catches
+them - `wikitool` does not know this tracker exists and must not learn (see
+"What no tool checks" below) - so a pass over the open issues is part of the
+rename, in the session that did it, not a follow-up someone remembers.
+
+Distinguish a wayfinder from a piece of evidence: a path meant to point at
+where something *is* gets pulled through; a path quoted for what was true at
+a time is left standing and dated. Note per corrected body what was pulled
+through and when, so the next pass can tell a checked body from one that
+merely looks right. Closed issues are out of scope - they guide nobody.
+
+Renames are not the only thing that ages an issue text. A page a body cites
+can vanish from `kb/` (`wikitool search` against the cited titles is the
+second pass), and an old body can carry private infrastructure detail into
+what is now a public tracker - both found in the same issue, both worth the
+same look.
+
 ## What no tool checks
 
 `wikitool` does not know this tracker exists, and should not learn. It ships to

instructions/dev/stack-close/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: stack-close
+description: Close out a stack-dev work package after its publish has landed - rewrite the issue body to its final state, check for docs/ staleness, and name which model ran which phase of the session. Use right after a stack-dev session's tools/wikitool publish succeeds, or when resuming a package that was published but never closed.
+---
+
+# Stack Close
+
+**Purpose:** Carry out the unchecked closing phase of a stack-development work package, as its
+own skill rather than a break `stack-dev` has to remember to ask for mid-flow.
+
+**Trigger:** A `stack-dev` session's `tools/wikitool publish` just succeeded - `stack-dev` ends
+there and hands off here rather than continuing into this phase in the same breath. Also: `publish`
+printed its stack-machinery note ("this publish touched stack machinery...") and nothing has
+closed the work package it belongs to yet; or a package was published in an earlier session and
+never went through this skill (the gap this split exists to make impossible to skip past
+silently - see [issue-tracking.md](../issue-tracking.md)'s note that a closed body is the version
+everyone reads afterwards and nobody revisits).
+
+**This directory is dev-only.** Same boundary as `stack-dev`
+([its own note](../stack-dev/SKILL.md) has the full reasoning) - `dist export` prunes
+`instructions/dev/` wholesale, so this skill never reaches a distributed instance.
+
+## Why this is a separate skill, not `stack-dev`'s step 6
+
+The two phases around the mechanical middle of a stack-dev session have no mechanical guard at
+all - `pytest`, `docs verify` and `instructions verify` cover the code and tests in between, and
+nothing covers a changelog entry's accuracy, a `docs/` page's staleness, or an issue body's final
+state (see [claude-code-model-selection.md](../../claude-code-model-selection.md)). Asking the
+same session to notice it has crossed into that second unchecked stretch - as a prose break inside
+`stack-dev`'s own step 6 - failed twice in a row on this stack (Gitea #42, then #30): both times
+the session knew the rule and skipped past it anyway, because nothing in the moment forced the
+question. Splitting the phase into its own skill does not add a check either - `wikitool` still
+does not know this tracker exists and must not learn (see
+[issue-tracking.md](../issue-tracking.md) § What no tool checks) - but it removes the thing that
+was actually failing: the closing *procedure* is no longer sitting in the session's context as a
+next step to run past - it exists only inside a skill someone has to invoke.
+
+**Be precise about what that does and does not buy**, because the honest version is weaker than
+"now it cannot be skipped". What did **not** change is the trigger: `stack-dev`'s "invoke it now"
+is still a sentence, and `publish`'s stack-machinery note is deliberately generic enough not to
+name this skill at all. Two of the three links in that chain remain self-discipline. The split
+narrows the failure, it does not close it - treat a session that reaches this text as the
+mechanism having worked *this time*, not as proof that it always will.
+
+See Gitea #47 for the full incident history and the rejected alternative (a
+model-switched subagent - not buildable in Claude Code, where a fork inherits the parent's model
+and a fresh subagent starts without the session's context).
+
+## Steps
+
+1. **Offer the model switch back up, once, and keep working either way.**
+
+   > Ab hier greift kein maschineller Check mehr - Issue-Body, `docs/`-Veralterung und
+   > Changelog-Prosa prüft nichts. Wenn du zurück auf Opus willst, ist jetzt der Moment.
+
+   **Never block on the answer.** The change is already published; a session that stops here
+   leaves exactly the state this skill exists to prevent.
+
+2. **Rewrite the issue body to its final state, then close.** The test is what a reader who
+   opens the closed issue tomorrow would conclude:
+
+   - every acceptance criterion ticked, or struck with the reason it was dropped
+   - proposals that were decided read as decided; a "to decide" section has become the decision
+     and its reasoning
+   - nothing left in the present tense about a defect that no longer exists
+   - what was verified is named - which checks ran, which CI run - not a commit hash alone
+
+   Then one short comment naming what changed against the previous state, and nothing else -
+   [issue-tracking.md](../issue-tracking.md) steps 2-3 and 7 have the full shape; this is that
+   procedure, run at the point this skill exists to guarantee it actually gets run.
+
+   **A closing report in a comment does not satisfy this**, however thorough: it reads as
+   complete to whoever writes it and leaves a body still phrased as open work. Nothing mechanical
+   catches it, which is why this is a step - and now a whole skill - rather than a habit. #44 and
+   #45 both closed exactly this way on the old, single-skill shape, the second an hour after the
+   rule was first written down.
+
+3. **Check whether a `docs/` page or new human doc went stale.** A `docs/` page carries no
+   normative sentence, so nothing verifies it by construction (AGENTS.md § File naming) - the
+   same is true of `README.md`/`INSTALL.md`/`DEVELOPMENT.md` prose and a new instruction's own
+   wording, which `instructions verify` checks structurally but never for what it claims. If the
+   change this package shipped moved the reasoning one of these pages documents, update it now;
+   if none did, say so rather than leaving the question unasked.
+
+4. **Name which model ran which phase - not only this one.** This is the handover in full, not
+   a note about the tail alone: state the model for the design/version-part/boundary-judgment
+   phase (`stack-dev` step 3), for the mechanical middle (code, tests, the version bump), and for
+   this closing phase - all three, even when they are all the same model. A handover that only
+   flags a cheap-model *closing* phase stays silent exactly when the earlier, equally unchecked
+   design phase also ran cheap and nobody offered the switch back then either; naming all three
+   every time is what keeps that omission from being the quiet default.
+
+## Decision points
+
+- **The work package spans several sessions?** Run this skill once, at the point the package is
+  actually finished and its last publish has landed - not after every individual publish. A
+  package still open across sessions keeps its body current per
+  [issue-tracking.md](../issue-tracking.md) step 2 in the meantime; that is maintenance, not
+  closing.
+- **Resuming a package whose publish landed in an earlier, already-ended session?** Run this
+  skill now, on whatever model the current session is - do not reopen the earlier session to run
+  it "correctly." The handover in step 4 names the earlier phases from the historical record
+  (the issue's comments, `CHANGES.md`) rather than from memory.
+- **Nothing to close - the session's own exploration, no publish happened?** This skill does not
+  apply; there is no package to rewrite a body for.
+
+## Scope
+
+Follows a `stack-dev` session's publish. Not for wiki content work - use
+`wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/`wiki-status` for that, whose own closing
+conventions (`kb/log.md`, page provenance) are unrelated to this tracker-body procedure.

instructions/dev/stack-dev/SKILL.md

@@ -46,9 +46,10 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
    package, labelled `area/`, `kind/`, `prio/` and `size/`. There is no `TODO.md`. **The body
    of the issue you are working on is this session's plan file:** keep it current as the state
    moves, so an interrupted session leaves a body the next one can resume from, *and* rewrite it
-   to its final state before closing. Both halves bind; the second is step 6 below. Read it
+   to its final state before closing. Both halves bind; the second is what
-   before filing something for later, before editing or closing an issue, or before deciding
+   [`stack-close`](../stack-close/SKILL.md) carries out once this skill's own work is published -
-   what to pick up next.
+   see step 5 below. Read it before filing something for later, before editing or closing an
+   issue, or before deciding what to pick up next.
    [testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
    empty machine; what the autouse fixture already neutralizes, and what a test still has to
    establish itself. Read it before adding or changing a test.
@@ -63,14 +64,18 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
    list grows without needing this skill file to change shape.
 3. **Settle the design before building - and break there for the model switch.** These are two
    different kinds of work, and the split is not stylistic: design, the version part and any
-   boundary judgment have **no** mechanical guard, while the code and tests that follow have
+   boundary judgment have **no** mechanical guard, while the code and tests that follow are mostly
-   `pytest`, `docs verify`, `instructions verify` and CI behind them.
+   covered - `pytest`, `docs verify`, `instructions verify` and CI catch a mistake **in what they
+   cover**.
 
    So when the design is settled - the issue body says what will be built, the open questions are
-   answered - stop and say so, in one sentence:
+   answered - stop and say so, in one sentence that names what the mechanical stretch does **not**
+   cover:
 
-   > Der Plan steht, ab hier ist die Arbeit mechanisch und durch Tests/CI abgedeckt. Wenn du auf
+   > Der Plan steht, ab hier ist die Arbeit größtenteils mechanisch und durch Tests/CI abgedeckt -
-   > Opus bist, ist jetzt der Moment für `/model sonnet` bei Effort `high`.
+   > mit Ausnahme der Changelog-Prosa (Schritt 4), einer berührten `docs/`-Seite, neuer
+   > Menschendoku oder des Prosa-Anteils einer Instruction. Wenn du auf Opus bist, ist jetzt der
+   > Moment für `/model sonnet` bei Effort `high`.
 
    **You cannot make this switch yourself** - the session's model is the user's `/model`, not a
    setting an agent applies. Offer it once and keep working either way; a session that argues
@@ -78,6 +83,15 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
    be settled after all - a boundary crossing surfaces, an assumption breaks - that is a reason to
    offer the switch back up, not to decide it alone.
 
+   **"Covered by tests" means covered by the tests that exist, not by the tests that should
+   exist.** Whether the right test was written is itself a judgment call with no mechanical
+   guard: two data-destroying bugs in `upstream merge` (Gitea #30) shipped past a green
+   `pytest`/`docs verify`/`instructions verify`/CI because no test exercised the case, not
+   because a weaker model wrote worse code for the case that *was* tested. This is not a third
+   break - it is a caveat on this one: the middle phase stays the cheaper phase to run on, but its
+   test suite is only as complete as the judgment that wrote it, and that judgment is unchecked
+   the same way the design phase is.
+
    Effort is the cheaper lever than the model, and `high` is the floor for anything touching more
    than one file or a contract. Full table and reasoning:
    [claude-code-model-selection.md](../../claude-code-model-selection.md).
@@ -119,47 +133,23 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
    Prose-only changes (`README.md`, `INSTALL.md`, `EVALS.md`) and the workflows under `.gitea/`
    do not need a bump - CI's version gate is scoped to what changes behaviour.
 
-5. **Verify before publishing.** `tools/wikitool docs verify`, `tools/wikitool instructions
+5. **Verify, then publish.** `tools/wikitool docs verify`, `tools/wikitool instructions verify`,
-   verify`, and the relevant `pytest` run in `tools/` - the same checks any stack change must
+   and the relevant `pytest` run in `tools/` - the same checks any stack change must pass, run
-   pass, run explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a
+   explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a full
-   full `setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves
+   `setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves `VERSION`
-   `VERSION` additionally triggers a tagged release. **CI does the tagging** - a session never
+   additionally triggers a tagged release. **CI does the tagging** - a session never creates a
-   creates a tag, which is what keeps AGENTS.md invariant 5 intact.
+   tag, which is what keeps AGENTS.md invariant 5 intact.
 
-6. **Close the issue with a body rewrite, not a comment.** The last act of a session that
+   Publish with `tools/wikitool publish`. When the changeset touches `tools/`, `types/`,
-   finished a work package, and the one most easily skipped: by here the change is published and
+   `instructions/`, `AGENTS.md` or a `<stage>/CONTRACT.md`, `publish` itself prints a one-line
-   the issue feels done. It is not. The body is the version everyone reads afterwards and nobody
+   reminder that the phase past this point is not covered by any of the checks above - that line
-   revisits, so it is the one place the debt comes due at the worst moment.
+   is the cue that this skill's own job just ended.
 
-   **Break here too, in the other direction.** Everything left in the session - this rewrite,
+   **This skill stops here.** The closing phase - rewriting the issue body to its final state,
-   whether a `docs/` page's reasoning went stale, the changelog prose - is the unchecked kind of
+   checking for `docs/` staleness, and naming which model ran which phase of the session - lives
-   work again, the mirror of step 3. If the session dropped to Sonnet there, say so now:
+   in [`stack-close`](../stack-close/SKILL.md), not in a further step of this one. Invoke it now;
-
+   do not fold its work into this session under this skill's rules, and do not treat "the change
-   > Ab hier greift kein maschineller Check mehr - Issue-Body, `docs/`-Veralterung und
+   is published" as this work package being done.
-   > Changelog-Prosa prüft nichts. Wenn du zurück auf Opus willst, ist jetzt der Moment.
-
-   Then **do the work regardless of the answer.** Never block a close on a model switch: the
-   change is already published, and a session that stops here leaves exactly the state this step
-   exists to prevent. If it ran on the cheaper model, name that in the handover rather than
-   leaving it silent.
-
-   Rewrite it to its final state *first*, then close. The test is what a reader who opens the
-   closed issue tomorrow would conclude:
-
-   - every acceptance criterion ticked, or struck with the reason it was dropped
-   - proposals that were decided read as decided; a "to decide" section has become the decision
-     and its reasoning
-   - nothing left in the present tense about a defect that no longer exists
-   - what was verified is named - which checks ran, which CI run - not a commit hash alone
-
-   Then one short comment naming what changed against the previous state, and nothing else.
-
-   **A closing report in a comment does not satisfy this**, however thorough: it reads as
-   complete to whoever writes it and leaves a body still phrased as open work. Nothing
-   mechanical catches it - `wikitool` does not know this tracker exists and must not learn it,
-   since it ships to instances that have no board - so this step is the only enforcement there
-   is. #44 and #45 both closed exactly this way, the second an hour after the rule was written.
-   [issue-tracking.md](../issue-tracking.md) step 7 has the full shape.
 
 ## Decision points
 
@@ -180,4 +170,5 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
 
 Not for wiki content work - use `wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/
 `wiki-status` for that. Not for setting up a new instance (`instructions/setup-instance.md`) or
-a fresh clone of this repo (`instructions/bootstrap.md`).
+a fresh clone of this repo (`instructions/bootstrap.md`). Not for closing a work package after
+its publish has landed - that is [`stack-close`](../stack-close/SKILL.md).

instructions/link-taxonomy.md

@@ -44,6 +44,16 @@ That is why most labels below have no inverse. Only three pairs do, because in e
 direction is a genuine primary statement someone would write on its own: `depends-on` /
 `required-by`, `runs-on` / `hosts`, and `composition` / `part-of`.
 
+**A self-dual label is still written once.** `alternative-to` is its own inverse - the sentence
+reads identically from either end - and that makes it the easiest label in the catalogue to
+write twice by reflex. Symmetry means the relation holds in both directions, not that both pages
+must declare it: one edge per pair, and the other page's inbound view carries it. The difference
+is not cosmetic at scale. Seven mutually substitutable tools are 21 pairs; declared once each
+that is 21 edges, declared from both ends it is 42, and the second 21 say nothing the first did
+not. This is the shape a `see-also` clique already had in this corpus before the labels existed,
+and relabelling such a clique without dropping to one edge per pair moves the problem rather
+than fixing it.
+
 The third was added after the 4.0.0 migration, from measurement rather than from the desk. A
 parent-child structure - a tier list and its tiers, a spectrum and its levels - produces the
 question on nearly every page: the parent writes `composition`, and the child then reaches for
@@ -100,10 +110,23 @@ entity to entity.
 | `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 |
+| `authored` | — | created the target as a one-time act |
+| `alternative-to` | itself | serves the same purpose as the target, so a reader choosing between them wants both |
 
 `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
+this thing, it is `depends-on`.
-they are often different people.
+
+`authored`, `owns` and `maintains` are three different sentences about the same pair, and often
+three different people: origination, accountability, labour. `owns` is a *standing* claim - it
+says someone answers for this thing now - so it reads false about a person who is dead or long
+gone from the project, however plainly they made it. That is the case `authored` exists for, and
+picking `owns` for it is not a weaker edge but a wrong one.
+
+`alternative-to` versus `contrasts` versus `compares-with`: `contrasts` asserts a *difference
+worth reading both for*, `alternative-to` asserts *substitutability* - two things a reader might
+pick between for the same job. `compares-with` weighs them on named dimensions, which in this
+instance is what routes to a `kb/comparisons/` page. Two agent CLIs are `alternative-to`; two
+opposed design principles are `contrasts`, and swapping the two says something false about both.
 
 ### Realization
 
@@ -135,6 +158,7 @@ Inference and comparison between ideas.
 | `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 |
+| `addresses` | is a response to the problem the target describes |
 | `composition` | is composed of the target |
 | `part-of` | is a component of the target |
 
@@ -149,6 +173,13 @@ about the same fact.
 listed separately rather than as inverses because either page may legitimately carry only its
 own side.
 
+`addresses` is the edge from a solution to the problem it answers - a decision to the trouble
+that forced it, a mechanism to the failure it prevents. Keep it apart from `rests-on`, which
+takes the target as a *premise* the source argues from: a decision usually does both, and the
+one worth writing is the one a reader here would follow. `addresses` has no inverse. The problem
+page's inbound view already answers "what did anyone do about this?", which is the only reason
+someone would want the reverse.
+
 ### Lineage
 
 Where something came from, and what replaced it.

instructions/wiki-lint/SKILL.md

@@ -26,8 +26,18 @@ never something an agent has to remember.
    unreadable frontmatter, broken wikilinks, dangling frontmatter references, orphan pages,
    catalog drift, missing fields, duplicate titles, filename/title mismatches, broken
    `raw_files:` references, raw files claimed by more than one source page, invalid type paths,
-   schema failures and citation/frontmatter drift. **Do not re-derive any of it by reading
+   schema failures, citation/frontmatter drift, and edges whose label is missing, not authorised
-   pages.**
+   by the source collection, or redundant beside a specific label on the reverse direction.
+   **Do not re-derive any of it by reading pages.**
+
+   The *Redundant see-also* section is the one that looks mechanical and is not - do **not**
+   clear it under step 7. It names a `see-also` edge standing beside a specific label on the
+   reverse direction, and the obvious repair destroys the thing worth keeping: `xref remove`
+   clears the reference in *both* directions (see [tools/CONTRACT.md](../../tools/CONTRACT.md)),
+   so removing the weak edge takes the labelled one with it and the pair ends up saying nothing
+   at all. Either relabel the weak edge to something true with `xref add`, which only ever
+   touches the source page, or leave it and report it at step 9. Clearing a batch of these is a
+   planned corpus sweep with its own run, never a reaction inside a lint.
 
    **To see more of the report, read the file - never run `lint` again.** A second run costs a
    budget slot and re-measures a corpus that has not changed. The file at step 9 overwrites this

kb/concepts/COLLECTION.md

@@ -1,8 +1,8 @@
 ---
 profile: concepts
 outbound:
-  concepts: [extends, grounds, rests-on, enables, precondition, exemplifies, abstracted-from, contrasts, compares-with, contradicts, composition, part-of, supersedes, derived-from, adapted-from, see-also]
+  concepts: [extends, grounds, rests-on, enables, precondition, exemplifies, abstracted-from, contrasts, compares-with, contradicts, addresses, alternative-to, composition, part-of, supersedes, derived-from, adapted-from, see-also]
-  entities: [operationalized-from, mechanism, procedure, applies-when, operates-on, invokes, exemplifies, see-also]
+  entities: [operationalized-from, mechanism, procedure, applies-when, operates-on, invokes, exemplifies, alternative-to, see-also]
   sources: [evidenced-by, derived-from, adapted-from, defined-in, see-also]
   comparisons: [compares-with, see-also]
 required_by_stack: false
@@ -58,6 +58,11 @@ nothing on its own.
 
 The widest authorisation in this instance, because argumentation is what concept pages do. Note that the operational labels are absent: a concept does not `depend-on` anything - the entity implementing it does.
 
+`addresses` is the one that pairs with this collection's own subtypes: a `concept_type: decision`
+or a mechanism pointing at the `concept_type: problem` it answers. Without it, the collection can
+declare a problem and never say what was done about it. `alternative-to` is self-dual and written
+once per pair - see [instructions/link-taxonomy.md](../../instructions/link-taxonomy.md).
+
 Adding a label here is a deliberate contract change, not a way around a refusal.
 
 ## Outbound linking

kb/entities/COLLECTION.md

@@ -1,8 +1,8 @@
 ---
 profile: entities
 outbound:
-  entities: [depends-on, required-by, runs-on, hosts, uses, produces, consumes, maintains, owns, part-of, composition, supersedes, see-also]
+  entities: [depends-on, required-by, runs-on, hosts, uses, produces, consumes, maintains, owns, authored, alternative-to, implements, part-of, composition, supersedes, derived-from, adapted-from, see-also]
-  concepts: [implements, exemplifies, rests-on, applies-when, operates-on, invokes, see-also]
+  concepts: [implements, exemplifies, rests-on, applies-when, operates-on, invokes, authored, alternative-to, see-also]
   sources: [evidenced-by, defined-in, see-also]
   comparisons: [compares-with, see-also]
 required_by_stack: false
@@ -57,6 +57,14 @@ nothing on its own.
 
 Operational labels dominate here because an entity's relationships are mostly to other concrete things. `implements` points *out* to a concept; the concept does not point back unless that direction is a statement of its own.
 
+Three of these carry a caveat this area produces more often than the others. `authored` belongs
+on a person page pointing at what they made, and it is the label a dead or departed creator
+takes - `owns` claims someone answers for the thing *now*. `alternative-to` is self-dual and is
+written **once per pair**, never from both ends: a set of interchangeable tools is where a
+mirrored clique grows fastest. `derived-from` and `adapted-from` are here for the fork and the
+re-implementation - one tool worked up out of another - which is a lineage claim the operational
+labels cannot make.
+
 Adding a label here is a deliberate contract change, not a way around a refusal.
 
 ## Outbound linking

kb/entities/people/Andrej Karpathy.md

@@ -5,9 +5,9 @@ tags: [researcher, ai, machine-learning, open-source]
 created: 2026-07-26
 modified: 2026-08-29
 related:
-  - see-also: LLM Wiki Pattern
+  - authored: LLM Wiki Pattern
-  - see-also: Three-Layer Architecture
+  - authored: Three-Layer Architecture
-  - see-also: Knowledge Compounding
+  - authored: Knowledge Compounding
 sources: [Source - LLM Wiki v2, Source - LLM Wiki Pattern]
 confidence: 0.95
 confidence_base: 0.95
@@ -42,7 +42,7 @@ Seine ursprüngliche Einsicht - "stop re-deriving, start compiling" - bildet die
 <!-- wikitool:links -->
 ## Beziehungen
 
-- **see-also:** [[LLM Wiki Pattern]]
+- **authored:** [[LLM Wiki Pattern]]
-- **see-also:** [[Three-Layer Architecture]]
+- **authored:** [[Three-Layer Architecture]]
-- **see-also:** [[Knowledge Compounding]]
+- **authored:** [[Knowledge Compounding]]
 <!-- /wikitool:links -->

kb/entities/people/Vannevar Bush.md

@@ -6,7 +6,7 @@ created: 2026-07-26
 modified: 2026-08-29
 related:
   - see-also: LLM Wiki Pattern
-  - owns: Memex
+  - authored: Memex
 sources: [Source - LLM Wiki Pattern]
 confidence: 0.90
 confidence_base: 0.90
@@ -72,5 +72,5 @@ Laut dem Artikel [[LLM Wiki Pattern]] war Bushs Memex-Vision:
 ## Beziehungen
 
 - **see-also:** [[LLM Wiki Pattern]]
-- **owns:** [[Memex]]
+- **authored:** [[Memex]]
 <!-- /wikitool:links -->

tools/CONTRACT.md

@@ -50,7 +50,7 @@ tools/wikitool <command> --help
 | `index rebuild [--dry-run]` | Regenerate the catalog from every page's frontmatter: `kb/index.md` becomes a map (statistics, one row per collection and per area, links to the shards) and the page tables are written to a generated `INDEX.md` in each collection. An area past 50 rows gets its own shard. Stale shards from removed collections/areas are deleted in the same pass |
 | `log append --op ingest\|query\|lint\|create\|update\|delete\|rename --title "..." [--body "..."\|--body-file path]` | Append a formatted entry to `kb/log.md` |
 | `log status` | Read-only: count `ingest` entries logged since the last `lint` entry - the deterministic trigger behind the Maintenance Schedule's "every 10 sources" full-lint cadence |
-| `lint [--json] [--markdown out.md] [--full] [--fail-on-error]` | Structural + provenance checks: broken wikilinks, dangling frontmatter references, orphan pages, index drift, schema gaps, duplicate titles, title mismatches, uncovered raw files, broken `raw_files:` refs, raw files claimed by more than one source page, unmarked provenance, citation/frontmatter drift, unbalanced generated-region markers, edges whose label is missing or not authorised by the source collection's `outbound:` (both hard once `kb_version` has reached the release that introduced labelled edges - advisory below it, so a corpus mid-migration is not refused by the check measuring it), quote-limit overages (>2 blockquoted lines/page, advisory only). Prints only the sections that found something and always writes the full report to `reports/Lint Report <date>.md` (or `--markdown`), naming the path - `--full` prints everything, `--json` prints the findings and writes nothing |
+| `lint [--json] [--markdown out.md] [--full] [--fail-on-error]` | Structural + provenance checks: broken wikilinks, dangling frontmatter references, orphan pages, index drift, schema gaps, duplicate titles, title mismatches, uncovered raw files, broken `raw_files:` refs, raw files claimed by more than one source page, unmarked provenance, citation/frontmatter drift, unbalanced generated-region markers, edges whose label is missing or not authorised by the source collection's `outbound:` (both hard once `kb_version` has reached the release that introduced labelled edges - advisory below it, so a corpus mid-migration is not refused by the check measuring it), `see-also` edges whose reverse direction already carries a specific label (advisory only - redundant rather than wrong, and never migration-gated, since no version turns the redundancy into an error), quote-limit overages (>2 blockquoted lines/page, advisory only). Prints only the sections that found something and always writes the full report to `reports/Lint Report <date>.md` (or `--markdown`), naming the path - `--full` prints everything, `--json` prints the findings and writes nothing |
 | `search ["<text>"] [--field <predicate> ...] [--kind/--subtype/--collection/--tag <v>] [--regex] [--limit N] [--sort [-]<field>] [--backend <name>] [--matches] [--json]` | Find pages in `kb/` without reading the index. Text search runs through a pluggable backend (`rg` today); `--field` predicates are evaluated on frontmatter - `f=v`, `f~substring`, `'f>=v'`, `'f:*'` (present), `'!f'` (absent), repeatable and ANDed. With no text this is a pure structured query. Results carry kind/summary/confidence so a hit can be judged without opening the page. A page whose frontmatter does not parse can match no positive predicate, so it is **named** rather than dropped: `--json` always carries an `unreadable` list of `{path, reason}` (usually empty), and the table form writes the same lines to stderr. `--regex` is applied by `rg` alone, whose engine is linear; the ranking boosts for title and summary are literal-containment only, so a non-literal pattern is ranked by match count. `rg` is killed after 30 s and reported as a failure. Read-only, and **exempt from the Iteration Budget Gate** |
 | `confidence decay [--apply]` | Recompute every page's derived `confidence` as `confidence_base * (1 - 0.01/month)`, floored at 0.2; dry-run by default |
 | `confidence init-base [--apply]` | One-time backfill: set `confidence_base` from the current `confidence` on pages that predate the derived-confidence model |
@@ -58,7 +58,7 @@ tools/wikitool <command> --help
 | `sources trace --raw <path>` \| `--page "<Title>"` | Trace provenance in either direction: raw file -> source page(s) -> citing pages, or page -> its sources -> their raw files |
 | `sources rebuild-index [--dry-run]` | Regenerate the `kb/provenance.md` reverse index (raw file -> source page -> citing pages) |
 | `sync [--remote origin] [--branch main] [--confirm-rebase TOKEN]` | Fetch `<remote>/<branch>` and bring the local branch up to date with it: fast-forward when the remote is simply ahead, rebase local commit(s) on top when both sides moved but touch disjoint files (a content conflict is then impossible by construction), and exit **42** for review when they touch the same file (the **rebase-review gate** - see `publish` below). Never commits, never pushes, never force-anything - no remote configured, or one that cannot be reached, is reported and skipped, not a failure. Meant to run once at the start of a writing session (`instructions/session-setup.md`) so the rest of it works against a current tree instead of discovering the drift at the final `publish` |
-| `publish --message "<op>: <desc>" [--no-push] [--confirm TOKEN] [--confirm-rebase TOKEN] [--threshold N] [--remote origin] [--branch main] [--path P ...]` | Reconcile with `<remote>/<branch>` exactly like `sync` (skipped for `--no-push`), then stage all changes, commit, and push. If the reconcile step found a still-unpushed local commit and there is nothing new to stage, that commit is pushed anyway - a previous `publish` whose push failed no longer strands it. If the push is rejected despite the pre-check (a genuine race - something landed on the remote in between), one more reconcile-and-retry is attempted before giving up; never more than one. **Mass-Update Gate:** when >= `--threshold` (default 10) *counted* files would be committed, exits **42 (`EXIT_NEEDS_CLEARANCE`)** instead of publishing - a third outcome distinct from success (0) and a validation error (1) - and prints a review report: a scale line (file count, total lines added/removed, status breakdown), only-what-applies attention notes (deletions by name, control-plane and harness-config touches, published pages, the largest single change, binaries), and every counted path grouped by area with its status and churn, generated files split out as needing no review. The token digests each counted path **and its contents** plus the publish target, so a clearance carries neither to a different file list nor to edited contents; a wrong, invented or superseded token exits 42 again with the current state. Two kinds of path are committed but never counted and never shown for approval: anything under `work/`, and the files `wikitool` generates itself (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md`) - each is recomputable from the tree, so approving it decides nothing, and a routine ingest rebuilds five or six of them. The refusal line accounts for both, by reason. The gate is evaluated *before* anything is staged, so a refused publish leaves the working tree untouched. **Publish-Remote Gate:** when this checkout carries a `.wikitool-remotes.json` and the resolved push URL of `--remote` is not listed in it, exits **42** before the reconcile step even fetches - the URL is read from `git remote get-url --push`, so a repointed remote does not pass on its name. Unlike the other two gates it has **no token and no flag**: the way past it is the user adding the URL to that file, and an agent editing it to get past a refusal is opening a gate on its own initiative. Absent file means unrestricted; a malformed one is an error, not permission. See [instructions/gates.md](../instructions/gates.md) `--yes`/`-y` are gone and now fail with an explicit error. `--path` (repeatable) scopes the whole operation - gate count, staging, and commit - to a subtree |
+| `publish --message "<op>: <desc>" [--no-push] [--confirm TOKEN] [--confirm-rebase TOKEN] [--threshold N] [--remote origin] [--branch main] [--path P ...]` | Reconcile with `<remote>/<branch>` exactly like `sync` (skipped for `--no-push`), then stage all changes, commit, and push. If the reconcile step found a still-unpushed local commit and there is nothing new to stage, that commit is pushed anyway - a previous `publish` whose push failed no longer strands it. If the push is rejected despite the pre-check (a genuine race - something landed on the remote in between), one more reconcile-and-retry is attempted before giving up; never more than one. **Mass-Update Gate:** when >= `--threshold` (default 10) *counted* files would be committed, exits **42 (`EXIT_NEEDS_CLEARANCE`)** instead of publishing - a third outcome distinct from success (0) and a validation error (1) - and prints a review report: a scale line (file count, total lines added/removed, status breakdown), only-what-applies attention notes (deletions by name, control-plane and harness-config touches, published pages, the largest single change, binaries), and every counted path grouped by area with its status and churn, generated files split out as needing no review. The token digests each counted path **and its contents** plus the publish target, so a clearance carries neither to a different file list nor to edited contents; a wrong, invented or superseded token exits 42 again with the current state. Two kinds of path are committed but never counted and never shown for approval: anything under `work/`, and the files `wikitool` generates itself (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md`) - each is recomputable from the tree, so approving it decides nothing, and a routine ingest rebuilds five or six of them. The refusal line accounts for both, by reason. The gate is evaluated *before* anything is staged, so a refused publish leaves the working tree untouched. **Publish-Remote Gate:** when this checkout carries a `.wikitool-remotes.json` and the resolved push URL of `--remote` is not listed in it, exits **42** before the reconcile step even fetches - the URL is read from `git remote get-url --push`, so a repointed remote does not pass on its name. Unlike the other two gates it has **no token and no flag**: the way past it is the user adding the URL to that file, and an agent editing it to get past a refusal is opening a gate on its own initiative. Absent file means unrestricted; a malformed one is an error, not permission. See [instructions/gates.md](../instructions/gates.md) `--yes`/`-y` are gone and now fail with an explicit error. `--path` (repeatable) scopes the whole operation - gate count, staging, and commit - to a subtree. **Stack-machinery note:** after a successful commit/push whose changed files include `tools/`, `types/`, `instructions/`, `AGENTS.md`, or a path ending in `CONTRACT.md` - roughly the scope a stack version bump covers, deliberately a shade broader than CI's version gate, which matches only a `CONTRACT.md` one segment deep - prints one reminder line that the phase past this point (an issue-body rewrite, `docs/` staleness, a changelog entry's accuracy) is not covered by `docs verify`, `instructions verify` or `pytest`. Not a gate: no exit code change, nothing to clear, silent for an ordinary content publish |
 | `work new (--input <raw path> \| --key <run key>) [--again] [--dry-run]` | Scaffold `work/<runkey>/` for one workshop run: refuses a collision instead of suffixing it, and writes the required `README.md` + `plan.md`. `--input` derives the run key from the path below `raw/` (an ingest); `--key` names it outright for a run with no raw input - a migration or a sweep across `kb/` - and may not start with `ingest-`, which stays reserved for derived keys. Exactly one of the two. `--again` opens a dated second pass over a tree that has itself changed. See [work/CONTRACT.md](../work/CONTRACT.md) |
 | `work close --run-key <name> [--yes] [--dry-run]` | Delete a finished workshop. Lists what would be lost and requires `--yes`, because nothing in it is recoverable from the rest of the repo - the durable conclusions must already be in `kb/` |
 | `budget status` | Show the current session's `wikitool` call count and recent command history (never counted against the budget) |

tools/chemenu/commands/docs_verify.py

@@ -136,7 +136,17 @@ ROOT_README = config.ROOT / "README.md"
 # tools/README.md is exactly the file it drifted in. INSTALL.md is here for the
 # same reason: it is human-facing prose about installing an instance, and the
 # command reference lives exactly once, in tools/CONTRACT.md.
-STAGE_READMES = ("tools/README.md", "INSTALL.md")
+#
+# DEVELOPMENT.md joined them after it drifted the same way (Gitea #47): it grew
+# a table describing what each verify command checks, which had to be removed by
+# hand because nothing compared it to anything. It is not shipped - dist_cmd
+# .ROOT_FILES excludes it - and that is not an argument against listing it here:
+# `check_readmes_have_no_command_table` skips a file that does not exist, so in
+# a distributed instance this entry is simply inert, while in the dev checkout
+# (the only place the file exists, and the only place it can drift) it is
+# checked. The name is now narrower than the tuple - these are the human-facing
+# prose docs that must not re-list commands, stage README or not.
+STAGE_READMES = ("tools/README.md", "INSTALL.md", "DEVELOPMENT.md")
 
 # Docs that must not re-introduce the pre-migration bare-enum `type:` form.
 # The per-collection contracts are appended at call time, since which ones exist

tools/chemenu/commands/git_publish.py

@@ -423,6 +423,46 @@ def counted_files_of(
     return [change for change in changes if not is_exempt(change.path, prefixes)]
 
 
+# The same scope `version-parts.md` names for the stack version itself -
+# "tools/, types/, instructions/, AGENTS.md and the contracts" - reused here
+# to decide whether a publish's changeset falls under it. Not a copy of that
+# rule: version-parts.md states the scope in prose for a human choosing a
+# version part, this instantiates the same boundary in code for a different
+# question (does this publish deserve the closing-phase reminder below).
+STACK_MACHINERY_PREFIXES = ("tools/", "types/", "instructions/")
+STACK_MACHINERY_NAMES = ("AGENTS.md",)
+
+STACK_MACHINERY_NOTE = (
+    "Note: this publish touched stack machinery. What a stack-dev session "
+    "does next - closing prose, a changelog entry's accuracy, whether a "
+    "docs/ page went stale - is not covered by docs verify, instructions "
+    "verify, or pytest. No tool checks it; a session has to."
+)
+
+
+def touches_stack_machinery(changed_files: list[str]) -> bool:
+    """Whether `changed_files` includes a path under the stack version's own
+    scope - `tools/`, `types/`, `instructions/`, `AGENTS.md`, or a path ending
+    in `CONTRACT.md` at any depth. A publish in this class is, by construction
+    of the `stack-dev`/`stack-close` split, always followed by the unchecked
+    closing phase - `STACK_MACHINERY_NOTE` times a reminder to land exactly
+    there, for any session, not only one that read the skill that names it.
+
+    Deliberately a shade broader than CI's version gate, which matches
+    `<one-segment>/CONTRACT.md` only: this decides whether to print a sentence,
+    so over-matching costs a reminder nobody needed, while under-matching costs
+    the reminder in the one case it was built for. The two are not the same
+    predicate and should not be described as one."""
+    for path in changed_files:
+        if path in STACK_MACHINERY_NAMES:
+            return True
+        if path.endswith("CONTRACT.md"):
+            return True
+        if path.startswith(STACK_MACHINERY_PREFIXES):
+            return True
+    return False
+
+
 YES_REMOVED_MESSAGE = (
     "--yes no longer exists. The Mass-Update Gate is cleared with `--confirm <token>`, and the "
     "token comes from the gate's own refusal output - run this command without it first to see "
@@ -1138,3 +1178,5 @@ def publish_command(
         },
     )
     success(f"Published changes to {remote}/{branch}." if push else "Committed changes (not pushed).")
+    if touches_stack_machinery(changed_files):
+        typer.echo(STACK_MACHINERY_NOTE)

tools/chemenu/evals/scorecard.py

@@ -30,6 +30,7 @@ ADVISORY_KEYS = (
     "unmarked_provenance",
     "missing_from_index",
     "title_mismatches",
+    "redundant_see_also",
 )
 
 

tools/chemenu/links.py

@@ -33,6 +33,17 @@ from typing import Any, Iterable, Optional
 # so `lint` cannot be satisfied by declaring the placeholder legal.
 UNLABELLED = None
 
+# The one catalogue label this tool knows by name. Everything else about the
+# vocabulary lives in `instructions/link-taxonomy.md` and each collection's
+# `outbound:` block, on purpose - an instance may authorise any label it likes
+# and the tool never has an opinion about which. `see-also` is the exception
+# because it is the catalogue's declared last resort: it asserts only that
+# nothing better fit, which is what lets `lint` judge it as *weaker than*
+# another edge on the same pair rather than merely different. No behaviour
+# depends on the string beyond that comparison, and an instance that dropped
+# `see-also` from every contract would simply never see the finding.
+SEE_ALSO = "see-also"
+
 
 @dataclass(frozen=True)
 class Edge:

tools/chemenu/lint_core.py

@@ -181,6 +181,26 @@ def run_lint(kb_dir: Path) -> dict:
     malformed_edges: list[dict] = []
     unlabelled_edges: list[dict] = []
     unauthorised_labels: list[dict] = []
+    redundant_see_also: list[dict] = []
+
+    # Every specific thing any page asserts about any pair, collected before the
+    # loop below because the reverse direction of an edge is not known while
+    # standing on the page that carries it.
+    #
+    # What it is for: `see-also` is the catalogue's declared last resort - it
+    # asserts that nothing better fit. When the *other* page already says
+    # something specific about the same pair (`Wine GE depends-on Wine` opposite
+    # `Wine see-also Wine GE`), the weak edge adds nothing a reader did not
+    # have: direction is authored but the inbound view is rendered, so the
+    # labelled edge already shows on both pages. Measured once on this corpus,
+    # that was 57 of 180 `see-also` edges - the largest single class, and none
+    # of it a vocabulary gap.
+    typed_edges: dict[tuple[str, str], str] = {}
+    for source_title, source_page in pages.items():
+        for edge in links.edges(source_page.frontmatter, "related"):
+            if edge.is_labelled and edge.label != links.SEE_ALSO:
+                typed_edges[(source_title, edge.target)] = edge.label
+
     for title, page in sorted(pages.items()):
         type_path = page.frontmatter.get("type")
         if not type_path:
@@ -211,6 +231,16 @@ def run_lint(kb_dir: Path) -> dict:
                 if not edge.is_labelled:
                     unlabelled_edges.append({"page": title, "target": edge.target})
                     continue
+                if edge.label == links.SEE_ALSO:
+                    reverse_label = typed_edges.get((edge.target, title))
+                    if reverse_label is not None:
+                        redundant_see_also.append(
+                            {
+                                "page": title,
+                                "target": edge.target,
+                                "reverse_label": reverse_label,
+                            }
+                        )
                 target_page = pages.get(edge.target)
                 if source_collection is None or target_page is None:
                     continue
@@ -301,6 +331,7 @@ def run_lint(kb_dir: Path) -> dict:
         "malformed_edges": malformed_edges,
         "unlabelled_edges": unlabelled_edges,
         "unauthorised_labels": unauthorised_labels,
+        "redundant_see_also": redundant_see_also,
         "unbalanced_markers": unbalanced_marker_findings,
         "quote_limit_violations": quote_limit_violations,
         "invalid_type_paths": invalid_type_paths,
@@ -403,6 +434,11 @@ def render_markdown(report: dict) -> str:
         report.get("unauthorised_labels", []),
         lambda i: f"[[{i['page']}]] `{i['label']}` -> kb/{i['destination']}/ ([[{i['target']}]])",
     )
+    _section(
+        lines, "Redundant see-also (the other page already says something specific)",
+        report.get("redundant_see_also", []),
+        lambda i: f"[[{i['page']}]] `see-also` -> [[{i['target']}]], but [[{i['target']}]] already asserts `{i['reverse_label']}` back - drop the weaker edge, the inbound view renders the other one here",
+    )
     _section(
         lines, "Dangling Frontmatter References", report["dangling_frontmatter_refs"],
         lambda i: f"[[{i['page']}]] `{i['field']}:` names `{i['target']}`, which is not a page",
@@ -485,7 +521,13 @@ def default_report_path(report: dict) -> Path:
 # Findings that make a tree structurally wrong rather than merely untidy.
 # `orphan_pages` is deliberately absent: many pages are validly reachable
 # through the index or navigation only. `quote_limit_violations` is advisory
-# too - it flags a habit, not a broken tree.
+# too - it flags a habit, not a broken tree. `redundant_see_also` joins them for
+# both of those reasons at once: a weak edge beside a specific one is redundant
+# rather than wrong, and the check arrived long after the corpora it judges, so
+# promoting it would turn every existing instance red on the upgrade that
+# shipped it. Unlike `unlabelled_edges` it is not migration-gated either - there
+# is no version at which the redundancy becomes an error, only a sweep someone
+# does or does not get to.
 #
 # `malformed_edges` and `unbalanced_markers` are hard from the start: neither
 # describes an unconverted page, only a broken one.

tools/chemenu/tests/test_docs_verify.py

@@ -100,6 +100,30 @@ def test_install_md_is_checked_too(tmp_path, monkeypatch):
     assert any("`doctor`" in issue for issue in issues)
 
 
+def test_development_md_is_checked_too(tmp_path, monkeypatch):
+    """DEVELOPMENT.md drifted exactly this way once (Gitea #47): a table
+    describing what each verify command checks, removed by hand because nothing
+    compared it to anything."""
+    root = tmp_path
+    (root / "DEVELOPMENT.md").write_text(
+        "| Command | Purpose |\n| `docs verify` | checks docs |\n", encoding="utf-8"
+    )
+    monkeypatch.setattr(docs_verify.config, "ROOT", root)
+    monkeypatch.setattr(docs_verify, "ROOT_README", root / "README.md")  # doesn't exist here
+    issues = docs_verify.check_readmes_have_no_command_table()
+    assert any("`docs verify`" in issue for issue in issues)
+
+
+def test_an_absent_listed_doc_is_skipped_not_reported(tmp_path, monkeypatch):
+    """The distributed-instance case: DEVELOPMENT.md is not shipped, so listing
+    it must stay inert where the file does not exist rather than failing a tree
+    that is correct."""
+    root = tmp_path
+    monkeypatch.setattr(docs_verify.config, "ROOT", root)
+    monkeypatch.setattr(docs_verify, "ROOT_README", root / "README.md")
+    assert docs_verify.check_readmes_have_no_command_table() == []
+
+
 def test_legacy_type_blocks_are_absent():
     assert docs_verify.check_legacy_type_blocks() == []
 

tools/chemenu/tests/test_git_publish.py

@@ -10,6 +10,7 @@ from chemenu.commands._util import EXIT_NEEDS_CLEARANCE
 from chemenu.commands.git_publish import (
     DEFAULT_MASS_UPDATE_THRESHOLD,
     GATE_EXEMPT_PREFIXES,
+    STACK_MACHINERY_NOTE,
     YES_REMOVED_MESSAGE,
     FileChange,
     attention_notes,
@@ -29,6 +30,7 @@ from chemenu.commands.git_publish import (
     rerun_command,
     scale_line,
     sync_command,
+    touches_stack_machinery,
 )
 
 
@@ -290,6 +292,26 @@ def test_gate_message_names_generated_files_as_their_own_reason():
     assert "kb/provenance.md" not in message
 
 
+def test_stack_machinery_detects_the_version_parts_scope():
+    """The same boundary version-parts.md names for the stack version: tools/,
+    types/, instructions/, AGENTS.md, and any <stage>/CONTRACT.md."""
+    assert touches_stack_machinery(["instructions/dev/issue-tracking.md"])
+    assert touches_stack_machinery(["tools/chemenu/commands/git_publish.py"])
+    assert touches_stack_machinery(["types/instruction.md"])
+    assert touches_stack_machinery(["AGENTS.md"])
+    assert touches_stack_machinery(["kb/CONTRACT.md"])
+    assert touches_stack_machinery(["raw/CONTRACT.md"])
+
+
+def test_stack_machinery_excludes_ordinary_content():
+    """kb/ content, docs/ prose and work/ scratch carry no normative sentence
+    and are not what the closing-phase reminder is about."""
+    assert not touches_stack_machinery(["kb/entities/systems/Foo.md"])
+    assert not touches_stack_machinery(["docs/why-gates-are-code.md"])
+    assert not touches_stack_machinery(["work/ingest-x/extract-0.md"])
+    assert not touches_stack_machinery([])
+
+
 # --- publish_command integration: a real git repo + a local bare remote ---
 
 
@@ -356,6 +378,24 @@ def test_below_threshold_publish_goes_straight_through(repo):
     assert _git(repo, "status", "--porcelain", "-uall").stdout == ""
 
 
+def test_publish_notes_stack_machinery_after_success(repo, capsys):
+    """The closing-phase reminder lands exactly once, after the OK line, and
+    only when the changeset actually falls under version-parts.md's scope."""
+    (repo / "instructions").mkdir()
+    (repo / "instructions/example.md").write_text("x\n", encoding="utf-8")
+    _publish(message="touch instructions")
+    out = capsys.readouterr().out
+    assert STACK_MACHINERY_NOTE in out
+    assert out.count(STACK_MACHINERY_NOTE) == 1
+
+
+def test_publish_stays_quiet_for_ordinary_content(repo, capsys):
+    _write_files(repo, 1)
+    _publish(message="ordinary content")
+    out = capsys.readouterr().out
+    assert STACK_MACHINERY_NOTE not in out
+
+
 def test_at_threshold_publish_asks_for_clearance_and_stages_nothing(repo):
     _write_files(repo, 10)
     with pytest.raises(typer.Exit) as excinfo:

tools/chemenu/tests/test_lint.py

@@ -579,3 +579,93 @@ def test_a_tree_that_never_declared_a_kb_version_keeps_every_key(kb_dir):
     migration for a gated finding to be the noise of."""
     assert kb_state.read_kb_version() is None
     assert hard_error_keys() == HARD_ERROR_KEYS
+
+
+# --- `redundant_see_also` --------------------------------------------------
+#
+# `see-also` is the catalogue's declared last resort. The finding is about the
+# case where the *other* page already said something specific about the same
+# pair, so the weak edge carries nothing the inbound view did not already
+# render. Measured once on this repo's corpus, that was 57 of 180 see-also
+# edges - which is why it is worth a check rather than a habit.
+
+
+def _pair(kb_dir, forward, backward):
+    """Two tool pages asserting `forward` and `backward` about each other."""
+    for name, edge in (("nearside", forward), ("farside", backward)):
+        other = "farside" if name == "nearside" else "nearside"
+        write_page(
+            kb_dir / f"entities/tools/{name}.md",
+            {"type": "types/entity.md", "entity_type": "tool", "tags": [],
+             "created": "2026-09-04", "modified": "2026-09-04",
+             "related": [] if edge is None else [{edge: other}],
+             "sources": [], "confidence": 0.8, "provenance": "general",
+             "summary": f"One half of a pair, asserting {edge} about the other."},
+            f"\n# {name}\n\nHalf a pair.\n",
+        )
+
+
+def test_see_also_is_redundant_when_the_other_page_asserts_something_specific(kb_dir):
+    """`nearside see-also farside` beside `farside depends-on nearside`: the
+    labelled edge already shows on both pages, so the weak one says nothing."""
+    _pair(kb_dir, "see-also", "depends-on")
+    report = run_lint(kb_dir)
+    assert {
+        "page": "nearside", "target": "farside", "reverse_label": "depends-on"
+    } in report["redundant_see_also"]
+
+
+def test_a_see_also_with_no_reverse_edge_at_all_is_not_redundant(kb_dir):
+    """The ordinary case the label exists for - nothing more specific fits, and
+    the other page says nothing back."""
+    _pair(kb_dir, "see-also", None)
+    assert [
+        i for i in run_lint(kb_dir)["redundant_see_also"] if i["page"] == "nearside"
+    ] == []
+
+
+def test_a_mutual_see_also_pair_is_not_reported_here(kb_dir):
+    """Two weak edges about one pair is a different finding - a mirror, which
+    the catalogue's 'direction is authored, never mirrored' rule covers and a
+    corpus sweep resolves. This check must not claim it: it is about a weak
+    edge standing beside a *specific* one, and reporting the mutual case here
+    would tell an author to drop an edge without saying which."""
+    _pair(kb_dir, "see-also", "see-also")
+    assert [
+        i for i in run_lint(kb_dir)["redundant_see_also"]
+        if i["page"] in ("nearside", "farside")
+    ] == []
+
+
+def test_the_specific_edge_is_never_the_one_reported(kb_dir):
+    """Only the `see-also` side is a finding. Reporting the labelled edge too
+    would make the pair unfixable - dropping both loses the assertion."""
+    _pair(kb_dir, "see-also", "depends-on")
+    assert [
+        i for i in run_lint(kb_dir)["redundant_see_also"] if i["page"] == "farside"
+    ] == []
+
+
+def test_redundant_see_also_is_advisory_at_every_kb_version(kb_dir):
+    """Redundant, not wrong - and the check arrived long after the corpora it
+    judges, so promoting it would turn every existing instance red on the
+    upgrade that shipped it. Unlike `unlabelled_edges` there is no version at
+    which it becomes an error, so it is not migration-gated either."""
+    _pair(kb_dir, "see-also", "depends-on")
+    report = run_lint(kb_dir)
+    assert report["redundant_see_also"] != []
+    for version in (Version(3, 0, 0), Version(4, 0, 0), Version(5, 0, 0)):
+        kb_state.write_kb_state(version, [])
+        assert "redundant_see_also" not in hard_error_keys()
+    assert has_hard_errors({"redundant_see_also": report["redundant_see_also"]}) is False
+
+
+def test_redundant_see_also_reaches_the_rendered_report_and_the_summary(kb_dir):
+    """A finding nobody prints is a finding nobody acts on. `render_summary`
+    drops every empty section, so this also proves the section is not empty."""
+    _pair(kb_dir, "see-also", "depends-on")
+    report = run_lint(kb_dir)
+    assert "Redundant see-also" in render_markdown(report)
+    summary = render_summary(report)
+    assert "Redundant see-also" in summary
+    assert "[[nearside]]" in summary and "depends-on" in summary