@event4u/agent-config 1.21.0 → 1.23.0

package/.agent-src/contexts/augment-infrastructure.md

@@ -106,7 +106,7 @@ Commands organized by workflow:
 | **Bugs** | `bug-investigate`, `bug-fix` |
 | **Contexts** | `context-create`, `context-refactor` |
 | **Modules** | `module-create`, `module-explore` |
-| **Roadmaps** | `roadmap-create`, `roadmap-execute` |
+| **Roadmaps** | `roadmap:create`, `roadmap:process-step`, `roadmap:process-phase`, `roadmap:process-full` |
 | **Quality** | `quality-fix`, `review-changes`, `prepare-for-review`, `update-form-request-messages`, `fix-seeder` |
 | **CI/PR** | `fix-ci`, `create-pr`, `create-pr-description`, `fix-pr-comments`, `fix-pr-bot-comments`, `fix-pr-developer-comments` |
 | **Testing** | `tests-create`, `tests-execute` |

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

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

package/.agent-src/contexts/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

@@ -0,0 +1,125 @@
+# Roadmap-Process Loop
+
+Loaded by [`/roadmap:process-step`](../../commands/roadmap/process-step.md),
+[`/roadmap:process-phase`](../../commands/roadmap/process-phase.md), and
+[`/roadmap:process-full`](../../commands/roadmap/process-full.md). Holds
+the canonical autonomous-execution loop, roadmap discovery, cadence
+resolution, commit-step pre-scan, halt conditions, and archival check.
+The three command files are thin wrappers that bind only the **scope
+delta**.
+
+**Size budget:** ≤ 4,000 chars.
+
+## 1. Resolve roadmap
+
+Search both locations:
+
+- `agents/roadmaps/*.md` (project root)
+- `app/Modules/*/agents/roadmaps/*.md` (module-scoped)
+
+**Exclude** `template.md`, `archive/`, and `skipped/`.
+
+- User named one (path, partial name, title) → use it.
+- None named, single active roadmap (`count_open > 0`) → use it.
+- None named, multiple active → default = **most recently modified**;
+  surface alternatives in the pre-run summary.
+- None active → tell the user; suggest [`/roadmap:create`](../../commands/roadmap/create.md).
+
+## 2. Pre-run summary — single confirmation gate
+
+Before the loop runs, show the resolved config in the user's language:
+
+> Roadmap: `<resolved-path>`
+> Phase 1: `<name>` — 3/5 done
+> Phase 2: `<name>` — 0/4
+> Next open step: `<description>`
+> Scope: **step | phase | full**
+> AI council: **on | off** (`<member list or "no members configured">`)
+> Quality cadence: **end_of_roadmap | per_phase | per_step**
+> Commit steps in roadmap: **N** (see § 3)
+>
+> 1. Go — start processing autonomously
+> 2. Different roadmap · 3. Different scope · 4. Toggle council · 5. Abort
+
+Skip the gate when scope, roadmap, and council are all unambiguous in
+the invocation (e.g. `/roadmap:process-phase road-to-X.md with council`).
+
+## 3. Commit-step pre-scan — one upfront ask
+
+Before step 4, scan the roadmap for explicit commit steps (lines
+matching `commit:` / `git commit` / `Commit phase` patterns).
+
+- **No commit steps** → nothing to ask. Never commit, never re-ask
+  per [`commit-policy`](../../rules/commit-policy.md).
+- **Commit steps present, autonomous mode** (`personal.autonomy: on`,
+  or `auto` after opt-in) → ask **once** upfront:
+  > "Roadmap contains N commit steps. Authorize all of them for this
+  > run? (yes / no / list them)"
+  Cache the answer for the whole run; do **not** re-ask per step.
+  Hard-Floor diffs (bulk deletions, infra) still trigger the
+  per-commit gate from [`commit-mechanics`](../authority/commit-mechanics.md).
+- **Commit steps present, non-autonomous** → ask before each commit
+  step inside the loop.
+
+## 4. Resolve quality cadence
+
+Read `roadmap.quality_cadence` from `.agent-settings.yml` once:
+
+| Value | Pipeline runs |
+|---|---|
+| `end_of_roadmap` (default) | Once, before archival (§ 6) |
+| `per_phase` | At every phase boundary + § 6 |
+| `per_step` | After every step + § 6 |
+
+Missing / unreadable / unknown → fall back to `end_of_roadmap`.
+The Iron Law [`verify-before-complete`](../../rules/verify-before-complete.md)
+still mandates fresh quality output before any "complete" claim.
+
+## 5. Step loop
+
+For each open step in the working set (scope-bound — see wrapper):
+
+1. Read the step description and inline notes.
+2. Analyze the codebase for what the step requires.
+3. Decide and act — implement. **No "should I implement this?" prompt.**
+4. **Open question handling:**
+   - **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`.
+
+### Halt conditions
+
+- Hard-Floor trigger ([`non-destructive-by-default`](../../rules/non-destructive-by-default.md))
+- Security-sensitive path ([`security-sensitive-stop`](../../rules/security-sensitive-stop.md))
+- Step reveals work outside the roadmap's scope
+- Test failure or quality red on `per_step`
+- Council off + true ambiguity
+
+On halt: stop, surface state, do **not** auto-fix outside the failing step.
+
+## 6. Final report and archival
+
+- Summary: scope-bound (steps/phases done in this run), council
+  consultations count (if on), steps remaining, halts.
+- Final dashboard regen.
+- **If the entire roadmap reached `count_open == 0`** → run the full
+  project quality pipeline. On green → archival via the
+  [`roadmap-management`](../../skills/roadmap-management/SKILL.md) skill
+  (`git mv` to `agents/roadmaps/archive/`, regenerate dashboard). On
+  red → stop, surface failures, do **not** archive.
+
+## Scope deltas — what each wrapper binds
+
+| Wrapper | Working set | Stop after |
+|---|---|---|
+| `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` 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.

package/.agent-src/contexts/skills-and-commands.md

@@ -30,7 +30,7 @@ Commands often chain together. Here are the main workflows:
 ### Feature Development
 
 ```
