@event4u/agent-config 1.20.0 → 1.22.0

package/docs/guidelines/agent-infra/skill-quality-checklist.md

@@ -0,0 +1,119 @@
+# Skill Quality
+
+> Creating, editing, or reviewing skills — minimum quality standard, every skill must be executable, validated, and self-contained
+
+_Origin: migrated from `.agent-src.uncompressed/rules/skill-quality.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# Skill Quality
+
+## Minimum Sharpness
+
+Every skill must answer four questions. If ANY answer is weak, the skill is not done.
+
+| # | Question | Section | Standard |
+|---|---|---|---|
+| 1 | When should I use this? | `When to use` | Concrete trigger, not generic |
+| 2 | What exactly do I do? | `Procedure` | Executable steps with decisions |
+| 3 | How do I verify it worked? | `Procedure` (validation step) | Concrete checks, not "verify it works" |
+| 4 | What common failure must I avoid? | `Gotcha` + `Do NOT` | Real failure patterns, not platitudes |
+
+## Required Sections
+
+Every skill MUST have: `When to use`, `Procedure`, `Gotcha`, `Output format`, `Do NOT`.
+
+## Frontmatter Contract
+
+Every skill's YAML frontmatter MUST validate against `scripts/schemas/skill.schema.json`.
+Violations are reported by `scripts/skill_linter.py` as `schema_<rule>` errors
+and fail `python3 scripts/validate_frontmatter.py` and the full CI pipeline.
+
+## Description Triggering
+
+Claude routes skills by their frontmatter `description`. Pushy,
+trigger-rich descriptions are required — polite or hedged ones cause
+undertriggering. The full recipe (concrete verb phrase, ≥2 triggers,
+`even if they don't explicitly ask for …` tail, ≤200 chars,
+litmus test) lives in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Description Triggering.
+
+## Skill Independence
+
+```
+If a skill is not executable without opening a guideline, it is broken.
+```
+
+- Skills MAY reference guidelines for detailed conventions
+- Skills MUST NOT outsource their core workflow to guidelines
+- If removing guideline references makes the skill useless → the skill is too weak
+
+**Litmus test:** Cover all guideline references in the Procedure. Is it still executable?
+If not → the skill needs more own steps, decisions, and validation — not more guideline links.
+
+## Merge & Compression Preservation
+
+When merging or compressing skills, the result MUST preserve the
+strongest validation, strongest examples, all anti-patterns, all
+decision criteria, and trigger quality. Full preservation invariants
+and "merge is invalid if …" / "compression may remove …" lists in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Merge Preservation and § Compression Preservation.
+
+## Refactor Safety
+
+When refactoring or optimizing skills:
+
+- NEVER weaken validation to pass linter
+- NEVER remove anti-patterns to reduce size
+- NEVER replace concrete checks with "verify it works"
+- NEVER merge skills if the result is broader than either source
+- ALWAYS run linter before and after — fail count must not increase
+
+## Senior-Tier Required Structure
+
+Skills with `tier: senior` in YAML frontmatter MUST carry four named
+blocks beyond the standard required sections:
+
+| # | Block | Heading / Location | Standard |
+|---|---|---|---|
+| 1 | Context-First lead | Frontmatter `description` | First sentence anchors the cognition cluster (domain + senior role); second sentence names the trigger. |
+| 2 | Related Skills | `## Related Skills` | Two-list pattern — `**WHEN to use this**` (situations this skill resolves) + `**WHEN NOT to use this**` (route-elsewhere peers, named). |
+| 3 | Proactive Triggers | `## When the agent should load this` | 3–5 concrete user-prompt patterns (paraphrases users actually type), not abstract categories. |
+| 4 | Output Artifacts | `## Output` | 1–4 named artifacts with shape (file path, table, markdown structure) — orchestrator-citable identifier each. |
+
+**Forward-only.** `scripts/skill_linter.py` enforces these blocks for
+`tier: senior` skills only; mid-tier and untiered skills skip the
+check. No retrofit pass on existing Wing-1 skills.
+
+Subsection specs (≤ 6-line spec + 1 reference example each), good /
+bad pattern pairs, and the WHEN-NOT routing peer rules live in
+[`contexts/communication/rules-auto/skill-quality-mechanics.md`](../contexts/communication/rules-auto/skill-quality-mechanics.md)
+§ Senior-tier patterns.
+
+## Structural Malice Floor
+
+`scripts/skill_linter.py` runs five regex patterns against every
+skill / rule / command body — credential exfiltration, remote
+execution, force-push to a protected ref, world-readable secret
+files, and shell-injection in subprocess calls. A match emits
+``Issue("error", "malice:<pattern>", "<line>:<matched>")`` and the
+linter exits with code **3** (security-failure), distinct from
+exit 2 (build-failure) so CI surfaces can split the two.
+
+The check is **structural**, not semantic — it catches the shapes
+the [`tool-safety`](tool-safety.md) rule denies in prose: hidden
+credentials, arbitrary execution, write-without-approval. Fixtures
+and the exit-code-3 contract live in
+[`tests/test_skill_linter_malice.py`](../../tests/test_skill_linter_malice.py).
+
+## Confidence Tagging
+
+Senior-tier procedure steps MAY append `[CONFIDENCE: high|medium|low]`
+at the end of multi-step chains where the agent's evidence varies
+across steps. Optional but recommended when a step's output feeds a
+downstream decision.
+
+Text-tag form is deliberate. Emoji 🟢 / 🟡 / 🔴 is **not** allowed —
+collides with [`direct-answers`](direct-answers.md) § Emoji scope
+(functional markers only). Linter does not enforce the tag itself;
+the rule documents the placement so authors converge on one form.

