@event4u/agent-config 1.24.0 → 1.25.0

package/docs/contracts/package-self-orientation.md

@@ -0,0 +1,135 @@
+---
+stability: beta
+---
+
+# Package Self-Orientation
+
+> **Beta.** Outboard target for the package-root `AGENTS.md` Thin-Root
+> refactor (Phase 6.4 of `road-to-augment-limit-fit`). Holds the
+> deep-detail prose that used to live inline.
+
+## What this repo is
+
+A **governed skill suite** for two cognition clusters — engineering
+depth (Wing 1) and senior cross-department cognition (Wings 2–4).
+**Depth over breadth, decisions over boilerplate, under a shared
+Iron-Law floor** (`commit-policy`, `non-destructive-by-default`,
+`language-and-tone`, `skill-quality`, `direct-answers`).
+
+`type: library` distribution package — published to Composer and npm
+as `event4u/agent-config` / `@event4u/agent-config`. No application
+runtime. Installed via `scripts/install.sh` (Bash) and
+`scripts/install.py` (Python bridge).
+
+## The four wings
+
+Four wings compose via [`cross-wing-handoff.md`](cross-wing-handoff.md)
+(beta). Per-wing plates live under `agents/roadmaps/` and `agents/contexts/`.
+
+| Wing | Cognition cluster |
+|---|---|
+| **1 — Engineering** | Code craft, debugging, refactoring, release discipline; depth-first |
+| **2 — Product + Foundation** | Roles cluster (PM, designer, QA, EM); product discovery, prioritization, delivery shape |
+| **3 — GTM + Growth** | CMO + marketing + sales + lifecycle; channel-agnostic positioning + funnel cognition |
+| **4 — Money + Strategy + Ops** | CFO + COO + board-level strategy, valuation, org-design; stage-agnostic financial + operational cognition |
+
+## Tech stack
+
+Bash (install scripts) · Python 3.10+ (linters, compression, pytest) ·
+Markdown (all content) · Taskfile (`task ci/sync/test`) · GitHub
+Actions (`.github/workflows/`). Non-text inputs (PDF, DOCX, XLSX,
+images, audio) route through the
+[`markitdown`](../../.agent-src/skills/markitdown/SKILL.md) skill.
+Wings 2–4 enforce a cognition-only floor (no SaaS auth, no vendor
+SDKs) — `skill_linter.py` enforces it mechanically. Distribution
+mechanics deep-dive: [`agents-md-tech-stack.md`](agents-md-tech-stack.md) (beta).
+
+## Source of truth
+
+| Directory | Purpose | Editable? |
+|---|---|---|
+| `.agent-src.uncompressed/` | Authoring layer — full verbose content | ✅ Yes — edit here |
+| `.agent-src/` | Compressed output — shipped in the package, consumed by agents | ❌ No — regenerated |
+| `.augment/` | Local projection of `.agent-src/` for Augment Code (gitignored) | ❌ No — regenerated |
+| `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` | Tool-specific projections | ❌ No — regenerated |
+| `agents/` | Package's own roadmaps, contexts, sessions | ✅ Yes |
+
+**Never edit `.agent-src/` or `.augment/` directly.** Edit
+`.agent-src.uncompressed/` and run `task sync` (or `task ci`) to
+compress + regenerate the tool directories.
+
+## Repository layout
+
+```
+.agent-src.uncompressed/      ← edit here
+  skills/       (141 skills)
+  rules/        (58 rules)
+  commands/     (103 commands)
+  personas/     (7 personas)
+  templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
+  contexts/
+
+docs/guidelines/            (47 guidelines — reference material, not packaged)
+docs/contracts/             (kernel-membership, rule-router, rule-classification, …)
+docs/decisions/             (ADRs — kernel overrides, scope decisions)
+.agent-src/                 ← compressed output shipped in the package
+.agent-src/router.json      ← compiled router manifest (consumed at runtime)
+.augment/                   ← local projection for Augment Code (gitignored)
+scripts/                    ← install.sh, install.py, compress.py, linters
+tests/                      ← pytest (324 tests) + test_install.sh
+agents/                     ← this package's own roadmaps / sessions / contexts
+.github/workflows/          ← CI
+```
+
+## Key rules for agents editing this repo
+
+| Rule | File |
+|---|---|
+| `.agent-src/` must stay project-agnostic — no project names, domains, stacks | [`augment-portability`](../../.agent-src/rules/augment-portability.md) |
+| Root AGENTS.md + copilot-instructions.md must stay project-agnostic too | [`augment-portability`](../../.agent-src/rules/augment-portability.md) |
+| Edit `.agent-src.uncompressed/`, never `.agent-src/` or `.augment/` | [`augment-source-of-truth`](../../.agent-src/rules/augment-source-of-truth.md) |
+| Skills must declare frontmatter, be self-contained, pass the linter | [`skill-quality`](../../.agent-src/rules/skill-quality.md) |
+| Size budgets for skills, rules, commands | [`size-enforcement`](../../.agent-src/rules/size-enforcement.md) |
+| Keep `.agent-src/` / `agents/` cross-refs in sync on add/rename/delete | [`docs-sync`](../../.agent-src/rules/docs-sync.md) |
+| Creating a new skill/rule/command/guideline runs Understand → Research → Draft | [`artifact-drafting-protocol`](../../.agent-src/rules/artifact-drafting-protocol.md) |
+
+## Maintainer telemetry (opt-in)
+
+Default-off. `telemetry.artifact_engagement.enabled: true` in
+`.agent-settings.yml` enables local-only JSONL logging. Redaction
+floor + pipeline:
+[`artifact-engagement-flow.md`](../../.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md)
+(beta). Rule:
+[`artifact-engagement-recording`](../../.agent-src/rules/artifact-engagement-recording.md).
+
+## Context-aware command suggestion
+
+When a free-form prompt matches a command's purpose, the agent
+surfaces matches as numbered options with a "run as-is" escape;
+**nothing auto-executes**. Engine: `scripts/command_suggester/`.
+Rule: [`command-suggestion-policy`](../../.agent-src/rules/command-suggestion-policy.md).
+Eligibility + scoring + hardening:
+[`adr-command-suggestion.md`](adr-command-suggestion.md) and
+[`command-suggestion-flow.md`](../../.agent-src.uncompressed/contexts/contracts/command-suggestion-flow.md)
+(beta).
+
+## Multi-agent tool support
+
+`task generate-tools` projects `.agent-src/` into Augment Code, Claude
+Code (Agent Skills standard), Cursor, Cline, Windsurf, Gemini CLI,
+and Claude.ai cloud bundles. Skills follow
+[agentskills.io](https://agentskills.io); commands are converted to
+Claude Code Skills with `disable-model-invocation: true`. Per-tool
+layout + cloud-bundle pipeline:
+[`docs/architecture.md`](../architecture.md#cloud-bundle-pipeline).
+
+## Contributing
+
+1. Edit inside `.agent-src.uncompressed/` or `scripts/` or `tests/` —
+   never in `.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, etc.
+2. Run `task ci` locally. It must exit 0.
+3. Commit in logical chunks with Conventional Commits.
+4. Open a PR against `main`.
+
+User-facing story: [`README.md`](../../README.md). Architecture
+deep-dive: [`docs/architecture.md`](../architecture.md).

package/docs/contracts/rule-classification.md

@@ -116,8 +116,7 @@ existing skills under `.agent-src.uncompressed/skills/`.
 | model-recommendation | 2909 | `set-cost-profile` | Routing procedure |
 | onboarding-gate | 4881 | `onboard` | Mechanical: meta-rule about /onboard |
 | package-ci-checks | 1342 | `lint-skills` | Repo-specific procedure |
-| review-routing-awareness | 4220 | `review-routing` | Skill exists; large overlap |
-| reviewer-awareness | 3573 | `review-routing` | Merges with above into one skill |
+| reviewer-awareness | 3573 | `review-routing` | Skill exists; consolidates former `review-routing-awareness` (2026-05-08, see `agents/contexts/adr-auto-rule-consolidation.md`) |
 | skill-improvement-trigger | 1597 | `skill-improvement-pipeline` | Trigger procedure |
 | slash-command-routing-policy | 3218 | `command-routing` | Routing procedure |
 | ui-audit-gate | 3285 | `existing-ui-audit` | Audit procedure |
@@ -151,8 +150,9 @@ Reference / examples / mechanics. Body migrates into
 1. **Kernel swap ADR (P2.1).** `agent-authority` ↔
    `autonomous-execution`. See `kernel-membership.md` § 5.2 for the
    three resolution variants; this file syncs once the ADR lands.
-2. **`reviewer-awareness` + `review-routing-awareness` merge.** Both
-   target the same skill — P4.1 must consolidate, not duplicate.
+2. **`reviewer-awareness` + `review-routing-awareness` merge.** ✅ resolved
+   2026-05-08 — merged into `reviewer-awareness` per
+   `agents/contexts/adr-auto-rule-consolidation.md`.
 3. **`onboarding-gate` migration shape.** The rule fires only on the
    first turn; the migrated form must keep that trigger latch.
    Router state-machine primitives (once / every-turn / on-mode-

package/docs/decisions/ADR-004-rule-governance-pruning.md

@@ -0,0 +1,240 @@
+---
+adr: 004
+status: accepted
+date: 2026-05-08
+decision: rule-governance-pruning
+supersedes: —
+superseded_by: —
+phase: road-to-augment-limit-fit · P5.5
+---
+
+# ADR-004 — Rule-Governance Pruning (Phase 5)
+
+## Status
+
+**Accepted** · 2026-05-08.
+
+## Context
+
+`road-to-augment-limit-fit` Phase 5 ran a Rule-Governance Audit on
+the 49 `type: auto` rules that consume the workspace-guidelines
+budget via description-stub injection (~250 chars each). Three
+analytic passes ran:
+
+- **5.1** `scripts/audit_auto_rules.py` — measured stub vs. body
+  cost. Auto-rule stubs total **11,513 chars · 23.3 %** of the
+  49,512 ceiling.
+- **5.2** `scripts/audit_overlap.py` — pairwise Jaccard on
+  `path_prefix` triggers + symmetric keyword overlap on
+  description/keyword/intent token sets. 4 pairs flagged
+  (path-Jaccard ≥ 0.5 OR keyword-overlap ≥ 0.4).
+- **5.3** `scripts/audit_likelihood.py` — corpus-keyword scoring
+  against indexed skills + commands + contexts + guidelines. 0
+  rules below the strict `< 2` hits floor; bottom-10 list surfaced
+  for council walk.
+
+**5.4** AI Council R3 (claude-sonnet-4-5 + gpt-4o, 2 rounds, prompt
+mode) walked the candidate list. Council convergence and host
+verdicts are recorded in `agents/reports/auto-rules-audit.md`
+§ Phase 5.4. The dominant council insight:
+
+> *"Rarity ≠ redundancy. Low corpus hits often indicate a
+> preventative rule that fires precisely when needed, not a useless
+> one. The audit cannot distinguish dead weight from option-value
+> insurance."* — claude-sonnet-4-5
+
+This narrowed the action surface from "remove anything in the
+bottom 10" to four targeted decisions where redundancy or
+mechanical-already status was structurally provable.
+
+## Decision
+
+Four approved actions, applied in Phase 5.6:
+
+### Implementation pattern: demote via frontmatter
+
+All four actions use the same mechanical pattern: change rule
+frontmatter `type: "auto"` → `type: "manual"`. This:
+
+- **Removes the stub from the workspace budget.**
+  `scripts/measure_augment_budget.py` only counts `type: "auto"`
+  rules (line 99). Anything else has zero stub cost.
+- **Preserves the file and its cross-references.**
+  Skills, contexts, templates, and contracts that link to the rule
+  (`size-enforcement` is referenced from `rule-writing/SKILL.md`,
+  `command-writing/SKILL.md`, `artifact-drafting-protocol.md`,
+  `proposal.example.md`, `rule-classification.md`,
+  `self-improvement-pipeline.md`, etc.) keep working.
+- **Keeps `compile_router.py` deterministic.**
+  Non-auto rules are skipped by `_resolve_tier`; the rule no
+  longer routes through `router.json` but remains a reference
+  document.
+
+This pattern was chosen over hard deletion after the
+cross-reference audit (Phase 5.6 prep) showed each candidate has
+≥ 5 inbound references. Deletion would force a wide-radius
+documentation rewrite for marginal additional savings.
+
+### 1. `guidelines` — demote
+
+- **Verdict:** demote (`type: "auto"` → `type: "manual"`).
+- **Rationale:** Generic name, no `routes_to:` target, 552 corpus
+  hits, no `path_prefix` trigger. Description ("Writing or
+  reviewing code — check relevant guideline before writing or
+  reviewing code") is ambient guidance already covered by the 9
+  always-rules and the Iron-Law floor. The auto-stub adds ~185
+  chars of overhead for a rule that fires on every code touch but
+  has no specific routing target — i.e., it functions as a noop
+  reminder. The body remains as a reference doc citing the
+  guidelines-mechanics context.
+- **Preserved triggers:** the body retains its trigger discussion
+  for human readers; auto-discovery is dropped.
+- **Migration:** none. Inbound link in
+  `contexts/communication/rules-auto/guidelines-mechanics.md`
+  remains valid.
+
+### 2. `size-enforcement` — demote (logical merge into `rule-type-governance`)
+
+- **Verdict:** demote (`type: "auto"` → `type: "manual"`); record
+  the logical merge in this ADR rather than physically folding the
+  body. `rule-type-governance` already routes to its own
+  guideline; both rules now share the same auto-trigger surface
+  conceptually but only `rule-type-governance` injects a stub.
+- **Rationale:** Both rules fire during rule/skill/command
+  authoring. `size-enforcement` enforces character budgets;
+  `rule-type-governance` enforces always-vs-auto classification.
+  Council R3 convergence on the merge. Physical body-fold rejected
+  to keep blast radius small (see implementation-pattern note).
+- **Preserved triggers:** "size", "budget", "limit", "char count",
+  artefact creation/editing scope — all retained in the rule body
+  for ad-hoc consultation; the auto-discovery surface is dropped.
+- **Migration:** none required. `rule-writing/SKILL.md`,
+  `command-writing/SKILL.md`, `artifact-drafting-protocol.md`,
+  `proposal.example.md`, and the contracts continue to cite the
+  rule by file path; the file still exists.
+
+### 3. `package-ci-checks` — demote
+
+- **Verdict:** demote (`type: "auto"` → `type: "manual"`).
+- **Rationale:** Rule is `mechanical-already` — `task ci` already
+  enforces the same checks before a PR can merge. The rule is also
+  package-self-referential (it only fires when contributing to
+  `event4u/agent-config` itself); consumer projects never benefit
+  from the stub. Council R3: gpt-4o (demote), Sonnet (verify skill
+  links contract first — confirmed: `routes_to: skill:lint-skills`).
+- **Preserved triggers:** "task ci", "before push", "before pr".
+  Body retains trigger phrases for human reference.
+- **Migration:** AGENTS.md "Working on this repo" section already
+  documents `task ci`; no consumer-project regression because
+  consumers never received this rule's stub anyway (`source: package`).
+
+### 4. `analysis-skill-routing` — demote
+
+- **Verdict:** demote (`type: "auto"` → `type: "manual"`).
+- **Rationale:** The rule's only function is to point host agents
+  at the `analysis-skill-router` skill when an analysis request
+  fires. The skill's own description carries the same trigger
+  surface ("picking which analysis or project-analysis-* skill
+  fits a request") and is already auto-discoverable as a Skill.
+  The rule is a redundant pointer-to-pointer. Council R3:
+  gpt-4o (merge into slash-command-routing-policy — host rejected:
+  analysis ≠ slash-commands; merge would collapse a meaningful
+  category distinction). Sonnet (keep + add `routes_to:` — host
+  rejected: routing already exists via the skill itself).
+- **Preserved triggers:** "analyze", "analysis", "dig into the
+  codebase". Already present in the skill's description.
+- **Migration:** Verify `analysis-skill-router` skill description
+  is pushy enough; no other action required.
+
+## Consequences
+
+### Accepted
+
+- **Stub-cost saving:** ~849 chars freed (~1.7 % of the 49,512 cap).
+  Phase 5 alone is insufficient to hit the 20 % headroom goal.
+- **Phase 6 (Thin-Root AGENTS.md) was mandatory**, not optional.
+  AGENTS.md was the largest single asset (12,042 chars) and the
+  only remaining lever once Phase 5 was locked in.
+- **Four rules (`guidelines`, `size-enforcement`,
+  `package-ci-checks`, `analysis-skill-routing`) demoted from
+  `type: "auto"` to `type: "manual"`.** Total auto-rules: 49 → 45.
+  Files preserved on disk; cross-references intact.
+- **Final budget after Phases 5–7** (`scripts/measure_augment_budget.py`,
+  2026-05-08): AGENTS.md 2,773 + always-rules (9) 26,322 + auto-rule
+  stubs (45) 10,664 = **39,759 chars · 80.3 % utilisation · 19.7 %
+  headroom** (149 chars / 0.3 % short of the ≥ 20 % goal — within
+  rounding; effectively at target). Phase 6 (Thin-Root AGENTS.md
+  refactor: 12,042 → 2,773 chars) carried the bulk of the saving
+  that Phase 5 alone could not deliver. Phase 7 (`scripts/lint_agents_md.py`,
+  CI-blocking) locks the contract in.
+
+### Trade-offs
+
+- **Sonnet's "rarity ≠ redundancy" critique honored.** The audit
+  identified 14 candidates; only 4 pass the host's redundancy /
+  mechanical-already test. Aggressive ceiling (~2,750 chars, per
+  gpt-4o) was rejected as it would force domain-specific rules
+  (`docker-commands`, `laravel-translations`) into manual
+  guideline-load workflows for the 20 % of projects that need them.
+- **`upstream-proposal` and `slash-command-routing-policy` both
+  retained without `routes_to:` fix.** Flagged as follow-up work
+  outside this ADR's scope; their preservation is justified by
+  rare-but-critical activation pattern.
+- **No `augment-portability` / `docs-sync` merge** despite 1.00
+  path-Jaccard. Council R3 convergence: workspace-layout
+  coincidence, not logical duplication. Different intents
+  (host-portability vs. sync-workflow hygiene).
+
+## Re-evaluation trigger
+
+- Augment changes its accounting model (e.g. starts injecting
+  auto-rule bodies into the workspace prompt) → re-open this
+  governance pass; the stub-cost / body-cost ratio changes
+  drastically.
+- Auto-rule count grows by ≥ 5 (history check via
+  `agents/.augment-budget-history.jsonl`) → repeat the audit
+  with the same three-pass methodology.
+- A retained rule (`upstream-proposal`, `slash-command-routing-policy`,
+  `analysis-skill-routing`'s sibling skill) shows a 30-day window
+  with zero documented activation in `agents/council-sessions/` →
+  open a follow-up ADR demoting it.
+
+## Alternatives considered
+
+- **Aggressive prune (gpt-4o R1 line):** demote
+  `agent-docs`, `docker-commands`, `laravel-translations`. Rejected.
+  Sonnet's rarity-≠-redundancy critique applies; these are
+  domain-specific rules with substantial corpus presence (240+
+  hits each) and their absence forces consumer projects into
+  manual guideline-load. The ~750-char additional saving is not
+  worth the behavioural regression.
+- **`augment-portability` / `docs-sync` merge (gpt-4o R2):**
+  Rejected. 1.00 path-Jaccard reflects shared filesystem
+  triggers (`docs/guides/agent-setup/augment.md`), not shared
+  intent. `augment-portability` enforces project-agnostic content
+  in `.agent-src/`; `docs-sync` enforces cross-reference integrity
+  on add/rename/delete. Different verbs, different blast radii.
+- **Defer all rule changes; focus on Phase 6 only:** Rejected.
+  The four approved actions are independently defensible; bundling
+  them with Phase 6 would obscure the rationale and conflate two
+  different optimisation strategies (rule-set hygiene vs.
+  AGENTS.md restructure). Each phase ships its own savings on its
+  own audit trail.
+
+## References
+
+- `agents/roadmaps/archive/road-to-augment-limit-fit.md` § Phase 5
+- `agents/reports/auto-rules-audit.md` (full audit findings,
+  council walk, host verdicts)
+- `agents/reports/auto-rules-overlap.json` (Phase 5.2 data)
+- `agents/reports/auto-rules-likelihood.json` (Phase 5.3 data)
+- `agents/council-questions/augment-limit-fit-rule-governance.md`
+  (Phase 5.4 prompt)
+- `agents/council-responses/augment-limit-fit-rule-governance.json`
+  (Phase 5.4 R3 raw debate) <!-- council-ref-allowed: ADR decision trace -->
+- `docs/decisions/ADR-rule-kernel-and-router.md` (kernel-membership
+  contract — Phase 5 changes leave kernel untouched per Lever C lock)
+- `.agent-src.uncompressed/rules/guidelines.md` (deprecated subject)
+- `.agent-src.uncompressed/rules/size-enforcement.md` (merged subject)
+- `.agent-src.uncompressed/rules/package-ci-checks.md` (demoted subject)
+- `.agent-src.uncompressed/rules/analysis-skill-routing.md` (demoted subject)

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 60 rules. No configuration needed.
+This is enforced automatically by 58 rules. No configuration needed.
 
 ---
 

package/docs/guidelines/agent-infra/review-routing-data-format.md

@@ -1,7 +1,7 @@
 # Review Routing Data Format
 
 Schema and conventions for the two project-local YAML files that feed the
-[`review-routing-awareness`](../../rules/review-routing-awareness.md) rule
+[`reviewer-awareness`](../../rules/reviewer-awareness.md) rule
 and the [`review-routing`](../../skills/review-routing/SKILL.md) skill.
 
 Both files are **optional** and live in the consumer repository — never
@@ -139,6 +139,5 @@ Field semantics:
 
 ## See also
 
-- [`review-routing-awareness`](../../rules/review-routing-awareness.md)
 - [`reviewer-awareness`](../../rules/reviewer-awareness.md)
 - [`review-routing`](../../skills/review-routing/SKILL.md)

package/package.json

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

package/scripts/_p4_migrate.py

@@ -52,12 +52,12 @@ SKILL_MIGRATIONS = [
     ("package-ci-checks", "skill:lint-skills",
      [("phrase", "task ci"), ("phrase", "before push"), ("phrase", "before pr")],
      "Run `task ci` locally and confirm green before pushing or opening a PR in this package."),
-    ("review-routing-awareness", "skill:review-routing",
-     [("keyword", "reviewer"), ("phrase", "risk hotspot"), ("phrase", "ownership map")],
-     "Consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe."),
+    # review-routing-awareness was merged into reviewer-awareness on 2026-05-08
+    # (see agents/contexts/adr-auto-rule-consolidation.md) as part of the
+    # Augment literal-budget relief work — Lever D consolidation.
     ("reviewer-awareness", "skill:review-routing",
-     [("keyword", "reviewer"), ("phrase", "suggest reviewers")],
-     "Anchor reviewer choice in paths and risk, never seniority; medium / high risk requires primary + secondary role."),
+     [("keyword", "reviewer"), ("phrase", "suggest reviewers"), ("phrase", "risk hotspot"), ("phrase", "ownership map")],
+     "Anchor reviewer choice in paths and risk, never seniority; consult ownership-map + historical-bug-patterns; medium / high risk requires primary + secondary role."),
     ("skill-improvement-trigger", "skill:skill-improvement-pipeline",
      [("phrase", "after completing"), ("keyword", "improvement"), ("keyword", "pipeline")],
      "After a meaningful task, trigger the post-task learning capture if `pipelines.skill_improvement` is enabled."),

package/scripts/audit_auto_rules.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Audit auto-rules for the Rule-Governance pass (Phase 5.1 of
+road-to-augment-limit-fit).
+
+Walk `.agent-src.uncompressed/rules/*.md`, collect per-rule frontmatter
+(`description`, `triggers`, `routes_to`, `tier`), measure body and
+registry-stub costs, and emit:
+
+- `agents/reports/auto-rules-audit.json` — deterministic, machine-readable.
+- `agents/reports/auto-rules-audit.md`   — ranked summary for review.
+
+The registry-stub cost mirrors `scripts/measure_augment_budget.py`'s
+accounting model: only the stub line is injected into the Augment
+workspace-guidelines budget for `type: auto` rules. The body cost is
+informational — it ships in the projected `.augment/rules/` tree but
+does NOT count against the 49,512-char ceiling.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SRC_RULES = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+PROJECTED_RULES = REPO_ROOT / ".augment" / "rules"
+REPORT_DIR = REPO_ROOT / "agents" / "reports"
+JSON_OUT = REPORT_DIR / "auto-rules-audit.json"
+MD_OUT = REPORT_DIR / "auto-rules-audit.md"
+
+# Stub Augment injects per auto-rule. Mirrors measure_augment_budget.STUB_TEMPLATE.
+STUB_TEMPLATE = (
+    'If the user prompt matches the description "{desc}", '
+    "read the file located in {path}"
+)
+
+
+def _split_frontmatter(text: str) -> tuple[dict, str]:
+    if not text.startswith("---\n"):
+        return {}, text
+    end = text.find("\n---", 4)
+    if end < 0:
+        return {}, text
+    fm = yaml.safe_load(text[4:end]) or {}
+    body = text[end + 4 :].lstrip("\n")
+    return fm, body
+
+
+def _trigger_summary(triggers: list) -> dict:
+    paths: list[str] = []
+    keywords: list[str] = []
+    intents: list[str] = []
+    for entry in triggers or []:
+        if not isinstance(entry, dict):
+            continue
+        if "path_prefix" in entry:
+            paths.append(str(entry["path_prefix"]))
+        if "keyword" in entry:
+            keywords.append(str(entry["keyword"]))
+        if "intent" in entry:
+            intents.append(str(entry["intent"]))
+    return {"path_prefixes": paths, "keywords": keywords, "intents": intents}
+
+
+def collect() -> list[dict]:
+    rules: list[dict] = []
+    for path in sorted(SRC_RULES.glob("*.md")):
+        text = path.read_text(encoding="utf-8")
+        fm, body = _split_frontmatter(text)
+        if fm.get("type") != "auto":
+            continue
+        desc = (fm.get("description") or "").strip()
+        rel_projected = f".augment/rules/{path.name}"
+        stub = STUB_TEMPLATE.format(desc=desc, path=rel_projected)
+        triggers = _trigger_summary(fm.get("triggers") or [])
+        routes_to = list(fm.get("routes_to") or [])
+        rules.append(
+            {
+                "name": path.stem,
+                "src_path": str(path.relative_to(REPO_ROOT)),
+                "tier": fm.get("tier"),
+                "description": desc,
+                "description_chars": len(desc),
+                "triggers": triggers,
+                "trigger_count": (
+                    len(triggers["path_prefixes"])
+                    + len(triggers["keywords"])
+                    + len(triggers["intents"])
+                ),
+                "routes_to": routes_to,
+                "body_chars": len(body),
+                "file_chars": len(text),
+                "stub_chars": len(stub),
+            }
+        )
+    return rules
+
+
+def render_markdown(rules: list[dict]) -> str:
+    total_stub = sum(r["stub_chars"] for r in rules)
+    total_body = sum(r["body_chars"] for r in rules)
+    total_desc = sum(r["description_chars"] for r in rules)
+    lines = [
+        "# Auto-Rule Audit",
+        "",
+        "Generated by `scripts/audit_auto_rules.py` for Phase 5 of",
+        "`agents/roadmaps/road-to-augment-limit-fit.md`. Re-run after",
+        "any rule add/merge/deprecate to refresh the baseline.",
+        "",
+        "## Totals",
+        "",
+        f"- auto-rules: **{len(rules)}**",
+        f"- registry-stub cost (counts against 49,512 cap): **{total_stub:,}** chars",
+        f"- description chars (subset of stub cost): **{total_desc:,}** chars",
+        f"- body chars (informational, NOT in budget): **{total_body:,}** chars",
+        "",
+        "## Ranked by registry-stub cost",
+        "",
+        "| # | Rule | Tier | Desc | Stub | Body | Triggers | Routes |",
+        "|---|------|------|------|------|------|----------|--------|",
+    ]
+    for i, r in enumerate(sorted(rules, key=lambda x: -x["stub_chars"]), 1):
+        triggers = (
+            f"{len(r['triggers']['path_prefixes'])}p / "
+            f"{len(r['triggers']['keywords'])}k / "
+            f"{len(r['triggers']['intents'])}i"
+        )
+        routes = ", ".join(r["routes_to"]) or "—"
+        lines.append(
+            f"| {i} | `{r['name']}` | {r['tier'] or '—'} | "
+            f"{r['description_chars']} | {r['stub_chars']} | "
+            f"{r['body_chars']} | {triggers} | {routes} |"
+        )
+    lines.append("")
+    lines.append("Trigger key: `Np` = path-prefix, `Nk` = keyword, `Ni` = intent.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    if not SRC_RULES.is_dir():
+        print(f"❌  Missing source dir: {SRC_RULES}", file=sys.stderr)
+        return 1
+    rules = collect()
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    payload = {"rule_count": len(rules), "rules": rules}
+    JSON_OUT.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+    MD_OUT.write_text(render_markdown(rules), encoding="utf-8")
+    print(f"✅  Audited {len(rules)} auto-rules.")
+    print(f"   JSON: {JSON_OUT.relative_to(REPO_ROOT)}")
+    print(f"   MD:   {MD_OUT.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())