@event4u/agent-config 1.22.0 → 1.23.0

package/.agent-src/commands/optimize/rtk.md

@@ -103,17 +103,22 @@ Run a quick test to confirm rtk picks up the filters:
 rtk config 2>&1 | tail -5
 ```
 
-### 7. Present results
-
-Show a summary table:
-
-```
-| # | Filter | Match | Max Lines |
-|---|---|---|---|
-| 1 | phpstan | phpstan\|quality:phpstan\|vendor/bin/phpstan | 80 |
-| 2 | pest | pest\|phpunit\|artisan test | 60 |
-| ... | ... | ... | ... |
-```
+### 7. Present results (verbosity-gated)
+
+Read `verbosity.post_action_reports` from `.agent-settings.yml` (default
+`minimal`).
+
+- `off` → emit nothing on success; surface errors only.
+- `minimal` (default) → one line: `→ N filters configured in .rtk/rtk.toml`.
+- `full` → multi-line summary table:
+
+  ```
+  | # | Filter | Match | Max Lines |
+  |---|---|---|---|
+  | 1 | phpstan | phpstan\|quality:phpstan\|vendor/bin/phpstan | 80 |
+  | 2 | pest | pest\|phpunit\|artisan test | 60 |
+  | ... | ... | ... | ... |
+  ```
 
 ### Rules
 

package/.agent-src/commands/prepare-for-review.md

@@ -80,12 +80,18 @@ Once all merges succeed:
 git checkout {head-branch-of-target-PR}
 ```
 
-### 7. Report
-
-Inform the user:
-- Which branch chain was processed (in order)
-- That the target branch is now checked out and up to date
-- Any warnings (e.g. branch was already up to date)
+### 7. Report (verbosity-gated)
+
+Read `verbosity.post_action_reports` from `.agent-settings.yml` (default
+`minimal`).
+
+- `off` → emit nothing on success; surface warnings/errors only.
+- `minimal` (default) → one line:
+  `→ {branch} ready · {N} branches merged · {warnings or "clean"}`.
+- `full` → multi-line block listing:
+  - Which branch chain was processed (in order)
+  - That the target branch is now checked out and up to date
+  - Any warnings (e.g. branch was already up to date)
 
 ## Rules
 

package/.agent-src/commands/project-analyze.md

@@ -75,12 +75,15 @@ LEGACY CHECK (indicators):
 ═══════════════════════════════════════════════
 ```
 
-Ask the user with numbered options:
+Per `verbosity.routine_confirmations` (default `false`):
 
-```
-> 1. Continue with Phase 2 — architecture analysis
-> 2. Stop here — keep the overview only
-```
+- `false` → continue to Phase 2 silently (user invoked `/project-analyze`
+  for the full pass; "continue" is dominant).
+- `true` → ask:
+  ```
+  > 1. Continue with Phase 2 — architecture analysis
+  > 2. Stop here — keep the overview only
+  ```
 
 ### Phase 2: Architecture mapping
 
@@ -192,12 +195,15 @@ BUSINESS DOMAINS:
 ═══════════════════════════════════════════════
 ```
 
-Ask the user with numbered options:
+Per `verbosity.routine_confirmations` (default `false`):
 
-```
-> 1. Yes — create domain analysis files
-> 2. Skip — continue with next phase
-```
+- `false` → create domain analysis files silently (user invoked
+  `/project-analyze`; "yes, create" is dominant).
+- `true` → ask:
+  ```
+  > 1. Yes — create domain analysis files
+  > 2. Skip — continue with next phase
+  ```
 
 For each confirmed domain, create `agents/analysis/domains/{domain}.md` using the template
 from the `project-analyzer` skill.
