Altlasten der Konfiguration bereinigen: die Einzeldateien .wikitool-*.json ziehen in die drei Stufen um und verschwinden #208

Closed
opened 2026-10-09 21:40:35 +00:00 by torben · 7 comments
Owner

Angelegt am 2026-10-09 in der Design-Sitzung zu #87/#200 (Stand 9.0.0, 7cfafd7), auf Wunsch des Betreibers: Nach #207 sollen die Altlasten verschwinden und nicht neben dem neuen Mechanismus weiterleben. Die Entscheidungen 1-9 hat der Betreiber am 2026-10-10 getroffen.

Stand 2026-10-10 (nach #207, 9.1.0-beta.1, e085a8b): Der Blocker #207 ist geschlossen. Ein Bau-Versuch hat gezeigt, dass der Body die Abbildung der alten Formen auf die flachen Abschnitte aus #207 nicht festlegte; daraus kamen die Entscheidungen 5-9.

Abgeschlossen 2026-10-11: Gebaut und veröffentlicht als 10.0.0-beta.2. CI-Lauf 655 auf 7c8e9ce ist grün und hat die Änderung verifiziert. Zur Umsetzung: doctor liest die Remotes-Liste direkt über settings.load und fängt dabei einen Fehler der Einstellungsdateien ab, statt abzustürzen. Die Live-Suite reicht die Wegwerf-Secrets der Profile als WIKITOOL_SECRET_<NAME> weiter. Die Entscheidungen 1-9 blieben unverändert.

Abweichung vom ersten Veröffentlichen (db8f90c, 10.0.0-beta.1): Dort fehlte in test_tracker_live.py ein Import (config_shapes, settings); die Live-Suite scheiterte mit einem NameError (Läufe 649 und 651), behoben in d09247d. Weil diese Korrektur unter tools/ liegt, verlangte das Versionstor einen Bump (Lauf 652), daher 10.0.0-beta.2 in 6a89a92. Lauf 653 scheiterte dann in der Verteilung, weil docs/reference/configuration.md auf das nicht ausgelieferte instructions/dev/tracker-testing.md verlinkte; der Link ist in 7c8e9ce entfernt (nur Prosa, kein Bump).

Abschlussprüfung: docs/how-to/update-an-instance.md beschrieb Migrationen nur als einmal pro Instanz umgeschriebene Seiten. Jetzt sagt sie, dass die Migration 10.0.0 pro Checkout fällig ist und ein zweiter Klon nach dem Pull selbst config migrate ausführt. Das steht in 298b514 (nur docs/, kein Bump), CI-Lauf 656. Die übrigen Seiten unter docs/, die Verträge und kb/ sind gegen die Änderung gelesen und brauchen nichts. Die zwei kb/-Stellen, die .wikitool-remotes.json nennen (wikitool.md, Publish-Remote Gate.md), sind datierte Verlaufseinträge zu 2.1.0 und bleiben richtig.

Ziel

Nach diesem Paket hat eine Instanz für Einstellungen genau drei Ablagen aus #207:

  • wikitool.json (eingecheckt);
  • .wikitool-local.json (lokal);
  • Secrets über Verweise: Umgebungsvariable, Secret-Datei im Nutzerverzeichnis oder 1Password.

Es gibt keine Einzeldatei pro Feature mehr und kein Secret mehr im Klartext im Arbeitsbaum. Kein Code liest mehr eine Altdatei, außer dem Migrationsschritt. Einzige bewusste Ausnahme ist .wikitool-tools.json als Zustand des Preflights (Entscheidung 2).

Ziel pro Datei

Datei bis 9.x Inhalt Ziel
.wikitool-remotes.json Allowlist für den Publish-Remote-Gate Abschnitt remotes, checkout, Feld mit gate (darf nach #207 Entwurf 2 nie instance sein)
.wikitool-telemetry.json Zustimmung plus zwei Mengendeckel Abschnitt telemetry, checkout, ohne gate (Entscheidung 6)
.wikitool-upload.json Opt-in für das MCP-Tool submit: Identitäts-Header, Größendeckel, erlaubte Endungen, Kontingent Abschnitt upload, checkout, jedes Feld mit gate (Entscheidungen 3, 6)
.wikitool-tasks.json Anbieter, Verbindung, drei Schwellen, Token/App-Passwort Abschnitte tasks, superproductivity, caldav (Entscheidungen 5, 6)
.wikitool-tasks.d/ Profile für die Live-Tests (nur Dev-Repo) bleibt, im Format von .wikitool-local.json mit Secret-Verweisen (Entscheidungen 4, 7)
.wikitool-tools.json Werkzeugpfade, vom Preflight geschrieben, vom Launcher gelesen bleibt eigene Datei (Entscheidung 2)

#198 (Platzhalter für das Token der Super-Productivity-Konfiguration fehlt) ist damit gegenstandslos. Eine .wikitool-tasks.json schreibt niemand mehr. Den Token setzt setup-instance.md Schritt 9 als Secret-Verweis über config set.

Entscheidungen des Betreibers (2026-10-10)

  1. Harter Schnitt, MAJOR mit Pflicht-Migration. Die neue Version liest keine Altdatei mehr. Eine Übergangsversion, die Altdateien mit Warnung weiter liest, gibt es nicht. Verworfen wurde sie, weil sie genau den Code am Leben hielte, den dieses Paket entfernen soll.
  2. .wikitool-tools.json bleibt eine eigene Datei. Sie ist Zustand des Preflights, keine Einstellung: maschinengeschrieben vom Preflight und gelesen vom Launcher (sh/ps1), bevor Python läuft. Ein Umzug hätte Preflight und Launcher auf beiden Plattformen berührt (#140, #151). Die Doku führt sie ausdrücklich als Zustand des Preflights. #207 trägt dort op als optionales Werkzeug ein.
  3. Die Grenzen des Uploads gehen nach checkout. Nur der Checkout, der den MCP-Server betreibt, braucht sie.
  4. .wikitool-tasks.d/ bleibt. Die Profile bekommen Secret-Verweise statt Klartext, passend sind op://-Verweise. Die Migration der Profile ist eine Zeile in instructions/dev/tracker-testing.md, kein Teil des Migrationsschritts (nur Dev-Repo).
  5. Flache Abschnitte, je Anbieter einer. Der Mechanismus aus #207 bleibt flach. Verworfen wurde, ihm Unterobjekte und Varianten beizubringen, weil dann die Stufe nicht mehr am Feld allein ablesbar wäre.
    • upload: identity_header, max_bytes, allowed_extensions, quota_submissions_per_day, quota_bytes_per_day.
    • tasks: provider, stalled_waiting_days, unpaged_project_weeks, someday_stale_months.
    • superproductivity: access, api_base_url, api_token, backups_dir.
    • caldav: Felder wie bis 9.x.
    • Was bis 9.x die Varianten je access prüften (api_token Pflicht nur bei api, backups_dir nur bei snapshot, kein Feld der anderen Variante), prüft der Leser im Adapter, mit derselben Meldung wie bis 9.x.
  6. Stufen und wer setzt.
    Feld Stufe
    tasks.* instance
    superproductivity.access instance
    superproductivity.api_base_url private
    superproductivity.api_token secret
    superproductivity.backups_dir checkout
    caldav.url, caldav.username private
    caldav.app_password secret
    caldav.inbox_list, someday_list, exclude_lists instance
    remotes.allowed_push_urls checkout + gate
    upload.* checkout + gate: Die Felder schalten einen Schreibweg von außen frei und wurden bis 9.x nur vom Nutzer angelegt, also endet config set dort mit 42
    telemetry.* checkout, ohne gate: setup-instance.md lässt den Agenten die Zustimmung nach der Antwort des Nutzers setzen
  7. WIKITOOL_TASKS_CONFIG bleibt, zeigt aber auf ein Profil.
    • Ein Profil hat das Format von .wikitool-local.json, enthält aber nur tasks und Anbieter-Abschnitte, plus live_test_version.
    • Ist die Variable gesetzt, ersetzt das Profil beim Lesen genau diese Abschnitte aus beiden Dateien. Die Platzierung wird geprüft wie in .wikitool-local.json, nur dürfen instance-Felder dort stehen.
    • Ein Secret steht auch im Profil nur als Verweis. Die Live-Suite reicht ihre Wegwerf-Tokens über WIKITOOL_SECRET_<NAME> und Namensverweise weiter.
    • Verworfen: die Variable streichen und pro Test ein Temp-Root bauen. Profile ließen sich dann nur noch durch Umkopieren nutzen.
  8. Der Telemetrie-Hook bleibt stumm.
    • Er ignoriert eine verbliebene .wikitool-telemetry.json, und es gilt der Standard der Installationsform.
    • Er liest nur den Abschnitt telemetry, nachsichtig wie bis 9.x: Ein Fehler in einem anderen Abschnitt oder im Format der Datei lässt ihn nicht scheitern.
    • doctor meldet die Altdatei als FAIL, wikitool-Kommandos enden mit 42.
  9. Der Migrationsschritt ist wikitool config migrate.
    • Die bisherigen Migrationen (3.0.0 bis 9.0.0) hatten kein eigenes Kommando: ein Dokument unter instructions/migrations/ plus die Buchführung migrate status/done/baseline/verify über .wikitool-kb.json, einmal pro Instanz. Die mechanische Arbeit machte ein Skript des Agenten oder eine Ersetzung von Hand.
    • Hier geht das nicht: Ein Secret darf nie durch den Agenten laufen (AGENTS.md § Settings), und gate-Felder setzt nur der Nutzer.
    • Das Dokument bleibt im Schema, nur der Schritt selbst wird ein Kommando, und zwar in der Gruppe config. Deren Dateien schreibt es, und wie sie läuft es pro Checkout.
    • Verworfen:
      • migrate settings: mischt Arbeit pro Checkout mit Buchführung pro Instanz in einer Gruppe;
      • migrate run <version>: das in migrate-corpus.md angekündigte mechanische Primitiv, ein eigenes, größeres Design.

Entwurf

  1. wikitool config migrate liest jede Altdatei und schreibt ihre Werte in die richtige Stufe.
    • Secrets legt er als Namensverweise an (superproductivity_api_token, caldav_app_password). Der Wert selbst kommt in die Secret-Datei im Nutzerverzeichnis. Wer 1Password nutzt, trägt ihn danach dort ein und ersetzt den Verweis per config set.
    • Felder mit gate darf config set nicht schreiben. config migrate darf es, denn er verschiebt nur den Wert, den der Nutzer schon gesetzt hat, und weitet nichts aus.
    • Die Altdatei entfernt der Schritt erst danach.
    • Ohne Altdatei endet er erfolgreich und ohne Änderung, ist also idempotent.
    • Eine Migrationsanleitung instructions/migrations/10.0.0-settings-tiers.md (migration_kind: mechanical, obligation: required) beschreibt den Ablauf, und version bump verweist darauf.
    • Buchführung: migrate done läuft einmal pro Instanz. config migrate läuft in jedem Checkout, weil remotes, telemetry und upload pro Checkout liegen. Einen zweiten Klon, der noch nicht migriert hat, fängt Entwurf 2 über die verbliebene Datei, nicht migrate status.
    • migrate-corpus.md § Decision points („There is no migrate run“) bekommt einen Satz dazu: Ein Schritt, den der Agent nicht selbst ausführen darf, ist ein Kommando der Gruppe, deren Dateien er schreibt. Das Dokument bleibt die Anleitung.
  2. Nach dem Upgrade liest wikitool keine Altdatei mehr. Liegt eine noch da, endet jeder Aufruf, der diese Einstellung braucht, mit exit 42 und der Zeile tools/wikitool config migrate (Ausnahme Telemetrie-Hook, Entscheidung 8). doctor meldet sie als FAIL.
  3. .gitignore, die Kanarien in docs verify und die doctor-Zeilen der Altdateien entfallen. Ein Ignore-Eintrag pro Altdatei bleibt bewusst stehen, damit eine nicht migrierte Datei nicht versehentlich eingecheckt wird. Wann er gehen darf, entscheidet #211.
  4. Die Records der Altdateien (config_shapes.TELEMETRY, REMOTES, UPLOAD, TASKS) werden zu Abschnitten in SETTINGS_SECTIONS (Entscheidungen 5, 6).
    • Die alten Formen braucht nur noch config migrate zum Lesen (tools/chemenu/legacy_settings.py).
    • docs reference --apply rendert die neuen Abschnitte in docs/reference/configuration.md.
    • Die Bedeutung eines fehlenden Abschnitts bleibt wie bis 9.x:
      • remotes fehlt: keine Einschränkung;
      • upload fehlt: Tool nicht registriert;
      • tasks fehlt: kein Tracker;
      • telemetry fehlt: Standard der Installationsform.
    • Ein leeres allowed_push_urls erlaubt weiterhin gar keinen Push.

Invarianten

  • Nach dem Migrationsschritt hat jede Einstellung denselben wirksamen Wert wie davor. Geprüft wird das für jede Altdatei, jeden Schlüssel und Standardwerte eingeschlossen.
  • Kein Secret-Wert steht danach in einer Datei im Arbeitsbaum oder im Git-Index, und keiner erscheint in einer Ausgabe des Migrationsschritts.
  • Ein Abbruch mitten in der Migration lässt die Altdateien unverändert. Die Altdatei wird erst entfernt, wenn ihre Werte an allen Zielen geschrieben und zurückgelesen sind.

Betroffene Dateien

  • tools/chemenu/config.py, tools/chemenu/config_shapes.py, tools/chemenu/settings.py, neu tools/chemenu/legacy_settings.py, alle Leser: upload.py, telemetry/policy.py, commands/git_publish.py, tasks/config.py, tasks/superproductivity.py, tasks/caldav.py
  • commands/config_cmd.py (neu config migrate mit Record), commands/doctor.py, commands/docs_verify.py, commands/task_cmd.py, commands/review_cmd.py (Records nennen WIKITOOL_TASKS_CONFIG), .gitignore
  • Tests: test_settings.py, test_tasks_config.py, test_config_shapes.py, test_doctor.py, test_task_cmd.py, test_review.py, tracker_live.py, test_tracker_live.py, conftest.py, neu ein Test für config migrate
  • neu: instructions/migrations/10.0.0-settings-tiers.md
  • AGENTS.md § Gates (Ort der Remotes-Allowlist), instructions/setup-instance.md, instructions/gates.md, instructions/preflight.md (.wikitool-tools.json als Zustand), instructions/ingest-queue.md, instructions/mcp-read-server.md, instructions/migrate-corpus.md (Entwurf 1), raw/CONTRACT.md § mcp-upload, INSTALL.md, tools/README.md, tools/CONTRACT.md (generiert), docs/how-to/ (trace-and-score-sessions, set-up-the-mcp-server, run-the-weekly-review, troubleshoot, beim Abschluss update-an-instance), docs/reference/ (configuration, generierte Kommandoseiten), docs/explanation/ (telemetry-and-evaluation, knowledge-and-commitment, why-gates-are-code)
  • instructions/dev/tracker-testing.md (Entscheidungen 4, 7), instructions/dev/doc-pull-through.md (Zeile zu den Einzeldateien)

Akzeptanzkriterien

  • Für jede Altdatei und jeden Schlüssel: Nach config migrate liefert die Leseschicht denselben wirksamen Wert wie die alte Leselogik davor (parametrisierter Test über alle Shapes).
  • Nach config migrate existiert keine Altdatei mehr außer .wikitool-tools.json, und git grep über den Index findet keinen der migrierten Secret-Werte.
  • Ein Abbruch nach dem Schreiben des ersten Ziels (Test per Fehlerinjektion) lässt alle Altdateien byte-identisch zurück.
  • Ein zweiter Lauf von config migrate endet mit exit 0 und ändert keine Datei.
  • Mit einer verbliebenen Altdatei endet ein Kommando, das die Einstellung braucht, mit exit 42 und der Zeile tools/wikitool config migrate; doctor meldet FAIL; der Telemetrie-Hook schreibt weiter nach dem Standard der Installationsform und endet nie mit 42.
  • Außer in config migrate liest kein Code eine der migrierten Altdateien (grep nach den Dateinamen in tools/chemenu/ außerhalb von legacy_settings.py, docs_verify.py (Testpfad eines Profils) und der Tests ist leer; beim Abschluss erneut geprüft).
  • config set auf ein upload.*- oder remotes.*-Feld endet mit 42; auf ein telemetry.*-Feld schreibt es in .wikitool-local.json.
  • Ein Super-Productivity-Abschnitt mit access: api ohne api_token, oder mit einem backups_dir daneben, endet beim Lesen mit exit 1, wie bis 9.x.
  • Mit WIKITOOL_TASKS_CONFIG auf ein Profil lesen task, review und doctor dessen Abschnitte statt derer aus den Einstellungsdateien; die Live-Suite läuft ohne Klartext-Token in einer Datei.
  • instructions/dev/tracker-testing.md beschreibt Profile mit Secret-Verweisen; kein Profil-Beispiel dort enthält einen Klartext-Token.
  • pytest, docs verify, instructions verify grün (lokal: 2748 bestanden, 4 übersprungen); CI grün (Lauf 655 auf 7c8e9ce; nach der Abschlussprüfung Lauf 656 auf 298b514).

Versionsteil

--major, mit Pflicht-Migration (vom Betreiber bestätigt, 2026-10-10). Die Form maschinenlesbarer Dateien ändert sich, WIKITOOL_TASKS_CONFIG zeigt künftig auf eine Datei anderer Form, und das Upgrade braucht einen Schritt über das Kopieren hinaus (Katalog in version-parts.md). Die Migration betrifft nur Konfiguration, kb/ bleibt unberührt. Der laufende Kandidat 9.1.0-beta.1 eskalierte damit zu 10.0.0-beta.1, und der Bump nennt instructions/migrations/10.0.0-settings-tiers.md. Ausgeliefert ist der Kandidat 10.0.0-beta.2.

Kette

Kette „Beschaffung und Konfiguration“

> Angelegt am 2026-10-09 in der Design-Sitzung zu #87/#200 (Stand `9.0.0`, `7cfafd7`), auf Wunsch des Betreibers: Nach #207 sollen die Altlasten verschwinden und nicht neben dem neuen Mechanismus weiterleben. Die Entscheidungen 1-9 hat der Betreiber am 2026-10-10 getroffen. > > **Stand 2026-10-10 (nach #207, `9.1.0-beta.1`, `e085a8b`):** Der Blocker #207 ist geschlossen. Ein Bau-Versuch hat gezeigt, dass der Body die Abbildung der alten Formen auf die flachen Abschnitte aus #207 nicht festlegte; daraus kamen die Entscheidungen 5-9. > > **Abgeschlossen 2026-10-11:** Gebaut und veröffentlicht als `10.0.0-beta.2`. CI-Lauf 655 auf `7c8e9ce` ist grün und hat die Änderung verifiziert. Zur Umsetzung: `doctor` liest die Remotes-Liste direkt über `settings.load` und fängt dabei einen Fehler der Einstellungsdateien ab, statt abzustürzen. Die Live-Suite reicht die Wegwerf-Secrets der Profile als `WIKITOOL_SECRET_<NAME>` weiter. Die Entscheidungen 1-9 blieben unverändert. > > **Abweichung vom ersten Veröffentlichen (`db8f90c`, `10.0.0-beta.1`):** Dort fehlte in `test_tracker_live.py` ein Import (`config_shapes`, `settings`); die Live-Suite scheiterte mit einem `NameError` (Läufe 649 und 651), behoben in `d09247d`. Weil diese Korrektur unter `tools/` liegt, verlangte das Versionstor einen Bump (Lauf 652), daher `10.0.0-beta.2` in `6a89a92`. Lauf 653 scheiterte dann in der Verteilung, weil `docs/reference/configuration.md` auf das nicht ausgelieferte `instructions/dev/tracker-testing.md` verlinkte; der Link ist in `7c8e9ce` entfernt (nur Prosa, kein Bump). > > **Abschlussprüfung:** `docs/how-to/update-an-instance.md` beschrieb Migrationen nur als einmal pro Instanz umgeschriebene Seiten. Jetzt sagt sie, dass die Migration 10.0.0 pro Checkout fällig ist und ein zweiter Klon nach dem Pull selbst `config migrate` ausführt. Das steht in `298b514` (nur `docs/`, kein Bump), CI-Lauf 656. Die übrigen Seiten unter `docs/`, die Verträge und `kb/` sind gegen die Änderung gelesen und brauchen nichts. Die zwei `kb/`-Stellen, die `.wikitool-remotes.json` nennen (`wikitool.md`, `Publish-Remote Gate.md`), sind datierte Verlaufseinträge zu 2.1.0 und bleiben richtig. ## Ziel Nach diesem Paket hat eine Instanz für Einstellungen genau drei Ablagen aus #207: - `wikitool.json` (eingecheckt); - `.wikitool-local.json` (lokal); - Secrets über Verweise: Umgebungsvariable, Secret-Datei im Nutzerverzeichnis oder 1Password. Es gibt keine Einzeldatei pro Feature mehr und kein Secret mehr im Klartext im Arbeitsbaum. Kein Code liest mehr eine Altdatei, außer dem Migrationsschritt. Einzige bewusste Ausnahme ist `.wikitool-tools.json` als Zustand des Preflights (Entscheidung 2). ## Ziel pro Datei | Datei bis 9.x | Inhalt | Ziel | |---|---|---| | `.wikitool-remotes.json` | Allowlist für den Publish-Remote-Gate | Abschnitt `remotes`, `checkout`, Feld mit `gate` (darf nach #207 Entwurf 2 nie `instance` sein) | | `.wikitool-telemetry.json` | Zustimmung plus zwei Mengendeckel | Abschnitt `telemetry`, `checkout`, ohne `gate` (Entscheidung 6) | | `.wikitool-upload.json` | Opt-in für das MCP-Tool `submit`: Identitäts-Header, Größendeckel, erlaubte Endungen, Kontingent | Abschnitt `upload`, `checkout`, jedes Feld mit `gate` (Entscheidungen 3, 6) | | `.wikitool-tasks.json` | Anbieter, Verbindung, drei Schwellen, **Token/App-Passwort** | Abschnitte `tasks`, `superproductivity`, `caldav` (Entscheidungen 5, 6) | | `.wikitool-tasks.d/` | Profile für die Live-Tests (nur Dev-Repo) | bleibt, im Format von `.wikitool-local.json` mit Secret-Verweisen (Entscheidungen 4, 7) | | `.wikitool-tools.json` | Werkzeugpfade, vom Preflight geschrieben, vom Launcher gelesen | bleibt eigene Datei (Entscheidung 2) | #198 (Platzhalter für das Token der Super-Productivity-Konfiguration fehlt) ist damit gegenstandslos. Eine `.wikitool-tasks.json` schreibt niemand mehr. Den Token setzt `setup-instance.md` Schritt 9 als Secret-Verweis über `config set`. ## Entscheidungen des Betreibers (2026-10-10) 1. **Harter Schnitt, MAJOR mit Pflicht-Migration.** Die neue Version liest keine Altdatei mehr. Eine Übergangsversion, die Altdateien mit Warnung weiter liest, gibt es nicht. Verworfen wurde sie, weil sie genau den Code am Leben hielte, den dieses Paket entfernen soll. 2. **`.wikitool-tools.json` bleibt eine eigene Datei.** Sie ist Zustand des Preflights, keine Einstellung: maschinengeschrieben vom Preflight und gelesen vom Launcher (sh/ps1), bevor Python läuft. Ein Umzug hätte Preflight und Launcher auf beiden Plattformen berührt (#140, #151). Die Doku führt sie ausdrücklich als Zustand des Preflights. #207 trägt dort `op` als optionales Werkzeug ein. 3. **Die Grenzen des Uploads gehen nach `checkout`.** Nur der Checkout, der den MCP-Server betreibt, braucht sie. 4. **`.wikitool-tasks.d/` bleibt.** Die Profile bekommen Secret-Verweise statt Klartext, passend sind `op://`-Verweise. Die Migration der Profile ist eine Zeile in `instructions/dev/tracker-testing.md`, kein Teil des Migrationsschritts (nur Dev-Repo). 5. **Flache Abschnitte, je Anbieter einer.** Der Mechanismus aus #207 bleibt flach. Verworfen wurde, ihm Unterobjekte und Varianten beizubringen, weil dann die Stufe nicht mehr am Feld allein ablesbar wäre. - `upload`: `identity_header`, `max_bytes`, `allowed_extensions`, `quota_submissions_per_day`, `quota_bytes_per_day`. - `tasks`: `provider`, `stalled_waiting_days`, `unpaged_project_weeks`, `someday_stale_months`. - `superproductivity`: `access`, `api_base_url`, `api_token`, `backups_dir`. - `caldav`: Felder wie bis 9.x. - Was bis 9.x die Varianten je `access` prüften (`api_token` Pflicht nur bei `api`, `backups_dir` nur bei `snapshot`, kein Feld der anderen Variante), prüft der Leser im Adapter, mit derselben Meldung wie bis 9.x. 6. **Stufen und wer setzt.** | Feld | Stufe | |---|---| | `tasks.*` | `instance` | | `superproductivity.access` | `instance` | | `superproductivity.api_base_url` | `private` | | `superproductivity.api_token` | `secret` | | `superproductivity.backups_dir` | `checkout` | | `caldav.url`, `caldav.username` | `private` | | `caldav.app_password` | `secret` | | `caldav.inbox_list`, `someday_list`, `exclude_lists` | `instance` | | `remotes.allowed_push_urls` | `checkout` + `gate` | | `upload.*` | `checkout` + `gate`: Die Felder schalten einen Schreibweg von außen frei und wurden bis 9.x nur vom Nutzer angelegt, also endet `config set` dort mit 42 | | `telemetry.*` | `checkout`, ohne `gate`: `setup-instance.md` lässt den Agenten die Zustimmung nach der Antwort des Nutzers setzen | 7. **`WIKITOOL_TASKS_CONFIG` bleibt, zeigt aber auf ein Profil.** - Ein Profil hat das Format von `.wikitool-local.json`, enthält aber nur `tasks` und Anbieter-Abschnitte, plus `live_test_version`. - Ist die Variable gesetzt, ersetzt das Profil beim Lesen genau diese Abschnitte aus beiden Dateien. Die Platzierung wird geprüft wie in `.wikitool-local.json`, nur dürfen `instance`-Felder dort stehen. - Ein Secret steht auch im Profil nur als Verweis. Die Live-Suite reicht ihre Wegwerf-Tokens über `WIKITOOL_SECRET_<NAME>` und Namensverweise weiter. - Verworfen: die Variable streichen und pro Test ein Temp-Root bauen. Profile ließen sich dann nur noch durch Umkopieren nutzen. 8. **Der Telemetrie-Hook bleibt stumm.** - Er ignoriert eine verbliebene `.wikitool-telemetry.json`, und es gilt der Standard der Installationsform. - Er liest nur den Abschnitt `telemetry`, nachsichtig wie bis 9.x: Ein Fehler in einem anderen Abschnitt oder im Format der Datei lässt ihn nicht scheitern. - `doctor` meldet die Altdatei als FAIL, `wikitool`-Kommandos enden mit 42. 9. **Der Migrationsschritt ist `wikitool config migrate`.** - Die bisherigen Migrationen (3.0.0 bis 9.0.0) hatten kein eigenes Kommando: ein Dokument unter `instructions/migrations/` plus die Buchführung `migrate status/done/baseline/verify` über `.wikitool-kb.json`, einmal pro Instanz. Die mechanische Arbeit machte ein Skript des Agenten oder eine Ersetzung von Hand. - Hier geht das nicht: Ein Secret darf nie durch den Agenten laufen (AGENTS.md § Settings), und `gate`-Felder setzt nur der Nutzer. - Das Dokument bleibt im Schema, nur der Schritt selbst wird ein Kommando, und zwar in der Gruppe `config`. Deren Dateien schreibt es, und wie sie läuft es pro Checkout. - Verworfen: - `migrate settings`: mischt Arbeit pro Checkout mit Buchführung pro Instanz in einer Gruppe; - `migrate run <version>`: das in `migrate-corpus.md` angekündigte mechanische Primitiv, ein eigenes, größeres Design. ## Entwurf 1. **`wikitool config migrate`** liest jede Altdatei und schreibt ihre Werte in die richtige Stufe. - Secrets legt er als Namensverweise an (`superproductivity_api_token`, `caldav_app_password`). Der Wert selbst kommt in die Secret-Datei im Nutzerverzeichnis. Wer 1Password nutzt, trägt ihn danach dort ein und ersetzt den Verweis per `config set`. - Felder mit `gate` darf `config set` nicht schreiben. `config migrate` darf es, denn er verschiebt nur den Wert, den der Nutzer schon gesetzt hat, und weitet nichts aus. - Die Altdatei entfernt der Schritt erst danach. - Ohne Altdatei endet er erfolgreich und ohne Änderung, ist also idempotent. - Eine Migrationsanleitung `instructions/migrations/10.0.0-settings-tiers.md` (`migration_kind: mechanical`, `obligation: required`) beschreibt den Ablauf, und `version bump` verweist darauf. - **Buchführung:** `migrate done` läuft einmal pro Instanz. `config migrate` läuft in **jedem** Checkout, weil remotes, telemetry und upload pro Checkout liegen. Einen zweiten Klon, der noch nicht migriert hat, fängt Entwurf 2 über die verbliebene Datei, nicht `migrate status`. - `migrate-corpus.md` § Decision points („There is no `migrate run`“) bekommt einen Satz dazu: Ein Schritt, den der Agent nicht selbst ausführen darf, ist ein Kommando der Gruppe, deren Dateien er schreibt. Das Dokument bleibt die Anleitung. 2. **Nach dem Upgrade liest `wikitool` keine Altdatei mehr.** Liegt eine noch da, endet jeder Aufruf, der diese Einstellung braucht, mit exit 42 und der Zeile `tools/wikitool config migrate` (Ausnahme Telemetrie-Hook, Entscheidung 8). `doctor` meldet sie als FAIL. 3. **`.gitignore`, die Kanarien in `docs verify` und die `doctor`-Zeilen der Altdateien entfallen.** Ein Ignore-Eintrag pro Altdatei bleibt bewusst stehen, damit eine nicht migrierte Datei nicht versehentlich eingecheckt wird. Wann er gehen darf, entscheidet #211. 4. **Die Records der Altdateien** (`config_shapes.TELEMETRY`, `REMOTES`, `UPLOAD`, `TASKS`) werden zu Abschnitten in `SETTINGS_SECTIONS` (Entscheidungen 5, 6). - Die alten Formen braucht nur noch `config migrate` zum Lesen (`tools/chemenu/legacy_settings.py`). - `docs reference --apply` rendert die neuen Abschnitte in `docs/reference/configuration.md`. - Die Bedeutung eines fehlenden Abschnitts bleibt wie bis 9.x: - `remotes` fehlt: keine Einschränkung; - `upload` fehlt: Tool nicht registriert; - `tasks` fehlt: kein Tracker; - `telemetry` fehlt: Standard der Installationsform. - Ein leeres `allowed_push_urls` erlaubt weiterhin gar keinen Push. ## Invarianten - Nach dem Migrationsschritt hat **jede Einstellung denselben wirksamen Wert** wie davor. Geprüft wird das für jede Altdatei, jeden Schlüssel und Standardwerte eingeschlossen. - **Kein Secret-Wert** steht danach in einer Datei im Arbeitsbaum oder im Git-Index, und keiner erscheint in einer Ausgabe des Migrationsschritts. - Ein Abbruch mitten in der Migration lässt die Altdateien unverändert. Die Altdatei wird erst entfernt, wenn ihre Werte an allen Zielen geschrieben und zurückgelesen sind. ## Betroffene Dateien - `tools/chemenu/config.py`, `tools/chemenu/config_shapes.py`, `tools/chemenu/settings.py`, neu `tools/chemenu/legacy_settings.py`, alle Leser: `upload.py`, `telemetry/policy.py`, `commands/git_publish.py`, `tasks/config.py`, `tasks/superproductivity.py`, `tasks/caldav.py` - `commands/config_cmd.py` (neu `config migrate` mit Record), `commands/doctor.py`, `commands/docs_verify.py`, `commands/task_cmd.py`, `commands/review_cmd.py` (Records nennen `WIKITOOL_TASKS_CONFIG`), `.gitignore` - Tests: `test_settings.py`, `test_tasks_config.py`, `test_config_shapes.py`, `test_doctor.py`, `test_task_cmd.py`, `test_review.py`, `tracker_live.py`, `test_tracker_live.py`, `conftest.py`, neu ein Test für `config migrate` - neu: `instructions/migrations/10.0.0-settings-tiers.md` - `AGENTS.md` § Gates (Ort der Remotes-Allowlist), `instructions/setup-instance.md`, `instructions/gates.md`, `instructions/preflight.md` (`.wikitool-tools.json` als Zustand), `instructions/ingest-queue.md`, `instructions/mcp-read-server.md`, `instructions/migrate-corpus.md` (Entwurf 1), `raw/CONTRACT.md` § mcp-upload, `INSTALL.md`, `tools/README.md`, `tools/CONTRACT.md` (generiert), `docs/how-to/` (trace-and-score-sessions, set-up-the-mcp-server, run-the-weekly-review, troubleshoot, beim Abschluss update-an-instance), `docs/reference/` (configuration, generierte Kommandoseiten), `docs/explanation/` (telemetry-and-evaluation, knowledge-and-commitment, why-gates-are-code) - `instructions/dev/tracker-testing.md` (Entscheidungen 4, 7), `instructions/dev/doc-pull-through.md` (Zeile zu den Einzeldateien) ## Akzeptanzkriterien - [x] Für jede Altdatei und jeden Schlüssel: Nach `config migrate` liefert die Leseschicht denselben wirksamen Wert wie die alte Leselogik davor (parametrisierter Test über alle Shapes). - [x] Nach `config migrate` existiert keine Altdatei mehr außer `.wikitool-tools.json`, und `git grep` über den Index findet keinen der migrierten Secret-Werte. - [x] Ein Abbruch nach dem Schreiben des ersten Ziels (Test per Fehlerinjektion) lässt alle Altdateien byte-identisch zurück. - [x] Ein zweiter Lauf von `config migrate` endet mit exit 0 und ändert keine Datei. - [x] Mit einer verbliebenen Altdatei endet ein Kommando, das die Einstellung braucht, mit exit 42 und der Zeile `tools/wikitool config migrate`; `doctor` meldet FAIL; der Telemetrie-Hook schreibt weiter nach dem Standard der Installationsform und endet nie mit 42. - [x] Außer in `config migrate` liest kein Code eine der migrierten Altdateien (`grep` nach den Dateinamen in `tools/chemenu/` außerhalb von `legacy_settings.py`, `docs_verify.py` (Testpfad eines Profils) und der Tests ist leer; beim Abschluss erneut geprüft). - [x] `config set` auf ein `upload.*`- oder `remotes.*`-Feld endet mit 42; auf ein `telemetry.*`-Feld schreibt es in `.wikitool-local.json`. - [x] Ein Super-Productivity-Abschnitt mit `access: api` ohne `api_token`, oder mit einem `backups_dir` daneben, endet beim Lesen mit exit 1, wie bis 9.x. - [x] Mit `WIKITOOL_TASKS_CONFIG` auf ein Profil lesen `task`, `review` und `doctor` dessen Abschnitte statt derer aus den Einstellungsdateien; die Live-Suite läuft ohne Klartext-Token in einer Datei. - [x] `instructions/dev/tracker-testing.md` beschreibt Profile mit Secret-Verweisen; kein Profil-Beispiel dort enthält einen Klartext-Token. - [x] `pytest`, `docs verify`, `instructions verify` grün (lokal: 2748 bestanden, 4 übersprungen); CI grün (Lauf 655 auf `7c8e9ce`; nach der Abschlussprüfung Lauf 656 auf `298b514`). ## Versionsteil **`--major`, mit Pflicht-Migration** (vom Betreiber bestätigt, 2026-10-10). Die Form maschinenlesbarer Dateien ändert sich, `WIKITOOL_TASKS_CONFIG` zeigt künftig auf eine Datei anderer Form, und das Upgrade braucht einen Schritt über das Kopieren hinaus (Katalog in `version-parts.md`). Die Migration betrifft nur Konfiguration, `kb/` bleibt unberührt. Der laufende Kandidat `9.1.0-beta.1` eskalierte damit zu `10.0.0-beta.1`, und der Bump nennt `instructions/migrations/10.0.0-settings-tiers.md`. Ausgeliefert ist der Kandidat `10.0.0-beta.2`. ## Kette Kette „Beschaffung und Konfiguration“ - Vorgänger: #207 - Nachfolger: #200
torben added the prio/plannedsize/Larea/distributionkind/decisionstatus/blocked labels 2026-10-09 21:40:35 +00:00
Author
Owner

Changelog: Frage 4 ist entschieden (2026-10-10): harter Schnitt, MAJOR mit Pflicht-Migration. Ziel-Tabelle und Migrationsschritt sind an die Verweise aus #207 angepasst (private-Basis-URL, Secrets als Verweis, Nachtrag nach 1Password per config set). Die Fragen 1-3 sind weiter offen, darum bleibt es bei kind/decision. Die Kettenzeile ist auf die Form aus #205 gekürzt.

**Changelog:** Frage 4 ist entschieden (2026-10-10): harter Schnitt, MAJOR mit Pflicht-Migration. Ziel-Tabelle und Migrationsschritt sind an die Verweise aus #207 angepasst (`private`-Basis-URL, Secrets als Verweis, Nachtrag nach 1Password per `config set`). Die Fragen 1-3 sind weiter offen, darum bleibt es bei `kind/decision`. Die Kettenzeile ist auf die Form aus #205 gekürzt.
torben added kind/build and removed kind/decision labels 2026-10-10 06:37:31 +00:00
Author
Owner

Changelog: Die Fragen 1-3 sind nach Empfehlung entschieden (2026-10-10): .wikitool-tools.json bleibt als Zustand des Preflights, die Grenzen des Uploads gehen nach checkout, die Profile in .wikitool-tasks.d/ bekommen Secret-Verweise. Dazu passende Kriterien. kind/decision → kind/build, blockiert bleibt es durch #207.

**Changelog:** Die Fragen 1-3 sind nach Empfehlung entschieden (2026-10-10): `.wikitool-tools.json` bleibt als Zustand des Preflights, die Grenzen des Uploads gehen nach `checkout`, die Profile in `.wikitool-tasks.d/` bekommen Secret-Verweise. Dazu passende Kriterien. `kind/decision` → `kind/build`, blockiert bleibt es durch #207.
torben removed the status/blocked label 2026-10-10 16:22:37 +00:00
Author
Owner

Der Blocker #207 ist geschlossen. Die drei Stufen sind in 9.1.0-beta.1 ausgeliefert, mit config_shapes.SETTINGS_SECTIONS (noch leer), tools/chemenu/settings.py und config set. status/blocked ist entfernt. Für den Bau gilt aus #207 Entwurf 6: Wenn die migrierten Tracker-Profile op://-Verweise in den Einstellungen nutzen, braucht die CI dafür op im Job und OP_SERVICE_ACCOUNT_TOKEN. Die vorhandene Action bedient nur Verweise per Namen.

Der Blocker #207 ist geschlossen. Die drei Stufen sind in `9.1.0-beta.1` ausgeliefert, mit `config_shapes.SETTINGS_SECTIONS` (noch leer), `tools/chemenu/settings.py` und `config set`. `status/blocked` ist entfernt. Für den Bau gilt aus #207 Entwurf 6: Wenn die migrierten Tracker-Profile `op://`-Verweise in den Einstellungen nutzen, braucht die CI dafür `op` im Job und `OP_SERVICE_ACCOUNT_TOKEN`. Die vorhandene Action bedient nur Verweise per Namen.
torben added kind/decision and removed kind/build labels 2026-10-10 19:57:06 +00:00
Author
Owner

Changelog: Ein Bau-Versuch hat die Prüfung „Ready to build“ nicht bestanden. Die Abschnitte aus #207 sind flach, die Altformen verschachtelt, und der Body legte die Abbildung nicht fest. Neu im Body ist der Abschnitt „Offene Fragen“ F1-F4, jeweils mit Vorschlag:

  • F1: Abschnitte flach machen;
  • F2: Stufen der restlichen Tracker-Felder, upload.* als gate;
  • F3: WIKITOOL_TASKS_CONFIG, Profile und Live-Suite;
  • F4: Telemetrie-Hook bei verbliebener Altdatei.

Ergänzt sind außerdem:

  • Entwurf 1: Kommandoname config migrate, Namen der Secret-Verweise, Ausnahme für gate-Felder beim Migrieren, Buchführung (migrate done einmal pro Instanz, config migrate in jedem Checkout), Dateiname der Migrationsanleitung;
  • Entwurf 4: Records → SETTINGS_SECTIONS;
  • weitere betroffene Dateien.

Der veraltete Hinweis „Blockiert durch #207“ ist entfernt. kind/build → kind/decision, bis F1-F4 entschieden sind.

**Changelog:** Ein Bau-Versuch hat die Prüfung „Ready to build“ nicht bestanden. Die Abschnitte aus #207 sind flach, die Altformen verschachtelt, und der Body legte die Abbildung nicht fest. Neu im Body ist der Abschnitt „Offene Fragen“ F1-F4, jeweils mit Vorschlag: - F1: Abschnitte flach machen; - F2: Stufen der restlichen Tracker-Felder, `upload.*` als `gate`; - F3: `WIKITOOL_TASKS_CONFIG`, Profile und Live-Suite; - F4: Telemetrie-Hook bei verbliebener Altdatei. Ergänzt sind außerdem: - Entwurf 1: Kommandoname `config migrate`, Namen der Secret-Verweise, Ausnahme für `gate`-Felder beim Migrieren, Buchführung (`migrate done` einmal pro Instanz, `config migrate` in jedem Checkout), Dateiname der Migrationsanleitung; - Entwurf 4: Records → `SETTINGS_SECTIONS`; - weitere betroffene Dateien. Der veraltete Hinweis „Blockiert durch #207“ ist entfernt. `kind/build` → `kind/decision`, bis F1-F4 entschieden sind.
torben added kind/build and removed kind/decision labels 2026-10-10 20:46:17 +00:00
Author
Owner

Changelog: Die Fragen F1-F5 sind entschieden (2026-10-10). F1-F4 wie vorgeschlagen, sie stehen als Entscheidungen 5-8 im Body. F5 ist Entscheidung 9: Der Migrationsschritt ist wikitool config migrate, die Varianten migrate settings und migrate run sind verworfen.

Neu sind Kriterien für:

  • die Idempotenz von config migrate;
  • gate-Felder in config set;
  • die Prüfung der Varianten von Super Productivity im Adapter;
  • Profile über WIKITOOL_TASKS_CONFIG;
  • den stillen Telemetrie-Hook.

migrate-corpus.md steht jetzt in den betroffenen Dateien. kind/decision → kind/build.

**Changelog:** Die Fragen F1-F5 sind entschieden (2026-10-10). F1-F4 wie vorgeschlagen, sie stehen als Entscheidungen 5-8 im Body. F5 ist Entscheidung 9: Der Migrationsschritt ist `wikitool config migrate`, die Varianten `migrate settings` und `migrate run` sind verworfen. Neu sind Kriterien für: - die Idempotenz von `config migrate`; - `gate`-Felder in `config set`; - die Prüfung der Varianten von Super Productivity im Adapter; - Profile über `WIKITOOL_TASKS_CONFIG`; - den stillen Telemetrie-Hook. `migrate-corpus.md` steht jetzt in den betroffenen Dateien. `kind/decision` → `kind/build`.
Author
Owner

Bau-Sitzung abgeschlossen: Die vier Einzeldateien .wikitool-remotes/-telemetry/-upload/-tasks.json sind in die drei Stufen umgezogen (Abschnitte remotes, telemetry, upload, tasks, superproductivity, caldav), neues Kommando wikitool config migrate mit Rollback, Migrationsanleitung instructions/migrations/10.0.0-settings-tiers.md. Ein Rest einer Altdatei endet mit exit 42, doctor meldet FAIL, der Telemetrie-Hook bleibt stumm. Doku durchgezogen (Referenz, How-tos, Gates, Setup, Live-Tracker-Profile).

Version 10.0.0-beta.2, letzter Commit 7c8e9ce, CI-Lauf 655 grün. Auf dem Weg dorthin drei rote Läufe, alle behoben: fehlender Import in test_tracker_live.py (649/651, d09247d), fehlender Bump für diese Testkorrektur (652, 6a89a92), und ein Link aus der Referenz auf das nicht ausgelieferte tracker-testing.md (653, 7c8e9ce).

Offen für /stack-close: Die kb/-Seiten kb/entities/tools/wikitool.md und kb/concepts/workflows/Publish-Remote Gate.md nennen womöglich noch die Altdateien und brauchen wiki-manage.

Bau-Sitzung abgeschlossen: Die vier Einzeldateien `.wikitool-remotes/-telemetry/-upload/-tasks.json` sind in die drei Stufen umgezogen (Abschnitte `remotes`, `telemetry`, `upload`, `tasks`, `superproductivity`, `caldav`), neues Kommando `wikitool config migrate` mit Rollback, Migrationsanleitung `instructions/migrations/10.0.0-settings-tiers.md`. Ein Rest einer Altdatei endet mit exit 42, `doctor` meldet FAIL, der Telemetrie-Hook bleibt stumm. Doku durchgezogen (Referenz, How-tos, Gates, Setup, Live-Tracker-Profile). Version `10.0.0-beta.2`, letzter Commit `7c8e9ce`, CI-Lauf 655 grün. Auf dem Weg dorthin drei rote Läufe, alle behoben: fehlender Import in `test_tracker_live.py` (649/651, `d09247d`), fehlender Bump für diese Testkorrektur (652, `6a89a92`), und ein Link aus der Referenz auf das nicht ausgelieferte `tracker-testing.md` (653, `7c8e9ce`). Offen für `/stack-close`: Die `kb/`-Seiten `kb/entities/tools/wikitool.md` und `kb/concepts/workflows/Publish-Remote Gate.md` nennen womöglich noch die Altdateien und brauchen `wiki-manage`.
Author
Owner

Changelog: Abschluss (2026-10-11). Der Body ist im Endstand: Altzustand heißt „bis 9.x“ statt „heute“, #198 ist als gegenstandslos vermerkt, die verbliebenen Ignore-Einträge sind als bewusst stehend markiert (kein Folgepaket angelegt). Bei der Prüfung auf veraltete Dokumente war docs/how-to/update-an-instance.md veraltet: Sie kannte nur Migrationen, die einmal pro Instanz laufen. Nachgezogen in 298b514, CI-Lauf 656 grün. Die kb/-Stellen aus dem Bau-Kommentar sind datierte Verlaufseinträge und bleiben unverändert.

**Changelog:** Abschluss (2026-10-11). Der Body ist im Endstand: Altzustand heißt „bis 9.x“ statt „heute“, #198 ist als gegenstandslos vermerkt, die verbliebenen Ignore-Einträge sind als bewusst stehend markiert (kein Folgepaket angelegt). Bei der Prüfung auf veraltete Dokumente war `docs/how-to/update-an-instance.md` veraltet: Sie kannte nur Migrationen, die einmal pro Instanz laufen. Nachgezogen in `298b514`, CI-Lauf 656 grün. Die `kb/`-Stellen aus dem Bau-Kommentar sind datierte Verlaufseinträge und bleiben unverändert.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#208