@event4u/agent-config 1.17.0 → 1.19.0

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

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "3"
 description: "Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default."
 alwaysApply: true
 source: package
@@ -22,8 +23,7 @@ ANSWER THE SUBSTANCE. SHIP THE TRUTH.
 - No subjective judgments on user's code/decisions ("nice approach", "boring") unless evaluation was asked.
 - "Good catch" / "you're right" only when literally true and load-bearing.
 - Acknowledge mistakes without performative apologies — one sentence, switch behavior.
-
-Failure mode: praise as a hedge before bad news. Drop the cushion, deliver the news.
+- Failure mode — praise hedging bad news; drop the cushion, deliver the news.
 
 ## Iron Law 2 — No Invented Facts (severity-tiered)
 
@@ -39,11 +39,10 @@ WHEN VERIFICATION IS NOT WORTH THE COST → ASK.
 | **Medium — project-shape** ("uses X for Y", conventions, file location) | Verify if one tool call reaches it; otherwise hedge: *"I'd guess X — not checked"*. |
 | **Low — well-known idioms** (generic language/framework idioms, public APIs) | Inference acceptable. Mark as inference if not 100% sure. |
 
-Concrete examples and hedge-language patterns:
+Examples + hedge-language patterns:
 [`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--severity-tiered-claim-examples).
-
-User override: "just guess", "rough estimate is fine", "skip the
-verify" → drop to Low for that turn.
+Override: "just guess", "rough estimate is fine", "skip the verify"
+→ drop to Low for that turn.
 
 ## Iron Law 3 — Brevity by Default
 
@@ -60,33 +59,26 @@ LONG ANSWERS ARE A FAILURE MODE, NOT A SIGN OF EFFORT.
 - One-true-answer question → one sentence + the answer.
 
 `token-efficiency` covers the loop side; this rule covers per-reply
-length. **Never overrides** `user-interaction` (numbered options
-stay) or command-mandated steps.
+length. **Never overrides** `user-interaction` (numbered options stay)
+or command-mandated steps.
 
 ## Emoji Scope — functional markers only
 
-**Whitelist (allowed):**
-
-- Mandated markers: `📒` (chat-history heartbeat, verbatim per
-  `chat-history-visibility`), mode markers from `role-mode-adherence`.
-- CLI status: `❌`, `✅`, `⚠️` (two-space rule from `language-and-tone`).
-- Roadmap checkboxes: `[x]`, `[~]`, `[-]`.
+**Whitelist:** `📒` (chat-history heartbeat, verbatim per
+`chat-history-visibility`); mode markers from `role-mode-adherence`;
+CLI status `❌` / `✅` / `⚠️` (two-space rule from `language-and-tone`);
+roadmap checkboxes `[x]` / `[~]` / `[-]`.
 
-**Blacklist (never in prose):**
+**Blacklist (never in prose):** opening flair (✨, 🚀, 🎉, 💡, 🔥, 👍);
+empathy (❤️, 🤗, 😊); section dividers, headline ornaments, reaction
+emojis. Unsure → assume blacklist.
 
-- Opening flair: ✨, 🚀, 🎉, 💡, 🔥, 👍.
-- Empathy: ❤️, 🤗, 😊.
-- Section dividers, headline ornaments, reaction emojis.
+## Failure modes
 
-Unsure → assume blacklist.
-
-## Failure modes the user will call out
-
-Trigger phrases per Iron Law and the in-language correction pattern:
+Trigger phrases + in-language correction pattern:
 [`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--failure-modes-the-user-will-call-out).
-
-When called out: acknowledge once in the user's language, switch,
-no excuses (mirrors `language-and-tone` § slip handling).
+On call-out: acknowledge once in the user's language, switch, no
+excuses (mirrors `language-and-tone` § slip handling).
 
 ## Interactions
 

package/.agent-src/rules/docker-commands.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 alwaysApply: false
 description: "Running PHP commands inside Docker containers — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, and any CLI tool execution"
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "Keeping .augment/ contexts, counts, and cross-references in sync when creating, renaming, or deleting skills, commands, rules, guidelines, templates, or any agent infrastructure files"
 source: package
 load_context:

package/.agent-src/rules/downstream-changes.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 alwaysApply: false
 description: "After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation"
 source: package

package/.agent-src/rules/e2e-testing.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 alwaysApply: false
 description: "Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention"
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 description: "Writing or reviewing code — check relevant guideline before writing or reviewing code"
 alwaysApply: false
 source: package

