@event4u/agent-config 1.22.0 → 1.24.0

package/.agent-src/commands/memory/promote.md

@@ -120,15 +120,23 @@ git push -u origin memory/promote-<curated-id>
 # Then route to /create-pr with the memory-promote template hint.
 ```
 
-### 7. Report
-
-```
-> ✅ Promotion drafted.
-> - Signal:   <sig-id>
-> - Curated:  <curated-id> in agents/memory/<type>.yml
-> - PR:       <url or branch name>
-> - Next:     review + merge
-```
+### 7. Report (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:
+  `→ Promoted <sig-id> → <curated-id> (PR: <url or branch>)`.
+- `full` → multi-line block:
+
+  ```
+  > ✅ Promotion drafted.
+  > - Signal:   <sig-id>
+  > - Curated:  <curated-id> in agents/memory/<type>.yml
+  > - PR:       <url or branch name>
+  > - Next:     review + merge
+  ```
 
 ## Safety
 

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/commands/roadmap/process-full.md

@@ -28,7 +28,8 @@ with the **scope delta below**.
 ## Scope delta
 
 - **Working set:** every open step across every phase, in document
-  order.
+  order. **Horizon markers do not narrow the working set** — see
+  Iron Law below.
 - **Stop after:** the entire roadmap reaches `count_open == 0`, or a
   halt condition fires (Hard-Floor, council-off + ambiguity,
   security-sensitive, scope-out-of-roadmap, test/quality red).
@@ -40,10 +41,49 @@ with the **scope delta below**.
   archival check from
   [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
 
+## Iron Law — Full is Full
+
+```
+/roadmap:process-full PROCESSES EVERY OPEN STEP IN THE FILE.
+HORIZON MARKERS, "OUT-OF-HORIZON" LABELS, "GATED ON PHASE X"
+NOTES, AND PHASE-INTERNAL "OPTIONAL" TAGS DO NOT NARROW THE
+WORKING SET. ONLY THE FIVE HALT CONDITIONS STOP THE RUN.
+```
+
+Roadmaps frequently carry a "Horizon (N-week visible plate)" section
+or "(out-of-horizon, gated on Phase N)" sub-headings as an authoring
+device. Those are **archival annotations**, not execution gates.
+`/roadmap:process-full` ignores them by construction. If the user
+wants horizon-respecting execution, they invoke `/roadmap:process-phase`
+(scope = single phase) or `/roadmap:process-step` (scope = single
+step) instead.
+
+## Iron Law — Real-time dashboard
+
+```
+EVERY DONE STEP FLIPS [ ] → [x] BEFORE THE LOOP MOVES TO THE NEXT STEP.
+DASHBOARD REGENERATES IN THE SAME REPLY THAT FLIPPED THE BOX.
+NO BATCH FLIP AT THE ARCHIVE COMMIT. NO "I'LL DO IT AT THE END."
+```
+
+`/roadmap:process-full` is the worst offender for batching because it
+runs continuously across many steps. Flipping all 13 boxes in the
+single archive commit defeats the dashboard's purpose — the user
+loses progress visibility for the entire run. Per Iron Law 2 of
+[`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md): the
+flip + regen pair is atomic with the step's work, executed inside
+[`roadmap-process-loop § 5`](../../contexts/execution/roadmap-process-loop.md#5-step-loop)
+step 5.
+
 ## Rules
 
 - **No silent acceleration past a halt.** Every halt condition stops
   the run; the user resumes on the next turn.
+- **No silent stop at a horizon marker.** Encountering "out-of-horizon",
+  "gated on Phase N", "deferred", or any equivalent annotation is
+  **not** a halt condition. Continue.
+- **No silent batch flip.** Each step's checkbox flips in the same
+  reply that lands its work — never deferred to the archive commit.
 - **Phase quality pipeline runs at every phase boundary** when cadence
   is `per_phase` or `per_step`. `end_of_roadmap` skips per-phase and
   runs only at the final archival check.

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/contexts/execution/roadmap-process-loop.md

@@ -86,10 +86,17 @@ For each open step in the working set (scope-bound — see wrapper):
    - **Council on** → invoke per [`ai-council`](../../skills/ai-council/SKILL.md),
      integrate convergence, proceed. Token spend was opted in.
    - **Council off** → halt, surface once, wait. Resume on next turn.
-5. Mark the checkbox: `[x]` done · `[~]` partial · `[-]` skipped.
-6. Regenerate the dashboard — `./agent-config roadmap:progress` — in
-   the **same response** per [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
-7. Run quality pipeline if cadence is `per_step`.
+5. **Atomic flip + regen** — before moving to step N+1, in the **same
+   reply** that landed step N's work:
+   1. Flip the checkbox in `agents/roadmaps/<file>.md`: `[x]` done ·
+      `[~]` partial · `[-]` skipped.
+   2. Run `./agent-config roadmap:progress` to regenerate the
+      dashboard.
+   This pair is **non-skippable** and **non-batchable** per Iron Law 2
+   of [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md). A
+   loop iteration that lands work without flipping its box is a rule
+   violation. Do not save flips for the archive commit.
+6. Run quality pipeline if cadence is `per_step`.
 
 ### Halt conditions
 
@@ -101,6 +108,20 @@ For each open step in the working set (scope-bound — see wrapper):
 
 On halt: stop, surface state, do **not** auto-fix outside the failing step.
 
+### Non-halt — horizon markers, gating notes, "optional" tags
+
+The following are **authoring annotations**, never halt conditions. Do
+**not** stop execution when the roadmap text contains them:
+
+- `Horizon (N-week visible plate)` section headers
+- `(out-of-horizon, gated on Phase N)` phase-header suffixes
+- `(deferred)` / `(later)` / `(optional)` tags on a step
+- "Gate: Phase 1 ships and …" prose inside an out-of-horizon phase
+
+`process-step` and `process-phase` honor scope by stopping at their
+configured boundary anyway. `process-full` is **defined by** ignoring
+these markers — see [`/roadmap:process-full § Iron Law`](../../commands/roadmap/process-full.md#iron-law--full-is-full).
+
 ## 6. Final report and archival
 
 - Summary: scope-bound (steps/phases done in this run), council
@@ -118,8 +139,10 @@ On halt: stop, surface state, do **not** auto-fix outside the failing step.
 |---|---|---|
 | `process-step` | Single first open step | One iteration of § 5 |
 | `process-phase` | All open steps in first phase with `count_open > 0` | Phase boundary; per-phase quality if cadence ≠ `end_of_roadmap` |
-| `process-full` | Every open step across every phase, in order | Roadmap fully closed (or halt) |
+| `process-full` | Every open step across every phase, in order — **horizon markers do not narrow this set** | Roadmap fully closed (or halt) |
 
 `process-full` runs the per-phase quality pipeline at every phase
 boundary when cadence is `per_phase` or `per_step`; on red it halts
-before the next phase.
+before the next phase. It does **not** stop at horizon markers,
+"out-of-horizon" labels, or "gated on Phase N" notes — those are
+archival annotations, not halt conditions.

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.