Referenztiefe: Anthropics "one level deep" gegen instructions/CONTRACT.md § Frontload entscheiden #72

Closed
opened 2026-09-09 09:00:39 +00:00 by torben · 1 comment
Owner

Entscheidung: Weg 2 - die Regel gilt skill-gebuendeltem Material

Vom Operator am 2026-09-09 entschieden, umgesetzt in 663b1c0, Version 4.8.0-beta.10.

Anthropics "one level deep" gilt in diesem Repo fuer Dateien im Skill-Verzeichnis neben der SKILL.md. Verweise auf repo-weite Contracts sind eine eigene Kategorie: die zugrundeliegende Nachlade-Mechanik greift dort ebenso, die Vorschrift ist fuer diesen Fall aber nicht belegt. Keine Datei wurde umgebaut; die Position steht jetzt schriftlich in instructions/CONTRACT.md § "Writing an instruction" im Unterabschnitt "Reference depth: bundled files, not repo-wide contracts".

Der Text unterscheidet ausdruecklich die beiden Haelften:

  • "The mechanic is real and directory-independent." Ein Contract auf dem zweiten Hop kann genauso angelesen statt gelesen werden. Nichts am Pfad macht ihn sicher.
  • "The rule is not." Die Reichweite weiter zu lesen, als die Quelle sie angibt, hiesse einer Quelle eine Regel zuzuschreiben, die sie nicht traegt.

Statt der Regel bleibt eine billigere Auflage: ein Link sagt, was der Schritt aus der Datei braucht. Ein blosses "read X first" macht einen Teil-Read unbemerkbar; wird benannt, was zu entnehmen ist (das Feld, der Abschnitt, die Entscheidung), bleibt der Schritt auch bei kurzem Read entscheidbar. wiki-ingest Schritt 7 ist die Form, auf die der Contract verweist.

Neuer Beleg fuer die Reichweitenfrage

In der Umsetzungssitzung gefunden, keinem der Vorgaenger-Issues bekannt: der vendorierte commonplace/kb/work/skill-creator-distillation/sources/codex-skill-creator/SKILL.md:205-221 zeigt die Regel in ihrem Herkunftskontext. Die Beispiele sind DOCX-JS.md, REDLINING.md, OOXML.md - alle im Skill-Buendel. Das ist direkter Textbeleg fuer die These, nicht nur ein Umkehrschluss aus dem Schweigen der Doku.

Dieselbe Stelle traegt uebrigens die Minderungsmassnahme, um die es in #73 geht: "For files longer than 100 lines, include a table of contents at the top so Codex can see the full scope when previewing."

Gegenposition, mitprotokolliert

commonplace/kb/instructions/COLLECTION.md loest dieselbe Spannung strenger: "Links are exceptional in this collection. A procedure must execute from its own text; an executing agent should not follow outbound links to complete the task." Das steht als Kontrast im Contract, mit der Begruendung, warum es hier nicht traegt: dort teilen die Prozeduren keinen Contract, hier tun sie es, und Invariante 8 schlaegt das Preview-Risiko.

Warum das keine Fleissaufgabe war

Die Regel liess sich nicht einfach anwenden, weil sie mit zwei eigenen Festlegungen kollidiert:

  1. instructions/CONTRACT.md § "Frontload" verlangt die entgegengesetzte Haltung: "Self-contained enough for an agent with no prior context: define terms inline, do not assume other documents are loaded."
  2. AGENTS.md Invariante 8 ("one rule, one place") ist der Grund, warum kb/CONTRACT.md, instructions/gates.md und tools/CONTRACT.md von mehreren Skills geteilt statt in jedes SKILL.md kopiert werden. Genau diese geteilten Contracts sind die Ebene-1-Knoten, die weiterverlinken.

Der Contract loest das jetzt explizit: § Frontload verlangt, dass ein Schritt ohne Vorkontext entscheidbar ist, nicht dass jede Regel, der er folgt, an ihm wiederholt wird.

Messung der Ketten (2026-09-09, nur Markdown-Links), unveraendert gueltig - sie war der Anlass, nicht der Massstab:

