@event4u/agent-config 1.15.0 → 1.17.0

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

@@ -2,19 +2,22 @@
 type: "auto"
 description: "Creating, editing, or modifying files inside .agent-src/ or .augment/ — the source of truth is .agent-src.uncompressed/, never edit the generated directories directly"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/augment-source-of-truth-mechanics.md
 ---
 
 # Source of Truth
 
-`.agent-src.uncompressed/` is the **single source of truth**. Compressed output
-ships as `.agent-src/`. In the package repo, `.augment/` is a local projection
-of `.agent-src/` for Augment Code (rules copied, rest symlinked). Consumer
-projects still see `.augment/` as the installed runtime tree.
+`.agent-src.uncompressed/` is the **single source of truth**. The compressed
+output ships as `.agent-src/`. In the package repo, `.augment/` is a local
+projection of `.agent-src/` for Augment Code (rules copied, rest symlinked).
+Consumer projects still see `.augment/` as the installed runtime tree.
 
-Never edit any generated layer directly:
+Never edit any of these generated layers directly:
 
 - `.agent-src/` — compressed output shipped in the package
-- `.augment/` — local projection (gitignored in package; installer output in consumers)
+- `.augment/` — local projection (gitignored in the package repo; installer
+  output in consumer projects)
 - `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` — tool projections
 
 ## The Iron Rule
