BP: AP6 Anhänge A.8 und AGENTS.md-Beispiel

- A.8 Schwellen 0/1/2; S = Summe Q1–15; A–C/D–E/Hebel numerisch - AGENTS.md-Beispiel Regel 40–80, Fence 80 Zeilen - Wörter 58 396→58 507 (+111); A.8 348→449 - Bericht audits/behebungsplan-ap6-2026-11-07.md
2026-11-07 19:44:43 +01:00
1 parent 06828bc8e0
commit bd37114dfb
@@ -0,0 +1,113 @@
+# Behebungsplan AP6 — Anhänge konsistent
+
+## 1. Kopf
+
+| Feld | Wert |
+|------|------|
+| Datum | 2026-11-07 |
+| Modell | Hauptsitzung wie eingestellt; Zweitleser dieselbe Instanz |
+| Basis-SHA | `2a5d21d` (`main`, AE-60 A); Arbeitsbaum trug bereits uncommittetes AP4+AP5 |
+| Branch | `main`, **nicht committet**, nicht gepusht; `origin/main` = `22ddedc` (9 Commits voraus) |
+| Plandatei | `audits/behebungsplan-2026-11-02.md` § 6 AP6 und § 9.3 |
+| Status | **AP6 Manuskript fertig**; Ampel **GELB** (Dist stale, Print 295 gegen `_print_pages` 298, AP4–AP6 uncommittet) |
+
+## 2. Auftrag und DoD
+
+Plan § 6 AP6:
+
+- A.8: numerische Schwellen Stufe 0/1/2 und explizite Aggregation (Summe, schwächste Dimension, Gewichtung).
+- AGENTS.md-Beispiel: auf höchstens 40 Zeilen kürzen **oder** die Regel auf „40–80 Zeilen“ präzisieren. Eine Variante begründen.
+- Anhang B: Methodenabschnitt und Datumsstempel aus AP2 (nur prüfen).
+- `templates/` und `checklists/` gegen A.3, A.7 und A.8 prüfen; Abweichungen melden, nicht still ändern.
+
+Abnahme: A.8 ist entscheidbar; Regel und Beispiel widersprechen sich nicht; Anhang B nennt Methode und Stand.
+
+**Nicht:** AP7, Freeze 18.1–18.4 / 17.5–17.6 / 5.5–5.7, `_print_pages`, Cover/`assets/`, Pipeline, ISBN, Merge, Push, Commit ohne Auftrag, A.3/A.7-Bodies angleichen.
+
+## 3. Metrik
+
+| Stelle | vorher | nachher | Band |
+|--------|--------|---------|------|
+| A.8 (`\S+`) | 348 | **449** | +80…+120 → **+101** |
+| Kap. 23 `wc -w` | 3 400 (AP5-Arbeit) | **3 511** | — |
+| Buch `manuskript/kapitel-*.md` `wc -w` | 58 396 (AP5-Arbeit) | **58 507** | — |
+| AGENTS.md-Beispiel `wc -l` auf den Block | 82 | **80** | Regel 40–80 |
+
+## 4. Ausgeführte Stellen
+
+**A.8 / `checklists/reife-assessment.md`**
+
+Aggregation als Setzung, drei Größen:
+
+1. **S** = Summe Q1–15 (0–30); Q16–17 zählen nicht.
+2. **Gewichtung:** A–C = (Q1+…+Q8)/8; D–E = (Q9+…+Q12)/4.
+3. **Hebel** = min der sieben Dimensionsmittel (A=Q1–3/3 … G=Q15). F/G zählen in S, blocken die Stufe nicht.
+
+Schwellen, erste zutreffende Zeile:
+
+| Stufe | Verfahren |
+|-------|-----------|
+| **0** | S < 12 **oder** A–C < 1,0 |
+| **1** | sonst S < 20 **oder** A–C < 1,5 **oder** D–E < 1,5 **oder** eine Dimension A–E = 0 |
+| **2** | sonst S ≥ 20 **und** A–C ≥ 1,5 **und** D–E ≥ 1,5 **und** keine Dimension A–E bei 0 |
+
+Beispiel: S = 18, A–C = 1,25, D–E = 1,25 → Stufe 1.
+
+**A.4 / `templates/agents-md-beispiel.md`**
+
+Variante **Regel 40–80**, nicht Kürzung auf 40. Begründung: der kopierbare Block trägt Context-Gabel (4.4 Option 1), Verify in drei Schichten (Kap. 10.6), Security-Invarianten, Permissions hart/weich und Karpathy-Block. Auf 40 Zeilen fiele eine dieser Pflichte. 40 bleibt Untergrenze einer wahren Datei; 400 Zeilen Historie bleibt der Gegenpol. Zwei Leerzeilen in den Verify-Kommentaren entfernt, Block **80** Zeilen. Snapshot A.4 und lebende Datei byte-gleich im Fence.
+
+**Anhang B**
+
+B.1 `### Methode und Grenzen` und Stand-Zeile je Tabelle: unverändert aus AP2. Kein Edit.
+
+## 5. Templates/Checklisten gegen A.3, A.7, A.8
+
+Abweichungen **gemeldet, nicht geändert** (außer der beauftragten A.8-Aggregation in der lebenden Checkliste und der 40–80-Regel in `agents-md-beispiel.md`).
+
+| Paar | Befund |
+|------|--------|
+| A.3 ↔ `templates/task-prompt-template.md` | Beide Markdown-Fences identisch (Kopiervorlage 45 Zeilen, Mini 6 Zeilen). Qualitätscheck identisch. Nur Wrapper: Snapshot hat Zweck-Zeile und „Im Buch-Repo“; lebend hat Titel + Intro. |
+| A.7 ↔ `templates/dod-bibliothek.md` | 6/9 Fences identisch. Drift in 3 Fences (lebende Datei ausführlicher): Domain-Kern „dokumentierte Team-Latte grün“ vs. „Team-Latte“; Boundary „generiert oder manuell“; Parser Property-based / Fuzz-Budget / Seed-Corpus. Überschriften Snapshot `**…**`, lebend `##`. |
+| A.8 ↔ `checklists/reife-assessment.md` | Nach AP6: Formeln und Schwellen gleich. Snapshot kompakt (Fragentabelle); lebend volle Fragen 1–17 plus Gates 0→1/1→2 plus Schnelldiagnose. Erwarteter Snapshot-Zuschnitt, kein stiller Drift in den Zahlen. |
+| Übrige `templates/` / `checklists/` | Keine zweiten Kopien von A.3/A.7/A.8. `handoff-template.md` hat eigene Ziel/Ausschlüsse-Felder (A.1). |
+
+## 6. Zweitleser
+
+Auftrag: neuer A.8-Text gegen Entscheidbarkeit, AE-26/27/44, Snapshot vs. Checkliste.
+
+| ID | Klasse | Ort | Ergebnis |
+|----|--------|-----|----------|
+| P1 | Aggregation A–C zweideutig (/8 vs. (A+B+C)/3) | A.8 + Checkliste | **behoben:** A–C = (Q1+…+Q8)/8 festgeschrieben; Nachprüfung `ok \| P1 Aggregation eindeutig` |
+| P2 | Beispiel 1,3 / 1,2 nicht auf dem Raster | A.8 + Checkliste | **behoben:** 1,25 / 1,25 (Vielfache 1/8 und 1/4) |
+
+Keine P0. AE-26/27/44: 0 Befunde (Checkliste bleibt Team-„ihr“, vorbestehend).
+
+## 7. Tight-Loop
+
+```text
+just markdownlint     → 0 error(s)
+just link-check       → 140 file(s) ok
+python3 .grok/scripts/manuskript_check.py → 0 harte Verstöße
+git diff --name-only  → siehe § 8
+```
+
+Dist nicht neu gebaut (kein PDF-/EPUB-Auftrag).
+
+## 8. Geänderte Dateien (dieser Slice)
+
+- `manuskript/kapitel-23-anhang-a-kern-templates.md` (A.4 Pflege + Verify-Leerzeilen, A.8 Aggregation)
+- `templates/agents-md-beispiel.md` (Regel 40–80, Block 80 Zeilen)
+- `checklists/reife-assessment.md` (Aggregation/Schwellen)
+- `audits/behebungsplan-ap6-2026-11-07.md` (dieser Bericht)
+- `HANDOFF-buch.md` (Meta / Slice / Offen)
+
+AP4- und AP5-Dateien bleiben dirty, gehören nicht zu diesem Slice.
+
+## 9. Nicht angefasst
+
+AP7, AP3-Rest 374 Wörter, Freeze 18.1–18.4 / 17.5–17.6 / 5.5–5.7, `justfile` `_print_pages`, Cover/`assets/`, Pipeline, Distillate, ISBN, Merge, Push, Commit. A.3- und A.7-Bodies. Anhang B.
+
+## 10. Nächster Schritt
+
+**AP7** — Verifikation und Erfolgsmessung inkl. Rescore des AP3-Bands (374 Wörter). Builds nur mit Freigabe. Commit von AP4–AP6 nur mit Auftrag.
@@ -8,8 +8,12 @@
 1. **Wer:** 1–2 Practitioners plus optional Tech Lead oder EM.
 2. **Material:** ein Agent-Ticket und ein Agent-PR der letzten zwei Wochen.
 3. **Antworten:** pro Frage **Ja** / **Teilweise** / **Nein**. *Teilweise* = Artefakt existiert, ist aber kein Standard.