package/.agent-src/rules/improve-before-implement.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+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

package/.agent-src/rules/language-and-tone.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "3"
 description: "Language and tone — informal German Du, English code comments, .md files always English"
 alwaysApply: true
 source: package

package/.agent-src/rules/laravel-translations.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "Laravel language files, translations, i18n, lang/de, lang/en, __() helper, localization, multilingual text"
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 description: "Generating markdown output that contains code blocks — prevent broken nesting"
 alwaysApply: false
 source: package

package/.agent-src/rules/minimal-safe-diff.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "When writing or reviewing a diff — the smallest change that solves the stated problem; no drive-by edits, no opportunistic refactors, no reformatting of untouched code"
 source: package

package/.agent-src/rules/missing-tool-handling.md

@@ -1,5 +1,6 @@
 ---
 type: auto
+tier: "2a"
 source: package
 description: "When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently"
 ---

package/.agent-src/rules/model-recommendation.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "Starting a new task, switching task type, or invoking a command — detect task complexity and recommend the optimal model (Opus/Sonnet/GPT) before any work"
 alwaysApply: false
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "3"
 description: "No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on)"
 alwaysApply: true
 source: package
@@ -9,13 +10,10 @@ source: package
 
 A question is **cheap** when the answer follows from stated context,
 an option breaches an Iron Law, choices differ only in sequencing /
-format, or one option is obviously dominant. Cheap questions are
-noise, regardless of `personal.autonomy`.
-
-Mode-independent. [`autonomous-execution`](autonomous-execution.md)'s
-"trivial" failure modes scope to `personal.autonomy: on` (or
-`auto`-after-opt-in); this rule lifts the **no-trade-off** subset to
-`off` and pre-opt-in `auto` too.
+format, or one option is obviously dominant. Mode-independent — holds
+in `off`, `auto`, and `on`; autonomy never lifts the no-trade-off
+floor (cf. [`autonomous-execution`](autonomous-execution.md), whose
+"trivial" failure modes only scope to `on` / opted-in `auto`).
 
 ## The Iron Laws
 
@@ -35,16 +33,12 @@ Hold in `off`, `auto`, and `on`. Autonomy never lifts them.
 - **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** — 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).
