@event4u/agent-config 1.19.0 → 1.21.0

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

@@ -3,60 +3,18 @@ type: "auto"
 tier: "2a"
 description: "Reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md"
 source: package
+triggers:
+  - path_prefix: "agents/"
+  - path_prefix: ".github/copilot-instructions"
+  - keyword: "AGENTS.md"
+  - keyword: "roadmap"
+routes_to:
+  - "skill:agent-docs-writing"
 ---
 
-# Agent Documentation
+# Agent Docs
 
-## When to read agent docs
+**Iron Law.** Read agent docs (`AGENTS.md`, `agents/`, module `agents/`) before work; update them after structural changes.
 
-**Before starting ANY work**, read the relevant documentation:
-
-1. **Always read** `AGENTS.md` (if it exists in the project root) for project-level setup and conventions.
-2. **Always read** `./agents/` for project-specific architecture, guidelines, and domain docs.
-3. **If domain contexts exist** (`agents/contexts/domain/`) → read any that are relevant to the current work area.
-4. **If working on a module** → also read `app/Modules/{Module}/agents/` for module-specific docs,
-   including `agents/contexts/` within the module if it exists.
-5. **If working on a package** → read the package's `./agents/` directory.
-6. **If a roadmap exists** for the current work → read it first and follow its steps.
-
-## When to update agent docs
-
-After making changes, check if any agent docs need to be updated:
-
-- **New module created** → create `app/Modules/{Module}/agents/` with at least a module description.
-- **Database schema changed** → update `agents/docs/database-setup.md` or equivalent.
-- **New service/pattern introduced** → update relevant guideline docs.
-- **Roadmap step completed** → mark it as done in the roadmap file (`[x]`).
-- **Structural changes** (new conventions, renamed classes, moved files) → update affected docs.
-
-If unsure whether a doc needs updating, **ask the user**.
-
-## When to create roadmaps
-
-When working on a **significant change** that spans multiple steps or sessions:
-
-- Ask the user whether to create a roadmap in `agents/roadmaps/`.
-- Use the `roadmap-create` command if yes.
-- This ensures future sessions (and other agents) can pick up the work.
-
-## Roadmap lifecycle
-
-Every roadmap ends in exactly one folder — never leave stale files in `agents/roadmaps/`:
-
-- `agents/roadmaps/` — active (in progress or planned)
-- `agents/roadmaps/archive/` — finished (work happened, fully or partially)
-- `agents/roadmaps/skipped/` — not pursued (typically 0 items `[x]`, scope rejected or superseded)
-
-The `roadmap-management` skill owns the trigger matrix and user-confirmation flow.
-Never delete a roadmap — always move it.
-
-## Documentation language
-
-- All `.md` files must be written in **English**.
-- If an existing file is in German or another language, translate it to English when you touch it.
-
-## Do NOT
-
-- Do NOT create docs unless there's a real need (new module, significant change, etc.).
-- Do NOT duplicate information that's already in `AGENTS.md` or `.github/copilot-instructions.md`.
-- Do NOT write docs just to document what you did — only document things others need to know.
+Body migrated to `skill:agent-docs-writing` (per P4 of `road-to-kernel-and-router.md`).
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/analysis-skill-routing.md

@@ -1,49 +1,19 @@
 ---
-type: auto
+type: "auto"
 tier: "3"
 description: "When choosing an analysis skill, route to the narrowest matching skill instead of defaulting to broad analysis"
 source: package
+triggers:
+  - keyword: "analyze"
+  - keyword: "analysis"
+  - phrase: "dig into the codebase"
+routes_to:
+  - "skill:analysis-skill-router"
 ---
 
 # Analysis Skill Routing
 
-When choosing an analysis skill, always route to the narrowest skill that still matches the actual problem shape.
+**Iron Law.** Route analysis tasks to the narrowest matching `project-analysis-*` skill, not the broad fallback.
 
