@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/rules/cli-output-handling.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 alwaysApply: false
-description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer"
+description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk when installed; tail/grep is fallback."
 source: package
 ---
 
@@ -10,11 +10,33 @@ source: package
 Loaded when actively working with code, tests, quality tools, CLI, or analysis.
 For communication and response style rules → see the always-loaded `token-efficiency` rule.
 
+## Iron Law — rtk first, tail/grep fallback
+
+```
+IF `rtk` IS INSTALLED, WRAP VERBOSE COMMANDS WITH rtk.
+USE tail / grep / cat ONLY AS FALLBACK WHEN rtk HAS NO MATCHING SUBCOMMAND.
+NEVER PIPE A STILL-RUNNING LONG COMMAND THROUGH tail — IT BUFFERS TO EOF.
+```
+
+Detection: `rtk_installed: true` in `.agent-settings.yml`, or `which rtk`
+exits 0. Caching the result for the session is fine.
+
+| Verbose command | Use | Fallback (no rtk) |
+|---|---|---|
+| CI-style suites, full test runs | `rtk err <cmd>` — only errors/warnings | redirect → tail → grep |
+| Unit tests | `rtk test <cmd>` — only failures | redirect → tail → grep |
+| `git status`/`log`/`diff` | `rtk git <subcmd>` | plain |
+| `gh pr list`, `gh run view` | `rtk gh <subcmd>` | plain |
+| Generic noisy command | `rtk summary <cmd>` or `rtk err <cmd>` | redirect → tail |
+
+For the full rtk subcommand catalog and project-local filter setup → see
+the `rtk-output-filtering` skill.
+
 ## Codebase Navigation
 
 ### Use what you already have
 
-- Edited a file → `str-replace-editor` showed the result. Skip re-reading.
+- Edited a file → the edit tool already returned the result. Skip re-reading.
 - Ran a command → you have the output. Skip re-running to "verify".
 - File in context from recent messages → skip reloading.
 - Found a symbol → use it. Skip searching again differently.
@@ -38,9 +60,10 @@ For communication and response style rules → see the always-loaded `token-effi
 - **`view_range`** when you know the exact lines.
 - **One `codebase-retrieval` call** with all symbols — batch, not 5 separate calls.
 
-## Pattern: Redirect, Summarize, Target
+## Fallback Pattern: Redirect, Summarize, Target
 
-Every command that MAY produce more than ~30 lines of output:
+When `rtk` has no matching subcommand for the tool at hand, fall back to
+this pattern. Every command that MAY produce more than ~30 lines of output:
 
 ### Step 1: Redirect to file
 ```bash

package/.agent-src/rules/command-suggestion.md

