@event4u/agent-config 1.20.0 → 1.21.0

package/docs/contracts/iron-law-overrides.txt

@@ -0,0 +1,25 @@
+# Iron-Law-override allowlist for the kernel-budget check.
+#
+# Source contract: docs/contracts/kernel-membership.md § 5.1
+# Enforced by:     scripts/measure_rule_budget.py --kernel-budget-check
+#
+# A rule listed here is allowed to exceed the per-rule hard cap
+# (PER_RULE_HARD = 2 500 chars) up to the override ceiling
+# (PER_RULE_OVERRIDE_CEILING = 4 000 chars). Adding an entry requires a
+# numbered ADR in docs/decisions/ that justifies the Iron-Law density
+# (e.g. multiple Iron-Law fences, exhaustive enumeration that cannot be
+# safely externalised, pre-send/pre-act gate that loses meaning if split).
+#
+# Format: one rule-id per line. Comments start with '#'. Blank lines OK.
+
+# ADR-002 (2026-05-06) — kernel-bucket cap raise + per-rule overrides.
+# Source: docs/decisions/ADR-002-kernel-bucket-overrides.md
+# Empirical r_actual=0.795 vs r_projected=0.712. The 6 rules below carry
+# Iron-Law fences + non-externalisable enumerations; further compression
+# would force semantic loss. All sit ≤ 4 000-char override ceiling.
+ask-when-uncertain
+direct-answers
+language-and-tone
+no-cheap-questions
+non-destructive-by-default
+scope-control

package/docs/contracts/kernel-membership.md