Skill Ebene 1 neue Ziele auf Ebene 2
wiki-ingest 10 13, ueber 8 der 10
wiki-lint 4 12, davon 9 allein ueber tools/CONTRACT.md
wiki-manage 6 12
wiki-query 2 5
wiki-status 0 -

Testbarkeit: geprueft, Ergebnis "nicht messbar"

Auf Wunsch des Operators wurde vor der Festschreibung im Eval-Aufbau nachgesehen, ob sich die behauptete Mechanik ueberhaupt beobachten laesst. Ergebnis: nein, nicht mit vertretbarem Aufwand.

  • Der Tool-Call-Teil (head -100, Read(limit=…)) waere grundsaetzlich sichtbar: tools/trace_ingest.py:90-110, 176-179 normalisiert tool_input mitsamt Argumenten in die Trace. Aber die fuenf L2-Trajectory-Regeln lesen ausschliesslich wikitool.call, gate.refused, gate.cleared, publish.commit, prompt.submitted (tools/chemenu/evals/trajectory.py:96-99, 128-134, 173-181, 217-230, 249-252) - kein Scorer sieht je tool.pre/tool.post an. Und auf Claude Code, dem primaeren Harness, ist ueberhaupt kein Tool-Hook verdrahtet: .claude/settings.json haengt nur UserPromptSubmit → prompt.submitted ein. Verdrahtet ist das nur bei Copilot CLI (.github/hooks/wiki-trace.json) und Vibe (.vibe/hooks.toml).
  • Der Kontext-Teil ("resulting in incomplete information") ist strukturell nicht messbar. Kein Event sagt, welche Bytes im Modellkontext standen; die Trace kennt Tool-Calls, keine Kontextfenster. instructions.loaded existiert im Vokabular (tools/chemenu/telemetry/schema.py:53) und ist nirgends verdrahtet.
  • Der Kausalzusammenhang "Ebene 2 ⇒ unvollstaendig gelesen" braucht N Laeufe desselben Tasks in zwei Armen, also den L3-Agent-Runner. Der ist entworfen und nicht gebaut (EVALS.md:430, 432-455); Blocker sind fehlende Provider-Credentials. EVALS.md:235-237 verlangt ohnehin Pass-Raten mit Varianz statt Einzellaeufen.

Es gaebe einen indirekten Proxy, sauberer als erwartet: instructions/link-taxonomy.md ist von keiner SKILL.md direkt verlinkt (Referenzen nur ueber kb/CONTRACT.md:200, kb/CONVENTIONS.md:95, die vier COLLECTION.md und das Migrationsdokument) und aus jedem Skill damit echte Ebene 2. Ihr Inhalt ist ein Enum, dessen Einhaltung hart geprueft wird: unauthorised_labels und unlabelled_edges stehen in HARD_ERROR_KEYS (tools/chemenu/lint_core.py:856-857) und werden von L1 gelesen (evals/scorecard.py:42). Ein Prompt wie "verknuepfe A und B ueber die passende Beziehung", ohne Nennung des Katalogs, ueber N ≥ 10 Laeufe, gaebe ein hartes Orakel ohne Judge.

Was das bewiese: dass ein nicht autorisiertes Label geschrieben wurde. Was nicht: dass die Referenztiefe die Ursache war - konfundiert mit Halluzination trotz vollstaendigem Read, mit Kompaktierung, mit der Modell-/Effort-Wahl und damit, dass der Katalog dem Modell aus dem Korpus selbst gelaeufig sein kann. Kausalitaet braucht den A/B-Arm und damit wieder den fehlenden Runner.

Dazu eine stehende Regel des Repos: neue Trajectory-Regeln erst, wenn eine reale Trace einen realen Fehlschlag zeigt (tools/chemenu/evals/trajectory.py:9-14, EVALS.md:324-328). Eine aus der Vendor-Doku abgeleitete Regel waere genau der dort beschriebene Fehlermodus.

Kosten/Nutzen: nicht gekauft. Der billige Teil misst die Haelfte der Behauptung und braucht auf dem primaeren Harness erst einen Hook-Ausbau; der teure Teil setzt Infrastruktur voraus, die es nicht gibt. Da die Entscheidung ohnehin gefallen war, waere der einzige realistische Gewinn eine Widerlegung gewesen - fuer die genau die fehlende Infrastruktur noetig ist. Der Contract sagt das jetzt ausdruecklich: "All of the above is a judgment, not a measurement", mit der Begruendung, warum es die zweite nicht sein kann.