-4. **Score:** Ja = 2, Teilweise = 1, Nein = 0. Die **schwächste** Dimension ist der Hebel, nicht der Mittelwert.
-5. **Output:** geschätzte Stufe (0–2 für die meisten Teams) + **ein** Must-have-Gap für 14 Tage.
+4. **Score:** Ja = 2, Teilweise = 1, Nein = 0. Fragen 1–15 zählen, 16–17 nicht.
+5. **Aggregation** (Setzung, keine geeichte Skala) — drei Größen:
+   1. **Summe S** — Punkte Q1–15 (0–30).
+   2. **Gewichtung** — A–C = (Q1+…+Q8)/8; D–E = (Q9+…+Q12)/4 (je 0–2). F und G zählen in S, blocken die Stufe nicht allein.
+   3. **Hebel** — Minimum der sieben Dimensionsmittel (A–G, je 0–2), nicht der Gesamtmittelwert.
+6. **Output:** Stufe 0–2 nach den Schwellen unten + **ein** Must-have-Gap für 14 Tage.

 Team-Reife (Standards) nicht mit Repo-Maturity (Orakel/Hygiene am Touchpoint) verwechseln — Letzteres: [Kapitel 21](../manuskript/kapitel-21-low-maturity-legacy-greenfield.md).

@@ -71,13 +75,19 @@ Fragen 16–17 sind optional; 1–15 tragen die Einordnung.

 ## Von Score zu Stufe