@@ -0,0 +1,273 @@
+---
+stability: beta
+---
+
+
+# Kernel Membership — Phase 1.3 of road-to-kernel-and-router
+
+> **Status:** active · **Stability:** beta · **Owner:** road-to-kernel-and-router P1.3
+> · **Source of truth:** `docs/contracts/rule-classification.md` § 3.1
+> · **Pilot artifacts:** `docs/contracts/pilot/`
+
+Locks the kernel set and the empirical compression rate `r` derived
+from the P1.3 pilot. Phase 2.2 executes against this contract.
+
+## § 1 — Inclusion criteria (kernel-only)
+
+A rule belongs in the kernel iff it satisfies **all** of:
+
+1. **Iron-Law floor.** Carries an Iron Law fence (```...```) that
+   governs every reply or every action — no skill, no command, no
+   guideline can override it.
+2. **Mode-independent.** Fires under `off`, `auto`, `on`, every
+   role mode, every cost profile.
+3. **Pre-send OR pre-act gate.** Either (3a) scans the reply draft
+   before transmission (prose, tone, language, claim verification),
+   or (3b) fires before tool execution / commit / workflow progression
+   (safety, permission, scope). Post-hoc remediation does not
+   qualify.
+4. **Cross-cutting.** Applies across at least two of the categories
+   (behaviour, safety, tone, ask-policy) and cannot be scoped to a
+   sub-domain (a stack, a workflow, a single artifact type).
+5. **Ask-policy floor.** *(included by criterion #1+#4 union, but
+   surfaced explicitly: rules governing when/how the agent may ask
+   the user a question — wrong ask-behaviour breaks the agent's core
+   contract with the user, so `ask-when-uncertain` and
+   `no-cheap-questions` are first-class kernel members even though
+   they fire during deliberation, not strictly pre-send.)*
+
+All other rules → `compress-and-keep` (auto-tier) or migrate to
+skill / guideline per `rule-classification.md`.
+
+> **Council amendment (P1.4).** Criterion #3 originally read "must be
+> checked before the agent emits the next token". Sonnet 4.5 noted
+> this conflated pre-send (scanning the draft) with pre-act (gating
+> tool execution); split per #3a / #3b above. Criterion #5 surfaced
+> the ask-policy floor that the original four-gate test left as an
+> implicit consequence of #1+#4. Both amendments preserve the
+> existing 9-rule kernel set. See
+> `agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
+
+## § 2 — Empirical compression rate (pilot)
+
+Pilot picks (per P1.3 algorithm: shortest / median / longest of the 9
+always-rules in `rule-classification.md` § 3.1):
+
+| pilot | original | compressed | r | per-rule cap (2.5k) | Iron-Law SHA |
+|---|---:|---:|---:|---|---|
+| agent-authority   | 1217 | 1020 | 0.838 | OK        | match (`e3b0c442…`) |
+| direct-answers    | 3991 | 2841 | 0.712 | +341 over | match (`ef438530…`) |
+| language-and-tone | 5318 | 3602 | 0.677 | +1102 over | match (`c017b26f…`) |
+
+| statistic | value |
+|---|---:|
+| mean r (outlier-skewed by lean pilot) | 0.742 |
+| **median r** (locked for projection) | **0.712** |
+| max r (already-lean floor) | 0.838 |
+| min r (most compressible) | 0.677 |
+
+Locked `r = 0.712` (median) for P2.2 projection. Council amendment
+(P1.4) — the original lock was the **mean** (0.742), but Sonnet 4.5
+flagged outlier skew: `agent-authority` at 1217 chars pre-pilot was
+already near the compression floor (`r = 0.838`), pulling the mean
+above the typical band. Median (0.712) is robust to the lean
+outlier and sits inside the roadmap-stated 0.6–0.75 band. Risk
+asymmetry confirms the choice: under-estimating compressed size
+blows the 25k cap mid-P2.2 (no abort path); over-estimating just
+yields headroom. GPT-4o concurred. Source:
+`agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
+
+**Pilot caveat — already-lean floor.** `agent-authority` (1217 chars
+pre-pilot) yielded only `r = 0.838`. Pre-compressed rules give less
+back; rules > 3k chars give more back. Future kernel additions
+≤ 1.5k chars should not assume the median — they may already be at
+floor.
+
+**Iron-Law preservation verified.** All three pilot SHAs match the
+originals (whitespace-normalised, case-folded, fence content only).
+
+## § 3 — Projection & demotion log
+
+Algorithm (per roadmap P1.3): `projected = current × r`; if sum > 25k,
+demote largest projected, re-sum; abort after 3 rounds.
+
+| round | candidates | sum-of-current | sum-of-projected (× 0.712) | budget |
+|---:|:--|---:|---:|---|
+| 0 | all 9 always-rules | 32403 | **23071** | ≤ 25 000 ✓ |
+
+**Result: 0 demotions fired.** All 9 always-rules stay in the kernel
+under median projection. Headroom = 1929 chars (= ~one median rule)
+absorbs pilot variance for the 6 untested rules.
+
+## § 4 — Locked kernel set
+
+| id | current | projected (× 0.712) | inclusion criterion |
+|---|---:|---:|---|
+| agent-authority           | 1217 |  867 | (4) cross-cutting router-of-routers † |
+| ask-when-uncertain        | 4096 | 2916 | (1)(5) Iron Law + ask-policy floor |
+| commit-policy             | 2972 | 2116 | (1)(2) safety-floor Iron Law |
+| direct-answers            | 3991 | 2842 | (1)(3a) three Iron Laws, pre-send gate |
+| language-and-tone         | 5318 | 3786 | (1)(3a) language-mirror, pre-send gate |
+| no-cheap-questions        | 3875 | 2759 | (1)(2)(5) ask-policy floor |
+| non-destructive-by-default| 4222 | 3006 | (1)(2)(3b) safety-floor Hard Floor |
+| scope-control             | 4368 | 3110 | (1)(3b) safety-floor permission gate |
+| verify-before-complete    | 2344 | 1669 | (1) completion-claim gate (post-act, pre-claim) ‡ |
+| **total**                 | **32403** | **23071** | **≤ 25 000** ✓ |
+
+### § 4.1 — Post-P2.2 locked kernel (empirical, 2026-05-06)
+
+P2.2 applied compression (imperative rewrite, examples → guidelines,
+rationale → contexts) + verified Iron-Law fence preservation.
+Empirical r=0.795 (vs 0.712 projected). Bucket cap raised 25k → 26k
+via `docs/decisions/ADR-002-kernel-bucket-overrides.md`. Six rules
+sit in the override band (≤ 4k ceiling).
+
+| id | post-P2.2 chars | r_actual | Iron-Law SHA-256 (normalised) | per-rule status |
+|---|---:|---:|---|---|
+| agent-authority           | 1020 | 0.838 | `e3b0c44298fc1c14…` (no fence) | OK ≤ 2.5k |
+| ask-when-uncertain        | 3130 | 0.764 | `6376ee72bbfd1eba…` | override (ADR-002) |
+| commit-policy             | 2354 | 0.792 | `e55af7f8a8053…` | OK ≤ 2.5k |
+| direct-answers            | 2841 | 0.712 | `ef4385308f52a8e4…` | override (ADR-002) |
+| language-and-tone         | 3602 | 0.677 | `c017b26f80c7aa01…` | override (ADR-002) |
+| no-cheap-questions        | 3238 | 0.836 | `86e023bee76a0a49…` | override (ADR-002) |
+| non-destructive-by-default| 3420 | 0.810 | `17e6ed8b418d9c49…` | override (ADR-002) |
+| scope-control             | 3641 | 0.834 | `03afe036755c8046…` | override (ADR-002) |
+| verify-before-complete    | 2344 | 1.000 | `abc942cf369ed60e…` | warn (> 2k target, ≤ 2.5k cap) |
+| **total**                 | **25590** | **0.795** | — | **≤ 26 000** ✓ |
+
+Acceptance gates (P2.2 § Equivalence):
+- ✅ `measure_rule_budget.py --kernel-budget-check` exits 0
+- ✅ `iron_law_sha.py --all-kernel` confirms byte-identical fence content for all 8 fence-bearing rules
+- ✅ `pytest tests/golden/` 29/29 green
+
+Future edits to any kernel rule must keep the Iron-Law SHA stable
+(or land a deliberate ADR-tracked SHA update). Cap re-raise requires
+a new ADR.
+
+† **agent-authority swap candidate (P1.4 ADR).** Sonnet 4.5 argues
+this is a routing index (zero Iron Law fences, dispatches to other
+kernel rules) and should be `compress-and-keep` (auto-tier-3),
+freeing 867 projected chars. The Council also recommends promoting
+`autonomous-execution` (5631 → 4009 projected) into kernel as a
+mode-independent Band-4 authority. Net effect: 23071 − 867 + 4009 =
+26213, **over the 25k cap by 1213 chars**. **Resolved by
+`docs/decisions/ADR-001-kernel-swap-deferred.md` (variant a):**
+status quo through P2.2 + P3.1, swap re-evaluated as a P3.2 ADR
+once the router schema and compiler ship.
+
+‡ **verify-before-complete borderline.** Council split criterion #3
+into pre-send (#3a) / pre-act (#3b); this rule fires post-act,
+pre-claim. Treated as Iron Law under criterion #1 alone (no #3
+flag). Demotion candidate if the swap above forces a third
+demotion round.
+
+## § 5 — ADR candidates (P2.1 input)
+
+Two distinct ADR classes land in P2.1 from this contract.
+
+### § 5.1 — Iron-Law-override ADRs (per-rule cap)
+
+**Council amendment (P1.4).** Per-rule cap raised from 1.5k to **2.5k**.
+Both Council members concurred — the original 1.5k figure forced 8 of
+9 kernel rules into ADR territory (process theatre, not governance).
+The 2.5k cap fits 7 of 9 rules without ADR; only the two largest
+remain as legitimate Iron-Law-density exceptions.
+
+Rules that land **above the 2.5k per-rule cap** even after compression
+and Iron-Law preservation:
+
+| rule | post-compression chars | over-cap (2.5k) | reason cap cannot be hit |
+|---|---:|---:|---|
+| direct-answers    | 2842 | +342  | Three Iron-Law fences (≈ 470 chars) + severity-tiered claim table required for invented-facts gate |
+| language-and-tone | 3786 | +1286 | Iron-Law fence + exhaustive user-visible-prose catalog + pre-send gate are co-load-bearing |
+| autonomous-execution* | 4009 | +1509 | (*if swap accepted per § 4 †) trivial-vs-blocking matrix + opt-in detection table |
+
+`*` = conditional on the agent-authority / autonomous-execution swap
+ADR (see § 5.2).
+
+Per roadmap § "Iron-Law over budget = ADR exception, not auto-
+compress" — these surface as `iron-law-override` exceptions for P2.1
+to gate behind ADRs in `docs/decisions/`.
+
+The remaining 6 always-rules project to 1669–2916 chars post-
+compression — all under the 2.5k cap with no ADR needed. P2.2
+measures the real post-compression sizes; if any breach the cap, an
+ADR lands per-rule.
+
+### § 5.2 — Kernel-set swap ADR (agent-authority ↔ autonomous-execution)
+
+Sonnet 4.5 flagged that `agent-authority` carries no Iron-Law fence
+(it is a routing index, not a governance rule) and that
+`autonomous-execution` does carry a mode-independent Band-4 authority
+that fires on every action decision. Swap proposal: `agent-authority`
+→ auto-tier-3 (router-loaded), `autonomous-execution` → kernel.
+
+| variant | sum-projected (× 0.712) | bucket budget | per-rule ADRs |
+|---|---:|---|---|
+| (a) status quo (current § 4)        | 23 071 | ✓ ≤ 25k | 2 (`direct-answers`, `language-and-tone`) |
+| (b) swap, raise hard cap to 27k     | 26 213 | ✓ ≤ 27k | 3 (+`autonomous-execution`) |
+| (c) swap + demote verify-before-complete | 24 545 | ✓ ≤ 25k | 3 (+`autonomous-execution`) |
+
+**Resolution: `docs/decisions/ADR-001-kernel-swap-deferred.md`
+(accepted variant a).** Status quo preserves the locked 25k cap and
+the 9-rule set through P2.2. Re-evaluation trigger fires at P3.2
+once the router schema and compiler ship; at that point
+`agent-authority`'s routing role becomes redundant (each kernel rule
+carries its own band as frontmatter, compiled into `router.json`),
+clearing the way for the swap under a fresh ADR.
+
+## § 6 — Abort criteria for P2.2
+
+**Council amendment (P1.4).** Sonnet 4.5 flagged that P2.2 compresses
+in place with no defined abort path. The following triggers force
+revert + re-projection rather than mid-phase scramble:
+
+- **Iron-Law drift.** Any kernel rule loses Iron-Law SHA equivalence
+  after compression (whitespace-normalised, case-folded fence-block
+  content). Single occurrence aborts the rule's compression.
+- **Bucket overflow.** Kernel sum post-compression > 27 500 chars
+  (10 % over hard cap). Aborts the entire P2.2 phase.
+- **Single-rule runaway.** Any kernel rule post-compression
+  > 4 000 chars. Aborts that rule's compression; flag for ADR.
+- **Empirical r drift.** Median of measured r across the first 4
+  compressed rules deviates > 0.10 from the locked 0.712 (i.e.,
+  measured median outside [0.612, 0.812]). P2.2 pauses, re-locks r,
+  re-runs § 3 projection.
+
+On abort: revert all P2.2 edits in scope, re-run P1.3 projection
+with the trigger-relaxed parameter, lock new value, re-attempt.
+
+## § 7 — Verification
+
+| check | command | acceptance |
+|---|---|---|
+| Pilot reproducibility | `python3 scripts/_pilot_measure.py` | r-values, sum, SHAs identical across runs |
+| Iron-Law preservation | SHA-256 of fence-block content (whitespace-norm, case-fold) | all 3 pilots match originals |
+| Bucket projection | `r_median × sum(always)` | ≤ 25 000 chars |
+| Per-rule cap (P2.1) | `measure_rule_budget.py --kernel-budget-check` (P2 deliverable) | each ≤ 2 500 chars OR ADR |
+
+## § 8 — What this contract does NOT do
+
+- It does **not** edit any source rule. P2.2 ships compression to
+  `.agent-src.uncompressed/rules/`.
+- It does **not** lock per-rule `chars` (only the bucket sum). Per-
+  rule values are projections; P2.2 measures real post-compression.
+- It does **not** decide kernel additions. Adding a rule to the
+  kernel requires an ADR per roadmap § "Sequencing-drift time-box"
+  and re-runs P1.3 with the new candidate.
+- It does **not** specify P3 router state-machine primitives
+  (once / every-turn / on-mode-switch). Council flagged this as a
+  P3.1 deliverable dependency before any P4 migration ships.
+- It does **not** specify P4 migration shapes (replace / merge /
+  stub / disappear). Council flagged this as a P4 deliverable spec.
+
+## § 9 — Provenance
+
+| date | source | scope |
+|---|---|---|
+| 2026-05-06 | `scripts/measure_rule_budget.py` | baseline (32 403 chars across 9 always-rules) |
+| 2026-05-06 | `docs/contracts/pilot/*.md` + `scripts/_pilot_measure.py` | empirical r distribution (3 pilots) |
+| 2026-05-06 | `agents/council-sessions/20260506T044821Z-phase1-cross-check.json` | Council R1 (truncated at 1024 tokens) | <!-- council-ref-allowed: contract decision trace -->
+| 2026-05-06 | `agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json` | Council R2 (3500 tokens) — locks median r, splits criterion #3, adds criterion #5, raises per-rule cap to 2.5k, defines abort criteria | <!-- council-ref-allowed: contract decision trace -->
+| 2026-05-06 | this file | kernel set locked: 9 rules, projected 23 071 chars (median r = 0.712) |
+| 2026-05-06 | P2.2 compression + `scripts/iron_law_sha.py --all-kernel` | empirical: 25 590 chars (r_actual = 0.795 across kernel; longer rules compress less than the pilot median) — see `docs/decisions/ADR-002-kernel-bucket-overrides.md` (KERNEL_HARD raised 25k → 26k, 6 per-rule overrides ≤ 4k ceiling, all Iron-Law SHAs preserved) |

