chemenu/kb/concepts/Mass-Update Gate.md

type, concept_type, tags, created, modified, related, sources, confidence, confidence_base, provenance, summary

type	concept_type	tags	created	modified	related	sources	confidence	confidence_base	provenance	summary
types/concept.md	workflow	gate safety mass-update confirmation	2026-08-03	2026-09-01	Content Quality Control wikitool Iteration and Cost Limits Structural Enforcement over Documented Rule Bulk Operations	Source - LLM Improvements Sonnet Analysis Source - LLM Improvements Production Agent Gaps 2026 Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31 Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31 Source - LLM Improvements Codex Analysis	0.88	0.88	sourced	Mass-Update Gate: publish endet mit 42 (Freigabe durch den Menschen noetig) ab 10 gezaehlten Dateien; generierte Dateien und work/ werden committet, aber seit 1.5.0 nicht gezaehlt; freigegeben per --confirm <token>

Mass-Update Gate

Typ: workflow

Definition

Das Mass-Update Gate ist ein Sicherheitsmechanismus, der die Ausführung pausiert und explizite Bestätigung anfordert, bevor mit Vorgängen fortgefahren wird, die eine große Anzahl von Seiten betreffen würden. Dies verhindert versehentliche Massenänderungen und stellt sicher, dass beabsichtigte großflächige Änderungen überprüft werden.

Kernpunkte

• Farzas Regel: „Wenn ein Vorgang ≥10 Seiten ändert, halte an und fordere Bestätigung an"¹

• Zweck: Verhindert versehentliche Massenaktualisierungen, die schwer rückgängig zu machen wären

• Begründung: Ein git push zu origin/main ist die einzige Aktion in diesem System mit echten, irreversiblen externen Auswirkungen - sie ist sofort öffentlich sichtbar (Commit-Verlauf, mögliche CI-Auslöser, andere Clients ziehen) und ein Revert birgt immer noch Risiken. Jede andere wikitool-Schreiboperation ist lokal und billig rückgängig zu machen, daher ist das Gate speziell auf publish begrenzt, nicht auf jeden Befehl.

• Implementiert (2026-08-07): tools/wikitool publish zählt die Dateien, die von git status --porcelain nach dem Staging berührt werden. Unter der Schwelle (Standard 10, --threshold zum Überschreiben) committed und pusht es automatisch, genau wie zuvor - Aufnahme-/Erstellungs-/Update-Vorgänge auf einzelnen Seiten werden nicht beeinflusst und führen nie zu Aufforderungen. Bei oder über der Schwelle wird 1 mit einem Mass-Update Gate-Fehler beendet, der jede geänderte Datei auflistet und weigert sich zu committen oder zu pushen.

• --yes zurückgezogen für einen Clearance-Exit-Code (2026-08-28): Das Gate öffnete sich ursprünglich mit einem --yes-Flag, genehmigt durch einen Menschen, aber vom Agenten eingegeben - also lebte der Genehmigungsdatensatz nur in Konversation, nicht in irgendetwas, das das Tool oder ein späterer Leser überprüfen konnte. Drei Sitzungen zeigten die gleiche Form: publish ausführen, beobachten, wie es sich weigert, --yes erneut ausführen in derselben Wendung, technisch den dokumentierten Befehl befolgen, während kein Mensch die Dateiliste je sah. Der Ersatz hat drei Teile:

  • Ein eigener Exit-Code. Ein ausgelöstes Gate beendet sich mit 42 (EXIT_NEEDS_CLEARANCE), nicht 1 - ein drittes Ergebnis neben Erfolg und Validierungsfehler, bedeutet „ein Mensch muss diese Ausgabe sehen, bevor irgendetwas fortgeht". Ein Agent, ein Hook, eine CI-Aufgabe oder ein Scorer können es alle von „deine Eingabe war falsch, behebe es und versuche es erneut" unterscheiden.
  • Die Prozedur lebt in der Ausgabe, nicht in der Anweisungsschicht. Die Weigerung druckt, was sich ändern würde, jede gezählte Datei und die genaue --confirm <token>-Zeile, die sie veröffentlicht. instructions/gates.md sagt nur „zeige dem Benutzer die Ausgabe und halte an" - ein Rezept, das im Voraus aufgeschrieben ist, ist eines, das ein Agent von Anfang bis Ende ohne einen Menschen durchführen kann, was die drei Vorfälle jeweils aussahen.
  • Der Token bindet Genehmigung an einen Changeset. --confirm nimmt eine Zusammenfassung der gezählten Dateiliste plus des Veröffentlichungsziels, daher macht das Anfassen einer weiteren Datei es ungültig und das Gate fragt wieder mit der neuen Liste. --yes hatte das nie: Es veröffentlichte, was immer im Arbeitsbaum war, wenn es lief, nicht unbedingt was der Mensch sah.

  Was dies NICHT tut, ehrlich gesagt: es beweist nicht, dass ein Mensch irgendetwas eingegeben hat. Der Token sitzt im eigenen Kontext des Agenten, und ein Agent, der das Gate umgehen möchte, kann dies tun. Das ist ein bewusster Kompromiss - ein früheres Design, das tatsächlich unabhängigen Beweis erforderte (ein Ticket von einem zweiten Terminal eingelöst) war korrekt und unbrauchbar, daher bleibt die Durchsetzung hier billig und die Frage „hat ein Mensch es wirklich genehmigt?" wurde auf die Eval-Schicht verschoben, wo clearance-was-asked-for und clearance-ended-the-turn (tools/chemenu/evals/trajectory.py) die ganze Flugbahn statt eines einzelnen Aufrufs sehen können.