-| Muster | Typische Stufe |
-|--------|----------------|
-| Viele Nein in A–C; Chat-Paste dominiert | **0** |
-| Ja/Teilweise in A–C bei Einzelnen; Team noch uneinheitlich | **1** |
-| Ja in A–E, Templates im Repo, Review erwartet DoD/Verify/Slice | **2** |
-| Dazu Metriken light, Guardrails teamweit, Hygiene-Rituale stabil | **3** |
-| Interne Plattform, Richtlinien als Code, Evals an eigenen Repos | **4** |
+Dimensionsmittel (nur Hebel): A = Q1–3 / 3; B = 4–6 / 3; C = 7–8 / 2; D = 9–10 / 2; E = 11–12 / 2; F = 13–14 / 2; G = Q15.
+
+Verfahren für Stufe **0–2** (erste zutreffende Zeile gilt):
+
+| Stufe | Schwellen |
+|-------|-----------|
+| **0** | S < 12 **oder** Mittel A–C < 1,0 |
+| **1** | sonst S < 20 **oder** Mittel A–C < 1,5 **oder** Mittel D–E < 1,5 **oder** eine Dimension A–E = 0 |
+| **2** | sonst S ≥ 20 **und** Mittel A–C ≥ 1,5 **und** Mittel D–E ≥ 1,5 **und** keine Dimension A–E bei 0 |
+
+Beispiel: S = 18, A–C = 1,25, D–E = 1,25, keine Null-Dimension → Stufe **1**; Hebel = schwächste Dimension.
+
+Stufen **3** und **4** bleiben qualitativ: 3 = Stufe 2 plus Metriken light, Guardrails teamweit, Hygiene-Rituale stabil; 4 = interne Plattform, Richtlinien als Code, Evals an eigenen Repos.

 Dimension D und Repo-Orakel systematisch rot → zuerst Kapitel 21, nicht die Team-Stufe nach oben schieben.