@@ -226,12 +232,14 @@ SERVICE MAP:
 ═══════════════════════════════════════════════
 ```
 
-Ask the user with numbered options:
+Per `verbosity.routine_confirmations` (default `false`):
 
-```
-> 1. Yes — create API and service analysis files
-> 2. Skip — continue with next phase
-```
+- `false` → create API + service analysis files silently.
+- `true` → ask:
+  ```
+  > 1. Yes — create API and service analysis files
+  > 2. Skip — continue with next phase
+  ```
 
 Create:
 - `agents/analysis/api/endpoints-v1.md`
@@ -253,12 +261,15 @@ Write all remaining analysis files that haven't been created yet:
 - `agents/analysis/modules/{module}.md` — one per module
 - `agents/analysis/testing/test-map.md` — test suites, coverage, strategy
 
-For each file, ask with numbered options:
+Per `verbosity.routine_confirmations` (default `false`):
 
-```
-> 1. Create — {filename}
-> 2. Skip
-```
+- `false` → create all listed files silently (per-file picker is pure
+  noise once the user invoked `/project-analyze`).
+- `true` → for each file, ask:
+  ```
+  > 1. Create — {filename}
+  > 2. Skip
+  ```
 
 ### Phase 8: Gap analysis & action plan
 

package/.agent-src/commands/review-changes.md

@@ -81,15 +81,22 @@ Pick dispatch mode based on diff size and environment:
 Each judge returns its own `Judge / Model / Target / Verdict /
 Issues` block in the format defined by that skill.
 
-### 4b. Optional external council (B3 hook)
+### 4b. Optional external council (B3 hook, verbosity-gated)
 
-If `.agent-settings.yml` has `ai_council.enabled: true` **and** at least
-one member is enabled, ask (in the user's language):
+Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
+(default `false`):
 
-> 1. Add an external council review alongside the four internal judges? (billable)
-> 2. Skip — internal judges only
+- `false` (default): skip the prompt silently. When `ai_council.enabled:
+  true` AND at least one member enabled, emit one line: `→ council
+  skipped (set verbosity.offer_council_in_delivery: true to enable, or
+  run /council diff:<base>..<head> directly)`. Otherwise emit nothing.
+- `true`: when `ai_council.enabled: true` **and** at least one member
+  enabled, ask (in the user's language):
 
-Suppress when `personal.autonomy: on` (council is billable).
+  > 1. Add an external council review alongside the four internal judges? (billable)
+  > 2. Skip — internal judges only
+
+  Also suppress when `personal.autonomy: on` (council is billable).
 
 If picked **1**:
 
@@ -124,17 +131,19 @@ Produce one combined report:
   ask before fixing 🟡 findings, report 🟢 as suggestions
 - If all four returned `apply` → the diff is ready; report and stop
 
-### 7. Quality tools (optional)
-
-After the consolidated report, ask:
+### 7. Quality tools (verbosity-gated)
 
-```
-> 1. Yes — run quality tools (formatter, static analyzer, linters)
-> 2. No — review done
-```
+Per `verbosity.routine_confirmations` (default `false`):
 
-If yes, hand off to the project's quality workflow (e.g. `/quality-fix`
-or the equivalent configured command).
+- `false` (default) → emit `→ run /quality-fix to format + lint` as a
+  single follow-up line; do not auto-invoke. User runs explicitly.
+- `true` → ask:
+  ```
+  > 1. Yes — run quality tools (formatter, static analyzer, linters)
+  > 2. No — review done
+  ```
+  If yes, hand off to the project's quality workflow (e.g.
+  `/quality-fix` or the equivalent configured command).
 
 ## Backward compatibility
 

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

@@ -137,18 +137,23 @@ Regenerate `agents/roadmaps-progress.md` so the new roadmap shows up:
 
 Mention the new overall count to the user.
 
-### 8. Offer council review (B1 hook)
+### 8. Offer council review (B1 hook, verbosity-gated)
 
-If `.agent-settings.yml` has `ai_council.enabled: true` **and** at least
-one member is enabled (`anthropic` or `openai`), ask the user (in their
-language):
+Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
+(default `false`):
 
-> 1. Run the council on this roadmap before execution? (billable)
-> 2. Skip council review
+- `false` (default): skip the prompt silently. When `ai_council.enabled:
+  true` AND at least one member enabled, emit one line: `→ council
+  skipped (set verbosity.offer_council_in_delivery: true to enable, or
+  run /council roadmap:<path> directly)`. Otherwise emit nothing.
+- `true`: when `ai_council.enabled: true` **and** at least one member
+  enabled (`anthropic` or `openai`), ask (in the user's language):
 
-Suppress this question entirely when `personal.autonomy: on` is set —
-council is billable, autonomous mode must not silently spend tokens
-(see `road-to-ai-council.md` Decision 3 / Q47).
+  > 1. Run the council on this roadmap before execution? (billable)
+  > 2. Skip council review
+
+  Also suppress when `personal.autonomy: on` (council is billable; see
+  `road-to-ai-council.md` Decision 3 / Q47).
 
 If the user picks **1**:
 

package/.agent-src/contexts/contracts/frugality-charter.md

@@ -0,0 +1,57 @@
+# Frugality Charter
+
+Cross-rule index for **writer skills** (skill-writing, rule-writing,
+command-writing, guideline-writing, context-authoring,
+agent-docs-writing, conventional-commits-writing, readme-writing,
+readme-writing-package, adr-create, persona-writing, roadmap-writing,
+script-writing).
+The canon is held by the named rules below; this file is index-only,
+plus the settings-hooks section that has no other canonical home.
+
+## Frugality canon — links into authoritative rules
+
+Cite the source rule in writer artifacts; do **not** restate it here.
+
+| Concern | Authoritative source |
+|---|---|
+| Default-terse output, skip intent prose, skip post-action summaries | [`direct-answers § Iron Law 3 — Brevity by Default`](../../rules/direct-answers.md#iron-law-3--brevity-by-default) |
+| Numbered-options trade-off rule (real consequence, not sequencing) | [`user-interaction § Iron Law 1 — Single-Source Recommendation`](../../rules/user-interaction.md#iron-law-1--single-source-recommendation) |
+| Cheap-question pre-send check (skip the ask if context already answers) | [`no-cheap-questions § Pre-Send Self-Check`](../../rules/no-cheap-questions.md#pre-send-self-check--mandatory-before-every-question) |
+| Tool-call discipline, act-skip-narration, fresh output over memory | [`token-efficiency § The Iron Laws`](../../rules/token-efficiency.md#the-iron-laws) and its mechanics file |
+
+## Confirmation taxonomy
+
+Iron-Law / Routine / Contextual classification with carve-outs
+lives in the roadmap [`§ Confirmation taxonomy`](../../../agents/roadmaps/road-to-token-frugality.md#confirmation-taxonomy).
+Charter does not duplicate the table.
+
+## Settings hooks
+
+Live Phase 1 schema (see [`templates/agent-settings.md`](../../templates/agent-settings.md#settings-reference)).
+
+| Key | One-line semantics |
+|---|---|
+| `verbosity.preview_artifacts` | When `false`, skip generated commit messages / PR titles / branch names preview before acting. |
+| `verbosity.routine_confirmations` | When `false`, skip "looks good?" gates on routine workflow steps. Iron-Law gates always ask. |
+| `verbosity.offer_council_in_delivery` | When `false`, delivery commands skip the optional "run Council on this?" offer. |
+| `verbosity.post_action_reports` | `off` / `minimal` / `full` — multi-line status blocks after a successful action. |
+| `verbosity.intent_announcements` | When `false`, writers must not generate "Let me…", "Now I will…", "Found it" openers. |
+| `caveman.speak_scope` | `off` / `prose_only` / `aggressive` — caveman-speak grammar scope. Iron-Law fenced blocks never touched. |
+
+Phase 10 adds `verbosity.script_output` (`silent` / `minimal` / `verbose`) and `verbosity.taskfile_command_echo` (`true` / `false`); writer artifacts cite this row when those land.
+
+## Cross-references — frugality canon rules
+
+Consolidated index. Source rules used to carry trailing
+`Interactions` / `See also` blocks; those are stripped to reclaim
+kernel chars. The pointers below replace them.
+
+| Rule | Interacts with |
+|---|---|
+| `direct-answers` | `language-and-tone` · `ask-when-uncertain` · `think-before-action` · `verify-before-complete` · `token-efficiency` · `user-interaction` (overrides brevity) · `caveman-speak` |
+| `no-cheap-questions` | `ask-when-uncertain` · `autonomous-execution` · `commit-policy` · `scope-control` · `non-destructive-by-default` · `user-interaction` · `direct-answers` |
+| `caveman-speak` | `language-and-tone` (mirror user language **before** caveman) · `direct-answers` Iron Law 3 (caveman is one brevity tactic, not a replacement) · `user-interaction` (numbered-options carve-out) · `commit-policy`, `non-destructive-by-default`, `scope-control` (Iron-Law literal fence carve-outs) |
+
+## Decidable carve-out predicates
+
+Predicates with one-sentence tests live in [`docs/guidelines/agent-infra/carve-out-predicates.md`](../../../docs/guidelines/agent-infra/carve-out-predicates.md). Default-terse applies unless a predicate's test is yes/no decidable from the artifact alone.

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

@@ -40,6 +40,15 @@ Each project documents its own architecture in `./agents/` and/or `AGENTS.md`.
 **Always read those files** before making structural decisions. Do not rely on this rule file
 for project-specific directory layouts, database conventions, or module systems.
 
+## Architectural Decision Records (ADRs)
+
+When a structural decision is non-trivial (kernel membership, contract change, library swap,
+deprecation, scope re-cut), record it as an ADR. Use the [`adr-create`](../skills/adr-create/SKILL.md)
+skill — it numbers the file (`ADR-NNN-<slug>.md`), writes the standard template
+(Status / Context / Decision / Consequences / Alternatives / References), and regenerates the
+index via `scripts/adr/regenerate_index.py`. ADRs land in `docs/adr/` by default; legacy
+projects use `docs/decisions/`. Reversible refactors and minor cleanups do **not** need ADRs.
+
 ## Module-Level Documentation
 
 Some projects use a module system (e.g. `app/Modules/` in Laravel projects).

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

@@ -17,7 +17,7 @@ ONE QUESTION PER TURN. NO EXCEPTIONS.
 ASK. WAIT FOR THE ANSWER. THEN ASK THE NEXT.
 ```
 