-/feature-explore → /feature-plan → /feature-roadmap → /roadmap-execute
+/feature-explore → /feature-plan → /feature-roadmap → /roadmap:process-phase
      ↓                  ↓                ↓                    ↓
   Brainstorm        Structure         Phases/Steps        Implement
 ```

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/improve-before-implement.md

@@ -4,6 +4,7 @@ tier: "2b"
 description: "Before implementing features or architectural changes — validate the request against existing code, challenge weak requirements, and suggest improvements"
 alwaysApply: false
 source: package
+council_depth: deep
 triggers:
   - intent: "implement feature"
   - intent: "architectural change"

package/.agent-src/rules/invite-challenge.md

@@ -0,0 +1,71 @@
+---
+type: "auto"
+tier: "2b"
+description: "Before executing a complex plan or non-trivial design — proactively ask 'am I solving the right problem?' and pause for user confirmation, even when no ambiguity is detected"
+alwaysApply: false
+source: package
+council_depth: deep
+triggers:
+  - intent: "complex plan"
+  - intent: "design decision"
+  - intent: "architectural plan"
+  - intent: "multi-step implementation"
+  - keyword: "plan"
+  - keyword: "design"
+  - keyword: "architecture"
+  - keyword: "approach"
+---
+
+# invite-challenge
+
+## The Iron Law
+
+```
+BEFORE EXECUTING A COMPLEX PLAN — ASK ONCE:
+"AM I SOLVING THE RIGHT PROBLEM?"
+PAUSE. WAIT FOR CONFIRMATION. THEN PROCEED.
+```
+
+Proactive confirmation checkpoint. Distinct from [`direct-answers`](direct-answers.md) (reactive — fires after misdirection is detected) and [`ask-when-uncertain`](ask-when-uncertain.md) (info-gathering — fires when context is missing). This rule fires when context is **sufficient** and direction **looks correct** but the plan is heavy enough that a silent misread would be expensive.
+
+## When to activate
+
+Two or more of:
+
+- Touches ≥ 3 files or ≥ 2 modules
+- New abstraction, pattern, or library
+- Security / billing / tenant / data-boundary path
+- Migration, schema change, or backwards-incompatible API change
+- Estimated effort > 30 min of agent work
+- High-level goal ("rebuild the dashboard") rather than a bounded task ("rename this method")
+
+**Does NOT activate for:** evidenced bug fixes · trivial edits · user-fenced tasks ("just do it") · steps inside an already-confirmed plan (ask once per plan, not per step) · cases handled by [`improve-before-implement`](improve-before-implement.md) Phase 1.
+
+## How to challenge
+
+One question, one turn. Numbered options per [`user-interaction`](user-interaction.md):
+
+```
+> Before I start, one check:
+>
+> Goal as I read it: {1-sentence restatement}
+> Plan: {2-3 bullet shape, not full implementation}
+> Risk if I misread: {what would be wasted}
+>
+> 1. Goal + plan match — proceed
+> 2. Goal right, plan needs adjustment — say what
+> 3. Goal wrong — let me restate
+```
+
+The restatement is the load-bearing part. Pick 1 → execute. Pick 2 or 3 → fold the correction in, do not re-ask.
+
+## Scope limits
+
+- **One challenge per plan**, not per step.
+- **Skip when the user already restated the goal** in the same turn.
+- **Skip when [`scope-control § fenced step`](scope-control.md) applies** — deliver the plan, hand back, no confirmation question appended.
+- **Never argue the goal twice** — user's restatement is final for the turn.
+
+## Interactions
+
+[`direct-answers`](direct-answers.md) fires after misdirection · [`ask-when-uncertain`](ask-when-uncertain.md) fires on missing context · [`improve-before-implement`](improve-before-implement.md) Phase 1 already runs a clarity check (do not double-ask) · [`scope-control § fenced step`](scope-control.md) handback wins · [`no-cheap-questions`](no-cheap-questions.md) — checkpoint must carry a real goal restatement, not a content-free "ready?".

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.