-Use `universal-project-analysis` only for:
-
-* full project analysis
-* deep architecture review
-* broad multi-layer debugging
-* unclear systems where the stack or boundaries must first be discovered
-
-Use framework-specific project-analysis skills only after the framework is known.
-
-Use root-cause analysis skills when the problem is concrete and hypothesis-driven.
-
-Do not use broad analysis skills for:
-
-* small isolated code questions
-* normal feature work
-* obvious local fixes
-* framework-specific issues that already have a dedicated skill
-
-Prefer:
-
-* narrow specialist skill over broad analysis skill
-* framework-specific skill over universal router when the framework is already explicit
-* root-cause skill over full-project analysis when the issue is already localized
-
-If the stack is unclear:
-
-* start broad
-* then narrow quickly
-
-## Routing quality gate
-
-Only route to the narrower skill if it still has:
-
-* executable workflow (concrete procedure steps)
-* concrete validation (specific checks, not "verify it works")
-* real decision power (not just "read the guideline")
-
-If the narrow skill is too weak or hollowed out, route through the broader skill and note the gap.
+Body migrated to `skill:analysis-skill-router` (per P4 of `road-to-kernel-and-router.md`).
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/architecture.md

@@ -4,6 +4,11 @@ tier: "3"
 alwaysApply: false
 description: "Architecture rules for creating new files, classes, controllers, modules, or making structural decisions about project organization"
 source: package
+triggers:
+  - keyword: "controller"
+  - keyword: "service"
+  - keyword: "module"
+  - intent: "structural decision"
 ---
 
 # Architecture Rules
@@ -11,7 +16,7 @@ source: package
 ## General Principles
 
 - **Controllers are thin** — no business logic, delegate to services.
-- **Only Single Action Controllers** — every new controller MUST use `__invoke()`. No multi-action / resource controllers. See `../../docs/guidelines/php/controllers.md` for naming conventions.
+- **Only Single Action Controllers** — every new controller MUST use `__invoke()`. No multi-action / resource controllers. See `../docs/guidelines/php/controllers.md` for naming conventions.
 - **Every controller needs a FormRequest** — never validate inline with `$request->validate()`. Use a dedicated `FormRequest` subclass.
 - **Services contain business logic** — calculations, orchestration, validation.
 - **Models have no business logic** — only relationships, scopes, accessors/mutators.

package/.agent-src/rules/artifact-drafting-protocol.md

@@ -4,6 +4,11 @@ tier: "2a"
 alwaysApply: false
 description: "Creating a new skill, rule, command, or guideline, or significantly rewriting one — runs a mandatory Understand → Research → Draft sequence before any artifact content is written."
 source: package
+triggers:
+  - intent: "create new skill"
+  - intent: "create new rule"
+  - intent: "create new command"
+  - intent: "create new guideline"
 ---
 
 # Artifact Drafting Protocol

package/.agent-src/rules/artifact-engagement-recording.md

@@ -4,75 +4,39 @@ tier: "mechanical-already"
 alwaysApply: false
 description: "After a /implement-ticket or /work phase-step (refine/memory/analyze/plan/implement/test/verify/report) or full task — emit one telemetry:record call with consulted+applied ids when enabled"
 source: package
+triggers:
+  - phrase: "/implement-ticket"
+  - phrase: "/work"
+  - keyword: "telemetry"
+routes_to:
+  - "contract:artifact-engagement-flow"
 load_context:
-  - .agent-src.uncompressed/contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md
+  - "../contexts/contracts/artifact-engagement-flow.md"
 ---
 
 <!-- cloud_safe: noop -->
 
 # Artifact Engagement Recording
 
-Records which **skills, rules, commands, guidelines, personas** the agent
-actually consulted and applied during a `/implement-ticket` or `/work` run.
-Default-off; opt-in via `.agent-settings.yml`. Zero overhead when disabled.
+**Iron Law.** After a `/implement-ticket` or `/work` phase-step, emit one
+`telemetry:record` call with consulted + applied ids when telemetry is
+enabled. Default-off; opt-in via `.agent-settings.yml`. Zero overhead when
+disabled. Recording contract + privacy floor:
+[`contexts/contracts/artifact-engagement-flow.md`](../contexts/contracts/artifact-engagement-flow.md).
 