@@ -24,73 +27,20 @@ NEVER create or edit files in .agent-src/ or .augment/ directly — not even "ju
 ALWAYS work in .agent-src.uncompressed/ — then compress via /compress command.
 ```
 
-**ZERO exceptions.** Even if the fix is obvious, small, or "faster" — STOP.
-Edit `.agent-src.uncompressed/` first. Always.
+**There are ZERO exceptions to this rule.** Even if:
 
-Direct edits to `.agent-src/` break compression hashes, cause CI failures, and create drift.
+- You "know" the compressed content is correct
+- It's "just adding a missing section"
+- It's "faster to edit the compressed file directly"
+- The fix is "trivially obvious"
 
-**Compression ONLY via `/compress` command.** Handles hashing, sync, and quality checks.
+**STOP. Edit `.agent-src.uncompressed/` first. Always.**
 
-## Workflow
+Direct edits to `.agent-src/` break compression hashes, cause CI failures
+("Verify compression hashes" step), and create drift between source and output.
 
-1. **Create or edit** the file in `.agent-src.uncompressed/{path}`
-2. **Do NOT auto-compress.** Continue working.
-3. **Before commit/push:** Check if compression is needed (`bash scripts/compress.sh --changed`).
-   If files need compression, ask the user:
-   ```
-   > 📦 {N} .agent-src files need compression before commit.
-   >
-   > 1. Compress now — run /compress
-   > 2. Later — commit without compression
-   ```
-4. If compressing: run `/compress` command, then `bash scripts/compress.sh --mark-done {path}`
-
-For new non-.md files (`.php`, configs): `bash scripts/compress.sh --sync` copies them automatically.
-
-**Key change:** Compression happens once before commit/push — not after every edit.
-This avoids interruptions when work is still in progress.
-
-## What "compress" means
-
-- Remove articles (a, an, the), filler, hedging, connective fluff
-- Shorten phrases: "in order to" → "to", "make sure to" → "ensure"
-- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
-- Merge redundant bullets
-
-## What NEVER changes during compression
-
-- Code blocks, inline code, URLs, file paths, commands
-- Headings (exact text preserved)
-- Tables (structure preserved, compress cell text only)
-- YAML frontmatter
-- Technical terms, library names, API names
-- Strong language: "NEVER", "MUST", "Do NOT" — these are load-bearing
-
-## Commands workflow
-
-Commands live in `.agent-src.uncompressed/commands/{name}.md` (single source of truth).
-Claude Code reads them via symlinks in `.claude/skills/{name}/SKILL.md`.
-
-**Required frontmatter for commands:**
-
-```yaml
-name: {command-name}
-description: {what it does}
-disable-model-invocation: true
-```
-
-- `name` and `disable-model-invocation: true` are required for Claude Code compatibility
-- Augment ignores unknown frontmatter fields — no conflict
-- Template: `.agent-src.uncompressed/templates/command.md`
-
-**Creating a new command:**
-
-1. Create `.agent-src.uncompressed/commands/{name}.md` (use template)
-2. Run `python3 scripts/skill_linter.py` — must be 0 FAIL
-3. Compress via `/compress`, which writes to `.agent-src/commands/`
-4. Run `python3 scripts/compress.py --generate-tools` — creates Claude symlink automatically
-
-**Never** create `.claude/skills/{name}/SKILL.md` manually for commands — always use the symlink workflow.
+**Compression is ONLY done via the `/compress` command.** The command handles
+hashing, sync verification, and quality checks automatically.
 
 ## Pre-review consistency checkpoints
 
@@ -101,28 +51,12 @@ Before asking for review or creating a PR, verify derived outputs are not stale:
 3. Before merge: verify derived outputs (`.agent-src/`, `.augment/`, `.claude/skills/`) are regenerated
 4. Do NOT leave `.agent-src/` stale across review cycles
 
-## Multi-agent symlink mapping
-
-`.claude/skills/` contains symlinks to **both** `.agent-src/skills/` and `.agent-src/commands/`.
-Claude Code treats both as "skills" — but they are different artifact types in our taxonomy.
-
-| `.claude/skills/{name}/SKILL.md` points to... | Actual type |
-|---|---|
-| `.agent-src/skills/{name}/SKILL.md` | **Skill** (workflow) |
-| `.agent-src/commands/{name}.md` | **Command** (slash-invoked procedure) |
-
-Always check the symlink target to determine the actual artifact type.
-Commands have `disable-model-invocation: true` in their frontmatter.
-
-## Quick reference
+## Mechanics — workflow, compression rules, commands, symlinks, quick reference
 
-| Task | What to do |
-|---|---|
-| Edit existing file | Edit in `.agent-src.uncompressed/`, compress to `.agent-src/` |
-| Create new `.md` | Create in `.agent-src.uncompressed/`, compress to `.agent-src/` |
-| Create new non-`.md` | Create in `.agent-src.uncompressed/`, run `bash scripts/compress.sh --sync` |
-| Create new command | Create in `.agent-src.uncompressed/commands/`, sync, `python3 scripts/compress.py --generate-tools` |
-| Delete a file | Delete from `.agent-src.uncompressed/` and `.agent-src/` |
-| Check what needs compression | `bash scripts/compress.sh --changed` |
-| Mark file as compressed | `bash scripts/compress.sh --mark-done {path}` |
-| Verify everything is in sync | `bash scripts/compress.sh --check` |
+The authoring workflow, what compression does (and never touches), the
+commands workflow with required frontmatter, the multi-agent symlink
+mapping, and the per-task quick-reference table live in
+[`contexts/communication/rules-auto/augment-source-of-truth-mechanics.md`](../contexts/communication/rules-auto/augment-source-of-truth-mechanics.md).
+Pull it whenever an edit, new file, new command, or sync question
+fires — the rule above is the obligation surface; the mechanics file
+is the lookup material.

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

@@ -1,158 +1,122 @@
 ---
-type: "always"
-description: "Suppress trivial workflow questions and act on the obvious next step; defers to non-destructive-by-default for the safety floor; never commit and never ask about committing except via /commit-in-chunks or explicit user instruction"
-alwaysApply: true
+type: "auto"
+description: "Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor"
+alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/execution/autonomy-detection.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-mechanics.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-examples.md
 ---
 
 # Autonomous Execution
 
 User's time is the scarce resource. Trivial workflow questions are
-noise. Defines **trivial** (just act), **blocking** (still ask), the
-**hard floor** (always ask, no override), and the **commit default**
-(never commit, never ask — review-first by design).
+noise. This rule defines **trivial** (just act), **blocking** (still
+ask), the **hard floor** (always ask, no override), and the **commit
+default** (never commit, never ask — review-first by design).
 
 ## Hard Floor — see [`non-destructive-by-default`](non-destructive-by-default.md)
 
-Universal safety floor (production-branch merges, deploys, pushes,
+The universal safety floor (production-branch merges, deploys, pushes,
 prod data/infra, whimsical bulk deletions, and commits containing
 bulk deletions or infra changes) is governed by the canonical
 [`non-destructive-by-default`](non-destructive-by-default.md) rule.
-
-Applies regardless of `personal.autonomy`, a standing autonomy
-directive (anchor list in [Opt-in detection](#opt-in-detection--match-by-intent-not-exact-string)),
-or any roadmap authorization. Nothing in **this** rule lifts it. If a
-trigger from that rule fires, stop and ask — every section below
-assumes the floor has cleared.
+It applies regardless of `personal.autonomy`, a standing autonomy
+directive, or any roadmap authorization. Nothing in **this** rule
+lifts it. If a trigger fires, stop and ask — every other section
+below assumes the floor has already been cleared.
 
 ## Setting — `personal.autonomy`
 
-| Value | Behavior |
-|---|---|
-| `on` | Suppress trivial questions. Act on obvious next step. Still ask on blocking decisions; ALWAYS ask on Hard-Floor triggers. |
-| `off` | Ask trivial questions too. Use to check in on each workflow step. |
-| `auto` (default) | Like `off` until user expresses "stop asking, just work" — then `on` for the rest of the chat. See **Opt-in detection** below; match by **intent**, not exact string. The flip never lifts the Hard Floor. |
-
-Read once on first turn (per [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
-and cache. Missing key → treat as `on`.
+Three values: `on` (suppress trivial questions), `off` (ask trivial
+questions too), `auto` (default — same as `off` until the user opts
+in via a standing autonomy directive). Read once on the first turn
+(per [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules))
+and cache. Missing key → treat as `on`. Full table, semantics, and
+cloud behavior:
+[`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md).
 
 ## Opt-in detection — match by intent, not exact string
 