@@ -2,9 +2,9 @@

 Kopierbare Werkbank — nicht zum Durchlesen, sondern zum Einbauen. Die Kapitel erklären das *Wann*; hier steht das *Was* zum Anpassen.

-Die folgenden Vorlagen sind die handlungsrelevantesten Artefakte dieses Buchs. Sie sind so abgedruckt, dass das PDF auch standalone nutzbar ist. Die vollständigen, aktuell gepflegten und weiteren Vorlagen liegen im **Begleit-Service** (versionierte ZIPs mit MANIFEST/SHA256, Stand & Drift, Errata, Hilfe) und im Buch-Repo unter `templates/` und `checklists/`.
+Die folgenden Vorlagen sind die handlungsrelevantesten Artefakte dieses Buchs. Sie sind so abgedruckt, dass das PDF auch standalone nutzbar ist. Die vollständigen, aktuell gepflegten und weiteren Vorlagen liegen im **Begleit-Service**. Dort gibt es versionierte ZIPs mit MANIFEST/SHA256, Stand, Drift, Errata und Hilfe. Dieselben Pfade stehen im Buch-Repo unter `templates/` und `checklists/`.

-A.1–A.6 sind die sechs Kern-Vorlagen. **A.7** (DoD-Bibliothek) und **A.8** (Reife-Assessment) sind zusätzliche Snapshots — Lehre bleibt in Kap. 10 bzw. 20.2.
+A.1–A.6 sind die sechs Kern-Vorlagen. **A.7** (DoD-Bibliothek) und **A.8** (Reife-Assessment) sind zusätzliche Snapshots. Die Lehre bleibt in Kap. 10 bzw. 20.2.

 **Begleit-Service:** <https://books.maatini.space/projects/coding-agents-praxis/>  
 Dort unter *Material*: `vorlagen.zip` (`templates/`) und `checklisten.zip` (`checklists/`). Kontakt: coding-agents@maatini.space.
@@ -319,10 +319,8 @@ Eine Aufgabe ist erst done, wenn:
 # Tight-Loop (nach sinnvollen Patches — schnell, scoped)
 - Tests: `npm test`   # oder: pnpm --filter … test / pytest path / go test ./pkg/...
 - Lint/Typecheck: `npm run lint`  # und/oder tsc --noEmit / mypy …
-
 # Slice-DoD (vor done / Hand-back)
 - dieselbe Kette + Scope-Check (`git diff --name-only` gegen die Allowlist)
-
 # Heavy (CI/Nightly — nicht nach jedem Edit)
 - full suite, Diff-Coverage, Mutation scoped; Build (wenn relevant): `npm run build`