@@ -0,0 +1,134 @@
+---
+type: "always"
+description: "Surface matching slash commands as numbered options when user intent matches a command's purpose — never auto-executes; user always picks (read-only suggestion layer)."
+alwaysApply: true
+source: package
+---
+
+# Command Suggestion
+
+When the user's prompt matches an eligible slash command, surface it
+as a **numbered option** alongside an "as-is" escape hatch. The user
+always picks. **Nothing auto-executes.** The suggestion layer is a
+read-only shortcut *finder*, not an invocation path.
+
+The deterministic engine lives in `scripts/command_suggester/`. The
+locked eligibility table lives in
+[`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md).
+The full design lives in
+[`road-to-context-aware-command-suggestion`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md).
+
+## Iron Law — never auto-execute
+
+```
+SUGGEST. NEVER INVOKE. THE USER PICKS, ALWAYS.
+```
+
+A suggestion block emits options. It does **not** start a command
+flow. The user picking option N triggers `slash-commands` on the
+**next** turn — with all the command's own halts intact.
+
+## When to fire
+
+On a user turn that matches **all** of the following:
+
+1. The message does **not** start with an explicit `/command` (those
+   bypass suggestion entirely — see `slash-commands`).
+2. `commands.suggestion.enabled` is `true` (default).
+3. The user has not issued `/command-suggestion-off` in this conversation.
+4. No clarification is owed for the same turn (per
+   `ask-when-uncertain` — clarification wins; suggestion can fire next turn).
+5. No active engine flow is mid-halt (e.g. an `/implement-ticket`
+   step waiting on the user — the active flow has the floor).
+6. The matcher returns at least one match above the effective
+   `confidence_floor` after rank + cooldown + anti-noise.
+
+When all six hold, the suggestion block is the **first and only**
+thing the agent emits that turn. No tools, no edits, no other prose.
+
+## What to emit
+
+Render exactly one numbered-options block conforming to
+`user-interaction`:
+
+```
+> 💡 Your request matches a command. Pick one or run the prompt as-is:
+>
+> 1. /implement-ticket — drive ticket end-to-end through refine → plan → implement → test
+> 2. /refine-ticket — tighten the AC and risks on a ticket before planning
+> 3. Just run the prompt as-is, no command
+
+**Recommendation: 1 — /implement-ticket** — the request matches its trigger description (`setze ticket abc-123 um`). Pick the last option to skip the command and run the prompt as written.
+```
+
+Rules — non-negotiable:
+
+- The "run as-is" option is **always present**, **always last**, never removed.
+- At most `commands.suggestion.max_options` command suggestions
+  precede the as-is option (default 4 → 5 total).
+- Exactly **one** `Recommendation:` line follows the block, naming
+  the highest-scoring command — or no recommendation when the top
+  two scores are within 0.05 of each other (single-source-of-truth
+  Iron Law from `user-interaction`).
+- Free-text replies count as the as-is option unless they
+  unambiguously name one of the listed commands.
+
+## Subordination — when to stay silent
+
+The suggestion rule is **junior** to:
+
+- `scope-control` — never surfaces a git-op command behind a
+  permission gate the user already declined this turn.
+- `ask-when-uncertain` — if a clarification is owed, the
+  clarification is the only question; suggestion suppresses for
+  that turn.
+- `verify-before-complete` — suggestion does not interrupt an
+  evidence-gate verification that's already running.
+- Any active role-mode contract (`role-mode-adherence`).
+- Any active engine halt (`/implement-ticket`, `/work`, etc.).
+
+On any conflict → suggestion stays silent. Zero output. The user's
+prompt is processed as it would be without this rule.
+
+## Anti-noise — silent when uncertain
+
+The engine's `rank.py` already drops:
+
+- Matches below the `confidence_floor` (default 0.6, per-command
+  override in frontmatter).
+- Single matches scoring `< floor + 0.1` with no structural bonus
+  (high uncertainty isn't worth interrupting for).
+- Short prompts (< 6 words) hitting > 2 commands with no structural
+  bonus (ticket key, file path) — too vague to disambiguate.
+- Pure-continuation messages (`ok`, `weiter`, `mach weiter`, `go on`,
+  …) — no new intent signal, no structural bonus → silent.
+- Suggestions that fired for the same `(command, evidence)` pair
+  within the cooldown window (default 10m, per-command override).
+
+If the engine returns an empty list → emit nothing. The user's
+prompt runs exactly as it would without this rule.
+
+## What this rule does NOT do
+
+- Invoke any command. Picking option N is what triggers `slash-commands`.
+- Stack with other questions. One numbered-options block per turn.
+- Re-trigger on its own output. Command names emitted in the
+  suggestion block are excluded from the next-turn matcher input.
+- Override `enabled: false`, blocklist entries, or per-conversation opt-out.
+- Suggest commands that are not in the locked eligibility table.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the rule is **inert**
+unless the suggester package is shipped in the bundle. Treat
+`commands.suggestion.enabled` as `false` when the engine is not
+available — degrade silently, never crash the turn.
+
+## Interactions
+
+- [`slash-commands`](slash-commands.md) — explicit `/command` skips suggestion entirely.
+- [`user-interaction`](user-interaction.md) — numbered-options Iron Law and single-source recommendation.
+- [`ask-when-uncertain`](ask-when-uncertain.md) — clarification wins on conflict.
+- [`scope-control`](scope-control.md) — git-op gates outrank suggestion.
+- [`role-mode-adherence`](role-mode-adherence.md) — active mode contract outranks suggestion.
+- [`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md) — locked eligibility table.