-In `auto`, flip to `on` for the rest of the chat when the user expresses
-**"stop asking on trivial steps, just work"**. Recognize the **intent**,
-not the literal substring — semantic equivalent in either language.
-
-Anchor examples (illustrative, not exhaustive):
-
-- DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
-- EN: "work autonomously" · "don't ask" · "just do it"
-
-Litmus test: standing permission to skip trivial questions? → flip.
-Single-decision delegation ("you decide for this step") → handle that
-step, do **not** flip standing mode.
-
-### Speech-act check — meta-instruction, not content
-
-Before flipping, verify the phrase is **addressed to the agent as
-guidance about how to work**, not a literal substring inside another
-instruction. Do **not** flip when the phrase is:
-
-- **Content / copy** — "Put the slogan 'just do it' on the landing page."
-- **Quote / reference** — "Nike's tagline is 'just do it' — write a blog post."
-- **Subject of a request** — "Write docs about the 'work autonomously' modes."
-- **Code / data** — string literals, fixtures, translations, JSON.
-- **About a third party** — "My colleague works autonomously."
-- **Question / hypothetical** — "Should I set `don't ask` as the default?"
-
-Heuristic: strip quotes, code blocks, embedded content. Read what's
-**left**. Still a directive to the agent about its working style →
-flip. Otherwise → don't.
-
-Opt-out (reversed intent) flips back to `off`:
+In `auto` mode, flip to `on` for the rest of the conversation when
+the user expresses **"stop asking on trivial steps, just work"**.
+Recognize **intent**, not the literal substring. Opt-out (same intent,
+reversed) flips back to `off`. Both directions are
+**speech-act-checked**: the phrase must be a meta-instruction to the
+agent, not content / quote / subject / code / third-party reference /
+hypothetical. In doubt → keep current mode, no speculative flips.
 
