--- title: 'Bestehende Concepts erweitern/präzisieren/korrigieren — Update-Formen operativ schärfen (Story 3.3)' type: 'feature' created: '2026-08-19' status: 'done' review_loop_iteration: 0 baseline_commit: 52f88fdc5f3ea0fe5323412ca3ba8b4a1bdbf549 context: - _bmad-output/implementation-artifacts/epic-3-context.md --- ## Intent **Problem:** Story 3.1 verankerte die Update-Mechanik (Erweitern/Präzisieren/Korrigieren) in `schema/compiler.md` §5.9 als Regeltext, Story 3.2 die Candidate-Erhebung (§3.2). Unoperativ bleibt die **Ausführung je Update-Form** — v. a. das Story-3.3-AC aus FR-6: „der Text wird präzisiert oder korrigiert, **ohne die Struktur zu zerstören**". Der Compiler hat keine deterministische Anleitung, wie Präzisieren (Schärfen einer bestehenden Aussage) von Erweitern (Anfügen) abzugrenzen ist und was die „Struktur" (Frontmatter, bestehende belegte Aussagen, Provenienz-Verkettung) beim Übergriff auf einen bestehenden Absatz schützt. **Approach:** Story 3.3 schärft §5.9 (Revision 2.8): die drei Update-Formen werden **operationell** ausformuliert — je Form ein deterministisch prüfbares **Abgrenzungskriterium** (Welche Form greift wann?), die **Struktur-Erhaltungsregel** (was bleibt unverändert: Frontmatter-Subset, bestehende belegte Aussagen + §5.5-Inline-Verweise, §5.6-Pin) und der Textgenauigkeits-Rahmen (Schärfen an der Aussage, kein Satz-Umbau, kein Neuschreiben ohne Ersetzungsbeleg). Zusätzlich eine **re-executierbare Sandbox** (`sandbox-3-3/run-sandbox.sh`, Muster Story-3.1): Demonstriert einen echten Update-Run mit committeter Neuevidenz in allen drei Formen + No-Op und prüft die Erhaltungs-Invariante (§5.9 Pkt. 5) als harte Assertion. Keine Inhalts-Mutation des realen Bundles (kein neues `raw/`-Material, AD-3); kein neues Prädikat, kein Vertrag-/Validator-/`raw/`-Change; kein Standalone (D-3). ## Boundaries & Constraints **Always:** - **Instruktions-Story (D-3):** Schärfung ausschließlich in `schema/compiler.md` §5.9 als deterministischer Text. Kein executable, kein Standalone, keine neue §7-Invaliditätsklasse, kein Change an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/` (AD-3). - **Struktur-Erhaltungs-Invariante (Kern, FR-6/AC-2):** Update tastet die Struktur nicht an — (1) Frontmatter bleibt Subset-konform (nur `sources`-Zuwachs um echten neuen Beleg + `generated.at`-Bump zulässig); (2) bestehende belegte Aussagen werden nicht umgeschrieben ohne Präzisieren an ihr selbst bzw. Korrigieren mit Ersetzungsbeleg (§5.5-Inline-Verweise bleiben gültig soweit Beleg Body-Bestand); (3) gepinnte Linkform unverändert, keine neuen Links außer bei echten Beziehungen (§5.9 Pkt. 3). - **Determinismus (AD-17h/A0-19):** Form-Wahl folgt aus der committeten Evidenz; gleicher Git-State + gleiche Eingabemenge → identischer Update-Vorgang. Abgrenzungsregeln textuell prüfbar (neue Aussage → Erweitern; Schärfung einer bestehenden → Präzisieren; ersetzende → Korrigieren). - **Kein Leasing-Scope in 3.3:** AC-4 (Mutation nur im geleasten Bereich, AD-17.3) bleibt Story 3.5/3.6; AD-17f-Basis unverändert. §5.9 Pkt. 5/6-R1/P2-Bausteine unverändert. - `sprint-status.yaml`: Key `3-3-bestehende-concepts-erweitern-präzisieren-korrigieren` → **in-progress** (bei Implementierung). **Ask First:** §5.6-Linkform-Änderung (A0-9) · AD-7d-Renames · Inhalts-Mutation des realen Bundles · Validator-/Vertrags-/`raw/`-Change · Commit-Boundary-Änderung · Leasing-Ausweitung (3.5-Scope). **Never:** Änderungen an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/` (AD-3) · neue §7-Invaliditätsklasse · Standalone (D-3) · Duplikat-Anlage eines bestehenden Pfads · „Regenerate Everything" (AD-5/A0-6) · stille Löschung von Provenienz ohne Ersetzungsbeleg (AD-16) · stiller Absatz-Neuschreib (Structure-Preservation-Fall). ## I/O & Edge-Case Matrix | Scenario | Input / State | Expected Output / Behavior | Error Handling | |----------|--------------|---------------------------|----------------| | HAPPY_ERWEITERN | Neue committete Evidenz trägt eine neue belegte Aussage zum bestehenden Concept | **Erweitern:** neue Aussage als Absatz ergänzt (mit §5.5-Inline-Beleg), bestehende Aussagen unverändert; `sources`-Zuwachs um echten neuen Beleg; `at`-Bump; `log.md`-Eintrag „Story 3.1-Update" | NO_MATCH → UNTOUCHED_CONCEPT (keine Mutation) | | HAPPY_PRAEZISIEREN | Evidenz schärft eine bestehende Aussage (präzisierende Information, FR-6/AC-2) | **Präzisieren:** Formulierung/Abgrenzung an der bestehenden Aussage geschärft, Position/Struktur erhalten; Beleg nachgeführt; kein Satz-Umbau/Neuschreib | keine bestehende Aussage als Anker → nicht Präzisieren (ggf. Erweitern) | | HAPPY_KORRIGIEREN | Evidenz ersetzt eine fehlerhafte/überholte Aussage | **Korrigieren:** ersetzte Aussage **nicht still gelöscht**, sondern explizit abgelöst + Ersetzungsbeleg (AD-16-Default Erhaltung) | widersprechender Inhalt ohne Ersetzungsevidenz → bleibt erhalten, Disagreement in `log.md` (Epic-4-Interface) | | NO_OP_KANDIDAT | Evidenz bereits vollständig im Body enthalten | **No-Op:** keine Mutation, kein `at`-Bump, kein `sources`-Zusatz, kein `log.md`-Eintrag — byte-identisch | im Zweifel greift Erweitern/Präzisieren (No-Op = engere Auslegung) | | STRUKTUR_ERHALT | Update greift in Body mit belegten Aussagen + Inline-Verweisen | Struktur unverändert: Subset, Verweise, Linkform; kein unbefugter Key | Verstoß → Update fehlerhaft; Rollback + textuell benannter Verstoß (NFR-4) | | MEHRFACH_TREFFER | Mehrere Einheiten desselben Runs treffen denselben Pfad | Konsolidierung: ein Update, ein `log.md`-Eintrag, ein konsolidierter `sources`-Zuwachs, ein `at` | Reihenfolge = Zuwachs-Sicht; lexikografischer Tie-Break | ## Code Map - `schema/compiler.md` — **primär mutiert** (D-3, einziger Instruktions-Ort): - §5.9 Pkt. 2 (`:261-269`): drei Update-Formen **operationell ausformulieren** (a) Abgrenzungskriterium je Form, (b) Struktur-Erhaltungsregel (Definition „Struktur" + was unverändert bleibt), (c) Textgenauigkeits-Rahmen für Präzisieren. Bestehender Regeltext (Form-Bullets, `sources`-Regel, `at`-Konvention, No-Op, Konsolidierung) bleibt normativ **unverändert** — Schärfung als Ausführungs-Ebene ohne neue Logik. - §5.9 Pkt. 5 (`:272-278`): Erhaltungs-Invariante — Struktur-Erhaltungs-Bezug ergänzen (Diff-Probe erfasst Pfad-Mengen; Struktur pro Pfad über Pkt.-2-Regeln geprüft). - §5.9 Pkt. 6 (`:279-281`): P2-Block — Struktur-Erhaltungs-Check als zusätzliches textuelles Element (keine unbefugten Keys, keine stille Löschung, Links unverändert). - §8 Revisionslog (`:375`): **Revision 2.8** (Story 3.3) mit Abschlussklausel (kein Vertrags-/Validator-/`raw/`-Change, keine §7-Klasse, kein Standalone). - `_bmad-output/implementation-artifacts/sandbox-3-3/run-sandbox.sh` — **neu** (re-executierbar, Muster Story-3.1-Sandbox): Mini-Bundle mit einem Concept + committeter Neuevidenz; alle drei Formen + No-Op durchspielen; Erhaltungs-Invariante als harte Assertion (Diff ⊆ {betroffener Pfad, log}; keine neue Datei; kein Ghost-Diff); Zwei-Run-Identität; Frontmatter-Konformität je mutiertem Concept. - `wiki/log.md` — **append** (append-only, Vertrag §5): Story-3.3-Eintrag (Schärfung, Sandbox-Nachweis, Statuswechsel, Validator-Verdikt); bestehende Bullets unverändert. - `_bmad-output/implementation-artifacts/sprint-status.yaml` — **mutiert**: Key `3-3-…` (`:56`) → `in-progress` (→ `done` bei Story-Abschluss). - `schema/validator.md`, `schema/wiki-compiler.md`, `raw/…` — **read-only** (AD-3). Keine Concept-Inhalts-Mutation (Instruktions-Story; kein neues committetes `raw/`-Material vorhanden — Demonstration per Sandbox). ## Tasks & Acceptance **Execution:** - [x] `schema/compiler.md` — §5.9-Pkt.-2-Update-Formen operationell schärfen (je Form Abgrenzungskriterium + Struktur-Erhaltungsregel + Textgenauigkeits-Rahmen; bestehender Regeltext unverändert) · §5.9-Pkt.-5/-6: Struktur-Bezug + P2-Check-Element · §8 Revision 2.8; ohne Change an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/`. - [x] `sandbox-3-3/run-sandbox.sh` — Update-Run-Demonstrator (Erweitern + Präzisieren + Korrigieren + No-Op), Erhaltungs-Invariante als harte Assertion, Zwei-Run-Identität. **Erweitert um U7 MEHRFACH_TREFFER** (I/O-Matrix-Row, Konsolidierung mehrerer Einheiten auf denselben Pfad) — alle 7 Tests (U1–U7) PASS, Exit 0. - [x] `wiki/log.md` — Story-3.3-Eintrag (Vertrag §5, append-only): Schärfung, Sandbox-Nachweis, Statuswechsel, per-Datei-Validator-Verdikt. - [x] `sprint-status.yaml` — Key `3-3-…` → in-progress. **Acceptance Criteria:** - Given eine neue Erkenntnis zu einem bestehenden Concept, when der Run sie verarbeitet, then erweitert er das bestehende Concept anstelle der Anlage einer neuen Datei (AC-1; FR-6) — Erweitern-Regel in §5.9 Pkt. 2, Sandbox belegt sie (keine neue Datei im Diff). - Given eine präzisierende Information, when sie eingearbeitet wird, then wird der Text präzisiert oder korrigiert, ohne die Struktur zu zerstören (AC-2; FR-6) — Struktur-Erhaltungsregel in §5.9 Pkt. 2/5 definiert. - Given eine Aktualisierung, when sie erfolgt, then bleiben Beziehungen und Provenienz soweit weiterhin gültig erhalten (AC-3; FR-6) — Inline-Verweise + Linkform unverändert gültig soweit Beleg Body-Bestand; `sources`-Zuwachs nur um echte neue Belege. - Given die Instruktion, when geprüft, then bleibt `schema/validator.md`/`schema/wiki-compiler.md`/`raw/` unverändert (AD-3), keine neue §7-Klasse, kein Standalone (D-3), kein Leasing-Scope (AC-4 → 3.5/3.6, AD-17.3-Hinweis in §7) — Validator auf Ist-Bundle SUCCESS (7/7 unverändert). ## Spec Change Log *(Append-only — hier von step-04 während der Review-Loops befüllt.)* ### Review Loop 1 (Step-04, 2026-08-19) — 3 Subagenten (blind-hunter 9, edge-case-hunter 2+Minors, verification-gap 18) **Klassifikation (Dedupe → Severity → Route):** High — Verifikations-Lücken des Sandbox-Nachweises (byte-Identität nur Teilmengen-assertiert; Struktur-Ebene/`??`-Sicht nie exerziert; U7 `-le 1`), Form-Abgrenzungs-Überlapp (keine Präzedenz → AD-17h-Gefahr), §5.5-Ankerform (`#S-N` ohne reale Kennung im Rohdokument). Medium — U3-Wortlaut-Mutation der abgelösten Aussage, `last_updated`-Präzisions-Regression, Frontmatter-Prüfung vollständig (Reihenfolge/Duplikat), No-Op-Form-Asymmetrie, „kein neuer normativer Inhalt" vs. Pkt.-5/6-Änderung, at↔AD-17h-Gap-Kreuzreferenz. Low — Diff-Artefakt-Pfade, Spec-Change-Log leer (per Konvention erst jetzt befüllt). **Ergebnis: kein intent_gap, kein bad_spec** (kein Loopback) — **patch** (auto-fixiert, s. Diff): §5.9 Pkt.-2-Operationelle-Ebene — Präzedenz-Reihenfolge `Korrigieren → Präzisieren → Erweitern → No-Op` + Überlapp-Bindung + No-Op als Nicht-Form + at↔AD-17h-Kreuzreferenz; Korrigieren-Struktur-Erhaltung — Original-Wortlaut bleibt als abgelöster Bestand erhalten; Sandbox — U1/U2/U3 byte-Identität auf alle drei Aussagen erweitert, U8 (unbefugter Frontmatter-Key → Struktur-HARD-FAIL) + U9 (ungetrackte neue Datei → `??`-Sicht-HARD-FAIL) neu, U7 `-le 1` → `-eq 1` + beide raw/-Quellen im konsolidierten log-Eintrag, assert_frontmatter um canoniche Reihenfolge + Duplikat-Prohibition erweitert, reale `S-N`-Anker in allen raw/-Evidenzdateien (§5.5), U3-Wortlaut nicht mehr verändert. **defer** (append-only `deferred-work.md`): `last_updated`-Präzision (sync-sprint-status-General), „Schärferung/Formata"-Typos (frozen Story-3.1-Text), „auch nach Commit"-Überzeichnung + at↔AD-17h-Gap-Kreuzreferenz (Home Story 3.8), U2-Selbsterfüllung + Zuwachs-Sicht-vs-lexikografisch-Rationale (Form-Wahl-Prüfung als Verfahren), Em-Dash/Umlaut-Normalisierung im Sandbox-Evidenztext. **reject:** U6-SHA-Reproduzierbarkeit von log.md (random baseline-SHA ist konstruktionsbedingt), Diff-Artefakt-Pfad-Präfix (nur Verbrauchskontext), Spec-Change-Log „leer" (per Konvention erst während Review-Loops befüllt). ## Design Notes **Warum Ergänzung, nicht Umbau:** Die Story-3.3-Schärfung ist ein Ausführungs-Sub-Block an Pkt. 2 — sie definiert die offene Frage „Was tue ich konkret bei jedem Form-Fall, und was lasse ich unangetastet?" als deterministische Brücke Regel → Run (AD-17h): dieselbe Evidenz + formale Struktur → identisches Update-Ergebnis. Der frozen Story-3.1-Regeltext bleibt unverändert; die operationellen Regeln werden als Präzisierungsebene darunter angefügt (keine Re-Negotiation). **Struktur-Definition (das Geschützte):** (1) Frontmatter (Subset + canonische Reihenfolge; zulässig: `sources`-Zuwachs, `at`-Bump; kein neuer Key, keine Entfernung ohne Beleg); (2) bestehende belegte Aussagen mit §5.5-Inline-Verweisen (nicht umgeschrieben ohne dass Präzisieren/Korrigieren greift); (3) Linkzeichen §5.6-Pin (kein Linkumbau bei reinem Body-Update). Das ist die Bedeutung von „ohne die Struktur zu zerstören" (FR-6/AC-2). **Abgrenzungskriterium (aus der Evidenz):** (a) belegte Aussage existiert im Body nicht → Erweitern; (b) schärft bestehende Formulierung/Abgrenzung ohne Ersatz → Präzisieren; (c) ersetzt eine bestehende als fehlerhaft/überholt → Korrigieren; (d) nichts davon → No-Op. Unschärfe → zugunsten Erweitern/Präzisieren (No-Op = engere Auslegung, bestehende §5.9-Regel). ## Verification **Commands (re-executierbar, ab Workspace-Root):** 1. `bash _bmad-output/implementation-artifacts/sandbox-3-3/run-sandbox.sh` — expected: alle Szenarien mit harten Pass/Fail-Assertionen, Erhaltungs-Invariante erzwungen, Exit 0. 2. `grep -n "Struktur-Erhaltungsregel\|operationelle\|Revision 2.8" schema/compiler.md` — liefert die operationellen Regeln + Revisionslog. 3. Read-only (AD-3): `git status --porcelain` zeigt keinen Change an `schema/validator.md`/`schema/wiki-compiler.md`/`raw/`. 4. Validator-Lauf: alle `wiki/`-Dateien SUCCESS (unverändert, keine Inhalts-Mutation). **Manual checks:** - §5.9 Pkt. 2 trägt Abgrenzungskriterium + Struktur-Erhaltungsregel + Textgenauigkeits-Rahmen; bestehender Regeltext unverändert; §8-Rev-2.8 mit Abschlussklausel; kein `validator.md`/`wiki-compiler.md`/`raw/`-Diff; §7 ohne neuen Platzhalter (Update-Thema entlassen, AC-4-Leasing an 3.5/3.6); `wiki/log.md`-Eintrag datiert mit Story-3.3-Semantik + Sandbox-Nachweis + Statuswechsel + Verdikt; `sprint-status.yaml` konsistent. ## Suggested Review Order **Abgrenzungs-Mechanik der Update-Formen (Kern)** - Einstieg: die neue operationelle Ausführungs-Ebene — Präzedenz-Reihenfolge Korrigieren → Präzisieren → Erweitern → No-Op, deterministische Form-Wahl (AD-17h/A0-19), No-Op als Nicht-Form. [`compiler.md:270`](../../schema/compiler.md#L270) - Korrigieren schützt den abgelösten Original-Wortlaut (AD-16-Default, keine stille Löschung). [`compiler.md:271`](../../schema/compiler.md#L271) - Präzisieren: Schärfen an der Aussage selbst, kein Satz-Umbau; No-Op-Erhaltungsregel volle Byte-Identität. [`compiler.md:272`](../../schema/compiler.md#L272) **Struktur-Erhaltungs-Invariante + P2-Check** - Die Pfad-Probe verifiziert jetzt zwei Ebenen — Menge + Struktur je berührtem Pfad (FR-6/AC-2). [`compiler.md:283`](../../schema/compiler.md#L283) - P2-Check-Block-Element (6): keine unbefugten Keys, keine stille Löschung, Linkform-Pin. [`compiler.md:287`](../../schema/compiler.md#L287) - Revisionslog Revision 2.8 mit Abschlussklausel (kein Vertrags-/Validator-/`raw/`-Change). [`compiler.md:382`](../../schema/compiler.md#L382) **Re-executierbarer Sandbox-Nachweis** - U8: unbefugter Frontmatter-Key löst die Struktur-Ebene-HARD-FAIL aus — Negativ-Kontrolle der Kern-Invariante. [`run-sandbox.sh:365`](./sandbox-3-3/run-sandbox.sh#L365) - U9: ungetrackte neue Datei wird über die `??`-Sicht erkannt (Duplikat-Kontrolle). [`run-sandbox.sh:378`](./sandbox-3-3/run-sandbox.sh#L378) - U7: Konsolidierung mehrerer Einheiten auf einen Pfad — ein log-Eintrag, beide raw/-Quellen verlinkt. [`run-sandbox.sh:320`](./sandbox-3-3/run-sandbox.sh#L320) - assert_frontmatter: canoniche Reihenfolge + Duplikat-Prohibition (Vertrag §3.3/§3.4-Subset). [`run-sandbox.sh:118`](./sandbox-3-3/run-sandbox.sh#L118) **Provenienz & Status** - Review-Loop-1-Bullet: Klassifikation, Patches, Defers, Rejects; Spec-Status `in-review`. [`log.md:4`](../../wiki/log.md#L4) - Defer-Einträge (5) inkl. Home Story 3.8 für at↔AD-17h-Gap und Normalisierungs-Lücken. [`deferred-work.md:9`](./deferred-work.md#L9) - Sprint-Status Key `3-3-…`: Review-Abschluss-Flip auf `done`. [`sprint-status.yaml:56`](./sprint-status.yaml#L56)