@event4u/agent-config 1.20.0 → 1.22.0

package/.agent-src/contexts/authority/scope-mechanics.md

@@ -35,6 +35,11 @@ concerns:
 A roadmap step or earlier turn does **not** count as authorization
 for these. Authorization is "the user said so on this turn".
 
+Earlier permission for a different operation does **not** carry over —
+permission is per-operation, this-turn. Standing autonomy directives
+narrow other rules but never grant permission for items in this Hard
+Floor subset.
+
 ## Brief-before-asking — separate branch / PR / worktree
 
 If a task seems to need a separate branch or PR (spike, hotfix,

package/.agent-src/contexts/communication/rules-auto/guidelines-mechanics.md

@@ -0,0 +1,76 @@
+# Guidelines — index
+
+Full table of available coding guidelines for the
+[`guidelines`](../../../rules/guidelines.md) rule. The rule body
+holds the obligation surface (always check the relevant guideline
+before writing or reviewing code); this file is the catalog.
+
+## PHP (`docs/guidelines/php/`)
+
+| File | Topic |
+|---|---|
+| `php.md` | General PHP style — strict types, naming, comparisons, early returns, JSON handling |
+| `controllers.md` | Thin controllers, single responsibility, delegation to services |
+| `eloquent.md` | Model conventions, relationships, scopes, accessors/mutators |
+| `validations.md` | FormRequest patterns, custom rules, validation structure |
+| `resources.md` | API Resource conventions, response structure |
+| `jobs.md` | Queue job patterns, serialization, retry strategies |
+| `git.md` | Branch naming, commit messages, PR conventions |
+| `api-design.md` | API conventions — response format, status codes, pagination, error handling |
+| `artisan-commands.md` | Console command conventions — naming, structure, safety, scheduling |
+| `blade-ui.md` | Blade template conventions — views, components, forms, escaping |
+| `database.md` | Database conventions — indexing, query optimization, migrations, transactions |
+| `flux.md` | Flux UI component conventions — usage, variants, forms, Livewire integration |
+| `livewire.md` | Livewire component conventions — state, actions, forms, performance, Alpine.js |
+| `logging.md` | Logging conventions — levels, structured context, Sentry patterns |
+| `naming.md` | Naming conventions — classes, database, routes, variables, modules, agent infra |
+| `performance.md` | Performance conventions — caching, Redis, eager loading, response time targets |
+| `security.md` | Security conventions — auth, authorization, SQL injection, XSS, CSRF, headers |
+| `sql.md` | Raw SQL conventions — parameterization, MariaDB syntax, common mistakes |
+| `websocket.md` | WebSocket conventions — Broadcasting, channel types, connection management |
+| `patterns.md` | Design patterns index (links to `patterns/` subdirectory) |
+
+## PHP Patterns (`docs/guidelines/php/patterns/`)
+
+| File | Pattern |
+|---|---|
+| `service-layer.md` | Service classes, business logic encapsulation |
+| `repositories.md` | Repository pattern, query encapsulation |
+| `dtos.md` | Data Transfer Objects, SimpleDto conventions |
+| `dependency-injection.md` | Constructor injection, service container |
+| `events.md` | Event/Listener patterns, dispatching |
+| `policies.md` | Authorization policies, gate definitions |
+| `factory.md` | Factory pattern usage |
+| `pipelines.md` | Laravel Pipeline pattern |
+| `strategy.md` | Strategy pattern implementation |
+
+## E2E (`docs/guidelines/e2e/`)
+
+Playwright best practices, Page Objects, fixtures, CI.
+
+## Agent Infrastructure (`docs/guidelines/agent-infra/`)
+
+| File | Topic |
+|---|---|
+| `size-and-scope.md` | Size limits and scope boundaries for rules, skills, commands, guidelines, AGENTS.md, copilot-instructions.md |
+| `output-patterns.md` | Redirect / Summarize / Target pattern, targeted operations, tool-first policy, general CLI rules |
+
+## Boundary: Guidelines vs Skills
+
+- Guidelines contain **conventions and reference knowledge**. Skills
+  contain **executable workflows**.
+- A skill MAY reference a guideline for conventions, but MUST NOT
+  outsource its core execution steps to a guideline.
+- Do NOT move a skill's operational core (procedure, validation,
+  decision logic) into a guideline.
+- A skill that becomes "go read the guideline" has lost its purpose
+  — restore the workflow.
+
+## Adding new guidelines
+
+When a new language or framework is introduced, create a directory:
+
+    docs/guidelines/{language}/
+
+Follow the existing PHP structure as a template. Read the specific
+guideline file on demand — don't memorize the full list.

