@event4u/agent-config 1.23.0 → 1.25.0

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.23.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())

package/scripts/audit_likelihood.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Activation-likelihood heuristic for the Rule-Governance pass
+(Phase 5.3 of road-to-augment-limit-fit).
+
+For every auto-rule from `agents/reports/auto-rules-audit.json`:
+
+1. Build a token set from `description`, `triggers[].keyword`,
+   `triggers[].intent`, and the rule name itself.
+2. Index a corpus of skills (`SKILL.md`), contexts
+   (`agents/contexts/**/*.md`), guidelines, and command files.
+3. Score `corpus_hits = sum(1 for token in tokens if token in corpus)`.
+4. Flag rules with `< 2` corpus hits as "low-likelihood" (their trigger
+   surface is so generic that the host LLM is unlikely to find a
+   project-local file the rule was written to bridge to).
+
+Result is a JSON dump + Markdown section appended to
+`agents/reports/auto-rules-audit.md`.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+REPORT_DIR = REPO_ROOT / "agents" / "reports"
+AUDIT_JSON = REPORT_DIR / "auto-rules-audit.json"
+AUDIT_MD = REPORT_DIR / "auto-rules-audit.md"
+LIKELIHOOD_JSON = REPORT_DIR / "auto-rules-likelihood.json"
+
+CORPUS_GLOBS = [
+    ".agent-src.uncompressed/skills/**/SKILL.md",
+    ".agent-src.uncompressed/commands/**/*.md",
+    "agents/contexts/**/*.md",
+    "docs/guidelines/**/*.md",
+]
+
+LOW_LIKELIHOOD_HITS = 2
+
+STOPWORDS = {
+    "the", "and", "for", "with", "when", "use", "or", "of", "to", "a",
+    "an", "is", "in", "on", "by", "be", "at", "as", "it", "if", "are",
+    "this", "that", "from", "but", "not", "can", "any", "all", "no",
+    "after", "before", "during", "user", "agent", "code", "project",
+    "via", "into", "onto", "even", "without", "naming", "rule", "rules",
+    "skill", "skills", "command", "commands", "files", "file", "doc",
+    "docs", "md", "txt",
+}
+
+
+def tokens(text: str) -> set[str]:
+    raw = re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", text.lower())
+    return {t for t in raw if t not in STOPWORDS and len(t) > 3}
+
+
+def build_corpus() -> Counter:
+    counter: Counter = Counter()
+    for glob in CORPUS_GLOBS:
+        for path in REPO_ROOT.glob(glob):
+            if not path.is_file():
+                continue
+            try:
+                text = path.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                continue
+            for tok in tokens(text):
+                counter[tok] += 1
+    return counter
+
+
+def score(rule: dict, corpus: Counter) -> dict:
+    rule_tokens = (
+        tokens(rule["description"])
+        | tokens(rule["name"].replace("-", " "))
+        | tokens(" ".join(rule["triggers"]["keywords"]))
+        | tokens(" ".join(rule["triggers"]["intents"]))
+    )
+    hits = {t: corpus[t] for t in rule_tokens if corpus[t] > 0}
+    return {
+        "name": rule["name"],
+        "tokens": sorted(rule_tokens),
+        "hits": dict(sorted(hits.items(), key=lambda x: -x[1])[:8]),
+        "hit_count": len(hits),
+        "total_hit_volume": sum(hits.values()),
+        "low_likelihood": len(hits) < LOW_LIKELIHOOD_HITS,
+    }
+
+
+def render_md(scores: list[dict]) -> str:
+    flagged = [s for s in scores if s["low_likelihood"]]
+    lines = [
+        "",
+        "## Phase 5.3 — Activation likelihood (corpus-keyword)",
+        "",
+        f"Corpus: skills + commands + contexts + guidelines.",
+        f"Low-likelihood threshold: `< {LOW_LIKELIHOOD_HITS}` distinct corpus hits.",
+        "",
+        f"Rules flagged: **{len(flagged)} / {len(scores)}**.",
+        "",
+        "### Low-likelihood rules",
+        "",
+    ]
+    if not flagged:
+        lines += ["_None._", ""]
+    else:
+        lines += ["| Rule | Hits | Tokens (top) |", "|------|------|--------------|"]
+        for s in sorted(flagged, key=lambda x: x["hit_count"]):
+            toks = ", ".join(f"`{t}`" for t in s["tokens"][:6]) or "—"
+            lines.append(f"| `{s['name']}` | {s['hit_count']} | {toks} |")
+        lines.append("")
+    lines += [
+        "### Full ranking (lowest hit-count first, top 20)",
+        "",
+        "| Rule | Distinct hits | Total hit volume |",
+        "|------|---------------|------------------|",
+    ]
+    for s in sorted(scores, key=lambda x: (x["hit_count"], x["total_hit_volume"]))[:20]:
+        lines.append(f"| `{s['name']}` | {s['hit_count']} | {s['total_hit_volume']} |")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    if not AUDIT_JSON.exists():
+        print(f"❌  Run audit_auto_rules.py first: missing {AUDIT_JSON}", file=sys.stderr)
+        return 1
+    rules = json.loads(AUDIT_JSON.read_text(encoding="utf-8"))["rules"]
+    corpus = build_corpus()
+    scores = [score(r, corpus) for r in rules]
+    LIKELIHOOD_JSON.write_text(
+        json.dumps({"corpus_size": len(corpus), "scores": scores}, indent=2),
+        encoding="utf-8",
+    )
+    md = AUDIT_MD.read_text(encoding="utf-8") if AUDIT_MD.exists() else ""
+    if "## Phase 5.3 — Activation likelihood" in md:
+        md = md.split("## Phase 5.3 — Activation likelihood")[0].rstrip() + "\n"
+    AUDIT_MD.write_text(md + render_md(scores), encoding="utf-8")
+    flagged = [s for s in scores if s["low_likelihood"]]
+    print(f"✅  Likelihood scored: {len(scores)} rules, {len(flagged)} low-likelihood.")
+    print(f"   JSON: {LIKELIHOOD_JSON.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())