@@ -364,7 +362,7 @@ Execute in vertikalen Slices → Verify (DoD) → Commit (nur wenn erlaubt).
 - Am Ende größerer Schritte: was geändert, wie verifiziert, was offen.
 ```

-**Pflege:** Wenig, aber wahr — besser 40 Zeilen aktuell als 400 Zeilen Historie. Soft Memory ersetzt keine harten Permissions; Harness-Allow/Deny mitziehen. Monorepo-Varianten im Buch-Repo unter `templates/agents-md-monorepo-root.md` / `templates/agents-md-monorepo-package.md`.
+**Pflege:** Wenig, aber wahr — **40–80 Zeilen** aktuell statt 400 Zeilen Historie. 40 = Untergrenze; dieses Beispiel = 80 (`wc -l` inkl. Leerzeilen). Soft Memory ersetzt keine harten Permissions; Harness-Allow/Deny mitziehen. Monorepo-Varianten im Buch-Repo unter `templates/agents-md-monorepo-root.md` / `templates/agents-md-monorepo-package.md`.

 Im Buch-Repo: `templates/agents-md-beispiel.md`

@@ -592,7 +590,7 @@ Human-Gate labeln; nicht als Loop-Orakel führen. Die Copy-Paste-Checkliste steh

 **Zweck:** In 20–30 Minuten Stufe 0–2 ehrlich einordnen und **einen** 14-Tage-Hebel wählen. Leiter: Kapitel 20.2. Lebende Datei: `checklists/reife-assessment.md`.

-**So:** 1–2 Practitioners, ein Agent-Ticket und ein Agent-PR der letzten zwei Wochen. Pro Frage Ja / Teilweise / Nein (Ja = 2, Teilweise = 1, Nein = 0). Die **schwächste** Dimension ist der Hebel.
+**So:** 1–2 Practitioners, ein Agent-Ticket und ein Agent-PR der letzten zwei Wochen. Pro Frage Ja / Teilweise / Nein (Ja = 2, Teilweise = 1, Nein = 0). Fragen 1–15 zählen, 16–17 nicht.

 **Fragen (Kern)**

@@ -606,7 +604,15 @@ Human-Gate labeln; nicht als Loop-Orakel führen. Die Copy-Paste-Checkliste steh
 | 13–14 | Security | Secrets draußen? Destruktive Tools gegated? |
 | 15 | Team | Templates und Review-Erwartung im Repo, nicht nur bei Heroes? |

-**Stufe (Faustregel):** viele Nein in 1–8 → **0**; Ja bei Einzelnen → **1**; Ja in Context/DoD/Slices/Hygiene/Handoff plus Templates im Repo → **2**. Repo-Orakel systematisch rot → zuerst Kapitel 21.
+**Aggregation** (Setzung). **S** = Summe Q1–15 (0–30). **Gewichtung:** A–C = (Q1+…+Q8)/8; D–E = (Q9+…+Q12)/4 (je 0–2). **Hebel** = min der sieben Dimensionsmittel (A=Q1–3/3; B=4–6/3; C=7–8/2; D=9–10/2; E=11–12/2; F=13–14/2; G=Q15). F/G zählen in S, blocken die Stufe nicht.
+
+| Stufe | Verfahren (erste zutreffende Zeile gilt) |
+|-------|------------------------------------------|
+| **0** | S < 12 **oder** Mittel A–C < 1,0 |
+| **1** | sonst S < 20 **oder** Mittel A–C < 1,5 **oder** Mittel D–E < 1,5 **oder** eine Dimension A–E = 0 |
+| **2** | sonst S ≥ 20 **und** Mittel A–C ≥ 1,5 **und** Mittel D–E ≥ 1,5 **und** keine Dimension A–E bei 0 |
+
+Beispiel: S = 18, A–C = 1,25, D–E = 1,25 → Stufe **1**; Hebel = schwächste Dimension. Repo-Orakel systematisch rot → zuerst Kapitel 21.

 **Must-have 0 → 1:** Task-Muster mit DoD · ein Verify-Command · Session endet mit Slice oder Handoff.  
 **Must-have 1 → 2:** `AGENTS.md` kanonisch · Vorlagen im Repo · Review erwartet Diff + Orakel · Handoff-Norm · Hygiene-Minimum.
@@ -43,10 +43,8 @@ Eine Aufgabe ist erst done, wenn:
 # Tight-Loop (nach sinnvollen Patches — schnell, scoped)
 - Tests: `npm test`   # oder: pnpm --filter … test / pytest path / go test ./pkg/...
 - Lint/Typecheck: `npm run lint`  # und/oder tsc --noEmit / mypy …
-
 # Slice-DoD (vor done / Hand-back)
 - dieselbe Kette + Scope-Check (`git diff --name-only` gegen die Allowlist)
-
 # Heavy (CI/Nightly — nicht nach jedem Edit)
 - full suite, Diff-Coverage, Mutation scoped; Build (wenn relevant): `npm run build`

@@ -90,7 +88,7 @@ Execute in vertikalen Slices → Verify (DoD) → Commit (nur wenn erlaubt).

 ## Hinweis zur Pflege

- **Wenig, aber wahr:** Besser 40 Zeilen aktuelle Regeln als 400 Zeilen Historie.
+- **Wenig, aber wahr:** Besser **40–80 Zeilen** aktuelle Regeln als 400 Zeilen Historie. 40 = Untergrenze; dieses Beispiel = 80 (`wc -l` inkl. Leerzeilen).
 - Nach großen Refactors AGENTS.md mitziehen.
 - Soft Memory (`AGENTS.md`) ersetzt keine harten Permissions (Kap. 15.1, 18).
  Harness-Allow/Deny mitziehen — nur-weiche Verbote sind Gift.