package/.agent-src/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md

@@ -4,46 +4,81 @@ Lookup table for the `slash-command-routing-policy` rule. Lists the
 locked clusters and their sub-commands so the rule itself can stay at
 its current LOC while still reflecting the full surface. Source of
 truth for the cluster names is
-[`docs/contracts/command-clusters.md`](../../../../docs/contracts/command-clusters.md);
+[`docs/contracts/command-clusters.md`](../../../../../docs/contracts/command-clusters.md);
 this file mirrors that contract for runtime lookup. Linter:
 `scripts/check_cluster_patterns.py` (verifies dispatcher shape).
 
 ## Locked clusters and sub-commands
 
-| Cluster | Phase | Sub-commands | Replaces |
-|---|:-:|---|---|
+| Cluster | Phase | Sub-commands | Replaces                                                                                                                                        |
+|---|:-:|---|-------------------------------------------------------------------------------------------------------------------------------------------------|
 | `/fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `/fix-ci` · `/fix-pr-comments` · `/fix-pr-bot-comments` · `/fix-pr-developer-comments` · `/fix-portability` · `/fix-references` · `/fix-seeder` |
-| `/optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills` |
-| `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap` |
-| `/chat-history` | 2 | `show` | `/chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` |
-| `/agents` | 2 | `audit` · `cleanup` · `prepare` | `/agents-audit` · `/agents-cleanup` · `/agents-prepare` |
-| `/memory` | 2 | `add` · `load` · `promote` · `propose` | `/memory-add` · `/memory-full` · `/memory-promote` · `/propose-memory` |
-| `/roadmap` | 2 | `create` · `execute` | `/roadmap-create` · `/roadmap-execute` |
-| `/module` | 2 | `create` · `explore` | `/module-create` · `/module-explore` |
-| `/tests` | 2 | `create` · `execute` | `/tests-create` · `/tests-execute` |
-| `/context` | 2 | `create` · `refactor` | `/context-create` · `/context-refactor` |
-| `/override` | 2 | `create` · `manage` | `/override-create` · `/override-manage` |
-| `/copilot-agents` | 2 | `init` · `optimize` | `/copilot-agents-init` · `/copilot-agents-optimize` |
-| `/judge` | 2 | `solo` · `on-diff` · `steps` | `/judge` (legacy standalone) · `/do-and-judge` · `/do-in-steps` |
-| `/commit` | 2 | flag: `--in-chunks` | `/commit:in-chunks` |
-| `/create-pr` | 2 | flag: `--description-only` | `/create-pr:description-only` |
+| `/optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills`                                                   |
+| `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap`                                                                 |
+| `/chat-history` | 2 | `show` | `/chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only`                                 |
+| `/agents` | 2 | `audit` · `cleanup` · `prepare` | `/agents-audit` · `/agents-cleanup` · `/agents-prepare`                                                                                         |
+| `/memory` | 2 | `add` · `load` · `promote` · `propose` | `/memory-add` · `/memory-full` · `/memory-promote` · `/propose-memory`                                                                          |
+| `/roadmap` | 2 | `create` · `process-step` · `process-phase` · `process-full` | `/roadmap-create` · `/roadmap-process` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope)                |
+| `/module` | 2 | `create` · `explore` | `/module-create` · `/module-explore`                                                                                                            |
+| `/tests` | 2 | `create` · `execute` | `/tests-create` · `/tests-execute`                                                                                                              |
+| `/context` | 2 | `create` · `refactor` | `/context-create` · `/context-refactor`                                                                                                         |
+| `/override` | 2 | `create` · `manage` | `/override-create` · `/override-manage`                                                                                                         |
+| `/copilot-agents` | 2 | `init` · `optimize` | `/copilot-agents-init` · `/copilot-agents-optimize`                                                                                             |
+| `/judge` | 2 | `solo` · `on-diff` · `steps` | `/judge` (legacy standalone) · `/do-and-judge` · `/do-in-steps`                                                                                 |
+| `/commit` | 2 | flag: `--in-chunks` | `/commit:in-chunks`                                                                                                                             |
+| `/create-pr` | 2 | flag: `--description-only` | `/create-pr:description-only`                                                                                                                   |
 
 ## Routing semantics
 
-1. The user types `/<cluster> [<sub>] [args]`.
+1. The user invokes a cluster sub-command in **one of two equivalent
+   forms**:
+   - `/<cluster>:<sub> [args]` — **canonical**. Single token, plays
+     well with shell autocompletion and the slash-command picker.
+   - `/<cluster> <sub> [args]` — **space-separated equivalent**.
+     Identical semantics. Accept everywhere.
+
+   Both forms route to the **same file** and the **same dispatcher**.
+   Implementations MUST treat `:` and `<space>` as interchangeable
+   delimiters at the cluster boundary. Autocompletion-aware UIs
+   (Claude.ai picker, IDE slash-menus, shell completers) should
+   surface the `:` form because it stays a single token.
+
 2. Match the cluster against the table above. If the leading token is
    a dispatcher cluster, route to the dispatcher's `commands/<cluster>.md`
    and let the dispatcher's "Dispatch" section pick the sub-command.
+
 3. If the leading token is a flag-cluster (`/commit`, `/create-pr`),
    the cluster file is the entry point itself; flags absorb the
    former helper command.
+
 4. **Legacy atomic shims** (`/fix-ci`, `/agents-audit`, …) keep working
    for one release cycle. They emit a deprecation warning and forward
    to the cluster invocation. New invocations should always use the
-   cluster form.
+   cluster form. **`/roadmap-execute` is removed** — invocations route
+   to `/roadmap:process-phase` (default execution scope) with a
+   one-time migration notice. Legacy `/roadmap-process[:<sub>]`
+   invocations (the short-lived top-level cluster) likewise forward
+   to `/roadmap:process-<sub>`.
+
 5. If a sub-command is unknown, the dispatcher prints the menu — never
    guess.
 
+## Why colon is canonical
+
+Locked by [ADR-003](../../../../docs/decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md)
+(2026-05-07) alongside the flat-cluster + composite-sub-name shape.
+
+- **Single token in autocompleters.** `roadmap:process-phase` completes
+  as one piece; `roadmap process-phase` requires the picker to
+  re-prompt after the space.
+- **Stable in chat history and logs.** Greppable as one string.
+- **Unambiguous against free-text args.** `/roadmap:process-phase
+  road-to-X.md` parses cleanly; the picker never confuses the sub
+  with the first argument.
+- **Symmetric across the catalog.** `/commit:in-chunks` and
+  `/create-pr:description-only` already use this form; cluster
+  dispatchers gain it without regressing the space form.
+
 ## Removal cycle
 
 | Cycle | Active form | Shim form |

package/.agent-src/contexts/communication/rules-auto/think-before-action-mechanics.md

@@ -0,0 +1,98 @@
+# Think Before Action — mechanics
+
+Workflow tables, verification matrix, and failure modes for the
+[`think-before-action`](../../../rules/think-before-action.md) rule.
+The rule body holds the obligation surface (analyze before coding,
+verify with real tools, no blind retries). This file is the lookup
+material agents pull when the rule fires.
+
+## The Developer Workflow — five-step order
+
+Work like a developer, not a text generator. Skipping steps 1–3 is the
+#1 cause of wrong implementations and wasted retries.
+
+1. **Understand** — Read the task, ticket, acceptance criteria. Unclear
+   → ask, don't assume.
+2. **Analyze** — Read affected code, trace data flow, compare with
+   requirements and existing patterns.
+3. **Plan** — Decide what to change, what NOT to change, and how to
+   verify success.
+4. **Implement** — Focused changes. Follow existing patterns. No
+   unrelated rewrites.
+5. **Verify** — Run tests, hit the endpoint, check the UI. Real
+   execution, never "should work".
+
+## Minimum read set — read before you write
+
+Before editing code, read the minimum set that defines its behavior:
+
+1. **Symbol under edit** — full method/function body, not just the
+   planned line.
+2. **Direct callers** — one level up (`grep -rn "<symbol>"` + open
+   the matches).
+3. **Tests** — if a test file exists, it encodes the contract.
+4. **One layer of related abstractions** — interface, parent class,
+   or trait (one hop, not the full hierarchy).
+5. **Data changes** — the migration that created the column + any
+   seeder/factory that references it.
+
+Stop expanding once you can explain, in your own words, what the
+symbol does, who calls it, and what breaks if you change its
+behavior. Cannot → read more.
+
+## Consult memory before editing
+
+Prior decisions and invariants live in the memory layer. Via
+[`memory-access`](../../../../../docs/guidelines/agent-infra/memory-access.md),
+call `retrieve(types=["architecture-decisions", "domain-invariants"], keys=<touched paths>, limit=3)`.
+A matching `architecture-decision` explains *why* the current shape
+exists; a matching `domain-invariant` is a hard constraint. Cite the
+`id` if a match influences the plan.
+
+## Verify with real tools
+
+| What changed | How to verify |
+|---|---|
+| **Backend/API** | `curl`, Postman (or Postman MCP if available), test endpoint |
+| **Frontend/UI** | Playwright MCP or browser — check rendered state, interactions |
+| **Logic/flow** | Xdebug (or Xdebug MCP if available) — trace execution, inspect variables |
+| **CLI/Jobs** | Run the command, check side effects, verify exit code |
+| **Database** | Query the result, check migrations ran correctly |
+
+If a debugging/testing tool is available as MCP server — prefer it
+over manual alternatives. Verification not possible (no endpoint, no
+UI, no test) → state what is missing and explain how the change
+should be tested.
+
+## Reduce output — targeted tools over full dumps
+
+Never load full datasets into context. Extract what you need:
+
+- `jq` for JSON: `curl -s /api/users | jq '.[0] | {id, email}'` — not the full response
+- `rg` / `grep` for text: search specific patterns, not full files
+- `head`, `tail`, `cut`, `sort`, `uniq` for narrowing results
+- `--filter`, `--json`, `--format` flags on CLI tools — use them
+- Laravel: `route:list --json | jq` over raw `route:list` dump
+- Logs: filter by request ID, timestamp, or error type — not full log files
+
+## No blind retries
+
+- Failure → **read the error**, analyze the cause, then fix it.
+- Do NOT retry the same approach hoping for a different result.
+- Do NOT loop through trial-and-error when one targeted inspection
+  would reveal the cause.
+- Max 2 retries for the same approach — then stop and rethink.
+
+## Open files are context, not intent
+
+The editor may report that the user has a file open. Background
+context only — does NOT mean the user's message is about that file.
+
+- The user's message determines intent — not which file is open.
+- A user can have `README.md` open and type `/compress` — intent is
+  to compress, not to discuss the README.
+- A user can have `UserController.php` open and ask "how do tests
+  work?" — intent is testing, not the controller.
+- Treat the open file as relevant only when the user's message
+  explicitly references it (e.g. "fix this file", "what does this
+  do?", "update the open file").

package/.agent-src/contexts/communication/rules-auto/token-efficiency-mechanics.md

@@ -0,0 +1,93 @@
+# Token Efficiency — mechanics
+
+Anti-loop patterns, conversation efficiency rules, and exception
+catalog for the [`token-efficiency`](../../../rules/token-efficiency.md)
+rule. The rule body holds the two Iron Laws and the fresh-output
+principle; this file is the lookup material.
+
+## Anti-loop: Extended Reasoning
+
+Do NOT use extended reasoning / chain-of-thought tools for simple
+tasks like viewing files, running commands, or making straightforward
+edits. They are ONLY for genuinely complex multi-step reasoning. If
+calling such tools more than once per task — you are looping. Stop
+immediately and act directly.
+
+## Anti-loop: "CRITICAL INSTRUCTION" and self-prompting
+
+Generating text that starts with "CRITICAL INSTRUCTION", "I need
+to", "Let me think", "Related tools:", or similar self-directed
+reasoning inside a tool call or as a preamble before acting → **you
+are in a loop**. Happens after connection errors or when the user
+says "continue" / "mach weiter".
+
+**Immediate action:**
+
+1. STOP generating self-instructions.
+2. Read the last user message — what did they actually ask?
+3. Do that ONE thing directly. No planning monologue, no tool
+   selection reasoning.
+4. Don't know what the user wanted → ask: "Where were we?"
+
+## Conversation Efficiency
+
+### Act, skip narration
+
+- **Skip repeating the user's request.** They know what they asked.
+- **Just do it** — skip announcing what you're about to do.
+- **Skip explaining obvious tool calls.** Reading a file needs no
+  justification.
+- **Report only outcomes** — skip intermediate step summaries unless
+  the user needs them.
+
+This rule NEVER overrides `user-interaction` or command rules. Token
+efficiency means fewer *unnecessary* words — NOT skipping required
+questions, numbered options, or command steps. When a rule or
+command says "ask the user", you ask.
+
+### Stop early — max 2 retries
+
+- Command fails twice with same error → stop, rethink. Try a
+  different approach.
+- `grep` / search returns nothing after 2 attempts → switch approach
+  or ask the user.
+- Max 3 diagnostic commands per error. Read the error, think, act.
+- One hypothesis at a time. Pick the most likely, try it. Fails →
+  ask.
+
+### Keep intermediate output minimal
+
+Read `personal.minimal_output` (default: `true`) and
+`personal.play_by_play` (default: `false`) from `.agent-settings.yml`.
+
+When `personal.minimal_output: true`:
+
+- Multi-step work: short bullet points only, no paragraphs.
+- No thinking out loud — user doesn't need your reasoning.
+- `personal.play_by_play: false` → silently investigate, report
+  conclusion only.
+- `personal.play_by_play: true` → briefly share intermediate
+  findings.
+- At the end: concise summary — what changed, what user needs to
+  know.
+
+### Don't re-read what you already know
+
+- Edited a file → edit tool showed result. Don't re-read.
+- Ran a command → you have output. Don't re-run to "verify".
+- File in context from recent messages → don't reload.
+
+### Minimize tool calls
+
+- Parallel reads — don't read 5 files sequentially.
+- Regex search over full file reads. View specific line ranges.
+- One codebase search call with all symbols — not 5 separate.
+- Short question → short answer. Summary tables only for 3+ items.
+
+### Exceptions
+
+- Small output (< 30 lines) — read directly.
+- Debugging — OK to read more context around one error.
+- User explicitly asks for full output — show it.
+
+→ Detailed patterns: `docs/guidelines/agent-infra/output-patterns.md`

package/.agent-src/contexts/communication/rules-auto/user-interaction-mechanics.md

@@ -1,10 +1,133 @@
 # User Interaction — mechanics
 
-Format examples, progress indicators, and summary patterns for the
-[`user-interaction`](../../../rules/user-interaction.md) rule. Iron
-Law 1 (single-source recommendation), Iron Law 2 (pre-send
-self-check), and the named failure-mode catalog live in the rule
-itself; this file is the lookup material for the format details.
+Rationale, failure-mode catalog, format examples, progress
+indicators, and summary patterns for the
+[`user-interaction`](../../../rules/user-interaction.md) rule. The
+rule body holds the two Iron Law fenced blocks (single-source
+recommendation, pre-send self-check); this file is the lookup
+material for everything else.
+
+## Why the agent must take a position
+
+The agent has read the code, the contracts, the trade-offs.
+Refusing to take a position dumps that work back on the user. Take
+the position; be wrong out loud if needed. "Egal, was bevorzugst
+Du?" / "no preference" is NEVER acceptable.
+
+## Position-agnostic — the most common slip
+
+End-of-turn "Wie weiter?" / "What next?" / "How to proceed?" / "How
+should we continue?" blocks with numbered options ARE numbered-options
+blocks. Same Iron Law applies — exactly one `Empfehlung: N` /
+`Recommendation: N` line, every time. No "these are just follow-up
+suggestions" exception, no "the user knows better here" exception, no
+"I genuinely don't have a preference" exception. If the agent prints
+`1. … 2. … 3. …` anywhere in the reply, the recommendation line is
+mandatory.
+
+## Format — non-negotiable
+
+- Options block stays NEUTRAL — no `(recommended)`, no `(rec)`, no
+  `←`, no bold, no checkmark.
+- Directly after the options block, ONE line, bolded, in the user's
+  language:
+  - English: `**Recommendation: N — <option-name>** — <why>. Caveat: <flip-condition>.`
+  - German:  `**Empfehlung: N — <option-name>** — <warum>. Caveat: <flip-bedingung>.`
+- Other numbers MAY appear later in the prose, but ONLY as caveats
+  (`escalate to 3 if …`, `flip to 1 when …`). NEVER as a primary
+  recommendation.
+- Genuine tie (rare — true 50/50 with missing data) → say what data
+  would break the tie and ask for that instead.
+
+## No trailing open-ended question
+
+Reply contains numbered options → the recommendation line IS the
+closer. No `Welcher Pfad?` / `What's it gonna be?` / `Was meinst
+Du?` / `Was sagst Du?` / `Welche willst Du?` / `What do you think?`
+after the recommendation — that reframes the vote as opinion-poll
+and is hedging in disguise. The user picks a number; the agent does
+not re-ask. Permitted: a clarifying caveat sentence on the
+recommendation line itself (`Caveat: flip to 2 if …`). Forbidden:
+any standalone trailing question that re-opens the choice.
+
+## What does NOT count as a recommendation
+
+- "Both work" / "either is fine" / "depends on what you prefer"
+- Listing pros and cons without picking a number
+- "I'd lean towards X" without a reason
+- Hiding behind "you know the project better"
+- Inline `(recommended)` tag with no follow-up `Recommendation: N` line
+
+## Pre-send self-check details
+
+Before emitting any reply that contains numbered options, scan the
+**entire drafted reply** — top to bottom, including end-of-turn
+"Wie weiter?" / "What next?" continuation menus, follow-up
+suggestion blocks, and any list of `1. … 2. … 3. …` regardless of
+position or framing:
+
+1. Count occurrences of `(recommended)` / `(rec)` / `(empfohlen)`
+   inline next to a numbered option → MUST be **zero**. Found one →
+   rewrite, drop the tag.
+2. Count `1\\.\\s` / `2\\.\\s` / `3\\.\\s` patterns inside blockquotes
+   or top-level prose → if **any** numbered-option block exists
+   anywhere in the reply, the recommendation line is mandatory.
+3. Count distinct `Recommendation:\\s*N` / `Empfehlung:\\s*N` lines
+   (case-insensitive) → MUST be **exactly one per options block**.
+   Zero → add one. Two or more distinct numbers → rewrite, pick one.
+4. The number on the recommendation line MUST exist in the option
+   block it follows.
+5. Multiple options blocks (e.g. clarification block AND end-of-turn
+   menu) → each block gets its own `Recommendation: N` line directly
+   underneath.
+
+Mechanical backstop:
+`python3 scripts/check_reply_consistency.py --stdin < draft.md`
+(non-zero exit on any rule above). Self-scan is the primary gate;
+the script is the deterministic safety net for ambiguous cases.
+
+## Common failure modes — known, named, no excuses
+
+- **End-of-turn menu skipped.** Reply answers fine, then ends with
+  `1. … 2. … 3. …` and no `Empfehlung:`. Iron Law 1 violated — these
+  are numbered options, position is irrelevant.
+- **Trailing-question hedge.** Reply has options + recommendation,
+  but ends with `Welcher Pfad?` / `What's it gonna be?` — reframes
+  the vote as opinion-poll. Banned by Iron Law 1.
+- **"Genuinely no preference" hedge.** Pick anyway. Agent has more
+  context than user on the trade-off; refusing to pick dumps the
+  work back. Pick the safest option, name the flip-condition.
+- **"User knows the project better" hedge.** Same failure mode,
+  different costume. The user asked for an opinion by virtue of
+  accepting the options block; deliver it.
+- **Multi-block reply with one recommendation.** Two options blocks
+  but only one `Empfehlung:` line — second block unguarded. Rule 5
+  of Iron Law 2 closes this.
+
+## Slip handling
+
+Same protocol as
+[`language-and-tone § slip-handling`](../../../rules/language-and-tone.md#slip-handling).
+User calls out a missing or wrong recommendation → acknowledge once
+in the user's language, rewrite the reply with a recommendation,
+ship. No "from now on" promises — only the next reply proves
+compliance.
+
+## Numbered Options — rules
+
+- **Every question with choices** must use numbered options — no
+  exceptions.
+- **Every numbered list with `1. … 2. … 3. …`** is a
+  numbered-options block, regardless of position. End-of-turn "Wie
+  weiter?" / "What next?" / "How to proceed?" menus, mid-reply
+  continuation prompts, and clarification blocks all count.
+- **Keep options short** — one line each, with a brief explanation
+  after the dash.
+- **Always include a "skip" or "no change" option** when applicable.
+- **Always state a recommendation** — Iron Law 1.
+- **Use the user's language** for the question and options.
+- **Accept both** the number and a natural-language answer ("1" or
+  "the first one").
 
 ## Examples
 

package/.agent-src/contexts/execution/autonomy-mechanics.md

@@ -27,3 +27,47 @@ The Hard Floor still applies on every surface, including cloud. There
 is no "cloud override" for production-branch merges, deploys, pushes,
 prod data/infra, or whimsical bulk deletions — see
 [`non-destructive-by-default`](../../rules/non-destructive-by-default.md#cloud-behavior).
+
+## Blocking — STILL ASK regardless of `personal.autonomy`
+
+Beyond the Hard Floor, the autonomy setting also never overrides:
+
+- **Vague-request triggers** in
+  [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) —
+  ambiguous requirements stay ambiguous; pick-one-and-pray is wrong.
+- **Architectural / structural choices** the codebase doesn't already
+  settle (multi-stack picks, library introductions).
+- **Security-sensitive paths** — see
+  [`security-sensitive-stop`](../../rules/security-sensitive-stop.md).
+- **Scope expansion** beyond the stated task — see
+  [`scope-control`](../../rules/scope-control.md).
+- **Remote-state operations** — push, merge, rebase, force-push,
+  branch create/delete/switch, PR create/close/retarget, tag/release.
+  Permission-gated by
+  [`scope-control`](../../rules/scope-control.md); the prod-trunk
+  and deploy-tied subset is governed by
+  [`non-destructive-by-default`](../../rules/non-destructive-by-default.md).
+- **Destructive ops** — see
+  [`non-destructive-by-default`](../../rules/non-destructive-by-default.md)
+  for the full taxonomy (whimsical bulk deletions, content
+  destruction, commits containing bulk deletions or infra changes).
+
+In doubt whether something is trivial or blocking → it is blocking.
+Ask.
+
+## Commit policy summary
+
+Committing is governed by the canonical
+[`commit-policy`](../../rules/commit-policy.md) rule, which applies
+regardless of `personal.autonomy`:
+
+- NEVER commit unless user said so this turn, a commit command was
+  invoked, a standing instruction is active, or the roadmap
+  authorizes it.
+- NEVER ask about committing. The user invokes a command or says so.
+- In autonomous mode, the **only** permitted commit-related question
+  is the one-shot pre-scan ask at the start of roadmap execution.
+
+Push, merge, rebase, branch creation, PR operations, and tags
+remain permission-gated by
+[`scope-control § git-operations`](../../rules/scope-control.md#git-operations--permission-gated).