package/docs/guidelines/augment-portability-patterns.md

@@ -0,0 +1,68 @@
+# Augment Portability
+
+> Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic
+
+_Origin: migrated from `.agent-src.uncompressed/rules/augment-portability.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# Package Portability
+
+Everything that ships with the `event4u/agent-config` package MUST be
+**project-agnostic**. That includes:
+
+- Everything inside `.augment/` (skills, rules, commands, guidelines,
+  templates, contexts)
+- The package repo's own root `AGENTS.md`
+- The package repo's own `.github/copilot-instructions.md`
+
+All three are either installed into consumer projects (`.augment/` via
+`install.sh`) or read by AI tools when working on the package itself
+(`AGENTS.md`, `copilot-instructions.md`). Leaking consumer-specific
+content into any of them pollutes downstream projects or misleads agents.
+
+## Rules
+
+- NEVER reference a specific consumer project, repo name, domain, or tech
+  stack directly. The package repo itself (`event4u/agent-config`) MAY be
+  named inside its own root `AGENTS.md` and `copilot-instructions.md` —
+  that is meta about the package, not a leak.
+- NEVER hardcode consumer-project paths, class names, or conventions.
+- Write content so it works as a **reusable package** across any project.
+- Project-specific behavior belongs in the **consumer's** `.agent-settings.yml`,
+  `AGENTS.md`, or `agents/` — never in files shipped by this package.
+- If a skill or rule needs project-specific input, read it from
+  `.agent-settings.yml` or accept it as a parameter.
+- When reviewing or editing package files, always ask: "Would this still
+  make sense in a completely different project?"
+
+## Runtime invocations — no `task` commands
+
+Skills, rules, commands, guidelines, personas, and context docs run in
+**consumer projects**, which may not have Task installed. **Never**
+reference a `task <something>` invocation inside any artefact file
+under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
+(and therefore also not in the compressed mirror under `.agent-src/`).
+Use direct script invocations instead.
+
+## Consumer CLI — `./agent-config`
+
+A subset of package scripts is exposed through a project-local CLI
+wrapper `./agent-config` (written into the project root by the
+installer, gitignored). Artefacts MUST prefer the CLI over raw
+`python3 scripts/…` paths for every command the CLI already covers.
+
+## Translation tables — see mechanics
+
+The full `task`-to-script translation table, the `./agent-config`
+CLI mapping, and the rationale (Task absence on consumers,
+maintainer-vs-artefact split) all live in
+[`contexts/communication/rules-auto/augment-portability-mechanics.md`](../contexts/communication/rules-auto/augment-portability-mechanics.md).
+Pull it whenever an artefact is about to mention a runtime
+invocation.
+
+## Enforcement
+
+`scripts/check_portability.py` scans `.augment/`, `.agent-src.uncompressed/`,
+and the package repo's root `AGENTS.md` + `.github/copilot-instructions.md`
+for forbidden identifiers, for any `task <name>` invocation inside
+artefact files, and for direct script invocations that bypass the
+`./agent-config` CLI. It runs in CI and must pass before any PR.

package/docs/guidelines/php/php-coding-patterns.md

@@ -0,0 +1,62 @@
+# Php Coding
+
+> Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions
+
+_Origin: migrated from `.agent-src.uncompressed/rules/php-coding.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# PHP Coding Rules
+
+- Use `declare(strict_types=1)` in every **new** PHP file. Not required when modifying existing files that don't have it.
+- If the project has a `Math` helper class, use it for ALL business calculations. Never use native PHP arithmetic operators (`+`, `-`, `*`, `/`) for business calculations. Search for the `Math` class in the project.
+- Never use `var_dump()`, `print_r()`, or `dd()` — they are disallowed by PHPStan config. Exception: legacy projects where these are already used and no alternative is feasible.
+- Never use `float` for money — use `decimal` or the `Math` helper.
+- Always use `===` / `!==` (strict comparison), Yoda style: `null === $var`.
+- Early return over nested if/else.
+- No one-liner if statements.
+- Single quotes for strings without interpolation. `sprintf()` for complex strings.
+- Variables: `camelCase`. Array keys: `snake_case`. Constants: `UPPER_SNAKE_CASE`.
+- Typed properties, parameters, and return types — always.
+- Constructor property promotion where it makes sense.
+
+## Eloquent Models — Attribute Access
+
+Read `eloquent.access_style` from `.agent-settings.yml` to determine the preferred style.
+Default: `getters_setters`. See the `eloquent` skill for the full reference table and examples.
+
+- **`getters_setters`** (strict): Every attribute has a typed getter + fluent setter. Inside the model: `getAttribute('column_name')`/`setAttribute('column_name', $value)`. Outside: always getters/setters. If a getter doesn't exist yet, create it first.
+- **`get_attribute`**: Use `getAttribute('column_name')`/`setAttribute('column_name', $value)` everywhere, no getters/setters needed.
+- **`magic_properties`**: Laravel default `$model->column_name` everywhere.
+
+### Relationship Getters
+
+- Every relationship MUST have a typed getter method **above** the relationship method.
+- **Inside the getter:** use `$this->getAttribute('relationship_name')`, NEVER `$this->relationship_name`.
+- **Outside the model:** ALWAYS use the getter (`$model->getEquipment()`), NEVER access the magic property (`$model->equipment`).
+- Use `instanceof` checks instead of `null ===` when checking relationship results.
+
+## Eloquent Models — Observers over `booted()`
+
+- Do NOT use `booted()` / `boot()` for model lifecycle hooks (saving, saved, deleted, etc.).
+- Use a dedicated **Observer** class registered via `#[ObservedBy]` attribute.
+- This keeps models slim and lifecycle logic testable and discoverable.
+
+## PHPStan
+
+- Always fix the root cause. Do NOT add entries to `phpstan-baseline.neon`.
+- Adding `ignoreErrors` to `phpstan.neon` is allowed for **structural toolchain limitations** (e.g., Pest runtime bindings). NOT for individual code issues. **If unsure → ask the user.**
+- If a fix is truly impossible (confirmed false positive), use an inline ignore as last resort:
+  ```php
+  // @phpstan-ignore-next-line — false positive: reason here
+  ```
+
+## Testing
+
+- Always write tests in **Pest**, not PHPUnit class syntax — unless the user explicitly asks for PHPUnit.
+- Pest tests in `tests/Unit/` automatically use `UnitTestCase` as the base class (configured in `tests/Pest.php`).
+
+## PHPDoc
+
+- Only add PHPDoc when type hints are insufficient (e.g. generic arrays: `@param array<int, MyObject> $items`).
+- Do NOT add PHPDoc that just repeats the method signature.
+- One docblock per method — never split into multiple `/** */` blocks.
+- Tag order: `@param` → `@return` → `@throws`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.20.0",
+    "version": "1.22.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_p43_bodies.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""P4.3 — Write compressed rule bodies. Run after _p43_compress.py."""
+from __future__ import annotations
+import pathlib
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+RULES = ROOT / ".agent-src.uncompressed" / "rules"
+
+
+def write(name: str, content: str) -> None:
+    p = RULES / f"{name}.md"
+    p.write_text(content, encoding="utf-8")
+    print(f"  ✓ {name}: {len(content)} chars")
+
+
+# Each entry is the FULL file content (frontmatter + body).
+FILES: dict[str, str] = {}
+
+FILES["think-before-action"] = """---
+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
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/think-before-action-mechanics.md
+triggers:
+  - intent: "before coding"
+  - intent: "before debugging"
+  - intent: "before modifying"
+---
+
+# think-before-action
+
+## The Iron Law
+
+```
+ANALYZE BEFORE CODING. VERIFY WITH REAL TOOLS. NEVER GUESS.
+NO BLIND TRIAL-AND-ERROR. MAX 2 RETRIES PER APPROACH.
+```
+
+- Always analyze before coding or modifying anything.
+- Never guess behavior — verify using code, data, or tools.
+- Prefer targeted inspection (jq, debugger, logs) over brute-force.
+- Always verify results after changes (API, UI, tests).
+- When behavior can be defined → prefer test-first / TDD.
+- Unclear requirements → precise clarification question, not hidden assumptions.
+- Refactors must preserve behavior, validation, examples, and anti-failure guidance unless explicitly changed.
+- Do NOT modify code you do not fully understand — read it, trace the flow, then change it.
+- Multiple valid frameworks/patterns coexist (Tailwind + Flux, multiple form libs, competing state stores) → do NOT pick one silently — ask. See [`no blind implementation`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
+
+## Mechanics — workflow, minimum read set, verify-with-real-tools, no blind retries
+
+The five-step Understand → Analyze → Plan → Implement → Verify workflow, the minimum read set (symbol, callers, tests, abstractions, data), the memory-consult step, the verification matrix, the output-reduction patterns, the no-blind-retries protocol, and the "open files are context, not intent" clause all live in [`contexts/communication/rules-auto/think-before-action-mechanics.md`](../contexts/communication/rules-auto/think-before-action-mechanics.md). The rule above is the obligation surface; the mechanics file is the lookup material.
+
+If analysis is skipped → results are unreliable.
+"""
+
+FILES["guidelines"] = """---
+type: "auto"
+tier: "3"
+description: "Writing or reviewing code — check relevant guideline before writing or reviewing code"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/guidelines-mechanics.md
+triggers:
+  - intent: "writing code"
+  - intent: "reviewing code"
+  - keyword: "convention"
+---
+
+# Guidelines
+
+Coding guidelines live under `docs/guidelines/` organized by language. **Always check the relevant guideline** before writing or reviewing code.
+
+## How guidelines work
+
+- **Guidelines** = detailed coding conventions (reference material, read on demand).
+- **Rules** = always-active behavior constraints (auto-loaded every conversation).
+- **Skills** = agent capabilities and workflows (matched by topic).
+
+Guidelines are the "how to write code" docs. Rules enforce critical subsets automatically. Skills reference guidelines when performing related tasks.
+
+## Index — see mechanics
+
+The full file index (PHP, PHP patterns, E2E, agent-infra) plus the guidelines-vs-skills boundary and the "adding new guidelines" template live in [`contexts/communication/rules-auto/guidelines-mechanics.md`](../contexts/communication/rules-auto/guidelines-mechanics.md). The rule above is the obligation surface; the mechanics file is the catalog.
+"""
+
+FILES["token-efficiency"] = """---
+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
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/token-efficiency-mechanics.md
+triggers:
+  - intent: "verbose CLI output"
+  - intent: "fetching logs"
+  - keyword: "minimize tool calls"
+---
+
+# Token Efficiency
+
+## The Iron Laws
+
+```
+NEVER load full command output into context. Redirect → read summary → targeted details.
+```
+
+```
+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.
+```
+
+## 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 causes silent mismatches — fresh output is the only source of truth.
+
+## Mechanics — anti-loop patterns, conversation efficiency, exceptions
+
+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.
+"""
+
+FILES["autonomous-execution"] = """---
+type: "auto"
+tier: "3"
+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
+triggers:
+  - intent: "trivial workflow question"
+  - intent: "autonomy mode"
+  - keyword: "personal.autonomy"
+---
+
+# Autonomous Execution
+
+User's time is the scarce resource. Trivial workflow questions are 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)
+
+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. 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`
+
+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 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` 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.
+
+Algorithm and speech-act heuristic: [`contexts/execution/autonomy-detection.md`](../contexts/execution/autonomy-detection.md). Anchor phrases (DE+EN), no-flip patterns, counter-examples, trivial-vs-blocking taxonomy, commit-policy summary, and named failure modes: [`contexts/execution/autonomy-mechanics.md`](../contexts/execution/autonomy-mechanics.md) + [`contexts/execution/autonomy-examples.md`](../contexts/execution/autonomy-examples.md).
+
+## 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
+- [`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 asks
+- [`commit-policy`](commit-policy.md) — never-commit / never-ask Iron Law
+- [`/commit:in-chunks`](../commands/commit/in-chunks.md), [`/commit`](../commands/commit.md)
+"""
+
+FILES["user-interaction"] = '''---
+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
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/user-interaction-mechanics.md
+triggers:
+  - intent: "ask user a question"
+  - intent: "numbered options"
+  - intent: "summarizing progress"
+---
+
+# User Interaction
+
+Two Iron Laws govern every reply that contains numbered options.
+They override conversation momentum, brevity, and the urge to defer
+to the user. **Missing a recommendation is a rule violation, not a slip.**
+
+## Iron Law 1 — Single-Source Recommendation
+
+```
+EXACTLY ONE LINE NAMES THE RECOMMENDED NUMBER. NO INLINE TAG. NO SECOND PROSE NUMBER.
+THE OPTION BLOCK STAYS NEUTRAL. THE RECOMMENDATION LINE IS THE ONLY SOURCE OF TRUTH.
+DRIFT BETWEEN OPTION-BLOCK AND PROSE IS STRUCTURALLY IMPOSSIBLE WHEN THE TAG DOES NOT EXIST.
+MISSING RECOMMENDATION = RULE VIOLATION, NOT A SLIP.
+POSITION-AGNOSTIC. END-OF-TURN MENUS COUNT. NEXT-STEP LISTS COUNT. NO EXCEPTIONS.
+THE RECOMMENDATION LINE LIVES DIRECTLY UNDER THE OPTIONS BLOCK. NOWHERE ELSE.
+PROSE NAMING A "RECOMMENDED" PATH ABOVE OR BEFORE THE OPTIONS BLOCK = NO RECOMMENDATION.
+WRONG-LANGUAGE LABEL (`Recommendation:` WHEN USER IS GERMAN, OR VICE VERSA) = NO RECOMMENDATION.
+```
+
+## Iron Law 2 — Pre-Send Self-Check
+
+```
+EVERY REPLY WITH NUMBERED OPTIONS RUNS THE SELF-CHECK. NO EXCEPTIONS.
+SKIPPING IT IS A RULE VIOLATION, NOT A SLIP.
+```
+
+Mechanical backstop:
+`python3 scripts/check_reply_consistency.py --stdin < draft.md`
+(non-zero exit on any rule below). Self-scan is the primary gate;
+the script is the deterministic safety net.
+
+## Mechanics — rationale, failure modes, format details, examples
+
+The "why take a position", position-agnostic clause, format
+specification (neutral block + bolded recommendation line + caveat),
+no-trailing-open-question rule, "what does NOT count" catalog, full
+five-step pre-send self-check, named failure-mode catalog (end-of-turn
+menu, trailing-question hedge, no-preference hedge, multi-block reply,
+…), slip-handling protocol, numbered-options rules, format examples,
+progress indicators, and summary-table patterns all live in
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md).
+The rule above is the obligation surface; the mechanics file is the
+lookup material.
+'''
+
+
+if __name__ == "__main__":
+    for name, content in FILES.items():
+        write(name, content)
+    print(f"✓ wrote {len(FILES)} compressed rule bodies")