Nebenfund, als eigenes Issue abgelegt: dass L2 auf Claude Code gar keine Tool-Calls zu sehen bekommt, ist unabhaengig von dieser Frage ein Loch im Eval-Aufbau - siehe #82.

Akzeptanzkriterien

  • Es ist entschieden und schriftlich festgehalten, ob Anthropics "one level deep" in diesem Repo fuer Verweise auf Dateien ausserhalb des Skill-Verzeichnisses gilt.
  • Die Festlegung steht an genau einer Stelle: instructions/CONTRACT.md § "Writing an instruction", Unterabschnitt "Reference depth".
  • Der Text unterscheidet erkennbar zwischen "Anthropic schreibt das vor" und "die Begruendung uebertraegt sich, ist aber von Anthropic nicht abgedeckt" - als zwei benannte Bullets.
  • Entfaellt: Weg 2 gewaehlt, also keine Versionsteil-Frage nach instructions/dev/version-parts.md. Die Aenderung selbst ist PATCH, gegen den Drop-in-Test geprueft (Kopieren von instructions/, nichts umbenannt oder entfernt, Rueckweg funktioniert).
  • tools/wikitool instructions verify laeuft ohne neue Findings. Dazu docs verify und pytest (1076 passed).

Auswirkung auf andere Issues

Weg 2 gewaehlt, also kein zusaetzlicher Link in den fuenf SKILL.md. Der Umfang von #70, #74, #75, #78 bleibt unberuehrt.

#73 (Inhaltsverzeichnisse) ist damit entsperrt und bekommt aus diesem Issue zwei Dinge mit: die Blockade ist weg, und der Beleg oben (codex-skill-creator/SKILL.md:222) nennt genau die 100-Zeilen-Schwelle und ihre Begruendung ("so Codex can see the full scope when previewing") - was das TOC zur Minderungsmassnahme fuer dieselbe Mechanik macht statt zu einer Lesbarkeitsfrage.

Nicht Gegenstand