package/docs/contracts/load-context-schema.md

@@ -25,13 +25,21 @@ Two keys, both optional, both top-level frontmatter:
 type: "always"
 description: "..."
 load_context:                # lazy — on-demand reference list
-  - .agent-src.uncompressed/contexts/<file>.md
-  - agents/contexts/<file>.md
+  - contexts/<area>/<file>.md         # logical name (canonical)
+  - agents/contexts/<file>.md         # project-local
 load_context_eager:          # opt-in eager — auto-loaded on rule fire
-  - .agent-src.uncompressed/contexts/<file>.md
+  - contexts/<area>/<file>.md
 ---
 ```
 
+> **Logical names only.** The `.agent-src.uncompressed/` prefix is
+> rejected by the schema regex (`scripts/schemas/rule.schema.json`) and
+> by `scripts/lint_load_context.py`. The compress-time rewriter
+> (`scripts/compress.py::_rewrite_paths`) resolves logical names to the
+> deployment-correct relative path (e.g. `../contexts/<area>/<file>.md`
+> for a rule at `rules/<name>.md`). The full migration history lives
+> in the archived path-fixes roadmap under `agents/roadmaps/archive/`.
+
 | Key | Loading | When to use |
 |---|---|---|
 | `load_context:` | **Lazy.** The agent reads the entry only when the rule's reasoning needs it. | Default. Use for everything that is "available knowledge" rather than "on every turn". |
@@ -43,15 +51,22 @@ opt-in and budget-gated.
 
 ## Path rules
 
-- Paths are repo-root relative.
+- Logical names rooted at the source. The rewriter resolves them at
+  compress time.
 - Paths MUST end in `.md`.
-- Allowed roots: `.agent-src.uncompressed/contexts/`, `agents/contexts/`,
-  `.agent-src/contexts/` (compressed mirror). Any other root → linter
-  error.
-- A rule MAY reference contexts under either tree, but a
-  `.agent-src.uncompressed/` rule SHOULD NOT eager-load an
-  `agents/contexts/` file (project-local leak into shared package).
-  Linter warns on this combination.
+- Allowed roots:
+  - `contexts/<area>/<file>.md` — canonical logical name (resolves
+    against `.agent-src.uncompressed/`).
+  - `agents/contexts/<file>.md` — project-local material (consumer
+    repo only).
+  - `.agent-src/contexts/<file>.md` — compressed mirror; tolerated
+    defensively, not authored.
+- The `.agent-src.uncompressed/` prefix is **rejected** by the schema
+  regex and by `lint_load_context.py` with a remediation hint pointing
+  at the canonical logical name.
+- A rule MAY reference contexts under either tree, but a package-shipped
+  rule SHOULD NOT eager-load an `agents/contexts/` file (project-local
+  leak into shared package). Linter warns on this combination.
 - A context file may itself declare `load_context:` (chain reasoning).
   The linter rejects cycles.
 

package/docs/contracts/pilot/agent-authority.md

@@ -0,0 +1,24 @@
+---
+type: "always"
+tier: "3"
+description: "Priority Index for the four authority rules — Hard Floor → Permission Gate → Commit Default → Trivial-vs-Blocking; read first, route to canonical rule"
+alwaysApply: true
+source: package
+---
+
+# Agent Authority — Priority Index
+
+Four rules answer **"may the agent do this autonomously?"** Higher band wins.
+
+| Band | Trigger | Canonical rule |
+|---|---|---|
+| **1. Hard Floor** | Prod-trunk merge · deploy · push · prod data/infra · whimsical bulk deletion · bulk-deletion or infra commit | [`non-destructive-by-default`](non-destructive-by-default.md) |
+| **2. Permission Gate** | Git op · branch / PR / tag · architectural or library change · scope expansion | [`scope-control`](scope-control.md) |
+| **3. Commit Default** | About to commit — never, unless one of four exceptions fires | [`commit-policy`](commit-policy.md) |
+| **4. Trivial-vs-Blocking** | Routine workflow question — act or ask | [`autonomous-execution`](autonomous-execution.md) |
+
+## Rules
+
+- Hard Floor wins, always — autonomy / roadmap / standing instruction never lift.
+- Higher band wins on conflict — commit exception ≠ Hard Floor override; scope permission ≠ commit override.
+- Unsure → [`ask-when-uncertain`](ask-when-uncertain.md).

package/docs/contracts/pilot/direct-answers.md

@@ -0,0 +1,70 @@
+---
+type: "always"
+tier: "3"
+description: "Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default."
+alwaysApply: true
+source: package
+---
+
+# Direct Answers
+
+Three Iron Laws govern every reply.
+
+## Iron Law 1 — No Flattery
+
+```
+NEVER OPEN WITH "GREAT QUESTION", "FASCINATING", "EXCELLENT POINT".
+NEVER PRAISE THE USER'S IDEA TO MAKE THEM HAPPY.
+ANSWER THE SUBSTANCE. SHIP THE TRUTH.
+```
+
+- No positive-adjective opener about user / question / idea / work.
+- No subjective judgment on user code unless evaluation was asked.
+- "Good catch" / "you're right" only when literally true.
+- Mistakes — one-sentence acknowledge, switch behavior, no apology theatre.
+
+## Iron Law 2 — No Invented Facts (severity-tiered)
+
+```
+DO NOT CLAIM WHAT YOU HAVEN'T VERIFIED.
+THE MORE LOAD-BEARING THE CLAIM, THE HARDER YOU VERIFY.
+WHEN VERIFICATION IS NOT WORTH THE COST → ASK.
+```
+
+| Severity | Action |
+|---|---|
+| **High** — load-bearing (paths, signatures, versions, security, "this passes") | Verify with `view` / `grep` / `codebase-retrieval` / fresh output. Too expensive → ask. |
+| **Medium** — project-shape (conventions, file location) | One-tool-call verify, else hedge: *"I'd guess X — not checked"*. |
+| **Low** — well-known idioms | Inference OK; mark as inference if not 100% sure. |
+
+Override: "just guess" / "rough estimate" / "skip verify" → drop to Low for that turn.
+Examples + hedge patterns: [`asking-and-brevity-examples § severity`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--severity-tiered-claim-examples).
+
+## Iron Law 3 — Brevity by Default
+
+```
+THE SHORTEST REPLY THAT FULLY ANSWERS THE QUESTION IS THE RIGHT REPLY.
+LONG ANSWERS ARE A FAILURE MODE, NOT A SIGN OF EFFORT.
+```
+
+- Skip restating the question; skip "Let me…" intent announcements.
+- Skip explaining tool use — the call result speaks.
+- Skip post-hoc summary unless rechecking a decision.
+- Multi-step → bullets. One-true-answer → one sentence.
+
+Never overrides `user-interaction` (numbered options stay) or command-mandated steps.
+
+## Emoji Scope — functional markers only
+
+**Whitelist:** mode markers (`role-mode-adherence`); CLI status `❌` / `✅` / `⚠️`; roadmap checkboxes `[x]` / `[~]` / `[-]`.
+**Blacklist:** opening flair (✨, 🚀, 🎉, 💡, 🔥, 👍); empathy (❤️, 🤗, 😊); section dividers; reaction emojis. Unsure → blacklist.
+
+## Failure modes & examples
+
+Trigger phrases + correction pattern: [`asking-and-brevity-examples § failure-modes`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--failure-modes-the-user-will-call-out).
+Pattern Memory (wrong / right / why): [`direct-answers-demos`](../../docs/guidelines/agent-infra/direct-answers-demos.md).
+Outcome baseline: [`tests/golden/outcomes/direct_answers.json`](../../tests/golden/outcomes/direct_answers.json).
+
+## Interactions
+
+`language-and-tone` · `ask-when-uncertain` · `think-before-action` · `verify-before-complete` · `token-efficiency` · `user-interaction` (overrides brevity).

package/docs/contracts/pilot/language-and-tone.md

@@ -0,0 +1,63 @@
+---
+type: "always"
+tier: "3"
+description: "Language and tone — informal German Du, English code comments, .md files always English"
+alwaysApply: true
+source: package
+---
+
+# Language and Tone
+
+## Iron Law — mirror the user's language, ALWAYS
+
+```
+MIRROR THE LANGUAGE OF THE USER'S LAST/CURRENT MESSAGE. ALWAYS.
+THE FIRST TOKEN OF EVERY REPLY MUST BE IN THAT LANGUAGE.
+EVERY USER-VISIBLE TOKEN MUST BE IN THAT LANGUAGE — NO EXCEPTIONS.
+A REPLY IN THE WRONG LANGUAGE IS A RULE VIOLATION, NOT A SLIP.
+NO MOMENTUM EXCEPTION. NO TECHNICAL-CONTEXT EXCEPTION.
+NO "SWITCH MID-PARAGRAPH". NO "LAST 20 TURNS WERE ENGLISH".
+NO "INTER-TOOL COMMENT IS JUST A NOTE" EXCEPTION.
+```
+
+Trigger = user's last **chat message**. Not turn count, open file, roadmap, ticket, codebase, tool output, prior reply, or files just edited. Short German (`3`, `weiter`, `mach das`) after many English turns flips the reply to German.
+
+## User-visible prose — every token mirrors
+
+Applies to opening / closing line, **inter-tool commentary** (`Found it`, `Let me check`, `OK`, `Alright`, `Here's`, `So`), section headings, table headers and cells, bullet text, blockquote text, status lines, and the `Recommendation:` / `Empfehlung:` label under numbered-options blocks (per [`user-interaction`](user-interaction.md) Iron Law 1). Wrong label = violation.
+
+Stays in source language: code blocks, command output, file contents, quoted tool output, frontmatter keys, file paths, identifier names, log lines.
+
+## Pre-send gate — MANDATORY
+
+1. **Detect** — language of user's last chat message. Mixed → dominant; tie → German.
+2. **Scan** — every user-visible token per catalog above.
+3. **Rewrite** — wrong-language token → rewrite the whole reply.
+4. **Confirm** — first sentence in target language; recommendation label matches; no English filler-phrase opener (`Let me`, `Now`, `Found`, `Confirmed`, `OK`, `Alright`, `Here's`, `So`) when target is German; no German opener (`Lass mich`, `Jetzt`, `Gefunden`, `Bestätigt`) when target is English.
+
+## Spelled out
+
+- German → informal "Du" (never "Sie"); capitalized at sentence start, lowercase otherwise.
+- Code blocks / command output / file contents / quoted tool output stay native; only surrounding prose mirrors.
+- Numbered options — `.md` source English; rendered reply translated at runtime.
+
+## Slip handling
+
+Acknowledge **once** in the correct language ("Entschuldigung" / "Sorry"). Switch on the same reply. No re-explain in wrong language; no "from now on" promise.
+
+Examples + wrong-vs-correct: [`language-and-tone-examples`](../../docs/guidelines/agent-infra/language-and-tone-examples.md).
+
+## Other language rules
+
+- Code comments in English.
+- `.md` files in English (see below). Translate existing German `.md` files when touched.
+- Two spaces after `❌`, `✅`, `⚠️` in CLI; one space for other icons.
+- One blank line max; no double/triple blanks. File ends with exactly one newline.
+
+## `.md` files — ALWAYS English
+
+Every text inside `.md` under `.augment/`, `.agent-src/`, `.agent-src.uncompressed/`, `agents/`: headings, paragraphs, bullets, option labels, prompts, placeholders, ASCII labels, table headers / content. Agent translates at runtime.
+
+**Labeled-anchor exception** — quoting German inside English prose is forbidden. Either translate, OR use a labeled `DE: … · EN: …` anchor block (only allowed location for German prose).
+
+**Detection heuristic** before saving: scan for umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) outside fenced code / paths / 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. Hit → translate or move to `DE: … · EN: …` block.