package/scripts/_p43_compress.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""P4.3 — Surgical compression of 22 compress-and-keep auto-rules.
+
+Writes new bodies for the largest rules (Iron Laws preserved verbatim,
+extended rationale relocated to contexts/communication/rules-auto/).
+Adds `triggers:` to all 22 so the router has a manifest entry per rule.
+Idempotent — re-running rewrites the same content.
+"""
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+RULES = ROOT / ".agent-src.uncompressed" / "rules"
+CTXDIR = ROOT / ".agent-src.uncompressed" / "contexts" / "communication" / "rules-auto"
+
+# Triggers per rule (keyword / phrase / file_pattern / path_prefix / intent / command)
+TRIGGERS: dict[str, list[dict]] = {
+    "architecture":              [{"keyword": "controller"}, {"keyword": "service"}, {"keyword": "module"}, {"intent": "structural decision"}],
+    "artifact-drafting-protocol": [{"intent": "create new skill"}, {"intent": "create new rule"}, {"intent": "create new command"}, {"intent": "create new guideline"}],
+    "augment-source-of-truth":   [{"path_prefix": ".agent-src/"}, {"path_prefix": ".augment/"}, {"path_prefix": ".claude/"}, {"path_prefix": ".cursor/"}],
+    "autonomous-execution":      [{"intent": "trivial workflow question"}, {"intent": "autonomy mode"}, {"keyword": "personal.autonomy"}],
+    "context-hygiene":           [{"intent": "long conversation"}, {"intent": "tool loop"}, {"intent": "fresh chat"}, {"keyword": "3-failure"}],
+    "downstream-changes":        [{"intent": "after code edit"}, {"keyword": "callers"}, {"keyword": "imports"}, {"keyword": "downstream"}],
+    "guidelines":                [{"intent": "writing code"}, {"intent": "reviewing code"}, {"keyword": "convention"}],
+    "improve-before-implement":  [{"intent": "implement feature"}, {"intent": "architectural change"}, {"keyword": "refactor"}],
+    "markdown-safe-codeblocks":  [{"intent": "markdown with code blocks"}, {"keyword": "triple backticks"}, {"file_pattern": "*.md"}],
+    "minimal-safe-diff":         [{"intent": "writing a diff"}, {"intent": "reviewing a diff"}, {"keyword": "drive-by"}],
+    "missing-tool-handling":     [{"keyword": "command not found"}, {"keyword": "not installed"}, {"intent": "install tool"}],
+    "no-attribution-footers":    [{"intent": "PR body"}, {"intent": "commit message"}, {"intent": "Jira comment"}, {"keyword": "co-authored"}],
+    "no-roadmap-references":     [{"path_prefix": "agents/roadmaps/"}, {"intent": "link from stable artifact"}],
+    "preservation-guard":        [{"intent": "merge skill"}, {"intent": "compress rule"}, {"intent": "refactor artifact"}, {"keyword": "Iron Law"}],
+    "role-mode-adherence":       [{"keyword": "active_role"}, {"keyword": "role-mode"}, {"intent": "mode marker"}],
+    "runtime-safety":            [{"keyword": "execution"}, {"keyword": "automated"}, {"keyword": "assisted"}, {"keyword": "handler"}],
+    "security-sensitive-stop":   [{"keyword": "auth"}, {"keyword": "billing"}, {"keyword": "tenant"}, {"keyword": "secret"}, {"keyword": "webhook"}],
+    "size-enforcement":          [{"intent": "create rule"}, {"intent": "create skill"}, {"intent": "create command"}, {"intent": "create guideline"}],
+    "think-before-action":       [{"intent": "before coding"}, {"intent": "before debugging"}, {"intent": "before modifying"}],
+    "token-efficiency":          [{"intent": "verbose CLI output"}, {"intent": "fetching logs"}, {"keyword": "minimize tool calls"}],
+    "tool-safety":                [{"keyword": "allowed_tools"}, {"keyword": "tool registry"}, {"intent": "external API"}],
+    "user-interaction":          [{"intent": "ask user a question"}, {"intent": "numbered options"}, {"intent": "summarizing progress"}],
+}
+
+
+def _read(p: pathlib.Path) -> str:
+    return p.read_text(encoding="utf-8")
+
+
+def _split_frontmatter(text: str) -> tuple[str, str]:
+    """Return (frontmatter_inner, body) — assumes leading ---\\n…---\\n\\n."""
+    m = re.match(r"^---\n(.*?)\n---\n*", text, re.DOTALL)
+    if not m:
+        raise ValueError("no frontmatter")
+    return m.group(1), text[m.end():]
+
+
+def _format_triggers(items: list[dict]) -> str:
+    out = ["triggers:"]
+    for it in items:
+        ((k, v),) = it.items()
+        out.append(f'  - {k}: "{v}"')
+    return "\n".join(out)
+
+
+def _strip_old_triggers(fm: str) -> str:
+    """Remove an existing triggers: block (with its inline children)."""
+    lines = fm.splitlines()
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        if lines[i].rstrip() == "triggers:":
+            i += 1
+            while i < len(lines) and lines[i].startswith(("  ", "\t")):
+                i += 1
+            continue
+        out.append(lines[i])
+        i += 1
+    return "\n".join(out)
+
+
+def patch_triggers_only(rule_id: str) -> bool:
+    """Inject triggers: into rule frontmatter without touching the body."""
+    p = RULES / f"{rule_id}.md"
+    if not p.exists():
+        print(f"  ✗ missing: {rule_id}", file=sys.stderr)
+        return False
+    text = _read(p)
+    fm, body = _split_frontmatter(text)
+    fm = _strip_old_triggers(fm).rstrip()
+    triggers = TRIGGERS.get(rule_id)
+    if triggers:
+        fm = fm + "\n" + _format_triggers(triggers)
+    p.write_text(f"---\n{fm}\n---\n\n{body.lstrip()}", encoding="utf-8")
+    return True
+
+
+def write_rule(rule_id: str, fm_extra: str, body: str) -> None:
+    """Overwrite a rule with given body + standard frontmatter additions."""
+    p = RULES / f"{rule_id}.md"
+    text = _read(p)
+    fm, _ = _split_frontmatter(text)
+    fm_clean = _strip_old_triggers(fm).rstrip()
+    triggers = TRIGGERS.get(rule_id)
+    parts = [fm_clean]
+    if fm_extra:
+        parts.append(fm_extra.rstrip())
+    if triggers:
+        parts.append(_format_triggers(triggers))
+    full_fm = "\n".join(parts)
+    p.write_text(f"---\n{full_fm}\n---\n\n{body.lstrip()}\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    # Imported by _p43_bodies.py — when run directly, only stamp triggers.
+    for rid in TRIGGERS:
+        patch_triggers_only(rid)
+    print("✓ triggers stamped on all 22 compress-and-keep rules")