-
-Concrete examples per class:
+- **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`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
 
 ## Pre-Send Self-Check — MANDATORY before every question
@@ -52,11 +46,11 @@ Concrete examples per class:
 Run silently before any numbered-options block:
 
 1. Answer already in stated context?
-2. Any option violates [`commit-policy`](commit-policy.md), [`scope-control § git-ops`](scope-control.md), or [`non-destructive-by-default`](non-destructive-by-default.md)?
+2. Any option violates `commit-policy`, `scope-control` § git-ops, or `non-destructive-by-default`?
 3. Options pure sequencing / format, no trade-off?
 4. One option obviously dominant?
-5. User fenced next step (*"plan only"*, *"review first"*) → deliver + handback per [`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates).
-6. User already declined? Re-ask forbidden per [`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+5. User fenced next step (*"plan only"*, *"review first"*) → deliver + handback per `scope-control` § fenced step.
+6. User already declined? Re-ask forbidden per `scope-control` § decline = silence.
 
 Any "yes" → **do not ask**. Pick the dominant path, state assumption
 inline (*"assuming X — adjust if wrong"*), hand back. One-question-per-turn
@@ -68,7 +62,7 @@ the question is genuine.
 - Real architectural / scope decision with non-obvious trade-offs.
 - Vague-request trigger per [`ask-when-uncertain`](ask-when-uncertain.md#vague-request-triggers--must-ask).
 - Security-sensitive path per [`security-sensitive-stop`](security-sensitive-stop.md).
-- Hard Floor in [`non-destructive-by-default`](non-destructive-by-default.md) — confirmation mandatory.
+- Hard Floor per `non-destructive-by-default` — confirmation mandatory.
 - Two genuinely-equivalent paths; user preference is the tiebreaker.
 
 In doubt → ask. This rule narrows asking, never widens silence.

package/.agent-src/rules/no-roadmap-references.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Adding a link to a specific file in agents/roadmaps/ from any stable artifact (rule, skill, command, context, guideline) — roadmaps are transient; promote durable findings to agents/contexts/ instead"
 alwaysApply: false
 source: package

package/.agent-src/rules/non-destructive-by-default.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "safety-floor"
 description: "Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass"
 alwaysApply: true
 source: package

package/.agent-src/rules/onboarding-gate.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt the user to run /onboard before executing any other request"
 alwaysApply: false
 source: package
@@ -7,6 +8,12 @@ source: package
 
 # Onboarding Gate
 
+> **Enforced by:** [`scripts/onboarding_gate_hook.py`](../../scripts/onboarding_gate_hook.py)
+> on Augment + Claude Code (`SessionStart`). The hook refreshes
+> `agents/state/onboarding-gate.json` from `.agent-settings.yml`; the
+> prose below is the spec the hook implements and the fallback for
+> platforms without a hook surface.
+
 Forces a one-time `/onboard` run for each developer on each project. This
 replaces the previously scattered "ask once" patterns across `user_name`,
 `personal.ide`, `personal.rtk_installed`, and cost profile confirmation.
@@ -86,9 +93,35 @@ gate. This protects projects that were set up before this rule shipped.
 - `scope-control` — option `2` writes exactly one key; no side effects.
 - `role-mode-adherence` — gate runs BEFORE the mode marker is emitted.
 
+## Copilot fallback
+
+GitHub Copilot has no `SessionStart` hook surface, so
+`scripts/onboarding_gate_hook.py` cannot run structurally and
+`agents/state/onboarding-gate.json` is not refreshed for the agent.
+On the first turn of a Copilot conversation:
+
+1. Read `onboarding.onboarded` from `.agent-settings.yml` directly
+   (one read per conversation, then cache as the prose above
+   describes).
+2. Optionally refresh the state file manually so other tooling sees
+   the same value the hook would have written:
+
+   ```bash
+   python3 scripts/onboarding_gate_hook.py < /dev/null
+   ```
+
+   The script reads `.agent-settings.yml`, atomically writes
+   `agents/state/onboarding-gate.json`, and exits 0 — same payload
+   the Augment / Claude / Cursor / Cline / Windsurf / Gemini hook
+   would have produced.
+3. Apply the gate behavior from "Gate behavior when `onboarded:
+   false`" above. The cooperative path is the spec; the hook is the
+   cache.
+
 ## See also
 
 - [`/onboard`](../commands/onboard.md) — the command this gate invokes
 - [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
 - [`agent-settings` template](../templates/agent-settings.md) — `onboarding.onboarded` reference
 - [`rule-type-governance`](rule-type-governance.md) — why this is `always`
+- [`hardening-pattern`](../../agents/contexts/hardening-pattern.md) — Tier 1 mechanical-rule contract

package/.agent-src/rules/package-ci-checks.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 alwaysApply: false
 description: "Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first"
 source: package

package/.agent-src/rules/php-coding.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 description: "Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions"
 alwaysApply: false
 source: package

package/.agent-src/rules/preservation-guard.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 alwaysApply: false
 description: "When merging, refactoring, compressing, or restructuring skills, rules, commands, or guidelines — prevent quality loss"
 source: package

package/.agent-src/rules/review-routing-awareness.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When routing reviewers or flagging risk hotspots — consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe"
 source: package
 load_context:

package/.agent-src/rules/reviewer-awareness.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When suggesting reviewers for a change — anchor the choice in paths and risk, never prestige or seniority; require primary + secondary role for medium/high risk"
 source: package
 ---

package/.agent-src/rules/roadmap-progress-sync.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response"
 alwaysApply: false
 source: package
@@ -12,6 +13,11 @@ load_context:
 
 # Roadmap Progress Sync
 
+> **Enforced by:** [`scripts/roadmap_progress_hook.py`](../../scripts/roadmap_progress_hook.py)
+> on Augment + Claude Code (`PostToolUse`). Hook is primary; the prose
+> below is the specification the hook implements and the fallback when
+> the platform has no hook surface.
+
 ## Iron Law — dashboard sync
 
 ```
@@ -90,6 +96,28 @@ roadmap left under `agents/roadmaps/` is a rule violation, not an
 optional cleanup. See `roadmap-management` skill for the archive vs
 skipped decision table.
 
+## Agent-authored roadmaps — placement is mandatory
+
+```
+A FILE THE AGENT DROPS INTO agents/roadmaps/ MUST EITHER
+(a) PASS check_roadmap_trackable.py AND LAND IN THE DASHBOARD, OR
+(b) NOT BE IN agents/roadmaps/ AT ALL.
+NO "DECISION MATRIX" / "DESIGN NOTE" SHORTCUT.
+```
+
+When the agent autonomously creates a roadmap, it owns the placement
+in the **same response**:
+
+- **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
+- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/contexts/<name>.md`.
+- **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
+
+A non-trackable file in `agents/roadmaps/` is a rule violation — the
+trackable CI fails it, the dashboard hides it. The agent that
+created it moves it the same response. If the autonomous run also
+**finishes** the roadmap within the session (every box `[x]`/`[~]`/`[-]`),
+the completion-archival rule above fires too — same response.
+
 ## Autonomous execution — checkbox cadence
 
 When executing a roadmap autonomously (multi-turn, no per-step user
@@ -129,3 +157,24 @@ the mandatory pre-send self-check, the failure-mode catalog, and the
 [`contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md`](../contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md).
 Pull it whenever a trigger fires — the rule above is the obligation
 surface; the mechanics file is the lookup material.
+
+## Copilot fallback
+
+GitHub Copilot has no `PostToolUse` hook surface, so
+`scripts/roadmap_progress_hook.py` cannot detect roadmap-file writes
+structurally. The dashboard at `agents/roadmaps-progress.md` will
+not regenerate on its own.
+
+The cooperative path: every time a roadmap touch fires (per the
+trigger list in the mechanics context above), the agent regenerates
+the dashboard in the same response — which is the same Iron Law the
+hook enforces, just executed manually:
+
+```bash
+./agent-config roadmap:progress
+```
+
+The hook implementation is the specification; on Copilot the agent
+runs the regenerator itself after the same triggers fire. Skipping
+it is a rule violation, not a hook gap — the Iron Law on dashboard
+sync survives the missing hook surface.

package/.agent-src/rules/role-mode-adherence.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When roles.active_role is set in .agent-settings.yml — closing outputs must match the mode's contract and emit the structured mode marker"
 alwaysApply: false
 source: package
@@ -12,8 +13,7 @@ one of the six modes defined in
 [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md):
 `developer`, `reviewer`, `tester`, `po`, `incident`, `planner`.
 
-Read `roles.active_role` from `.agent-settings.yml` at session start.
-Empty or missing → rule is inert. Do NOT guess a mode.
+Read `roles.active_role` from `.agent-settings.yml` at session start. Empty / missing → rule is inert; do NOT guess a mode.
 
 When active, every closing output MUST:
 

package/.agent-src/rules/rule-type-governance.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "Creating or editing rules, or auditing rule types — decides when a rule should be always vs auto"
 alwaysApply: false
 source: package
@@ -44,3 +45,31 @@ The `description` field IS the trigger. It must describe **when** the rule appli
 - Default to `auto`. Justify `always`.
 - If >50% of conversations don't need a rule → it must be `auto`.
 - `optimize-agents` command checks this and suggests changes.
+
+## Hardening tier — required on new or edited rules
+
+Every new rule, and every edited rule whose body changes the trigger
+or the obligation, MUST classify itself against the hardening tiers
+documented in [`rule-trigger-matrix.md`](../../agents/contexts/rule-trigger-matrix.md):
+
+| Tier | Meaning |
+|---|---|
+| `1` | Mechanically enforceable — hook acts, rule body stays minimal. |
+| `2a` | Marker nudge — hook injects signal, agent acts on it. |
+| `2b` | Structured injection / tool-call gate — hook reads/writes state, may deny. |
+| `3` | Soft, judgment-bound — no platform surface; self-check rule. |
+| `safety-floor` | Iron-Law subset, never modified. |
+| `mechanical-already` | Precedent — script enforces, rule body documents. |
+
+Classification surface: the optional `tier:` frontmatter field
+(declared in `scripts/schemas/rule.schema.json`). Recommended for new
+rules; bulk-retrofit of existing rules is tracked separately.
+
+Tier 3 dispositions are recorded centrally in
+[`agents/contexts/tier-3-dispositions.md`](../../agents/contexts/tier-3-dispositions.md)
+with a 6-month re-audit clock. New Tier 3 rules append to that list
+on landing.
+
+The `optimize-agents` command checks the tier alongside `type`/`source`
+and suggests escalations when a rule's trigger matches a hardening
+opportunity that has shipped since the rule was authored.

package/.agent-src/rules/runtime-safety.md

@@ -1,5 +1,6 @@
 ---
 type: auto
+tier: "2b"
 source: package
 description: "When a skill declares execution metadata — enforce safety constraints for assisted and automated execution types"
 ---

package/.agent-src/rules/scope-control.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "safety-floor"
 description: "Scope control — no unsolicited architectural changes, refactors, or library replacements"
 alwaysApply: true
 source: package

package/.agent-src/rules/security-sensitive-stop.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 alwaysApply: false
 description: "Security-sensitive paths — auth, billing, tenant boundaries, secrets, file uploads, external integrations, webhooks, public endpoints — stop and run threat analysis BEFORE editing"
 source: package

package/.agent-src/rules/size-enforcement.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Creating or editing rules, skills, commands, guidelines, AGENTS.md, or copilot-instructions.md — enforce size and scope limits"
 alwaysApply: false
 source: package

package/.agent-src/rules/skill-improvement-trigger.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "After completing a meaningful task — trigger post-task learning capture if pipelines.skill_improvement is enabled"
 alwaysApply: false
 source: package

package/.agent-src/rules/skill-quality.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "mechanical-already"
 description: "Creating, editing, or reviewing skills — minimum quality standard, every skill must be executable, validated, and self-contained"
 alwaysApply: false
 source: package

package/.agent-src/rules/slash-command-routing-policy.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "1"
 description: "When user types a slash command like /create-pr, /commit, or pastes command file content"
 alwaysApply: false
 source: package
@@ -31,3 +32,41 @@ This is **irrelevant** for command detection.
 - If command file content appears in the context alongside an open file, the **command invocation takes priority**.
 - Do NOT confuse "file is open" with "user wants to discuss this file".
 - The user's typed message determines intent — not editor state.
+
+## Read the whole prompt — command is the operator, prose is the target
+
+```
+/<command> IS THE OPERATOR.
+THE REST OF THE USER MESSAGE NAMES THE TARGET.
+NEVER ASSUME THE COMMAND NAME IS THE TARGET.
+```
+
+Slash token = **what to do**; surrounding prose = **what to do it on**.
+
+- `/council and analyse chat-history` → target is `chat-history`,
+  not `council`. Council is the *tool*, prose names the *artefact*.
+- `/work the memory bug from PROJ-123` → target is "the memory bug
+  from PROJ-123".
+- `/fix ci and then open a PR` → target is "CI failure"; trailing
+  "open a PR" is a follow-up needing separate permission (per
+  `scope-control`).
+
+### Pre-flight before expensive operations
+
+Before any operation costing real time or money — external API call,
+large codebase analysis, multi-file refactor, council run, generated
+test suite — run silently:
+
+1. Re-read the **whole** user message, not just slash + first token.
+2. Identify the target the prose actually names.
+3. Target unambiguous → execute, no question.
+4. Target **genuinely** ambiguous after re-reading (prose names *two*
+   artefacts, can't tell which is the operand) → ask ONE
+   disambiguating numbered-options question per
+   [`ask-when-uncertain`](ask-when-uncertain.md), then proceed.
+
+**Not** a license to re-introduce cheap questions (`no-cheap-questions`
+still binds). Threshold: *"would this guess waste the user's tokens,
+money, or trust?"* — not *"I'd feel safer asking"*. Single failure
+mode to avoid: spending API spend on the wrong artefact because the
+agent fixated on the command name.

package/.agent-src/rules/think-before-action.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 description: "Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error"
 alwaysApply: false
 source: package

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

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise"
 alwaysApply: false
 source: package

package/.agent-src/rules/tool-safety.md

@@ -1,5 +1,6 @@
 ---
 type: auto
+tier: "2b"
 source: package
 description: "When a skill uses external tools — enforce allowlist, deny-by-default, and no hidden credential patterns"
 ---

package/.agent-src/rules/ui-audit-gate.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2b"
 description: "Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings in state.ui_audit before non-trivial UI change; gate, not suggestion"
 alwaysApply: false
 source: package

package/.agent-src/rules/upstream-proposal.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "2a"
 description: "After creating or significantly improving a skill, rule, guideline, or command — ask if it should be contributed upstream to the shared package"
 alwaysApply: false
 source: package

package/.agent-src/rules/user-interaction.md

@@ -1,5 +1,6 @@
 ---
 type: "auto"
+tier: "3"
 description: "Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators"
 alwaysApply: false
 source: package

package/.agent-src/rules/verify-before-complete.md

@@ -1,5 +1,6 @@
 ---
 type: "always"
+tier: "2a"
 description: "Verify before completion — run tests and quality tools before claiming done"
 alwaysApply: true
 source: package