-The schema, CLI, and storage layer are owned by
-[`scripts/telemetry/`](../../../scripts/telemetry/) and the
-`./agent-config telemetry:record` / `telemetry:status` commands. The
-recording contract lives in
-[`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md).
-This rule says **when** to call the CLI, not how the file is structured.
+The schema, CLI, and storage layer are owned by `scripts/telemetry/` and
+the `./agent-config telemetry:record` / `telemetry:status` commands.
 
-## Activation gate — read settings ONCE per task, then cache
+## Activation gate — read settings ONCE per task
 
-Before the first `/implement-ticket` or `/work` step runs, read
-`telemetry.artifact_engagement.enabled` from `.agent-settings.yml`. Cache
-the value (and `granularity`) for the whole task.
+Before the first phase-step runs, read
+`telemetry.artifact_engagement.enabled`. Cache the value (and
+`granularity`) for the whole task.
 
-- `enabled: false` or section missing → rule is a **no-op**. Do not import
-  the script, do not open the log, do not mention recording. Skip the rest
-  of this rule.
-- `enabled: true` → continue with the cadence below.
+- `enabled: false` or section missing → rule is a **no-op**.
+- `enabled: true` → continue with the cadence in the contract.
 
-Use `./agent-config telemetry:status --format json` if the value is
-not already in working memory; the call is read-only and never touches
-the log file.
+## Cloud Behavior
 
-## Cadence — depends on `granularity`
-
-| `granularity` | When to emit | Coalescing |
-|---|---|---|
-| `task` *(default)* | Once, when the eight-step flow ends (success, blocked, partial — any terminal state) | All consulted/applied artefacts from refine through report merged into a single event |
-| `phase-step` | At the close of each phase-step (refine, memory, analyze, plan, implement, test, verify, report) | One event per step; per-step consulted/applied lists only |
-
-Within a single boundary, **dedupe** consulted and applied lists. A skill
-consulted three times in the same boundary records once.
-
-## What counts as consulted vs applied
-
-- **`consulted`** — the agent **read** the artefact this boundary: opened
-  its `SKILL.md`, scanned its rule body, viewed its frontmatter,
-  referenced its guideline, checked its persona contract, dispatched its
-  command. Reading does not imply behaviour change.
-- **`applied`** — the artefact **influenced the output** this boundary:
-  its instructions changed how the agent answered, what code it wrote,
-  what tools it ran, or what halt surface it produced. Applied is a
-  strict subset of consulted.
-
-When in doubt → record as `consulted` only. Over-recording `applied`
-inflates the engagement signal and defeats the purpose.
-
-## Mechanics — CLI invocation, privacy contract, failure handling
-
-The exact `telemetry:record` call shape with all flags, the privacy
-contract (what NEVER goes into a record), the failure-mode handling
-(do NOT block the user's task), and the "what this rule does NOT do"
-catalog live in
-[`contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md`](../contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md).
-
-## See also
-
-- [`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md) — recording contract details
-- [`/implement-ticket`](../commands/implement-ticket.md) and [`/work`](../commands/work.md) — boundary points where this rule fires
-- [`scripts/telemetry/`](../../../scripts/telemetry/) — engine source
-- [`agent-settings`](../templates/agent-settings.md) — `telemetry.artifact_engagement.*` reference
+The `cloud_safe: noop` marker keeps this rule inert on cloud surfaces
+(Claude.ai Web, Skills API). The cloud-bundle pipeline skips it.

package/.agent-src/rules/ask-when-uncertain.md

@@ -8,8 +8,7 @@ source: package
 
 # Ask When Uncertain
 
-**When in doubt, ask the user.** Do not guess, assume, or improvise.
-Asking one question too many is always better than a wrong assumption.
+**When in doubt, ask.** Don't guess, assume, or improvise. One question too many beats one wrong assumption.
 
 ## Iron Law — one question per turn, ALWAYS
 