• Generierte Dateien zählen nicht mehr mit (1.5.0, 2026-08-31): kb/index.md, kb/log.md, kb/provenance.md und jede INDEX.md werden weiterhin gestaged, committet und gepusht, gehen aber nicht mehr in die Zählung gegen die Schwelle ein - aus demselben Grund wie work/: sie tragen keine Entscheidung. Jede von ihnen ist über index rebuild bzw. sources rebuild-index aus dem Baum reproduzierbar, ihre Freigabe entscheidet also nichts und erzeugt nur die Prüfermüdung, gegen die die Schwelle existiert. Die Bausteine lagen bereits vor: is_generated() in git_publish.py kannte die Liste, GATE_EXEMPT_PREFIXES = ("work/",) und counted_files() boten den Mechanismus; verbunden waren beide nie, is_generated gruppierte nur die Anzeige unter „rebuilt by wikitool - no review needed". Gemessen an drei realen Ingests desselben Tages: 14 Dateien 14 → 9 gezählt, 16 → 9, 11 → 5 - alle drei hätten nicht mehr angehalten. Die Schwelle selbst blieb bei 10, und ein Test hält fest, dass zehn echte Seiten weiterhin auslösen, damit die Ausnahme nicht still zur Abschaltung wird.²

• Zwei Konsequenzen der Ausnahme: Die Weigerungszeile führt beide Gründe getrennt auf („3 under work/ and 5 generated by wikitool committed but not counted"), weil ein Prüfer die Differenz zwischen 14 geänderten und 9 gezählten Dateien sonst für einen Fehler hält - und weil Scratch-Zustand und abgeleitete Ausgabe nicht dasselbe sind. Und der --confirm-Token fasst seither nur noch zusammen, was ein Mensch tatsächlich gelesen hat: eine neu gebaute INDEX.md macht eine erteilte Freigabe nicht mehr ungültig.²

• Das alte Zählverhalten war ungetestet. Alle 67 Gate-Tests liefen grün, bevor die Tests für die Ausnahme geschrieben waren - kein Test hatte je behauptet, dass generierte Dateien mitgezählt werden. Ein Teil der Erklärung, warum es so lange unbemerkt blieb.²

• Agent-Vertrag: Exit 42 beendet die Wendung. Dem Benutzer die Ausgabe des Befehls wörtlich zeigen, einschließlich Dateiliste, und anhalten; die Ausgabe selbst benennt den nächsten Schritt. Siehe AGENTS.md-Abschnitt „Tool error contract" und instructions/gates.md.

• Ursprünglicher Vorschlag war breiter als das Gebaute: Die früheste Analyse-Quelle schlug Bestätigungs-Gates vor jeder riskanten Massenoperation vor - auch vor Massen-Löschungen und Massen-Umklassifizierungen, mit einem konfigurierbaren Schwellenwert.³ Gebaut wurde davon nur der publish-Pfad; ein Lösch- oder Umklassifizierungs-Gate existiert nicht, aus demselben Grund, aus dem das Gate oben auf publish begrenzt bleibt - jeder andere wikitool-Schreibvorgang ist lokal und billig rückgängig zu machen.

Beispiele

• 2026-08-31 - Der Fix für die Gitea-Issues #12 und #13 berührte 21 Dateien. publish endete mit 42, druckte die Aufschlüsselung nach Bereich und die --confirm-Zeile; der Agent gab die vollständige Liste wieder und stoppte, Torben gab frei, der bestätigte Publish erzeugte 40adbb7 mit 593 Einfügungen und 73 Löschungen. Anschließend wurde gegen das Repository geprüft, dass HEAD gleich origin/main ist und VERSION 1.2.0 liest, statt der Erfolgszeile des Werkzeugs zu vertrauen⁴
• 2026-08-31 - Drei gewöhnliche Ingests (Comma Bug, Issue Triage, Auto Mode) blieben nacheinander am Gate stehen, obwohl keiner eine Massenänderung war. Die Beobachtung löste die Ausnahme für generierte Dateien aus; nachgerechnet lagen die drei Changesets danach bei 9, 9 und 5 gezählten Dateien² Vorgänge, die das Gate auslösen:
• wikitool xref link-source --entities E1,E2,E3,E4,E5,E6,E7,E8,E9,E10 (10+ entities), wenn direkt vor einem publish ausgeführt wird, das alle auf einmal bereitstellt
• Massenaufnahme mehrerer Quelldateien auf einmal
• Bulk-Seitenerstellung bei Lint-Fixes (wie die 2026-07-31-Operation, die 36 Seiten erstellte)

Gate-Verhalten (wie in tools/wikitool publish implementiert):

• git status --porcelain zuerst (bevor irgendetwas bereitgestellt wird), um die genaue Anzahl und Liste der geänderten Dateien zu erhalten
• Gezählt werden nur Dateien, die eine Entscheidung tragen: alles unter work/ und alle generierten Dateien sind seit 1.5.0 von der Zählung ausgenommen, werden aber mit committet²
• Wenn Anzahl < Schwelle: Commit und Push sofort, wie immer
• Wenn Anzahl >= Schwelle ohne passendes --confirm <token>: Exit 42, drucke die Anzahlen, das Veröffentlichungsziel, die volle gezählte Dateiliste und die genaue --confirm-Zeile, die es veröffentlicht; nichts wird committet oder gepusht
• Erneutes Ausführen mit diesem Token veröffentlicht normalerweise. Ein falsches, erfundenes oder überholtes Token beendet sich wieder mit 42 mit der aktuellen Liste, statt etwas zu veröffentlichen, das der Benutzer nicht sah

Wann zu verwenden

• Als Sicherheitsprüfung in wikitool CLI-Befehlen
• Für Vorgänge, die viele Seiten ändern oder referenzieren
• Wenn der Benutzer versehentliche Massenänderungen verhindern möchte

Wann NICHT zu verwenden

• Für Vorgänge auf einzelnen Seiten
• Wenn der Benutzer explizit mit --force umgeht
• In automatisierten Skripten, bei denen das Gate den nicht-interaktiven Gebrauch brechen würde

Verwandte Concepts

• Content Quality Control - Qualitätsrahmen, den Massenaktualisierungen bewahren sollten
• wikitool - Das CLI-Tool, das dieses Gate implementieren könnte
• Workflow Orchestration - Koordinierte Vorgänge, die Gates benötigen könnten

Beziehungen

• wird gespiegelt durch: Iteration and Cost Limits
• wendet an: Structural Enforcement over Documented Rule
• grenzt ab gegen: Bulk Operations

Siehe auch

• Source - LLM Improvements Sonnet Analysis
• Iteration and Cost Limits
• Source - LLM Improvements Production Agent Gaps 2026
• Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31
• Structural Enforcement over Documented Rule
• Bulk Operations

Fußnoten

---

1. Source - LLM Improvements Sonnet Analysis ↩︎

2. Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31 ↩︎

3. Source - LLM Improvements Codex Analysis ↩︎

4. Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31 ↩︎