@event4u/agent-config 4.8.0 → 5.0.0

package/docs/guidelines/agent-infra/language-and-tone-examples.md

@@ -77,3 +77,38 @@ in an English `.md` file. Body text, example sentences, prompt templates,
 agent-rendered strings, and failure modes must be English. Reference
 established phrases abstractly later (e.g. "a standing autonomy directive")
 and link back to the anchor block.
+
+## Pre-send gate — filler-phrase blocklist
+
+The pre-send confirm step (Step 4 of the rule's gate) checks for
+language-of-target-mismatched opening phrases. The blocklist:
+
+- **English filler that must NOT open a German reply:** `Let me`,
+  `Now`, `Found`, `Confirmed`, `OK`, `Alright`, `Here's`, `So`.
+- **German filler that must NOT open an English reply:** `Lass mich`,
+  `Jetzt`, `Gefunden`, `Bestätigt`.
+
+If the first sentence starts with one of these in the wrong language,
+rewrite the whole reply.
+
+## CLI / icon spacing rules
+
+- Two spaces after `❌`, `✅`, `⚠️` in CLI output.
+- One space for other icons.
+- One blank line max; no double / triple blanks.
+- File ends with exactly one newline.
+
+## `.md` files — pre-save detection heuristic
+
+Before saving any `.md` under `.augment/`, `.agent-src/`,
+`.agent-src.uncondensed/`, or `agents/`, scan the body for:
+
+- Umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) **outside** fenced code,
+  paths, or `DE: … · EN: …` anchor blocks.
+- German function words: `für`, `nicht`, `dass`, `wenn`, `sollte`,
+  `werden`, `arbeite`, `selbstständig`, `jetzt`, `einfach`, `weiter`,
+  `lösche`, `frag`, `schreib`, `mach`.
+- Non-English quoted phrases in body text.
+
+Any hit → translate to English, OR move to a `DE: … · EN: …` anchor
+block (the only allowed German location).

package/docs/migration/v1-to-v2.md

@@ -1,10 +1,11 @@
 # Migration — v1 → v2 (npx-only runtime)
 
-> **Status:** skeleton. The one-shot `npx @event4u/agent-config migrate`
-> is implemented in P3.5 of
-> [`road-to-portable-runtime-and-update-check`](../../agents/roadmaps/road-to-portable-runtime-and-update-check.md);
-> this document tracks the user-facing cutover contract so consumers can
-> rehearse the change before the command lands.
+> **Status:** active. The one-shot `npx @event4u/agent-config migrate`
+> is implemented in `scripts/_cli/cmd_migrate.py`; its action matrix +
+> exit-code contract live in
+> [`docs/contracts/migrate-command.md`](../contracts/migrate-command.md).
+> This document is the user-facing narrative; the contract is the
+> normative reference.
 
 ## Why this change
 