package/.agent-src/rules/commit-policy.md

@@ -0,0 +1,109 @@
+---
+type: "always"
+description: "Commit policy — never commit and never ask about committing unless the user said so this turn, the roadmap authorizes it, or a commit command is invoked"
+alwaysApply: true
+source: package
+---
+
+# Commit Policy
+
+Local commits do not change remote state, but committing prematurely
+makes review harder. This is the **canonical** rule for committing,
+referenced by [`autonomous-execution`](autonomous-execution.md),
+[`scope-control`](scope-control.md), and the roadmap commands.
+
+## The Iron Law
+
+```
+NEVER COMMIT. NEVER ASK ABOUT COMMITTING.
+EXCEPTIONS ARE EXPLICIT, NOT INFERRED.
+```
+
+Applies regardless of `personal.autonomy`, conversation momentum, or
+"but it's a clean stopping point". Default is **no commit, no
+question**.
+
+## Exceptions — when committing IS allowed
+
+Exactly four ways the agent may commit:
+
+1. **User says so this turn** — explicit phrase like "commit this now",
+   "go ahead and commit". Permission is for **this commit only**, not
+   standing.
+2. **Standing instruction not yet revoked** — user said earlier in
+   the conversation "commit after every phase" or similar, and has not
+   revoked it. Cache and honor.
+3. **Commit command invoked** — `/commit` (with confirmation) or
+   `/commit-in-chunks` (auto-split, no confirmation).
+4. **Roadmap authorization** — the roadmap file lists explicit commit
+   steps and the user invoked roadmap execution. See
+   [Roadmap-authorized commits](#roadmap-authorized-commits) below.
+
+Anything else → no commit.
+
+## Hard Floor still applies — bulk deletions and infra changes
+
+Even when one of the four exceptions above authorizes a commit, the
+[`non-destructive-by-default`](non-destructive-by-default.md) Hard
+Floor still fires when the diff:
+
+- Removes a directory
+- Deletes ≥5 unrelated files
+- Touches Terraform / Pulumi / k8s manifests / Ansible / cloud-config
+
+In those cases, **surface the diff** (paths + counts) and confirm
+this turn before committing — even under `/commit-in-chunks`,
+roadmap pre-scan authorization, or an explicit "commit this now". The
+four exceptions cover *whether* commits happen; the Hard Floor covers
+*which diffs* still need a separate confirmation.
+
+## NEVER ask about committing
+
+Asking "should I commit this?", "do we want to commit?", or any
+variant is **forbidden**. The user invokes a command or says so
+explicitly. Don't surface a commit option in numbered-options blocks
+unless the rest of the message would be incomplete without it.
+
+The same speech-act check from [`autonomous-execution`](autonomous-execution.md#speech-act-check--the-phrase-must-be-a-meta-instruction-to-the-agent)
+applies in reverse: an explicit commit phrase inside a quote, code
+block, or content (e.g. a copy-paste of a chat log) is **not** a
+permission grant.
+
+## NEVER write commit steps into roadmaps unsolicited
+
+When **creating** a roadmap (via `/roadmap-create`,
+`/feature-roadmap`, or any roadmap-producing flow), do **not** include
+commit steps unless the user explicitly requested them. Commits are a
+delivery decision; roadmaps plan **work**.
+
+If the user explicitly wants commit steps in the roadmap, write them
+clearly and unambiguously (e.g. "Commit phase X: chore: …").
+
+## Roadmap-authorized commits
+
+When **executing** a roadmap that contains commit steps:
+
+- **Non-autonomous mode** (`personal.autonomy: off`, or `auto`
+  before opt-in) — agent may ask before each commit step. The user
+  authorized commits by writing them into the roadmap, but retains
+  step-level control.
+- **Autonomous mode** (`personal.autonomy: on`, or `auto` after
+  opt-in) — agent does a quick pre-scan of the roadmap **before
+  starting execution**. If commit steps are found, ask **once** at
+  the very start: "Roadmap contains N commit steps — should they be
+  executed?". After that, honor or skip per the answer.
+  No re-asking per step.
+
+The pre-scan ask is the **only** permitted commit-related question
+in autonomous mode. Once answered, the decision is cached for the
+rest of the roadmap execution.
+
+## See also
+
+- [`autonomous-execution`](autonomous-execution.md) — when to suppress
+  trivial questions; this rule survives the suppression.
+- [`scope-control`](scope-control.md) — git-ops permission gate
+  (push, merge, branch, PR, tag stay separately permission-gated).
+- [`/commit`](../commands/commit.md) — split and commit with confirmation.
+- [`/commit-in-chunks`](../commands/commit-in-chunks.md) — auto-split
+  and commit without confirmation.

package/.agent-src/rules/direct-answers.md

@@ -0,0 +1,114 @@
+---
+type: "always"
+description: "Always — direct, unembellished answers. No flattery, no invented facts (verify the load-bearing ones with tools, otherwise ask). Emojis only as functional markers — status, warning, mandated. Brevity is the default."
+alwaysApply: true
+source: package
+---
+
+# Direct Answers
+
+Three Iron Laws govern every reply. They override conversation
+momentum, politeness defaults, and the urge to fill space.
+
+## 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 adjectives about the user, their question, idea, or
+  work product as an opener.
+- No subjective judgments on the user's code, decisions, or work
+  products ("nice approach", "clean design", "boring") unless the
+  user asked for an evaluation.
+- "Good catch" / "you're right" only when literally true and
+  load-bearing for the answer.
+- Acknowledge mistakes without performative apologies. One sentence,
+  switch behavior.
+
+Failure mode: praise as a hedge before delivering bad news. Drop the
+cushion, deliver the news.
+
+## 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 | Examples | Required action |
+|---|---|---|
+| **High — load-bearing** | File paths, function/method signatures, version numbers, security claims, API contracts, "this test passes/fails", "this method exists" | MUST verify with tools (`view`, `grep`, `codebase-retrieval`, command output) before claiming. If too expensive → ask the user. |
+| **Medium — project-shape** | "This project uses X for Y", general conventions, file location guesses | Verify if one tool call reaches it; otherwise hedge explicitly ("I'd guess X — not checked"). |
+| **Low — well-known idioms** | Generic language/framework idioms, illustrative examples, well-documented public APIs | Inference acceptable. Mark as inference if not 100% sure. |
+
+User override: "just guess", "rough estimate is fine", "skip the
+verify" → drop to Low for that turn.
+
+Hedging language is explicit and short: "haven't verified X",
+"guess, not checked". Never bare "probably" / "vermutlich" without
+naming what's unverified.
+
+## 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 user's question.
+- Skip announcing intent ("Let me…", "I will now…"). Just do.
+- Skip explaining why a tool was used — the call result speaks.
+- Skip post-hoc summary unless the user must recheck a decision.
+- Multi-step work → bullet points, not paragraphs.
+- Question with one true answer → one sentence + the answer.
+
+`token-efficiency` covers the loop side (no repeated tool calls);
+this rule covers the per-reply-length side. **Never overrides**
+`user-interaction` (numbered options stay) or command-mandated
+steps — brevity ≠ skipping required questions.
+
+## Emoji Scope — Whitelist + Blacklist
+
+Emojis are **functional markers**, never decoration.
+
+**Whitelist — allowed and expected:**
+
+- Mandated markers from rules/scripts: `📒` (chat-history heartbeat,
+  verbatim per `chat-history-visibility`), mode markers from
+  `role-mode-adherence`.
+- CLI status icons: `❌`, `✅`, `⚠️` — two-space rule from
+  `language-and-tone` § other-language-rules still applies.
+- Roadmap status checkboxes: `[x]`, `[~]`, `[-]`.
+
+**Blacklist — never in the agent's own prose:**
+
+- Opening flair: ✨, 🚀, 🎉, 💡, 🔥, 👍.
+- Empathy signaling: ❤️, 🤗, 😊.
+- Section dividers / headline ornaments.
+- Reaction reactions to the user's message.
+
+If unsure whether a given emoji is functional → assume blacklist.
+
+## Failure modes the user will call out
+
+- "Great question, …" / "Das ist eine gute Frage" — Iron Law 1.
+- Stating a function name without `grep`/`view` — Iron Law 2.
+- Three paragraphs for a one-line answer — Iron Law 3.
+- ✨/🎉/💡 to mark "this is interesting" — emoji blacklist.
+
+When called out: acknowledge once in the user's language, switch,
+no excuses (mirrors `language-and-tone` § slip handling).
+
+## Interactions
+
+- `language-and-tone` — language mirroring, `.md` always English,
+  CLI-icon two-space rule.
+- `ask-when-uncertain` — resolution surface for Iron Law 2 gaps.
+- `think-before-action` — how to verify code-behavior claims.
+- `verify-before-complete` — completion-claim evidence gate.
+- `token-efficiency` — loop-side brevity.
+- `user-interaction` — numbered-options Iron Law overrides brevity.

package/.agent-src/rules/docs-sync.md

@@ -61,6 +61,42 @@ exist in `.augment/templates/agent-settings.md`:
 **This step is mandatory.** If the template gains a new key but the local `.agent-settings.yml`
 is not updated, the user cannot discover the new setting exists.
 
+## Distribution manifests and hook registries
+
+`.augment/`-internal sync (counts, contexts, cross-refs) is one half. The
+other half is **distribution manifests** that ship the package to consumers
+and **hook registries** that wire engine code into platform lifecycles.
+These are not auto-derived — they drift silently until CI catches them, and
+on cooperative platforms (no pre-commit) they can sit broken in a branch
+for hours.
+
+When a **skill** is added, renamed, or deleted under
+`.agent-src.uncompressed/skills/`:
+
+| Manifest | Required update |
+|---|---|
+| `.claude-plugin/marketplace.json` | Add/remove the `./.claude/skills/<name>` entry in `plugins[0].skills[]`, alphabetical position. Caught by `scripts/lint_marketplace.py` in CI. |
+| `.augment-plugin/marketplace.json` | Skill-name-agnostic — no update needed. Touch only when plugin metadata (description, tags) changes. |
+| `.github/plugin/marketplace.json` | Same as above — metadata-only manifest. |
+
+When a **hook** is added, renamed, or deleted under
+`.agent-src.uncompressed/templates/scripts/work_engine/hooks/builtin/`:
+
+| Registry | Required update |
+|---|---|
+| `templates/scripts/work_engine/hooks/builtin/__init__.py` | New hook class → add the import + `__all__` entry. Single source of truth for engine-side registration. |
+| `templates/consumer-settings/claude-settings.json` | Only when a **new platform event** is wired (e.g. first time a hook listens on `SessionEnd`). Existing hooks reuse the `./agent-config chat-history:hook --platform claude` dispatcher — no per-hook entry needed. |
+| `templates/consumer-settings/augment-cli-hooks.json` | Same logic — new platform event → new `command` block; new hook on existing event → no update. |
+
+Failure mode that motivated this section: a skill on disk without its
+`marketplace.json` entry passes local edits, builds, and tests — only
+CI catches it via `lint_marketplace`. The cooperative path is
+"agent updates the manifest in the same response as the skill"; the
+structural backstop is a pre-commit hook installed by
+`scripts/install-hooks.sh` that runs `lint_marketplace` on every
+commit. Run the installer once per clone; bypass for an unrelated WIP
+commit is `git commit --no-verify`.
+
 ## Content consistency
 
 **CRITICAL — MANDATORY CHECK:** When a rule, skill, or guideline's **content** is changed

package/.agent-src/rules/downstream-changes.md

@@ -7,6 +7,16 @@ source: package
 
 # Downstream Changes
 
+## The Iron Law
+
+```
+EVERY EDIT IS INCOMPLETE UNTIL ALL DOWNSTREAM CHANGES ARE MADE.
+MISSING A CALLER, A TEST, OR AN IMPORT IS A CRITICAL FAILURE.
+```
+
+Do NOT move on to the next task, claim completion, or suggest
+committing until every caller, test, import, and reference is updated.
+
 ## Rule
 
 After EVERY code edit, find **ALL downstream changes** needed. Missing a caller, a test,
@@ -59,12 +69,3 @@ After completing all downstream changes:
 2. **No broken tests** — run the test suite
 3. **No broken types** — PHPStan Level 9 catches signature mismatches
 4. **No stale references** — grep for the old name/namespace to confirm zero results
-
-## The iron law
-
-```
-Every edit is incomplete until all downstream changes are made.
-```
-
-Do NOT move on to the next task, claim completion, or suggest committing
-until every caller, test, import, and reference is updated.

package/.agent-src/rules/improve-before-implement.md

@@ -40,10 +40,11 @@ Before coding, quickly verify:
 - Does similar functionality already exist?
 - Does it follow established patterns in the codebase?
 - Does it contradict existing conventions?
-- Do **multiple valid patterns/frameworks** already exist (Tailwind + Flux, multiple form libs, competing state stores)? If yes → do NOT pick arbitrarily, ask.
+- Do **multiple valid patterns/frameworks** already exist (e.g. Tailwind + Flux, multiple form libraries, competing state stores)? If yes, do NOT pick one arbitrarily — ask which to use.
+- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`guidelines/php/patterns/strategy.md`](../guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
 
 **If misfit** → show evidence (file references), propose alternative.
-**If multiple valid options** → list them, ask which. See [`no blind implementation`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
+**If multiple valid options** → list them, ask which to use. See [`no blind implementation`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
 
 ### 3. Is the approach sound?
 
@@ -90,7 +91,9 @@ The agent is a thought partner, not a gatekeeper. After presenting concerns:
 
 ## Creating new agent artifacts
 
-For skill/rule/command/guideline creation or major rewrite, the architecture-fit
-check is handled by [`artifact-drafting-protocol`](artifact-drafting-protocol.md)
-Phase B (Research) — scans `.agent-src.uncompressed/` for overlap before
-creating a new file.
+When the request is to create or significantly rewrite a skill, rule, command,
+or guideline, the "fit the existing architecture" check above is handled by
+[`artifact-drafting-protocol`](artifact-drafting-protocol.md)'s Phase B
+(Research). Follow that protocol instead of improvising a one-shot check — it
+scans `.agent-src.uncompressed/` for overlap and reports candidates to extend
+before creating a new file.

package/.agent-src/rules/language-and-tone.md

@@ -10,20 +10,46 @@ source: package
 ## Iron Law — mirror the user's language, ALWAYS
 
 ```
-MIRROR THE LANGUAGE OF THE USER'S LAST MESSAGE. ALWAYS.
-BEFORE SENDING ANY REPLY, RUN THE PRE-SEND GATE BELOW.
+MIRROR THE LANGUAGE OF THE USER'S LAST/CURRENT MESSAGE. ALWAYS.
+THE FIRST TOKEN OF EVERY REPLY MUST BE IN THAT LANGUAGE.
 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".
 ```
 
-**Overrides** conversation momentum, tool-output habits, convenience.
-First thing to check on every reply, last thing to check before sending.
+**Overrides** conversation momentum, tool-output habits, prior-reply
+language, codebase language, open-file language, files-just-edited
+language, convenience. First thing to check on every reply, last thing
+to check before sending.
+
+Canonical failure: agent edited English `.md` for many turns; user
+types short German (`3`, `weiter`, `mach das`, `und jetzt X`); agent
+answers English because momentum wins. **Trigger is the user's last
+message, not the turn count.** Length irrelevant — `3` after a German
+question still means German continues.
+
+### Source of language truth — chat messages ONLY
+
+```
+THE LANGUAGE SIGNAL IS THE USER'S CHAT MESSAGES. NOTHING ELSE.
+OPEN FILES, ROADMAPS, .md CONTENT, TOOL OUTPUT, CODE, COMMIT MESSAGES,
+TICKETS, PR DESCRIPTIONS, FILE NAMES — NONE OF THEM COUNT.
+```
+
+`.md` files in this repo are English by rule (see below) — that says
+nothing about chat language. Same for: file contents read via `view` /
+`grep`, quoted commits / tickets / PRs / branches, code identifiers,
+the agent's own previous replies. Only the most recent **chat message**
+sets the language. User opens an English roadmap and types German →
+reply in German.
 
 ### Pre-send gate — MANDATORY before every reply
 
 Run silently **before** emitting any tokens:
 
-1. **Detect** — language of user's last message.
-   German signals: "ich", "Du", "nicht", "warum", "wie", "ist", umlauts.
+1. **Detect** — language of user's last **chat message** (not the open
+   file, not the roadmap, not the prior reply).
+   German signals: "ich", "Du", "nicht", "warum", "wie", "ist", umlauts. <!-- md-language-check: ignore -->
    English signals: "I", "you", "is", "the", "how".
    Mixed → mirror the **dominant** language; tie → German wins (project default).
 2. **Check** — is drafted prose (not code, not file contents) in that language?
@@ -66,6 +92,10 @@ Run silently **before** emitting any tokens:
   code identifiers as-is; translate everything else.
 - Assuming English because "the codebase is English" — codebase language ≠
   conversation language.
+- Mirroring the **open file** the IDE reports — open files are background
+  context, not chat messages.
+- Mirroring the **roadmap or ticket** being executed — artefacts are English
+  by `.md` rule; chat language is whatever the user wrote.
 
 ## Other language rules
 
@@ -102,3 +132,52 @@ The `.md` source files are the English blueprint — they define WHAT to say, no
 > 1. Interactive — ask before each comment
 > 2. Automatic — handle all independently
 ```
+
+### Quoted user-input examples — same rule, with one labeled exception
+
+Common drift pattern: a rule documents trigger phrases the agent
+should recognize and writes them as quoted German examples inside
+English prose. **Not allowed**, even when demonstrative.
+
+**Wrong** (DE quote embedded in EN prose):
+
+```md
+Single-decision delegation ("für diesen Schritt entscheide du") →
+handle that step autonomously.
+
+A standing "arbeite selbstständig" never lifts the floor.
+```
+
+**Correct** — two ways:
+
+1. **Translate to English.** Trigger recognition is semantic; the
+   agent matches intent across languages regardless of the example.
+   `("you decide for this step")` works as well as the German.
+2. **Use a labeled `DE: … · EN: …` anchor list** when the
+   multilingual nature of recognition is the point:
+
+   ```md
+   - DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
+   - EN: "work autonomously" · "don't ask" · "just do it"
+   ```
+
+The labeled-anchor block is the **only** allowed location for German
+prose 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.
+
+### Detection heuristic
+
+Before saving an `.md` file under `.augment/`, `.agent-src/`,
+`.agent-src.uncompressed/`, or `agents/`, scan for:
+
+- Umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) outside fenced code,
+  file paths, and the labeled anchor block.
+- German function words in unquoted prose: `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 (paragraphs, list items,
+  table cells) when the surrounding prose is English.
+
+Hit → translate the fragment or move it into a `DE: … · EN: …` block.