@event4u/agent-config 1.20.0 → 1.21.0

package/.agent-src/commands/set-cost-profile.md

@@ -25,7 +25,7 @@ the [`agent-settings` template](../templates/agent-settings.md#cost-profiles):
 - For first-run setup use [`/onboard`](onboard.md).
 - For any other single-value change, edit `.agent-settings.yml`
   directly or ask the agent — the merge rules live in
-  [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+  [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 - For role modes use [`/mode`](mode.md) — different concept (sets
   `roles.active_role`, not `cost_profile`).
 
@@ -73,7 +73,7 @@ value directly — still echo the old → new line in step 6.
 ### 5. Write the value
 
 Update `cost_profile` in `.agent-settings.yml` using the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 (preserve comments, preserve key order, touch only the changed field).
 
 If the user picked "Keep current", do nothing and stop.
@@ -107,6 +107,6 @@ flip. Cost behaviour on those surfaces is governed by the platform itself.
 ## See also
 
 - [`agent-settings`](../templates/agent-settings.md) — profile matrix and settings reference
-- [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
+- [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
 - [`onboard`](onboard.md) — first-run setup (includes profile confirmation)
 - [`mode`](mode.md) — role-mode setter (different concept)

package/.agent-src/commands/sync-agent-settings.md

@@ -15,7 +15,7 @@ Reconciles `.agent-settings.yml` with the shipped template
 (`config/agent-settings.template.yml`) and the selected cost-profile
 preset (`config/profiles/{profile}.ini`). Applies the section-aware
 merge rules documented in
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md):
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md):
 
 - Template section order wins — keys reorder to match.
 - Existing user scalar values are preserved.
@@ -129,6 +129,6 @@ is a local-agent concern.
 - [`scripts/sync_agent_settings.py`](../../../scripts/sync_agent_settings.py) — the helper
 - [`config/agent-settings.template.yml`](../../../config/agent-settings.template.yml) — canonical template
 - [`config/profiles/`](../../../config/profiles/) — profile presets
-- [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
+- [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
 - [`scripts/install.py`](../../../scripts/install.py) — first-install path; this command handles the update path
 - [`/sync-gitignore`](sync-gitignore.md) — sibling command for the `.gitignore` block

package/.agent-src/commands/tests/create.md

@@ -59,7 +59,7 @@ suggestion:
 - Place tests in the matching directory structure under `tests/` (mirror the source structure).
 - Group related tests with `describe` blocks (Pest) or separate test methods (PHPUnit).
 - Use data providers for testing multiple input/output combinations.
-- Mock external dependencies (database, HTTP, file system) — don't test infrastructure.
+- Mock external deps (database, HTTP, file system) — don't test infrastructure.
 
 ### 6. Verify
 
@@ -70,7 +70,7 @@ suggestion:
 
 - **Do NOT commit or push.**
 - **Quality over quantity** — 5 meaningful tests beat 20 trivial ones.
-- If a class is hard to test (too many dependencies, global state), flag it and suggest a refactoring approach instead of writing brittle
+- If a class is hard to test (too many deps, global state), flag it and suggest a refactoring approach instead of writing brittle
   tests.
 
 ## See also

package/.agent-src/commands/tests.md

@@ -22,7 +22,7 @@ commands with a single entry point + sub-command dispatch.
 | `/tests execute` | `commands/tests/execute.md` | Run PHP tests inside the Docker container |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/threat-model.md

@@ -71,7 +71,7 @@ Produce one combined report with these sections, in order:
 5. **Required controls** — the minimum set of validations, authorization
    checks, logging, and negative tests that must exist before the change ships
 6. **Open questions** — anything the skills flagged as uncertain and the user
-   must answer before implementation starts
+   must answer before impl starts
 
 ### 5. Decide next step
 
@@ -83,7 +83,7 @@ After the report, ask:
 > 3. Stop here — threat model is the deliverable, no implementation yet
 ```
 
-- On **1**: hand off to the implementation flow (e.g., `feature-plan`,
+- On **1**: hand off to the impl flow (e.g., `feature-plan`,
   `bug-fix`, or direct edit) with the required-controls list pinned
 - On **2**: re-gather context and re-dispatch
 - On **3**: save the report as the deliverable, stop
@@ -106,7 +106,7 @@ After the report, ask:
 - NEVER merge `threat-modeling` and `authz-review` outputs into a single
   block — each skill owns its format
 - NEVER write production code in the same turn as this command — the
-  deliverable is the report; implementation is a separate step
+  deliverable is the report; impl is a separate step
 - NEVER mark the change "safe" if any 🔴 abuse case has no control
 
 ## See also
@@ -116,4 +116,4 @@ After the report, ask:
 - [`data-flow-mapper`](../skills/data-flow-mapper/SKILL.md) — trace specific data through the change
 - [`blast-radius-analyzer`](../skills/blast-radius-analyzer/SKILL.md) — enumerate affected call sites
 - [`security-sensitive-stop`](../rules/security-sensitive-stop.md) — the trigger rule
-- [`minimal-safe-diff`](../rules/minimal-safe-diff.md) — keep the implementation scoped
+- [`minimal-safe-diff`](../rules/minimal-safe-diff.md) — keep the impl scoped

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

@@ -8,6 +8,19 @@ in autonomous vs. non-autonomous mode.
 **Size budget:** ≤ 3,000 chars. Tracked under Phase 6 of
 `road-to-pr-34-followups`.
 
+## The four commit exceptions — restated
+
+Outside the four below, no commit is allowed and no commit ask is allowed.
+
+1. **User says so this turn** — "commit this now", "commit it", "go
+   ahead and commit". Single commit, not standing.
+2. **Standing instruction not yet revoked** — earlier "commit after
+   every phase"; cache the instruction and commit per its terms.
+3. **Commit command invoked** — `/commit` (split + confirm per commit)
+   or `/commit:in-chunks` (auto-split, Hard Floor still applies).
+4. **Roadmap authorization** — roadmap lists explicit commit steps and
+   the user invoked roadmap execution; each commit matches a step.
+
 ## Hard Floor still applies — bulk deletions and infra changes
 
 Even when one of the four `commit-policy` exceptions authorizes a
@@ -19,7 +32,7 @@ Hard Floor still fires when the diff:
 - 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`,
+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.

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

@@ -9,6 +9,19 @@ context holds everything an agent reaches for once those have fired.
 **Size budget:** ≤ 3,500 chars. Tracked under Phase 7.4 of
 `road-to-pr-34-followups`.
 
+## Iron Law — restatement
+
+The rule's Iron Law ("HARD FLOOR OVERRIDES EVERYTHING") is the universal
+non-destructive-by-default safety net. No autonomy setting, roadmap step,
+or standing instruction can lift it. This is the same Iron Law restated
+in `commit-policy` (row 6 of its trigger table) and in `scope-control`
+(production / infra / bulk-destructive subset).
+
+The trigger surface covers production-branch merges, deploys / releases,
+production data and infrastructure changes, pushes to remote, and
+whimsical or unscoped bulk-destructive operations. Authorization is
+"user said so this turn", never inferred from a previous turn.
+
 ## Bulk deletions during WIP — allowed if task-connected
 
 Deletions inside an **active, user-stated task** are allowed in the
@@ -58,7 +71,7 @@ the diff (paths + counts), get confirmation, then commit.
 - Committing a diff that removes a directory, deletes ≥5 unrelated
   files, or touches Terraform / k8s manifests / Ansible without
   surfacing the diff first — even when [`commit-policy`](../../rules/commit-policy.md)
-  otherwise authorizes commits (e.g. `/commit-in-chunks`, roadmap
+  otherwise authorizes commits (e.g. `/commit:in-chunks`, roadmap
   pre-scan, an explicit "commit this now"). Bulk-deletion / infra
   commits need their own ask, every time.
 - Reading a roadmap step listing files to delete as authorization to

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,7 +4,7 @@ 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).
 

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).

package/.agent-src/contexts/model-recommendations.md

@@ -91,7 +91,7 @@ produce opus-level quality by enforcing habits that weaker models skip by defaul
 - **Default to `sonnet`** — it's the cost-efficient workhorse.
 - **Escalate to `opus`** only when architecture, refactoring, or unclear debugging is involved.
 - **After Opus work** (architecture plan, refactoring design, root cause found):
-  → Recommend switching back to `sonnet` for implementation.
+  → Recommend switching back to `sonnet` for impl.
 - **Use `gpt`** for large-scale analysis, searching across many files, or automation.
 
 ## Recommendation Flow
@@ -121,7 +121,7 @@ When user says they want to continue with the current model:
 ### Downgrade reminder
 
 After completing an opus-level task (architecture plan done, refactoring complete, root cause found),
-remind the user to switch back to sonnet for the implementation phase:
+remind the user to switch back to sonnet for the impl phase:
 
 ```
 > 💡 The {architecture/debugging/design} phase is done.