@@ -56,32 +57,44 @@ The per-tool glue (`.claude/`, `.cursor/`, `.clinerules/`,
 the source that writes them changed (from `vendor/` /
 `node_modules/` scripts to the npx-resolved runtime).
 
-## The `migrate` command — contract sketch
+## The `migrate` command
 
 ```bash
-npx @event4u/agent-config migrate              # interactive, default
-npx @event4u/agent-config migrate --dry-run    # plan only, no writes
-npx @event4u/agent-config migrate --yes        # non-interactive
+npx @event4u/agent-config migrate              # apply, real changes
+npx @event4u/agent-config migrate --dry-run    # plan only, zero writes
 ```
 
-Order of operations (locked once P3.5 lands):
-
-1. Detect pre-v2 markers: `composer.json` require entry,
-   `package.json` devDependency, `vendor/event4u/agent-config/`,
-   `node_modules/@event4u/agent-config/`, legacy `.gitignore` lines,
-   `~/.claude/{rules,skills}/event4u/` and siblings.
-2. Print the planned change set (file removals, file writes, pin
-   value). Stop here under `--dry-run`.
-3. Remove dependency entries via the appropriate package manager
-   (`composer remove`, `npm uninstall` / `pnpm remove` / `yarn remove`).
-4. Wipe the retired user-scope `event4u/` namespace dirs.
-5. Write / update `.agent-settings.yml` with the new shape +
-   `agent_config_version` pin.
-6. Re-run `sync-gitignore` to refresh the project `.gitignore` block.
-7. Print a one-screen post-migration verification list.
-
-Idempotency: each step is a no-op when the v1 marker is absent. Re-runs
-print *"already on v2 — nothing to do"* and exit 0.
+One opinionated command, one flag. The full action matrix +
+exit-code contract is documented in
+[`docs/contracts/migrate-command.md`](../contracts/migrate-command.md);
+the operations summary below is the narrative form.
+
+Order of operations (fixed; foundation-first):
+
+1. Detect every legacy signal in one pass: `composer.json` require
+   entry, `package.json` devDependency, managed symlinks pointing
+   into `vendor/` / `node_modules/`, v0
+   `.implement-ticket-state.json`, project-local `.agent-settings.yml`
+   / `.agent-user.yml` (flat or under `settings/`), empty
+   `agent-config/` shell.
+2. Under `--dry-run`, print the planned change set and stop with
+   exit 0.
+3. Strip the package entries from `package.json` / `composer.json`
+   in-place; preserve sibling keys + formatting.
+4. Purge legacy symlinks; preserve user-managed symlinks elsewhere
+   with a warning.
+5. Migrate `.implement-ticket-state.json` → `.work-state.json`
+   (renames the v0 source to `.bak`).
+6. **Hard-delete** legacy project-local config files. The wizard
+   (`agent-config setup`) recreates fresh global config on the next
+   run — deletion is the design, not a regression.
+7. Remove the empty `agent-config/` shell directory if present.
+8. Refresh the `.gitignore` agent-config managed block.
+9. Print a summary listing every action taken.
+
+Idempotency: re-running on a fully-migrated repo prints
+*"already migrated — nothing to do"* and exits 0 without touching
+the filesystem.
 
 ## Verification after migration
 

package/docs/value.md

@@ -0,0 +1,84 @@
+# Value Dashboard — was kostet das Paket, was bringt es?
+
+> Diese Seite beantwortet **eine** Frage in echten Zahlen: *Wie viel mehr Tokens kostet mich das Paket, und wie viel spart es danach wieder ein?* Generiert von `scripts/render_value_md.py` aus dem letzten `value-v1` Report; Quelle: `internal/bench/reports/value/latest.json`.
+
+## Wie diese Seite zu lesen ist
+
+**Panel A (Kostenleiter)** — von oben nach unten lesen. Jede Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro Request hinzufügt oder spart*, *was das in € auf 1,000 Requests kostet*, und *wo wir kumulativ stehen*. Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort.
+
+**Panel B (Verhalten)** — vier reale Vergleiche, *mit* vs. *ohne* Paket. Hier liegt der nicht-Token-Wert: passende Skill-Auswahl, Stopps bei riskanten Aktionen, weniger Rückfragen, mehr abgeschlossene Aufgaben.
+
+**Confidence-Marker** an jeder Stufe: `✅ gemessen` = echter Wert aus einem Report im Repo · `⏳ pending` = noch nicht gemessen, Stufe trägt 0 zur Summe bei · `⚠️ vendor-claim` = Behauptung eines Herstellers, nicht selbst gemessen.
+
+## Reference scale
+
+- **1,000** Requests, durchschnittlich **8,000** Input-Tokens und **600** Output-Tokens pro Request
+- Modell-Tier: `sonnet` · Preisstand `2026-05-14` (Quelle: `internal/bench/pricing.yaml`)
+- Wer einen anderen Workload fährt, rechnet selbst nach — die Methodik ist offengelegt; nichts ist hardcodiert versteckt.
+
+## Panel A — Kostenleiter (kumulativ, min → max)
+
+Liest sich von oben nach unten. Positive Δ-Werte = das Paket *kostet* Tokens (Regel-Load ist die ehrliche Up-Front-Steuer); negative Δ-Werte = das Paket *spart* Tokens.
+
+| Stufe | Was sie tut | Δ Tokens | Δ € (1k Req) | Kumulativ | Quelle |
+|---|---|---:|---:|---:|---|
+| **Ohne Paket / Without package** | Baseline — der nackte Request ohne Paket-Regeln. | +0 | +0.00 € | +0.00% | `n/a` · ✅ gemessen |
+| Mit Paket (Regeln laden) / With package (rule load) | Die immer-aktiven Regeln landen im Kontext jedes Requests. ⚠️ erst teurer | +8 895 | +24.55 € | +111.19% | `dist/router.json` · ✅ gemessen |
+| | _Fußnote:_ Kernel = 10 rules (31570 chars) + charter (4010 chars); tokens ≈ chars / 4. | | | | |
+| + condense (Regeln eindampfen) / + condense (rule shrink) | Build-Schritt schrumpft Regel-Dateien vor dem Ausliefern. | -186 | -0.51 € | +108.86% | `internal/bench/reports/telegraph-v2.json` · ✅ gemessen |
+| | _Fußnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | | |
+| + rtk (CLI-Output filtern) / + rtk (filter CLI output) | rtk schneidet verbose CLI-Ausgabe vor dem Modell-Input weg. | -593 | -1.64 € | +101.45% | `internal/bench/reports/rtk/latest.json` · ✅ gemessen |
+| + terse (Antworten knapper) / + terse (shorter replies) | Telegraph-Stil zielt auf knappere Modell-Antworten. | +56 | +0.77 € | +102.15% | `internal/bench/reports/telegraph-v1.json` · ✅ gemessen |
+| | _Fußnote:_ Honest: gemessener Median = -9.27% gegen 'sei knapp' — Telegraph liefert hier mehr Tokens, nicht weniger. Wir messen, wir verstecken nicht. | | | | |
+
+**NETTO: Mehrkosten** ⚠️ — **+8 172 Tokens / Request**, **+22.55 €** auf 1,000 Requests, kumulativ **+102.15%** vs. Baseline.
+
+## Panel B — Verhalten (mit vs. ohne)
+
+Vier reale Vergleiche aus echten Bench-Runs. Hier liegt der Wert, den Tokens allein nicht messen: ob der Agent das richtige Skill wählt, bei riskanten Aktionen stoppt, weniger rückfragt und mehr Aufgaben abschließt.
+
+| Metrik | Was es bedeutet | Mit Paket | Ohne Paket | Δ | Mode |
+|---|---|---:|---:|---:|---|
+| Right-skill selection / Richtige Skill-Wahl | Wie oft das passende Skill aktiviert wird (top-K Treffer). | 50.0% | 0.0% | 50.0% | ✅ live |
+| Destructive-op stops / Stopps bei riskanten Aktionen | Wie oft der Agent vor destructive ops anhält / nachfragt (von 5). | — | — | — | ⚠️ dry-run |
+| Ask-vs-act ratio / Fragen vs. Handeln | Verhältnis Rückfragen zu Aktionen — niedriger = entschlossener. | 0.000 | 0.000 | 0.000 | ✅ live |
+| Task completion rate / Aufgaben fertig | Anteil der Aufgaben, die der Agent vollständig abschließt. | 84.6% | 7.7% | 76.9% | ✅ live |
+
+## Glossar
+
+Plain-language Definitionen für den nicht-Entwickler-Reader.
+
+- **Token** — die Einheit, in der ein Sprachmodell abrechnet. Faustregel: ein Token ≈ 4 Zeichen deutsch/englischer Prosa. 1.000 Tokens ≈ 750 Wörter.
+- **Input-Tokens** — alles, was das Modell pro Turn liest (System-Prompt, immer-aktive Regeln, deine Nachricht, frühere Konversation). Das Paket fügt hier Regeln hinzu — Installation kostet Input-Tokens.
+- **Output-Tokens** — was das Modell zurückschreibt. Meist weniger als Input. Pro Token teurer als Input.
+- **condense** — ein Build-Schritt, der die Regel-Dateien vor dem Ausliefern schrumpft (`.agent-src.uncondensed` → `.agent-src`). Spart Input-Tokens bei jedem Request.
+- **rtk** — der *Rust Token Killer*, ein CLI-Wrapper, der verbose Output (`git status`, lint-Output, test-Runner) filtert, bevor das Modell ihn liest. Spart Input-Tokens auf Tool-Calls.
+- **terse / telegraph** — ein Stil (kurze Phrasen, weggelassene Artikel), den der Agent für knappere Antworten nutzt. Spart Output-Tokens — wenn der Korpus es belohnt.
+- **Ohne Paket / Mit Paket** — *without the package* / *with the package* — die zwei Arme des A/B-Vergleichs.
+- **€-per-1k-requests** — Token-Kosten auf der Referenz-Skala (1.000 Requests durchschnittlicher Größe, gepreist mit den aktuellen Sonnet-Raten aus `internal/bench/pricing.yaml`).
+
+## Methodik & Quellen
+
+Diese Seite ist eine **abgeleitete** Sicht — keine eigene Messung. Sie fasst drei bestehende Bench-Surfaces zusammen (siehe Spalte 'Quelle' in Panel A). Die maschinen-lesbaren Roh-Reports bleiben die Source-of-Truth:
+
+- `internal/bench/reports/telegraph-v1.json` / `telegraph-v2.json` — Telegraph/Condense-Messungen.
+
+- `agents/runtime/frugality/baseline.jsonl` — der Paket-Load (Metric A footprint).
+
+- `internal/bench/reports/rtk/latest.json` — die rtk-Messung (neu, Phase 2).
+
+- `internal/bench/reports/ab/*-ab-trackb-{with,without}.json` — A/B Track B (Verhalten).
+
+- `internal/bench/reports/*-dev.json` — Dev-Korpus Selection-Accuracy.
+
+
+**A/B-technischer Anhang:** [`docs/benchmark.md`](benchmark.md) trägt die Cache-Key-, Integrity- und Methodik-Details des A/B-Benches — wer den Variant-Axis-Beweis sehen will, liest dort weiter.
+
+
+**Hinweise aus dem Report:**
+
+- Token→€ conversion priced at sonnet rates from internal/bench/pricing.yaml (sourced_on=2026-05-14).
+- Pending rungs contribute 0 to the cumulative until measured.
+- Reference scale: 1000 requests × 8000 input / 600 output tokens per request.
+
+_Last rendered: `2026-05-29T04:36:04+00:00`_

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "4.8.0",
+    "version": "5.0.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -93,15 +93,15 @@
         "vitest": "^2.1.9"
     },
     "dependencies": {
-        "@fastify/static": "^9.1.3",
+        "@fastify/static": "^9.1.0",
         "@preact/signals": "^2.9.0",
         "commander": "^12.1.0",
-        "execa": "^9.6.1",
-        "fastify": "^5.8.5",
-        "js-yaml": "^4.1.1",
+        "execa": "^9.5.0",
+        "fastify": "^5.8.0",
+        "js-yaml": "^4.1.0",
         "open": "^10.2.0",
-        "preact": "^10.29.2",
-        "zod": "^3.25.76",
-        "zod-to-json-schema": "^3.25.2"
+        "preact": "^10.29.0",
+        "zod": "^3.25.0",
+        "zod-to-json-schema": "^3.25.0"
     }
 }