-Absolute. Every turn with a question has **exactly one** — even if trivial, independent, or batchable.
+Even if trivial, independent, or batchable — exactly one.
 
 ## When to ask
 
@@ -29,19 +29,9 @@ Absolute. Every turn with a question has **exactly one** — even if trivial, in
 
 ## Vague-request triggers — MUST ask
 
-Match without further context → ask **before** touching code:
+Nine patterns — "improve / optimize" · "add caching" · "make it better / cleaner" · "clean up this file" · "fix this" (no symptom) · "refactor X" · "use best practices" · "handle errors properly" · "add a UI / component / tile / page" in a mixed-framework repo. Match without further context → ask **before** touching code.
 
-- "improve / optimize this" — metric? speed, readability, memory?
-- "add caching" — store? scope? invalidation?
-- "make it better / cleaner" — by what standard?
-- "clean up this file" — dead code? format? refactor?
-- "fix this" (no symptom) — what output is wrong?
-- "refactor X" — target pattern? boundaries?
-- "use best practices" — whose? for what?
-- "handle errors properly" — which errors? log/retry/propagate?
-- "add a UI/component/tile/page" in mixed-framework repo — which stack?
-
-Examples: [`asking-and-brevity-examples § vague-triggers`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#vague-request-triggers--example-questions).
+Per-pattern missing-info and clarifying questions: [`asking-and-brevity-examples § vague-triggers`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#vague-request-triggers--example-questions).
 
 **Escape hatch:** unambiguous from ticket / open file / prior turn → proceed, state the assumption.
 

package/.agent-src/rules/caveman-speak.md

@@ -0,0 +1,78 @@
+---
+type: "auto"
+tier: "1"
+description: "When caveman.speak_scope != off — compress reply prose to caveman grammar with byte-for-byte carve-outs for numbered options, Iron-Law literals, code, paths, and error markers."
+source: package
+triggers:
+  - intent: "any reply"
+---
+
+# Caveman Speak
+
+Compress reply prose to caveman grammar per `caveman.speak_scope`. Body
+prose only — carve-outs preserved byte-for-byte.
+
+## Scope
+
+Read `caveman.speak_scope` from `.agent-settings.yml`:
+
+- `off` — rule inactive.
+- `prose_only` (default) — caveman in body prose; carve-outs preserved.
+- `aggressive` — caveman everywhere except Iron-Law literals.
+
+Compile-time toggle `caveman.speak`: `false` → rule omitted from
+`router.json` (zero runtime cost). `caveman.enabled: false` forces all
+sub-switches off regardless.
+
+## Carve-outs — byte-for-byte preserved
+
+Mangling these breaks Iron Laws. Apply regardless of `speak_scope`:
+
+1. **Triple-backtick ALL-CAPS blocks** — Iron-Law literal fences in
+   `commit-policy`, `non-destructive-by-default`, `direct-answers`, etc.
+2. **Numbered-options blocks** — lines matching `^>?\s*\d+\.\s` plus
+   the `**Recommendation:**` / `**Empfehlung:**` label
+   (`user-interaction` Iron Law 1).
+3. **Code blocks** — any triple-backtick fence, any language.
+4. **Backtick spans** — file paths, command names, identifiers
+   (`direct-answers` Iron Law 2 — no invented facts).
+5. **Status / error markers** — lines prefixed `❌`, `⚠️`, `✅`.
+6. **Mode markers** per `role-mode-adherence`.
+7. **Deliverables** — PR titles / bodies, commit messages, ticket
+   summaries, articles, single-question prompts asked to the user.
+   These are written **for** the user, not chat-prose.
+
+## Enforcement mechanism
+
+Post-rewrite validator runs on every reply when `speak_scope != off`:
+
+1. **Snapshot** — before compression, hash each line in carve-out
+   regions (1–7 above).
+2. **Rewrite** — compress body prose to caveman grammar.
+3. **Validate** — re-scan; for each carve-out region whose line hash
+   differs from the snapshot, **restore the original prose**.
+4. **Emit** — the validated reply.
+
+The rule documents the algorithm; agents apply it inline before
+sending. The mechanism is the rule, not a hidden script.
+
+## Caveman grammar
+
+- Drop articles (`the`, `a`, `an`).
+- Drop linking auxiliaries (`is`, `are`, `was`, `be`) where
+  unambiguous.
+- Drop pronouns when context is clear.
+- Keep nouns, verbs, key adjectives, negation, numbers.
+
+Example: *"I will now check the file and see if it exists"* →
+*"Check file. Exists?"*
+
+## Settings
+
+| Key | Default | Effect |
+|---|---|---|
+| `caveman.enabled` | `true` | Master — `false` forces all sub-switches off. |
+| `caveman.speak` | `true` | Compile-time include in `router.json`. |
+| `caveman.speak_scope` | `prose_only` | Runtime scope of caveman grammar. |
+
+Cross-rule index: [`frugality-charter § cross-references`](../contexts/contracts/frugality-charter.md#cross-references--frugality-canon-rules).

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

@@ -13,12 +13,10 @@ Three Iron Laws govern every reply.
 ## Iron Law 1 — No Flattery
 
 ```
-NEVER OPEN WITH "GREAT QUESTION", "FASCINATING", "EXCELLENT POINT".
-NEVER PRAISE THE USER'S IDEA TO MAKE THEM HAPPY.
+NEVER OPEN WITH "GREAT QUESTION", "FASCINATING", OR PRAISE TO PLEASE THE USER.
 ANSWER THE SUBSTANCE. SHIP THE TRUTH.
 ```
 
-- No positive-adjective opener about user / question / idea / work.
 - No subjective judgment on user code unless evaluation was asked.
 - "Good catch" / "you're right" only when literally true.
 - Mistakes — one-sentence acknowledge, switch behavior, no apology theatre.
@@ -31,14 +29,7 @@ THE MORE LOAD-BEARING THE CLAIM, THE HARDER YOU VERIFY.
 WHEN VERIFICATION IS NOT WORTH THE COST → ASK.
 ```
 
-| Severity | Action |
-|---|---|
-| **High** — load-bearing (paths, signatures, versions, security, "this passes") | Verify with `view` / `grep` / `codebase-retrieval` / fresh output. Too expensive → ask. |
-| **Medium** — project-shape (conventions, file location) | One-tool-call verify, else hedge: *"I'd guess X — not checked"*. |
-| **Low** — well-known idioms | Inference OK; mark as inference if not 100% sure. |
-
-Override: "just guess" / "rough estimate" / "skip verify" → drop to Low for that turn.
-Examples + hedge patterns: [`asking-and-brevity-examples § severity`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--severity-tiered-claim-examples).
+Severity tiers (High = load-bearing · Medium = project-shape · Low = idioms), per-tier verification actions, and "just guess" override: [`asking-and-brevity-examples § severity`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--severity-tiered-claim-examples).
 
 ## Iron Law 3 — Brevity by Default
 
@@ -54,6 +45,8 @@ LONG ANSWERS ARE A FAILURE MODE, NOT A SIGN OF EFFORT.
 
 Never overrides `user-interaction` (numbered options stay) or command-mandated steps.
 
+**Narration carve-out:** restore narration only when both `personal.play_by_play` AND `verbosity.intent_announcements` are `true` in `.agent-settings.yml`.
+
 ## Emoji Scope — functional markers only
 
 **Whitelist:** mode markers (`role-mode-adherence`); CLI status `❌` / `✅` / `⚠️`; roadmap checkboxes `[x]` / `[~]` / `[-]`.
@@ -65,6 +58,4 @@ Trigger phrases + correction pattern: [`asking-and-brevity-examples § failure-m
 Pattern Memory (wrong / right / why): [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md).
 Outcome baseline: [`tests/golden/outcomes/direct_answers.json`](../../tests/golden/outcomes/direct_answers.json).
 
-## Interactions
-
-`language-and-tone` · `ask-when-uncertain` · `think-before-action` · `verify-before-complete` · `token-efficiency` · `user-interaction` (overrides brevity).
+Cross-rule index: [`frugality-charter § cross-references`](../contexts/contracts/frugality-charter.md#cross-references--frugality-canon-rules).

package/.agent-src/rules/markdown-safe-codeblocks.md

@@ -12,12 +12,11 @@ triggers:
 
 # Markdown Safe Codeblocks
 
-When generating markdown with code blocks:
+When generating markdown that contains code blocks:
 
-- **NEVER** nest triple backticks inside triple backticks — this breaks rendering and copy/paste.
-- If content already contains triple backticks, use one of:
-  - Plain text blocks (indented by 4 spaces) — **preferred**
-  - `~~~` fences instead of backtick fences
-  - Four backticks (``````) as outer fence
+- **NEVER** nest triple backticks inside triple backticks — breaks rendering and copy/paste.
+- Content to be wrapped contains ``` blocks → **use `~~~` as the outer fence. This is the default.** Inner ``` renders correctly inside `~~~`.
+- Four-backtick outer fences render inconsistently across clients — **do not use**.
+- 4-space indented blocks: acceptable fallback only when plain text without language highlighting is enough.
 - Prefer stability over pretty formatting.
-- Always validate: no broken rendering, no prematurely closed blocks, entire content is selectable and copyable.
+- Always validate before sending: no broken rendering, no prematurely closed blocks, entire content selectable and copyable.

package/.agent-src/rules/no-cheap-questions.md

@@ -20,17 +20,9 @@ NEVER OFFER NUMBERED CHOICES WITHOUT A REAL TRADE-OFF.
 
 ## What counts as cheap
 
-- **Sequencing** — "Step 2 or 3 next?" when the roadmap orders them.
-- **Format-only** — "Table or paragraph?"; no semantic trade-off.
-- **Commit asks** — forbidden by [`commit-policy`](commit-policy.md).
-- **CI / test asks** — [`verify-before-complete`](verify-before-complete.md) decides, not the user.
-- **Fenced-step re-asks** — "Start Phase 1?" after *"plan only"*; see [`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates).
-- **Iron-Law option** — breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`.
-- **Context-derived** — answer follows from prior turn / standing instruction / roadmap; act, state the assumption inline.
-- **Dominant option** — one choice obviously correct; alternatives carry no upside.
-- **Re-ask after decline** — forbidden per [`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task).
-
-Examples per class: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
+Nine classes — sequencing · format-only · commit asks (forbidden by [`commit-policy`](commit-policy.md)) · CI / test asks ([`verify-before-complete`](verify-before-complete.md) decides) · fenced-step re-asks ([`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates)) · Iron-Law option (breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`) · context-derived · dominant option · re-ask after decline ([`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task)).
+
+Per-class patterns and examples: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
 
 ## Pre-Send Self-Check — MANDATORY before every question
 
@@ -55,6 +47,4 @@ Any "yes" → **do not ask**. Pick the dominant path, state assumption inline (*
 
 In doubt → ask. This rule narrows asking, never widens silence.
 
-## Interactions
-
-[`ask-when-uncertain`](ask-when-uncertain.md) · [`autonomous-execution`](autonomous-execution.md) · [`commit-policy`](commit-policy.md) · [`scope-control`](scope-control.md) · [`non-destructive-by-default`](non-destructive-by-default.md) · [`user-interaction`](user-interaction.md) · [`direct-answers`](direct-answers.md).
+Cross-rule index: [`frugality-charter § cross-references`](../contexts/contracts/frugality-charter.md#cross-references--frugality-canon-rules).

package/.agent-src/rules/token-efficiency.md

@@ -21,16 +21,14 @@ NEVER load full command output into context. Redirect → read summary → targe
 ```
 
 ```
-NEVER call the same tool more than 2 times in a row with similar parameters.
-If you catch yourself repeating a tool call — STOP, rethink, try a different approach, or ask the user.
+NEVER CALL THE SAME TOOL >2 TIMES IN A ROW WITH SIMILAR PARAMETERS.
+IF YOU CATCH YOURSELF REPEATING → STOP, RETHINK, ASK.
 ```
 
 ## Fresh Output Over Memory
 
-When a tool or command returns a value (branch name, file path, PR number), use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in the conversation. Context decay → silent mismatches — fresh output is the only source of truth.
+When a tool returns a value (branch name, file path, PR number), use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in the conversation. Context decay causes silent mismatches — fresh output is the only source of truth.
 
-## Mechanics — anti-loop patterns, conversation efficiency, exceptions
+## Mechanics
 
-The anti-loop patterns (extended-reasoning loops, "CRITICAL INSTRUCTION" self-prompting), the act-skip-narration / stop-early / keep-output-minimal / don't-re-read / minimize-tool-calls clauses, and the small-output / debugging / explicit-full-output exceptions all live in [`contexts/communication/rules-auto/token-efficiency-mechanics.md`](../contexts/communication/rules-auto/token-efficiency-mechanics.md). The rule above is the obligation surface; the mechanics file is the lookup material.
-
-This rule NEVER overrides `user-interaction` or command rules. Token efficiency means fewer *unnecessary* words — NOT skipping required questions, numbered options, or command steps.
+Anti-loop patterns, act-skip-narration / stop-early / minimize-tool-calls clauses, and small-output / debugging exceptions: [`token-efficiency-mechanics`](../contexts/communication/rules-auto/token-efficiency-mechanics.md). Precedence: never overrides `user-interaction` or command rules.