@@ -18,22 +17,19 @@ ONE QUESTION PER TURN. NO EXCEPTIONS.
 ASK. WAIT FOR THE ANSWER. THEN ASK THE NEXT.
 ```
 
-Absolute. Not a default, not "usually". Every turn with a question
-has **exactly one**. Even if trivial, independent, or batchable.
-Self-check, ordering, handoff under [How to ask](#how-to-ask).
+Absolute. Every turn with a question has **exactly one** — even if trivial, independent, or batchable.
 
 ## When to ask
 
-- Requirement ambiguous or multi-interpretable
-- Not 100% sure which approach is correct
-- About to touch code you haven't fully understood
-- Choosing between multiple valid approaches
-- A fix "seems to work" but you can't explain why
+- Requirement ambiguous or multi-interpretable.
+- Not 100 % sure which approach is correct.
+- About to touch code you haven't fully understood.
+- Choosing between multiple valid approaches.
+- A fix "seems to work" but you can't explain why.
 
 ## Vague-request triggers — MUST ask
 
-These patterns are too vague to execute safely. Match without further
-context → ask **before** touching code:
+Match without further context → ask **before** touching code:
 
 - "improve / optimize this" — metric? speed, readability, memory?
 - "add caching" — store? scope? invalidation?
@@ -45,52 +41,33 @@ context → ask **before** touching code:
 - "handle errors properly" — which errors? log/retry/propagate?
 - "add a UI/component/tile/page" in mixed-framework repo — which stack?
 
-Example questions per pattern:
-[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#vague-request-triggers--example-questions).
+Examples: [`asking-and-brevity-examples § vague-triggers`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#vague-request-triggers--example-questions).
 
-**Escape hatch:** if context (ticket, open file, prior turn) makes
-the answer unambiguous, proceed — but state the assumption.
+**Escape hatch:** unambiguous from ticket / open file / prior turn → proceed, state the assumption.
 
 ## How to ask
 
-Numbered options (per `user-interaction`). Short. The Iron Law is at
-the top; this section adds self-check and ordering.
-
-The user must never track sub-numbers, scroll stacked option blocks,
-or split a reply across multiple questions. Rationale shorthand: if
-the user has to *think* about an answer, that answer almost always
-reframes the next question. Full rationale:
-[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#one-question-per-turn--why-serial-always-wins).
+Numbered options (per [`user-interaction`](user-interaction.md)). Short.
 
 ### Self-check before asking
 
-Before sending a turn with a question, ask yourself:
-
-1. Does this turn contain more than one `?` directed at the user?
-2. Does this turn present two or more separate numbered-option blocks?
-3. Would the user need to reply with a structured answer (`1a, 2b`)
-   instead of a single number or word?
+1. More than one `?` directed at the user this turn?
+2. Two or more separate numbered-option blocks?
+3. User would need a structured reply (`1a, 2b`) instead of a single number?
 
-If any answer is "yes" → **collapse to ONE question** and send. Hold
-every other question for its own turn. No exceptions, no "but these
-are related".
+Any "yes" → **collapse to ONE question**. Hold the rest for their own turn. Rationale: [`asking-and-brevity-examples § serial-wins`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#one-question-per-turn--why-serial-always-wins).
 
 ### Ordering & handoff
 
-- **Session handoff** (`/agent-handoff`, fresh-chat proposal): ask LAST,
-  after all domain / clarifying questions — so the user's answers can be
-  folded into the handoff prompt. Full rationale in
-  [`agent-interaction-and-decision-quality`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#handoff--model-switch-questions).
-- **Model switch**: different phase — [`model-recommendation`](model-recommendation.md)
-  triggers at task start with its own STOP-AND-WAIT gate, standalone, not
-  appended to a Q&A block. Do not conflate the two.
-- **Blocking clarification** (can't proceed without it): ask FIRST,
-  alone, before any research or planning output.
-- **Optional refinement**: don't ask at all — state the assumption
-  and proceed.
+- **Session handoff** (`/agent-handoff`, fresh-chat) — ask LAST, after domain / clarifying questions, so answers fold into the handoff. Full: [`agent-interaction-and-decision-quality § handoff`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#handoff--model-switch-questions).
+- **Model switch** — [`model-recommendation`](model-recommendation.md) STOP-AND-WAIT gate is standalone, not appended.
+- **Blocking clarification** — ask FIRST, alone, before any research or planning output.
+- **Optional refinement** — don't ask; state the assumption, proceed.
 
 ## Creating new agent artifacts
 
-For skill/rule/command/guideline creation or major rewrite, follow
-[`artifact-drafting-protocol`](artifact-drafting-protocol.md) — structured
-Understand → Research → Draft. Don't improvise questions.
+Skill / rule / command / guideline creation or major rewrite → [`artifact-drafting-protocol`](artifact-drafting-protocol.md) (Understand → Research → Draft). Don't improvise questions.
+
+## Examples
+
+Pattern Memory (wrong / right / why): [`ask-when-uncertain-demos`](../docs/guidelines/agent-infra/ask-when-uncertain-demos.md). Outcome baseline: [`tests/golden/outcomes/ask_when_uncertain.json`](../../tests/golden/outcomes/ask_when_uncertain.json).

package/.agent-src/rules/augment-portability.md

@@ -3,69 +3,21 @@ type: "auto"
 tier: "mechanical-already"
 description: "Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic"
 source: package
-load_context:
-  - .agent-src.uncompressed/contexts/communication/rules-auto/augment-portability-mechanics.md
+triggers:
+  - path_prefix: ".augment/"
+  - path_prefix: ".agent-src.uncompressed/"
+  - keyword: "portable"
+routes_to:
+  - "guideline:augment-portability-patterns"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncompressed/"
+    reason: "Rule scopes the portability gate to the uncompressed authoring tree."
 ---
 
-# Package Portability
+# Augment Portability
 
-Everything that ships with the `event4u/agent-config` package MUST be
-**project-agnostic**. That includes:
+**Iron Law.** Files inside `.augment/` and `.agent-src.uncompressed/` MUST stay project-agnostic — no project names, domains, stacks.
 
-- Everything inside `.augment/` (skills, rules, commands, guidelines,
-  templates, contexts)
-- The package repo's own root `AGENTS.md`
-- The package repo's own `.github/copilot-instructions.md`
-
-All three are either installed into consumer projects (`.augment/` via
-`install.sh`) or read by AI tools when working on the package itself
-(`AGENTS.md`, `copilot-instructions.md`). Leaking consumer-specific
-content into any of them pollutes downstream projects or misleads agents.
-
-## Rules
-
-- NEVER reference a specific consumer project, repo name, domain, or tech
-  stack directly. The package repo itself (`event4u/agent-config`) MAY be
-  named inside its own root `AGENTS.md` and `copilot-instructions.md` —
-  that is meta about the package, not a leak.
-- NEVER hardcode consumer-project paths, class names, or conventions.
-- Write content so it works as a **reusable package** across any project.
-- Project-specific behavior belongs in the **consumer's** `.agent-settings.yml`,
-  `AGENTS.md`, or `agents/` — never in files shipped by this package.
-- If a skill or rule needs project-specific input, read it from
-  `.agent-settings.yml` or accept it as a parameter.
-- When reviewing or editing package files, always ask: "Would this still
-  make sense in a completely different project?"
-
-## Runtime invocations — no `task` commands
-
-Skills, rules, commands, guidelines, personas, and context docs run in
-**consumer projects**, which may not have Task installed. **Never**
-reference a `task <something>` invocation inside any artefact file
-under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
-(and therefore also not in the compressed mirror under `.agent-src/`).
-Use direct script invocations instead.
-
-## Consumer CLI — `./agent-config`
-
-A subset of package scripts is exposed through a project-local CLI
-wrapper `./agent-config` (written into the project root by the
-installer, gitignored). Artefacts MUST prefer the CLI over raw
-`python3 scripts/…` paths for every command the CLI already covers.
-
-## Translation tables — see mechanics
-
-The full `task`-to-script translation table, the `./agent-config`
-CLI mapping, and the rationale (Task absence on consumers,
-maintainer-vs-artefact split) all live in
-[`contexts/communication/rules-auto/augment-portability-mechanics.md`](../contexts/communication/rules-auto/augment-portability-mechanics.md).
-Pull it whenever an artefact is about to mention a runtime
-invocation.
-
-## Enforcement
-
-`scripts/check_portability.py` scans `.augment/`, `.agent-src.uncompressed/`,
-and the package repo's root `AGENTS.md` + `.github/copilot-instructions.md`
-for forbidden identifiers, for any `task <name>` invocation inside
-artefact files, and for direct script invocations that bypass the
-`./agent-config` CLI. It runs in CI and must pass before any PR.
+Body migrated to `guideline:augment-portability-patterns` (per P4 of `road-to-kernel-and-router.md`).
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/augment-source-of-truth.md

@@ -4,7 +4,16 @@ tier: "1"
 description: "Creating, editing, or modifying files inside .agent-src/ or .augment/ — the source of truth is .agent-src.uncompressed/, never edit the generated directories directly"
 source: package
 load_context:
-  - .agent-src.uncompressed/contexts/communication/rules-auto/augment-source-of-truth-mechanics.md
+  - ../contexts/communication/rules-auto/augment-source-of-truth-mechanics.md
+triggers:
+  - path_prefix: ".agent-src/"
+  - path_prefix: ".augment/"
+  - path_prefix: ".claude/"
+  - path_prefix: ".cursor/"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncompressed/"
+    reason: "Rule documents the source-of-truth boundary; mentioning the path is its purpose."
 ---
 
 # Source of Truth

package/.agent-src/rules/autonomous-execution.md

@@ -5,119 +5,38 @@ description: "Deciding whether to ask the user or just act on a workflow step
 alwaysApply: false
 source: package
 load_context:
-  - .agent-src.uncompressed/contexts/execution/autonomy-detection.md
-  - .agent-src.uncompressed/contexts/execution/autonomy-mechanics.md
-  - .agent-src.uncompressed/contexts/execution/autonomy-examples.md
+  - ../contexts/execution/autonomy-detection.md
+  - ../contexts/execution/autonomy-mechanics.md
+  - ../contexts/execution/autonomy-examples.md
+triggers:
+  - intent: "trivial workflow question"
+  - intent: "autonomy mode"
+  - keyword: "personal.autonomy"
 ---
 
 # Autonomous Execution
 
-User's time is the scarce resource. Trivial workflow questions are
-noise. This rule defines **trivial** (just act), **blocking** (still
-ask), the **hard floor** (always ask, no override), and the **commit
-default** (never commit, never ask — review-first by design).
+User's time is the scarce resource. Trivial workflow questions are noise. This rule defines **trivial** (just act), **blocking** (still ask), the **hard floor** (always ask, no override), and the **commit default** (never commit, never ask — review-first by design).
 
 ## Hard Floor — see [`non-destructive-by-default`](non-destructive-by-default.md)
 
-The universal safety floor (production-branch merges, deploys, pushes,
-prod data/infra, whimsical bulk deletions, and commits containing
-bulk deletions or infra changes) is governed by the canonical
-[`non-destructive-by-default`](non-destructive-by-default.md) rule.
-It applies regardless of `personal.autonomy`, a standing autonomy
-directive, or any roadmap authorization. Nothing in **this** rule
-lifts it. If a trigger fires, stop and ask — every other section
-below assumes the floor has already been cleared.
+The universal safety floor (production-branch merges, deploys, pushes, prod data/infra, whimsical bulk deletions, and commits containing bulk deletions or infra changes) is governed by the canonical [`non-destructive-by-default`](non-destructive-by-default.md) rule. It applies regardless of `personal.autonomy`, a standing autonomy directive, or any roadmap authorization. Nothing in **this** rule lifts it. If a trigger fires, stop and ask — every other section below assumes the floor has already been cleared.
 
 ## Setting — `personal.autonomy`
 
-Three values: `on` (suppress trivial questions), `off` (ask trivial
-questions too), `auto` (default — same as `off` until the user opts
-in via a standing autonomy directive). Read once on the first turn
-(per [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
-and cache. Missing key → treat as `on`. Full table, semantics, and
-cloud behavior:
-[`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md).
+Three values: `on` (suppress trivial questions), `off` (ask trivial questions too), `auto` (default — same as `off` until the user opts in via a standing autonomy directive). Read once on the first turn and cache. Missing key → treat as `on`. Full table, semantics, and cloud behavior: [`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md).
 
 ## Opt-in detection — match by intent, not exact string
 
-In `auto` mode, flip to `on` for the rest of the conversation when
-the user expresses **"stop asking on trivial steps, just work"**.
-Recognize **intent**, not the literal substring. Opt-out (same intent,
-reversed) flips back to `off`. Both directions are
-**speech-act-checked**: the phrase must be a meta-instruction to the
-agent, not content / quote / subject / code / third-party reference /
-hypothetical. In doubt → keep current mode, no speculative flips.
+In `auto` mode, flip to `on` for the rest of the conversation when the user expresses **"stop asking on trivial steps, just work"**. Recognize **intent**, not the literal substring. Opt-out (same intent, reversed) flips back to `off`. Both directions are **speech-act-checked**: the phrase must be a meta-instruction to the agent, not content / quote / subject / code / third-party reference / hypothetical. In doubt → keep current mode, no speculative flips.
 
-Algorithm and speech-act heuristic:
-[`contexts/execution/autonomy-detection.md`](../contexts/execution/autonomy-detection.md).
-Anchor phrases (DE+EN), no-flip patterns, counter-examples:
-[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
-
-## Trivial — JUST ACT, do not ask
-
-In `personal.autonomy: on` or `auto`-after-opt-in, do not ask
-trivial workflow questions — pick the obvious next step and proceed.
-In `personal.autonomy: off`, ask them. Worked cases:
-[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
-
-## Blocking — STILL ASK regardless of `personal.autonomy`
-
-Beyond the Hard Floor above, the autonomy setting also never
-overrides:
-
-- **Vague-request triggers** in [`ask-when-uncertain`](ask-when-uncertain.md)
-  — ambiguous requirements stay ambiguous; pick-one-and-pray is wrong.
-- **Architectural / structural choices** that the codebase doesn't
-  already settle (multi-stack picks, library introductions).
-- **Security-sensitive paths** — see [`security-sensitive-stop`](security-sensitive-stop.md).
-- **Scope expansion** beyond the stated task — see [`scope-control`](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`](scope-control.md); the
-  prod-trunk and deploy-tied subset is governed by
-  [`non-destructive-by-default`](non-destructive-by-default.md).
-- **Destructive ops** — see [`non-destructive-by-default`](non-destructive-by-default.md)
-  for the full taxonomy (whimsical bulk deletions, content
-  destruction, commits containing bulk deletions or infra changes).
-
-When in doubt whether something is trivial or blocking → it is
-blocking. Ask.
-
-## Commit policy — see [`commit-policy`](commit-policy.md)
-
-Committing is governed by the canonical [`commit-policy`](commit-policy.md)
-rule, which applies regardless of `personal.autonomy`. Summary:
-
-- 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`](scope-control.md#git-operations--permission-gated).
-
-## Failure modes
-
-Autonomy-side wrong-behavior patterns (sequencing-only asks, CI-run
-asks, commit asks, no-trade-off option blocks, re-asking after a
-standing opt-in):
-[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
-For Hard-Floor failure modes see
-[`non-destructive-by-default`](non-destructive-by-default.md#failure-modes).
+Algorithm and speech-act heuristic: [`contexts/execution/autonomy-detection.md`](../contexts/execution/autonomy-detection.md). Anchor phrases (DE+EN), no-flip patterns, counter-examples, trivial-vs-blocking taxonomy, commit-policy summary, and named failure modes: [`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md) + [`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
 
 ## See also
 
-- [`non-destructive-by-default`](non-destructive-by-default.md) —
-  universal safety floor; never overridden by autonomy
+- [`non-destructive-by-default`](non-destructive-by-default.md) — universal safety floor; never overridden by autonomy
 - [`scope-control`](scope-control.md) — git-ops permission gate
-  (push/merge/branch/PR/tag stays explicit)
-- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request
-  triggers that always require asking
-- [`no-cheap-questions`](no-cheap-questions.md) — mode-independent
-  floor against context-derived, sequencing-only, and
-  Iron-Law-violating asks (applies in `off` and pre-opt-in `auto` too)
-- [`direct-answers`](direct-answers.md) — Iron Laws on brevity and
-  no-flattery (this rule extends to no-trivial-questions)
-- [`/commit-in-chunks`](../commands/commit-in-chunks.md) — auto-split and commit without confirmation
-- [`/commit`](../commands/commit.md) — split and commit with confirmation
+- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request triggers that always require asking
+- [`no-cheap-questions`](no-cheap-questions.md) — mode-independent floor against context-derived asks
+- [`commit-policy`](commit-policy.md) — never-commit / never-ask Iron Law
+- [`/commit:in-chunks`](../commands/commit/in-chunks.md), [`/commit`](../commands/commit.md)