Das fehlende Inhaltsverzeichnis (#73) und der fehlende Checklisten-Block in wiki-ingest (#74). Die Nachruestung der "ein Link sagt, was der Schritt braucht"-Auflage in den vier uebrigen Skills ist ebenfalls nicht Teil dieser Aenderung - wiki-ingest Schritt 6 wurde in derselben Sitzung mitgezogen, weil #79 die Datei ohnehin anfasste.

Herkunft

Analyse aus #65 (Fund 4), Sitzung 2026-09-09. Primaerquelle im Volltext geprueft; Reichweitenfrage zusaetzlich durch eine Operator-Recherche und - in der Umsetzungssitzung - durch den vendorierten codex-skill-creator bestaetigt. Kettenmessung per Skript ueber alle fuenf Skills. Eval-Testbarkeit durch einen read-only Subagenten geprueft.

## Entscheidung: Weg 2 - die Regel gilt skill-gebuendeltem Material Vom Operator am 2026-09-09 entschieden, umgesetzt in `663b1c0`, Version `4.8.0-beta.10`. Anthropics "one level deep" gilt in diesem Repo fuer Dateien **im Skill-Verzeichnis** neben der `SKILL.md`. Verweise auf repo-weite Contracts sind eine eigene Kategorie: die zugrundeliegende Nachlade-Mechanik greift dort ebenso, die Vorschrift ist fuer diesen Fall aber nicht belegt. Keine Datei wurde umgebaut; die Position steht jetzt schriftlich in `instructions/CONTRACT.md` § "Writing an instruction" im Unterabschnitt **"Reference depth: bundled files, not repo-wide contracts"**. Der Text unterscheidet ausdruecklich die beiden Haelften: - *"The mechanic is real and directory-independent."* Ein Contract auf dem zweiten Hop kann genauso angelesen statt gelesen werden. Nichts am Pfad macht ihn sicher. - *"The rule is not."* Die Reichweite weiter zu lesen, als die Quelle sie angibt, hiesse einer Quelle eine Regel zuzuschreiben, die sie nicht traegt. Statt der Regel bleibt eine billigere Auflage: **ein Link sagt, was der Schritt aus der Datei braucht.** Ein blosses "read X first" macht einen Teil-Read unbemerkbar; wird benannt, was zu entnehmen ist (das Feld, der Abschnitt, die Entscheidung), bleibt der Schritt auch bei kurzem Read entscheidbar. `wiki-ingest` Schritt 7 ist die Form, auf die der Contract verweist. ### Neuer Beleg fuer die Reichweitenfrage In der Umsetzungssitzung gefunden, keinem der Vorgaenger-Issues bekannt: der vendorierte `commonplace/kb/work/skill-creator-distillation/sources/codex-skill-creator/SKILL.md:205-221` zeigt die Regel in ihrem Herkunftskontext. Die Beispiele sind `DOCX-JS.md`, `REDLINING.md`, `OOXML.md` - alle **im Skill-Buendel**. Das ist direkter Textbeleg fuer die These, nicht nur ein Umkehrschluss aus dem Schweigen der Doku. Dieselbe Stelle traegt uebrigens die Minderungsmassnahme, um die es in #73 geht: "For files longer than 100 lines, include a table of contents at the top so Codex can see the full scope when previewing." ### Gegenposition, mitprotokolliert `commonplace/kb/instructions/COLLECTION.md` loest dieselbe Spannung strenger: "Links are exceptional in this collection. A procedure must execute from its own text; an executing agent should not follow outbound links to complete the task." Das steht als Kontrast im Contract, mit der Begruendung, warum es hier nicht traegt: dort teilen die Prozeduren keinen Contract, hier tun sie es, und Invariante 8 schlaegt das Preview-Risiko. ## Warum das keine Fleissaufgabe war Die Regel liess sich nicht einfach anwenden, weil sie mit zwei eigenen Festlegungen kollidiert: 1. **`instructions/CONTRACT.md` § "Frontload"** verlangt die entgegengesetzte Haltung: "Self-contained enough for an agent with no prior context: define terms inline, do not assume other documents are loaded." 2. **AGENTS.md Invariante 8 ("one rule, one place")** ist der Grund, warum `kb/CONTRACT.md`, `instructions/gates.md` und `tools/CONTRACT.md` von mehreren Skills geteilt statt in jedes `SKILL.md` kopiert werden. Genau diese geteilten Contracts sind die Ebene-1-Knoten, die weiterverlinken. Der Contract loest das jetzt explizit: § Frontload verlangt, dass ein **Schritt** ohne Vorkontext entscheidbar ist, nicht dass jede Regel, der er folgt, an ihm wiederholt wird. Messung der Ketten (2026-09-09, nur Markdown-Links), unveraendert gueltig - sie war der Anlass, nicht der Massstab: | Skill | Ebene 1 | neue Ziele auf Ebene 2 | |---|---|---| | `wiki-ingest` | 10 | 13, ueber 8 der 10 | | `wiki-lint` | 4 | 12, davon 9 allein ueber `tools/CONTRACT.md` | | `wiki-manage` | 6 | 12 | | `wiki-query` | 2 | 5 | | `wiki-status` | 0 | - | ## Testbarkeit: geprueft, Ergebnis "nicht messbar" Auf Wunsch des Operators wurde vor der Festschreibung im Eval-Aufbau nachgesehen, ob sich die behauptete Mechanik ueberhaupt beobachten laesst. Ergebnis: **nein, nicht mit vertretbarem Aufwand.** - **Der Tool-Call-Teil** (`head -100`, `Read(limit=…)`) waere grundsaetzlich sichtbar: `tools/trace_ingest.py:90-110, 176-179` normalisiert `tool_input` mitsamt Argumenten in die Trace. Aber die fuenf L2-Trajectory-Regeln lesen ausschliesslich `wikitool.call`, `gate.refused`, `gate.cleared`, `publish.commit`, `prompt.submitted` (`tools/chemenu/evals/trajectory.py:96-99, 128-134, 173-181, 217-230, 249-252`) - kein Scorer sieht je `tool.pre`/`tool.post` an. Und auf Claude Code, dem primaeren Harness, ist ueberhaupt kein Tool-Hook verdrahtet: `.claude/settings.json` haengt nur `UserPromptSubmit → prompt.submitted` ein. Verdrahtet ist das nur bei Copilot CLI (`.github/hooks/wiki-trace.json`) und Vibe (`.vibe/hooks.toml`). - **Der Kontext-Teil** ("resulting in incomplete information") ist **strukturell** nicht messbar. Kein Event sagt, welche Bytes im Modellkontext standen; die Trace kennt Tool-Calls, keine Kontextfenster. `instructions.loaded` existiert im Vokabular (`tools/chemenu/telemetry/schema.py:53`) und ist nirgends verdrahtet. - **Der Kausalzusammenhang** "Ebene 2 ⇒ unvollstaendig gelesen" braucht N Laeufe desselben Tasks in zwei Armen, also den L3-Agent-Runner. Der ist entworfen und **nicht gebaut** (`EVALS.md:430, 432-455`); Blocker sind fehlende Provider-Credentials. `EVALS.md:235-237` verlangt ohnehin Pass-Raten mit Varianz statt Einzellaeufen. **Es gaebe einen indirekten Proxy**, sauberer als erwartet: `instructions/link-taxonomy.md` ist von keiner `SKILL.md` direkt verlinkt (Referenzen nur ueber `kb/CONTRACT.md:200`, `kb/CONVENTIONS.md:95`, die vier `COLLECTION.md` und das Migrationsdokument) und aus jedem Skill damit echte Ebene 2. Ihr Inhalt ist ein Enum, dessen Einhaltung hart geprueft wird: `unauthorised_labels` und `unlabelled_edges` stehen in `HARD_ERROR_KEYS` (`tools/chemenu/lint_core.py:856-857`) und werden von L1 gelesen (`evals/scorecard.py:42`). Ein Prompt wie "verknuepfe A und B ueber die passende Beziehung", ohne Nennung des Katalogs, ueber N ≥ 10 Laeufe, gaebe ein hartes Orakel ohne Judge. **Was das bewiese:** dass ein nicht autorisiertes Label geschrieben wurde. **Was nicht:** dass die Referenztiefe die Ursache war - konfundiert mit Halluzination trotz vollstaendigem Read, mit Kompaktierung, mit der Modell-/Effort-Wahl und damit, dass der Katalog dem Modell aus dem Korpus selbst gelaeufig sein kann. Kausalitaet braucht den A/B-Arm und damit wieder den fehlenden Runner. **Dazu eine stehende Regel des Repos:** neue Trajectory-Regeln erst, wenn eine reale Trace einen realen Fehlschlag zeigt (`tools/chemenu/evals/trajectory.py:9-14`, `EVALS.md:324-328`). Eine aus der Vendor-Doku abgeleitete Regel waere genau der dort beschriebene Fehlermodus. **Kosten/Nutzen:** nicht gekauft. Der billige Teil misst die Haelfte der Behauptung und braucht auf dem primaeren Harness erst einen Hook-Ausbau; der teure Teil setzt Infrastruktur voraus, die es nicht gibt. Da die Entscheidung ohnehin gefallen war, waere der einzige realistische Gewinn eine Widerlegung gewesen - fuer die genau die fehlende Infrastruktur noetig ist. Der Contract sagt das jetzt ausdruecklich: "All of the above is a judgment, not a measurement", mit der Begruendung, warum es die zweite nicht sein kann. **Nebenfund, als eigenes Issue abgelegt:** dass L2 auf Claude Code gar keine Tool-Calls zu sehen bekommt, ist unabhaengig von dieser Frage ein Loch im Eval-Aufbau - siehe **#82**. ## Akzeptanzkriterien - [x] Es ist entschieden und schriftlich festgehalten, ob Anthropics "one level deep" in diesem Repo fuer Verweise auf Dateien ausserhalb des Skill-Verzeichnisses gilt. - [x] Die Festlegung steht an genau einer Stelle: `instructions/CONTRACT.md` § "Writing an instruction", Unterabschnitt "Reference depth". - [x] Der Text unterscheidet erkennbar zwischen "Anthropic schreibt das vor" und "die Begruendung uebertraegt sich, ist aber von Anthropic nicht abgedeckt" - als zwei benannte Bullets. - [x] Entfaellt: Weg 2 gewaehlt, also keine Versionsteil-Frage nach `instructions/dev/version-parts.md`. Die Aenderung selbst ist PATCH, gegen den Drop-in-Test geprueft (Kopieren von `instructions/`, nichts umbenannt oder entfernt, Rueckweg funktioniert). - [x] `tools/wikitool instructions verify` laeuft ohne neue Findings. Dazu `docs verify` und `pytest` (1076 passed). ## Auswirkung auf andere Issues Weg 2 gewaehlt, also **kein** zusaetzlicher Link in den fuenf `SKILL.md`. Der Umfang von #70, #74, #75, #78 bleibt unberuehrt. **#73** (Inhaltsverzeichnisse) ist damit entsperrt und bekommt aus diesem Issue zwei Dinge mit: die Blockade ist weg, und der Beleg oben (`codex-skill-creator/SKILL.md:222`) nennt genau die 100-Zeilen-Schwelle und ihre Begruendung ("so Codex can see the full scope when previewing") - was das TOC zur *Minderungsmassnahme fuer dieselbe Mechanik* macht statt zu einer Lesbarkeitsfrage. ## Nicht Gegenstand Das fehlende Inhaltsverzeichnis (#73) und der fehlende Checklisten-Block in `wiki-ingest` (#74). Die Nachruestung der "ein Link sagt, was der Schritt braucht"-Auflage in den vier uebrigen Skills ist ebenfalls nicht Teil dieser Aenderung - `wiki-ingest` Schritt 6 wurde in derselben Sitzung mitgezogen, weil #79 die Datei ohnehin anfasste. ## Herkunft Analyse aus #65 (Fund 4), Sitzung 2026-09-09. Primaerquelle im Volltext geprueft; Reichweitenfrage zusaetzlich durch eine Operator-Recherche und - in der Umsetzungssitzung - durch den vendorierten `codex-skill-creator` bestaetigt. Kettenmessung per Skript ueber alle fuenf Skills. Eval-Testbarkeit durch einen read-only Subagenten geprueft.
torben added the prio/plannedsize/Marea/processkind/decision labels 2026-09-09 09:00:39 +00:00
torben added kind/build and removed kind/decision labels 2026-09-09 14:31:08 +00:00
Author
Owner

Changelog: § "Was zu entscheiden ist" (drei Wege) ist durch die getroffene Entscheidung ersetzt - Weg 2, vom Operator bestaetigt. Neu: der Herkunftsbeleg aus codex-skill-creator/SKILL.md:205-221 (die Regel-Beispiele sind alle im Skill-Buendel), die mitprotokollierte Gegenposition aus commonplace/kb/instructions/COLLECTION.md, und ein vollstaendiger Abschnitt zur Eval-Testbarkeit - auf Wunsch des Operators geprueft, Ergebnis "nicht messbar", mit dem indirekten Proxy und seinen Grenzen. § "Auswirkung auf andere Issues" von Konjunktiv auf Tatsache umgestellt: #70/#74/#75/#78 unberuehrt, #73 entsperrt und um die 100-Zeilen-Schwelle ergaenzt. kind/decisionkind/build. Nebenfund als #82 abgelegt. Umgesetzt in 663b1c0, 4.8.0-beta.10. Geschlossen.

**Changelog:** § "Was zu entscheiden ist" (drei Wege) ist durch die getroffene Entscheidung ersetzt - Weg 2, vom Operator bestaetigt. Neu: der Herkunftsbeleg aus `codex-skill-creator/SKILL.md:205-221` (die Regel-Beispiele sind alle im Skill-Buendel), die mitprotokollierte Gegenposition aus `commonplace/kb/instructions/COLLECTION.md`, und ein vollstaendiger Abschnitt zur Eval-Testbarkeit - auf Wunsch des Operators geprueft, Ergebnis "nicht messbar", mit dem indirekten Proxy und seinen Grenzen. § "Auswirkung auf andere Issues" von Konjunktiv auf Tatsache umgestellt: #70/#74/#75/#78 unberuehrt, #73 entsperrt und um die 100-Zeilen-Schwelle ergaenzt. `kind/decision` → `kind/build`. Nebenfund als #82 abgelegt. Umgesetzt in `663b1c0`, `4.8.0-beta.10`. Geschlossen.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#72