From b8ed8bd61066700ef94419946141647b1da757b6 Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Sat, 26 Sep 2026 22:31:18 +0200 Subject: [PATCH] fix: kb page references by title, not by moved path; Iteration and Cost Limits cites existing sections (#147 follow-up) gates.md named kb/concepts/.md for two pages that live under kb/concepts/workflows/; run_budget.py carried the same stale path. The concept page pointed at AGENTS.md sections that do not exist, the same defect #147 fixed in the refusal messages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2 Files changed: - CHANGES.md - VERSION - instructions/gates.md - kb/concepts/INDEX.md - kb/concepts/workflows/Iteration and Cost Limits.md - kb/index.md - kb/log.md - tools/chemenu/commands/run_budget.py --- CHANGES.md | 13 ++++++++++++- VERSION | 2 +- instructions/gates.md | 4 ++-- kb/concepts/INDEX.md | 2 +- kb/concepts/workflows/Iteration and Cost Limits.md | 4 ++-- kb/index.md | 2 +- kb/log.md | 6 ++++++ tools/chemenu/commands/run_budget.py | 3 ++- 8 files changed, 27 insertions(+), 9 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 02c7e0c..d8d3a03 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse. --- -## 7.1.0-beta.27 - 2026-09-26 - Budget gate and loop-breaker refusals exit without a traceback +## 7.1.0-beta.28 - 2026-09-26 - gates.md and a run_budget comment name kb pages by title, not by a path that moved **Author:** Torben Nehmer @@ -96,8 +96,19 @@ concern - readable here, never shipped as something to parse. - log append: unreadable --body-file is an ERROR line, not a traceback - Command records: three more mismatches from #142 aligned to code - docs contract: the merged-stream test pins its own ON FAILURE line +- gates.md and a run_budget comment name kb pages by title, not by a path that moved <!-- /wikitool:bumps --> +### gates.md and a run_budget comment name kb pages by title, not by a path that moved + +`instructions/gates.md` pointed at `kb/concepts/Mass-Update Gate.md` and +`kb/concepts/Iteration and Cost Limits.md`, and a comment in `run_budget.py` at the second - both +pages live under `kb/concepts/workflows/`, where `types/concept.md` places a workflow concept. A +page's title is its only stable identifier, and its directory is whatever the type-spec computes, +so the three references now name the page by title and no longer carry a path. The comment also +says why the page still quotes the old 15-25 band: deliberately, as a sourced claim about the +field, next to the band measured here. Text only. + ### Budget gate and loop-breaker refusals exit without a traceback `cli.main()` calls `run_budget.record_and_check()` before Typer ever dispatches to a subcommand, diff --git a/VERSION b/VERSION index 7ce7ad0..9640530 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -7.1.0-beta.27 +7.1.0-beta.28 diff --git a/instructions/gates.md b/instructions/gates.md index 9fcd755..60a0219 100644 --- a/instructions/gates.md +++ b/instructions/gates.md @@ -74,7 +74,7 @@ Not a gate you may widen: the prefix list is a constant in the tool. `--path <di scopes a large change into reviewable batches, which is a legitimate alternative to one big clearance. -Background: [[Mass-Update Gate]] (`kb/concepts/Mass-Update Gate.md`). +Background: the [[Mass-Update Gate]] concept page in `kb/`. ### Publish-Remote Gate @@ -215,7 +215,7 @@ never in response to a gate refusal.** The plan is the human approval the gate w have to ask for; a refusal means that approval has not been given yet. If you are tempted to re-export the variable after an `ERROR` line, that is the gate working. -Background: [[Iteration and Cost Limits]] (`kb/concepts/Iteration and Cost Limits.md`). +Background: the [[Iteration and Cost Limits]] concept page in `kb/`. ## Scope diff --git a/kb/concepts/INDEX.md b/kb/concepts/INDEX.md index d5e6cf2..9a3275e 100644 --- a/kb/concepts/INDEX.md +++ b/kb/concepts/INDEX.md @@ -18,7 +18,7 @@ | [[Event-Driven Automation]] | workflow | Muster, das automatische Auslöser an Wiki-Lebenszyklusereignisse hängt, um manuellen Pflegeaufwand und das Risiko der Verwahrlosung zu senken. | 2026-08-29 | | [[Hooks]] | workflow | Mechanismus von Event-Listenern, der bei Wiki-Lebenszyklusereignissen wie Quellen-Ingest, Seitenänderung und Sitzungsende automatisch Aktionen auslöst. | 2026-08-29 | | [[Index Scaling]] | workflow | Skalierungsregeln für Indexseiten: Tabellenabschnitte ab 50 Einträgen teilen, ab 200 Seiten _meta/topic-map.md anlegen | 2026-08-29 | -| [[Iteration and Cost Limits]] | workflow | Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session, Loop-Breaker bei 3 identischen Wiederholungen, Slot-Erstattung, ein gemessenes Kalibrierungsband, und Retrieval sowie der MCP-Leseserver bleiben ausgenommen | 2026-09-02 | +| [[Iteration and Cost Limits]] | workflow | Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session, Loop-Breaker bei 3 identischen Wiederholungen, Slot-Erstattung, ein gemessenes Kalibrierungsband, und Retrieval sowie der MCP-Leseserver bleiben ausgenommen | 2026-09-26 | | [[KB Migration]] | workflow | Migration des KB-Inhalts entlang einer geordneten Versionskette; abgegrenzt gegen offene Instanz-Aktionen, die in den doctor-Check gehoeren statt in die Kette | 2026-08-31 | | [[Knowledge Compounding]] | workflow | Effekt, bei dem Wissen im Wiki an Wert gewinnt, weil jede neue Quelle an bestehende, untereinander verwiesene Seiten anknüpft und sie ergänzt. | 2026-08-29 | | [[Lint Workflow]] | workflow | Deterministischer Health-Check rund um wikitool lint; seit 1.7.2 maskiert es Code vor dem Notation-Match und zaehlt Zitat-Bloecke statt Zeilen | 2026-09-01 | diff --git a/kb/concepts/workflows/Iteration and Cost Limits.md b/kb/concepts/workflows/Iteration and Cost Limits.md index 0a16769..230a288 100644 --- a/kb/concepts/workflows/Iteration and Cost Limits.md +++ b/kb/concepts/workflows/Iteration and Cost Limits.md @@ -3,7 +3,7 @@ type: types/concept.md concept_type: workflow tags: [gate, safety, iteration-budget, loop-breaker] created: 2026-08-07 -modified: 2026-09-02 +modified: 2026-09-26 related: - compares-with: Mass-Update Gate - see-also: Anti-Cramming Heuristic @@ -35,7 +35,7 @@ Eine hart in Code durchgesetzte Obergrenze für die Anzahl der Tool-Aufrufe, die - **Erstattung bei abgelehntem Aufruf (2026-08-31):** Das Budget soll Iteration zählen, nicht Reibung. Die Erstattung ist deshalb nicht auf den Exit-Code 1 gekeyt - das hätte `lint --fail-on-error` gratis gemacht, sobald es etwas findet -, sondern auf `_util.fail()`. `fail()` heißt: der Befehl hat abgelehnt, ein Argument zurückgewiesen oder als lesender Check Befunde gemeldet; es ist nichts passiert, also wird der Slot zurückgegeben. Ein Befehl, der seine Arbeit getan hat und danach ein Nicht-Null-Ergebnis meldet, wirft `typer.Exit(1)` direkt und bleibt gezählt. `record_and_check()` meldet zurück, ob es belastet hat, und `cli._run_traced` ruft im `finally`-Block `run_budget.refund()`. Der Aufruf bleibt in `recent`, damit der Loop-Breaker ihn weiterhin sieht - für eine wiederholt kaputte Invokation ist er das richtige Instrument, nicht der Zähler.[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31] - **Verworfene Alternative:** die Schreibstellen zu markieren (35 Stellen in 15 Dateien), um die Erstattung auf „es wurde nichts geschrieben" zu keyen. Das ist fail-open: eine neue Schreibstelle, die den Marker vergisst, schwächt still ein Gate.[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31] - **Obergrenze 30 → 60 (2026-08-31):** Das Kalibrierungsband (5-15 Aufrufe einfach, 15-25 komplex) blieb unangetastet, weil es die Arbeit beschreibt. Die Obergrenze beschrieb nichts und lag so dicht am Band, dass der Overhead eines realen Ingests sie allein erreichte. Der Loop-Breaker wurde bewusst **nicht** mitverdoppelt: er ist ein Detektor für drei identische Aufrufe und kein Budget, und eine Verdopplung ließe einen festgefahrenen Agenten doppelt so lange kreisen.[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31] Das Band selbst wurde noch am selben Tag in `1.5.0` an realen Läufen nachgemessen - siehe den gemessenen Punkt oben.[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31] -- **Eskalation, nicht stilles Versagen:** Ein ausgelöstes Gate ist nicht flüchtig - das Wiederholen mit denselben Argumenten schlägt absichtlich identisch fehl. Die richtige Reaktion ist, zu stoppen, Fortschritt und Blockierer dem Benutzer zusammenzufassen und auf Anweisungen zu warten (siehe AGENTS.md-Abschnitte „Tool Error Contracts" und „Iteration and Cost Limits"). +- **Eskalation, nicht stilles Versagen:** Ein ausgelöstes Gate ist nicht flüchtig - das Wiederholen mit denselben Argumenten schlägt absichtlich identisch fehl. Die richtige Reaktion ist, zu stoppen, Fortschritt und Blockierer dem Benutzer zusammenzufassen und auf Anweisungen zu warten (siehe AGENTS.md-Abschnitt „Tool error contract" und `instructions/gates.md`, Abschnitt „Iteration Budget Gate and loop-breaker"). ## Beispiele diff --git a/kb/index.md b/kb/index.md index 96b0acb..6aeec0b 100644 --- a/kb/index.md +++ b/kb/index.md @@ -19,7 +19,7 @@ The page tables live in a generated `INDEX.md` inside each collection, linked be - **Entities:** 72 - **Gtd:** 0 - **Sources:** 29 -- **Last Updated:** 2026-09-19 +- **Last Updated:** 2026-09-26 --- diff --git a/kb/log.md b/kb/log.md index 5ef3f57..70d563c 100644 --- a/kb/log.md +++ b/kb/log.md @@ -215,3 +215,9 @@ Korpusmigration zu #86/#60: confidence/confidence_base aus allen 152 betroffenen Die Kerndaten-Zeile "Architektur" nannte noch `wiki/` als Wissensschicht; das Verzeichnis heisst seit der Umbenennung am 2026-08-21 `kb/`. Nur der Pfad wurde nachgezogen - "Dreilagig" bleibt stehen, weil es sich mit [[Three-Layer Architecture]] deckt, wo `reports/` als vierte Phase neben den drei Schichten gefuehrt wird. Teil eines Stack-Durchgangs, der dieselbe veraltete Zeichenkette an 27 Stellen unter tools/ und types/ beseitigt hat. --- + +## [2026-09-26] update | Iteration and Cost Limits + +Verweis im letzten Kernpunkt auf die tatsächlich existierenden Abschnitte korrigiert: AGENTS.md § Tool error contract und instructions/gates.md § Iteration Budget Gate and loop-breaker statt der nicht existierenden AGENTS.md-Abschnitte „Tool Error Contracts“ und „Iteration and Cost Limits“. Keine inhaltliche Aussage geändert. + +--- diff --git a/tools/chemenu/commands/run_budget.py b/tools/chemenu/commands/run_budget.py index 060b04a..068e23e 100644 --- a/tools/chemenu/commands/run_budget.py +++ b/tools/chemenu/commands/run_budget.py @@ -43,7 +43,8 @@ LOCK_FILE = STATE_DIR / "budget.lock" # a simple task, ~20-35 for a complex multi-tool workflow such as an ingest. # # The upper band used to read 15-25, taken from an industry rule of thumb (see -# kb/concepts/Iteration and Cost Limits.md, which still cites it as such). Four +# the "Iteration and Cost Limits" concept page in kb/, which still cites it as +# such - deliberately, as a sourced claim about the field). Four # consecutive real ingests measured 24, 26, 29 and 30 calls - every one of them # at or above the old band's ceiling while doing nothing unusual. A guideline # that the normal case exceeds is not a guideline; it teaches an agent that the