-- DE: "frag mich wieder" · "frag mich erst" · "stop autonomous mode"
-- EN: "ask me first" · "ask me again" · "stop being autonomous"
-
-Same speech-act check applies.
-
-Counter-examples — do **not** flip on meta-questions, self-descriptions,
-or one-shot delegations: "why don't you ask that yourself?", "I'm
-working autonomously right now", "can you decide that yourself?".
-
-In doubt → keep current mode, no speculative flips.
+Algorithm and speech-act heuristic:
+[`contexts/execution/autonomy-detection.md`](../contexts/execution/autonomy-detection.md).
+Anchor phrases (DE+EN), no-flip patterns, counter-examples:
+[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
 
 ## Trivial — JUST ACT, do not ask
 
-Examples (matches `personal.autonomy: on` or `auto`-after-opt-in):
-
-- "Step 2 or Step 3?" — pick the obvious next roadmap step; if blocked, name the blocker, otherwise go.
-- "Commit now or after the next change?" — answered by the commit-default below.
-- "How should I split the commits?" — never asked; either `/commit-in-chunks` was invoked (split + commit) or it wasn't (don't commit).
-- "Run linter / tests now or later?" — `verify-before-complete` decides; act.
-- "Found 3 follow-ups — fix all or stop?" — if within scope and minimal-safe-diff allows, fix; if scope expands, stop and surface as list.
-- "Filename `X.md` or `Y.md`?" when one matches convention — pick convention-matching one.
-- "Verification table or paragraph?" — pick whichever fits; format isn't a decision worth a turn.
-- "Show me a diff before regenerating output from a tracked source?"
-  — compression, code-gen, formatter passes, lock-file rebuilds — run
-  it and report the result. Reversibility comes from the source, not
-  from per-file confirmation. See [`non-destructive-by-default`](non-destructive-by-default.md#not-in-scope--deterministic-regeneration)
-  § Not in scope.
-
-`personal.autonomy: off`: ask these. `on` or `auto`-after-opt-in: act.
+In `personal.autonomy: on` or `auto`-after-opt-in, do not ask
+trivial workflow questions — pick the obvious next step and proceed.
+In `personal.autonomy: off`, ask them. Worked cases:
+[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
 
 ## Blocking — STILL ASK regardless of `personal.autonomy`
 
-Beyond the Hard Floor, the autonomy setting also never overrides:
+Beyond the Hard Floor above, the autonomy setting also never
+overrides:
 
-- **Vague-request triggers** in [`ask-when-uncertain`](ask-when-uncertain.md) — ambiguous stays ambiguous; pick-one-and-pray is wrong.
-- **Architectural / structural choices** the codebase hasn't settled (multi-stack picks, library introductions).
+- **Vague-request triggers** in [`ask-when-uncertain`](ask-when-uncertain.md)
+  — ambiguous requirements stay ambiguous; pick-one-and-pray is wrong.
+- **Architectural / structural choices** that the codebase doesn't
+  already settle (multi-stack picks, library introductions).
 - **Security-sensitive paths** — see [`security-sensitive-stop`](security-sensitive-stop.md).
-- **Scope expansion** beyond stated task — see [`scope-control`](scope-control.md).
-- **Remote-state ops** — push, merge, rebase, force-push, branch create/delete/switch, PR create/close/retarget, tag/release. Permission-gated by [`scope-control`](scope-control.md); the prod-trunk and deploy-tied subset is governed by [`non-destructive-by-default`](non-destructive-by-default.md).
-- **Destructive ops** — see [`non-destructive-by-default`](non-destructive-by-default.md) for the full taxonomy (whimsical bulk deletions, content destruction, commits containing bulk deletions or infra changes).
-
-In doubt → blocking. Ask.
+- **Scope expansion** beyond the stated task — see [`scope-control`](scope-control.md).
+- **Remote-state operations** — push, merge, rebase, force-push,
+  branch create/delete/switch, PR create/close/retarget, tag/release.
+  Permission-gated by [`scope-control`](scope-control.md); the
+  prod-trunk and deploy-tied subset is governed by
+  [`non-destructive-by-default`](non-destructive-by-default.md).
+- **Destructive ops** — see [`non-destructive-by-default`](non-destructive-by-default.md)
+  for the full taxonomy (whimsical bulk deletions, content
+  destruction, commits containing bulk deletions or infra changes).
+
+When in doubt whether something is trivial or blocking → it is
+blocking. Ask.
 
 ## Commit policy — see [`commit-policy`](commit-policy.md)
 
-Committing is governed by [`commit-policy`](commit-policy.md), which
-applies regardless of `personal.autonomy`. Summary:
+Committing is governed by the canonical [`commit-policy`](commit-policy.md)
+rule, which applies regardless of `personal.autonomy`. Summary:
 
 - NEVER commit unless user said so this turn, a commit command was
   invoked, a standing instruction is active, or the roadmap authorizes it.
-- NEVER ask about committing.
-- In autonomous mode, the **only** permitted commit-related question
-  is the one-shot pre-scan ask at the start of roadmap execution.
+- NEVER ask about committing. The user invokes a command or says so.
+- In autonomous mode, the **only** permitted commit-related question is
+  the one-shot pre-scan ask at the start of roadmap execution.
 
-Push, merge, rebase, branch creation, PR ops, tags remain
-permission-gated per [`scope-control`](scope-control.md#git-operations--permission-gated).
+Push, merge, rebase, branch creation, PR operations, and tags remain
+permission-gated by [`scope-control`](scope-control.md#git-operations--permission-gated).
 
 ## Failure modes
 
-- Asking "Step 2 or Step 3?" when the roadmap orders them.
-- "Should I run the CI checks?" — `verify-before-complete` decides; act.
-- "Do we want to commit this?" — no, by default. Don't ask.
-- Numbered-options block whose only difference is sequencing ("A then B" vs "B then A") with no real trade-off.
-- Asking after user already issued a standing autonomy directive earlier (cache the opt-in for `auto`).
-
-For Hard-Floor failure modes (treating autonomy as cover for a
-floor-crossing action, reading a roadmap step as deploy authorization,
-refusing task-aligned WIP deletions, committing bulk-deletion / infra
-diffs without surfacing them) see
+Autonomy-side wrong-behavior patterns (sequencing-only asks, CI-run
+asks, commit asks, no-trade-off option blocks, re-asking after a
+standing opt-in):
+[`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
+For Hard-Floor failure modes see
 [`non-destructive-by-default`](non-destructive-by-default.md#failure-modes).
 
-## Cloud Behavior
-
-Settings reads degrade gracefully on cloud platforms (no
-`.agent-settings.yml`). Treat as `personal.autonomy: on` — user had to
-deliberately ship a custom skill bundle and is unlikely to want
-trivial-question friction.
-
 ## See also
 
-- [`non-destructive-by-default`](non-destructive-by-default.md) — universal safety floor; never overridden by autonomy
-- [`scope-control`](scope-control.md) — git-ops permission gate (push/merge/branch/PR/tag stays explicit)
-- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request triggers that always require asking
-- [`direct-answers`](direct-answers.md) — Iron Laws on brevity and no-flattery (this rule extends to no-trivial-questions)
+- [`non-destructive-by-default`](non-destructive-by-default.md) —
+  universal safety floor; never overridden by autonomy
+- [`scope-control`](scope-control.md) — git-ops permission gate
+  (push/merge/branch/PR/tag stays explicit)
+- [`ask-when-uncertain`](ask-when-uncertain.md) — vague-request
+  triggers that always require asking
+- [`no-cheap-questions`](no-cheap-questions.md) — mode-independent
+  floor against context-derived, sequencing-only, and
+  Iron-Law-violating asks (applies in `off` and pre-opt-in `auto` too)
+- [`direct-answers`](direct-answers.md) — Iron Laws on brevity and
+  no-flattery (this rule extends to no-trivial-questions)
 - [`/commit-in-chunks`](../commands/commit-in-chunks.md) — auto-split and commit without confirmation
 - [`/commit`](../commands/commit.md) — split and commit with confirmation

package/.agent-src/rules/capture-learnings.md

@@ -82,7 +82,7 @@ Body: 1-paragraph **pattern** (not anecdote) + 1 concrete example.
 A learning file is the input to `learning-to-rule-or-skill`, which
 produces a proposal draft under `agents/proposals/`. The proposal is
 then gated by `scripts/check_proposal.py`; see
-[`self-improvement-pipeline`](../guidelines/agent-infra/self-improvement-pipeline.md).
+[`self-improvement-pipeline`](../../docs/guidelines/agent-infra/self-improvement-pipeline.md).
 
 The `agents/learnings/` and `agents/proposals/` directories are
 consumer-owned — the package ships templates and schemas, never the

package/.agent-src/rules/chat-history-cadence.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Append cadence for .agent-chat-history — when to call append (per_turn/per_phase/per_tool), turn-check ownership refusal handling, never write the file directly, cadence is the trigger not reply length"
-alwaysApply: true
+type: "auto"
+description: "Appending to .agent-chat-history — cadence boundaries (per_turn/per_phase/per_tool), turn-check ownership refusal handling, never writing the file directly; cadence is the trigger, not reply length"
+alwaysApply: false
 source: package
 ---
 

package/.agent-src/rules/chat-history-ownership.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Detect file ownership of .agent-chat-history on first turn — match/returning/foreign/missing handshake, two-paths classification (HOOK/ENGINE/CHECKPOINT/MANUAL), Foreign/Returning numbered-options prompt"
-alwaysApply: true
+type: "auto"
+description: "First turn or reference to .agent-chat-history — detects ownership (match/returning/foreign/missing) and HOOK/ENGINE/CHECKPOINT/MANUAL path classification with numbered-options prompt"
+alwaysApply: false
 source: package
 ---
 

package/.agent-src/rules/chat-history-visibility.md

@@ -1,7 +1,7 @@
 ---
-type: "always"
-description: "Heartbeat marker visibility for .agent-chat-history — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints only on drift, slip handling per language-and-tone"
-alwaysApply: true
+type: "auto"
+description: "Emitting the chat-history heartbeat marker — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints on drift only, slip handling per language-and-tone"
+alwaysApply: false
 source: package
 ---
 

package/.agent-src/rules/cli-output-handling.md

@@ -3,6 +3,8 @@ type: "auto"
 alwaysApply: false
 description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk when installed; tail/grep is fallback."
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/cli-output-handling-mechanics.md
 ---
 
 # Development Efficiency
@@ -32,83 +34,15 @@ exits 0. Caching the result for the session is fine.
 For the full rtk subcommand catalog and project-local filter setup → see
 the `rtk-output-filtering` skill.
 
-## Codebase Navigation
+## Lookup material — see mechanics
 
-### Use what you already have
-
-- Edited a file → the edit tool already returned the result. Skip re-reading.
-- Ran a command → you have the output. Skip re-running to "verify".
-- File in context from recent messages → skip reloading.
-- Found a symbol → use it. Skip searching again differently.
-
-### Search before reading
-
-- **Search first** — `codebase-retrieval`, `search_query_regex`, or `grep`.
-- **Load only what you need** — use `view_range` or `search_query_regex`, not full files.
-- **Small files** (< 50 lines) — OK to read fully.
-
-### Ignored files (`.augmentignore`)
-
-- `vendor/`, `node_modules/`, lock files, and generated files are excluded from `codebase-retrieval`.
-- When you need to understand a vendor package (base class, interface, API), **read the specific file** with `view`. This bypasses the ignore.
-- Load only the file you need — never browse entire vendor directories.
-
-### Minimize tool calls
-
-- **Parallel reads** — read multiple files in one batch, not sequentially.
-- **`search_query_regex`** over full file reads.
-- **`view_range`** when you know the exact lines.
-- **One `codebase-retrieval` call** with all symbols — batch, not 5 separate calls.
-
-## Fallback Pattern: Redirect, Summarize, Target
-
-When `rtk` has no matching subcommand for the tool at hand, fall back to
-this pattern. Every command that MAY produce more than ~30 lines of output:
-
-### Step 1: Redirect to file
-```bash
-docker compose exec -T <service> <command> 2>&1 > /tmp/<tool>-output.txt
-echo "EXIT=$?"
-```
-
-### Step 2: Read ONLY the summary
-```bash
-tail -5 /tmp/<tool>-output.txt
-```
-
-### Step 3: If errors exist, read ONLY what you need to fix
-```bash
-grep "ERROR\|error\|✏️" /tmp/<tool>-output.txt | head -20
-grep "app/Services/MyService.php" /tmp/<tool>-output.txt
-```
-
-**NEVER** do:
-- `cat /tmp/<tool>-output.txt` (loads everything)
-- Read the full output of a passing command (waste)
-- Read diffs you don't plan to act on
-
-## General Rules
-
-For tool-specific commands → see the `quality-tools` skill.
-
-1. **Exit code first**: Check `$?` before reading ANY output. If 0, you're done — skip reading.
-2. **Summary line**: Most tools print a summary as the last few lines. That's all you need.
-3. **Targeted grep**: When you need details, `grep` for the specific file or error type.
-4. **Read once, act, move on**: Once you've read output and acted on it, skip re-reading.
-5. **Iterative fixing**: Fix one error at a time, re-run, check exit code.
-   Output becomes stale after each fix — always re-run before reading again.
-
-## CLI Over MCP
-
-MCP servers are **significantly more token-expensive** than CLI equivalents.
-When both options exist, prefer the CLI tool.
-
-- **Git**: `git` CLI, not Git MCP
-- **Files**: shell commands, not filesystem MCP
-- **APIs**: `curl`/`httpie`, not HTTP MCP
-- **Database**: `mysql`/`psql` CLI, not DB MCP
-
-Exception: MCPs with **unique capabilities** (Sentry, Playwright, Jira).
+Codebase-navigation tips, the redirect-summarize-target fallback
+pattern (with the three-step `tail`/`grep` recipe), the general rules
+(exit code first, summary line, targeted `grep`, read-once-act-move-on,
+iterative fixing), and the CLI-over-MCP catalog all live in
+[`contexts/communication/rules-auto/cli-output-handling-mechanics.md`](../contexts/communication/rules-auto/cli-output-handling-mechanics.md).
+Pull it whenever a verbose command is about to run without an `rtk`
+match.
 
 ## Exceptions
 

package/.agent-src/rules/command-suggestion-policy.md

@@ -0,0 +1,93 @@
+---
+type: "auto"
+description: "User prompt without /command but matching an eligible slash command — surface matches as numbered options with as-is escape hatch; never auto-executes, user always picks"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/command-suggestion-policy-mechanics.md
+---
+
+# Command Suggestion
+
+When the user's prompt matches an eligible slash command, surface it
+as a **numbered option** alongside an "as-is" escape hatch — the
+"run prompt as-is" option is **always last** and **always present**,
+never omitted. The user always picks. **Nothing auto-executes.** The
+suggestion layer is a read-only shortcut *finder*, not an invocation
+path.
+
+The deterministic engine lives in `scripts/command_suggester/`. The
+locked eligibility table lives in
+[`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md).
+The scoring contract and hardening list live in
+[`docs/contracts/adr-command-suggestion.md`](../../docs/contracts/adr-command-suggestion.md)
+and
+[`docs/contracts/command-suggestion-flow.md`](../../docs/contracts/command-suggestion-flow.md).
+
+## Iron Law — never auto-execute
+
+```
+SUGGEST. NEVER INVOKE. THE USER PICKS, ALWAYS.
+```
+
+A suggestion block emits options. It does **not** start a command
+flow. The user picking option N triggers `slash-command-routing-policy` on the
+**next** turn — with all the command's own halts intact.
+
+## When to fire
+
+On a user turn that matches **all** of the following:
+
+1. The message does **not** start with an explicit `/command` (those
+   bypass suggestion entirely — see `slash-command-routing-policy`).
+2. `commands.suggestion.enabled` is `true` (default).
+3. The user has not issued `/command-suggestion-off` in this conversation.
+4. No clarification is owed for the same turn (per
+   `ask-when-uncertain` — clarification wins; suggestion can fire next turn).
+5. No active engine flow is mid-halt (e.g. an `/implement-ticket`
+   step waiting on the user — the active flow has the floor).
+6. The matcher returns at least one match above the effective
+   `confidence_floor` after rank + cooldown + anti-noise.
+
+When all six hold, the suggestion block is the **first and only**
+thing the agent emits that turn. No tools, no edits, no other prose.
+
+## Subordination — when to stay silent
+
+The suggestion rule is **junior** to:
+
+- `scope-control` — never surfaces a git-op command behind a
+  permission gate the user already declined this turn.
+- `ask-when-uncertain` — if a clarification is owed, the
+  clarification is the only question; suggestion suppresses for
+  that turn.
+- `verify-before-complete` — suggestion does not interrupt an
+  evidence-gate verification that's already running.
+- Any active role-mode contract (`role-mode-adherence`).
+- Any active engine halt (`/implement-ticket`, `/work`, etc.).
+
+On any conflict → suggestion stays silent. Zero output. The user's
+prompt is processed as it would be without this rule.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the rule is **inert**
+unless the suggester package is shipped in the bundle. Treat
+`commands.suggestion.enabled` as `false` when the engine is not
+available — degrade silently, never crash the turn.
+
+## Mechanics — output format, anti-noise, what this rule does NOT do
+
+The exact rendered options block, the `Recommendation:` rules, the
+`max_options` cap, the `rank.py` anti-noise filters, and the
+"what this rule does NOT do" catalog live in
+[`contexts/communication/rules-auto/command-suggestion-policy-mechanics.md`](../contexts/communication/rules-auto/command-suggestion-policy-mechanics.md).
+
+## Interactions
+
+- [`slash-command-routing-policy`](slash-command-routing-policy.md) — explicit `/command` skips suggestion entirely.
+- [`user-interaction`](user-interaction.md) — numbered-options Iron Law and single-source recommendation.
+- [`ask-when-uncertain`](ask-when-uncertain.md) — clarification wins on conflict.
+- [`scope-control`](scope-control.md) — git-op gates outrank suggestion.
+- [`role-mode-adherence`](role-mode-adherence.md) — active mode contract outranks suggestion.
+- [`agents/contexts/command-suggestion-eligibility.md`](../../agents/contexts/command-suggestion-eligibility.md) — locked eligibility table.