@event4u/agent-config 1.24.0 → 1.26.0

package/docs/contracts/linter-structural-model.md

@@ -0,0 +1,180 @@
+---
+stability: beta
+---
+
+# Linter Structural Model
+
+**Status:** LOCKED — shipped 2026-05-08 on
+`feat/road-to-structural-linter-reform`. The linter now applies the
+structural model to skills, rules, and commands.
+
+## Why a structural model
+
+Council convergence (Sonnet + GPT-4o, 2026-05-06): raw line / word
+counts produce ratchet drift. Three failure modes that the pure-size
+gate cannot distinguish:
+
+- A 500-line skill with **one** 10-step procedure (legitimate) vs a
+  500-line skill with **ten** independent procedures (split candidate).
+- A 1700-word command that **delegates** to a cluster (legitimate
+  orchestrator) vs a 1700-word command that **inlines** the work.
+- A 60-line rule whose body is a **verbatim Iron-Law block**
+  (legitimate) vs a 60-line rule that is **prose explanation**
+  (split candidate).
+
+The structural model replaces the size threshold with four primitives.
+
+## Primitives
+
+### 1. Density score (0.0 – 1.0)
+
+```
+density = structured_lines / total_non_blank_lines
+```
+
+`structured_lines` = lines inside fenced blocks + markdown-table rows
++ bullet-list lines + numbered-list lines + section-heading lines.
+Higher = more structured (catalogue, table, code, list); lower =
+prose-dominant.
+
+### 2. Multi-workflow detector (skills only)
+
+Skills with **≥ 2 `## Procedure`** (or `## Procedure: <name>`)
+sections ship multiple independently invocable procedures. Combined
+with size, this is the cluster-split signal.
+
+### 3. Delegation detector (commands only)
+
+Command has a delegation signal when **either** holds:
+
+- frontmatter declares `cluster:` or `routes_to:`
+- body contains ≥ 3 markdown links to other `.md` files
+
+Absence of both signals on a large command = inlined logic.
+
+### 4. Iron-Law block detector (rules only)
+
+A fenced block is an Iron-Law block when its body has **≥ 30
+alphabetical characters** with **≥ 60 % uppercase** across **≥ 1
+non-empty line**. The 30-character floor filters single ALL-CAPS
+markers (`OK`, `WIP`); the 60 % uppercase floor catches verbatim
+imperatives (`NEVER COMMIT.`).
+
+## Phase 1 calibration (2026-05-08)
+
+Sweep covered all 310 lintable artifacts via
+[`scripts/measure_density.py`](../../scripts/measure_density.py); raw
+data lives at `agents/.density-snapshot.jsonl` (local-only — re-run
+`python3 scripts/measure_density.py --root .agent-src --jsonl
+agents/.density-snapshot.jsonl` to regenerate).
+
+| Type | Count | Avg density | Median | Bucket [0.4-0.6] | Bucket [0.6-1.0] |
+|---|---|---|---|---|---|
+| skill | 142 | 0.76 | 0.78 | 22 | 119 |
+| command | 103 | 0.59 | 0.57 | 46 | 45 |
+| rule | 58 | 0.47 | 0.48 | 25 | 11 |
+| persona | 7 | 0.38 | 0.38 | 1 | 0 |
+
+Iron-Law detector recall on 9 canonical Iron-Law rules: **8 / 9** (all
+except `agent-authority`, which uses a markdown-table index instead of
+a fenced block — correct miss).
+
+`quality-tools` (411 lines, single workflow): density **0.83**, single
+procedure → no warning under the new model. ✓ roadmap success criterion.
+
+`optimize/augmentignore.md` (1679 words): delegation signal **present**
+(frontmatter `routes_to:`) → no warning under the new model. ✓ roadmap
+success criterion.
+
+Of 13 commands ≥ 1000 words, only **2** lack a delegation signal —
+both are candidates for Phase 4.1 review (`compress.md`,
+`project-analyze.md`; the latter has density 0.86, exempt under the
+density-AND-delegation gate).
+
+## Warn rules (shipped Phase 3, 2026-05-08)
+
+| Artifact | Warn condition |
+|---|---|
+| **skill** | `lines > 400` AND (`density < 0.6` OR `procedures ≥ 2`) |
+| **command** | `words > 1000` AND no delegation signal AND `density < 0.65` |
+| **rule** | `lines > 60` AND `density < 0.5` AND `iron_law_blocks == 0` |
+
+The 200-line rule **error** stays unconditional. No new frontmatter
+keys ship — the four structural primitives are the contract.
+
+Calibration sweep on the 2026-05-08 corpus (310 artifacts):
+
+| Type | Old warns | New warns | New band | Δ |
+|---|---|---|---|---|
+| rule | 23 | 2 | 3.4 % | −91 % |
+| skill | 2 | 1 | 0.7 % | −50 % |
+| command | 9 | 1 | 1.0 % | −89 % |
+| **total** | **34** | **4** | **1.3 %** | **−88 %** |
+
+Pass rate: 186 → 209 (`pass`); 124 → 101 (`pass_with_warnings`); 0
+errors. Each remaining warning is a genuine structural defect:
+
+- `compress.md` (1569 words, density 0.58, no delegation signal) —
+  inlined logic in a non-orchestrator command.
+- `artifact-drafting-protocol.md` rule (65 lines, density 0.37, no
+  Iron-Law block) — prose-dominant long rule.
+- `minimal-safe-diff.md` rule (69 lines, density 0.41, no Iron-Law
+  block) — prose-dominant long rule.
+- `ai-council/SKILL.md` (525 lines, density 0.37) — orchestrator
+  skill below the density floor; refactor candidate.
+
+Roadmap target ≤ 10 % rule-warning band. ✓ (3.4 %)
+
+## Frontmatter contract — Phase 2 decisions (2026-05-08)
+
+AI Council run (Claude Sonnet 4.5 + GPT-4o, 2 rounds, $0.046; raw
+transcript local-only per the council-references convention).
+
+**Key 1 — `iron_law:` frontmatter — DECISION: Option A (auto-detect, no tag).**
+
+Both council members converged on Option A. The detector recall on
+the canonical 9-rule set is 8 / 9, and the one miss
+(`agent-authority`) uses a markdown-table priority index that is
+**not** an Iron-Law imperative — its body delegates to the rules it
+indexes. The detector is correct to skip it. No `iron_law:`
+frontmatter key is added.
+
+**Key 2 — `density_exempt:` frontmatter — DECISION: Option A (no flag).**
+
+Council split:
+
+- Sonnet 4.5: Reject any flag. Add **type-based density floors**
+  (orchestrators 0.35, executors 0.6, imperatives 0.4) so the
+  detector classifies structurally instead of relying on author
+  declarations.
+- GPT-4o: Adopt Option C (`density_exempt: true` + required
+  `density_exempt_reason:`) with periodic re-audit.
+
+Sonnet's structural argument carries: an escape hatch for a 1-in-142
+corpus case ships maintenance debt across every future artifact that
+brushes the boundary. The single failing skill (`ai-council`,
+density 0.36) is a documentation-heavy reference-orchestrator and is
+left as a Phase-4 review candidate — either restructure the skill or
+add orchestrator-aware type-floors as a follow-up. No
+`density_exempt:` key is added in Phase 3.
+
+The Phase-3 implementation therefore ships **zero new frontmatter
+keys** — the structural primitives are the contract.
+
+## Out of scope
+
+- Hard error thresholds beyond the 200-line rule cap.
+- Automatic refactoring of artifacts that fail the new model.
+- Cross-artifact dependency counts (a skill linking 4 other skills is
+  `routes_to` doing its job, not a defect).
+
+## References
+
+- `scripts/measure_density.py` — Phase 1.1 measurement tool.
+- `agents/.density-snapshot.jsonl` — full per-artifact metrics
+  (gitignored, re-run the measurement script to regenerate).
+- `scripts/skill_linter.py` — structural-model implementation
+  (`_density_score`, `_count_procedure_sections`,
+  `_command_delegation_signal`, `_iron_law_blocks`).
+- `docs/guidelines/agent-infra/size-and-scope.md` — guideline now
+  describes the structural model; Option 2 transition notes removed.

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/docs/guidelines/agent-infra/size-and-scope.md

@@ -33,10 +33,14 @@ Size is a signal — not the goal.
 - Acceptable: **< 100–120 lines**
 - Hard limit: **< 200 lines**
 
-Linter (council review 2026-05-06): the > 40 / > 60 line warnings are
-**density-gated** — rules with ≥ 30 % fenced content (verbatim Iron-Law
-blocks, worked-example fences) are exempt from the line-count warning.
-The 200-line hard error stays unconditional.
+Linter (structural model, 2026-05-08 — see
+[`docs/contracts/linter-structural-model.md`](../../contracts/linter-structural-model.md)):
+the long-rule warning fires only when the rule is **> 60 non-empty
+lines AND density < 0.50 AND ships no Iron-Law block**. Rules whose
+body is a verbatim ALL-CAPS imperative (`commit-policy`,
+`ask-when-uncertain`, `direct-answers`) are auto-exempt — no
+frontmatter flag required. The 200-line hard error stays
+unconditional.
 
 Reason:
 - Loaded frequently
@@ -48,10 +52,11 @@ Reason:
 ## Skills
 
 - Target: **300–900 words**
-- Warning: **> 400 lines** (raised from 300, council review 2026-05-06)
-- Strong split signal: reference-rich skills (analyzer, quality-tool
-  catalog, council orchestration) may legitimately sit between 300 and
-  400 lines without being split-candidates
+- Warning: **> 400 lines AND (density < 0.60 OR ≥ 2 `## Procedure`
+  blocks)** — structural model, 2026-05-08
+- Reference-rich skills with high density (`quality-tools` at 0.83,
+  catalogue-style skills) pass without splitting; the multi-procedure
+  trigger flags genuine cluster-split candidates regardless of size
 
 Focus:
 - scanability
@@ -64,10 +69,11 @@ Focus:
 
 - Target: **200–600 words**
 - Acceptable: **up to ~1000 words**
-- Warning: **> 1000 words AND lacks delegation structure** (< 5
-  sub-sections OR < 3 code blocks). Well-factored orchestrators with ≥ 5
-  sub-sections AND ≥ 3 code blocks are exempt — the size reflects
-  dispatch breadth, not bloat (council review 2026-05-06).
+- Warning: **> 1000 words AND no delegation signal AND density < 0.65**
+  — structural model, 2026-05-08. A delegation signal is either
+  frontmatter (`cluster:` / `routes_to:`) OR ≥ 3 markdown links to
+  other `.md` files. Well-factored orchestrators pass automatically;
+  inlined logic in a non-orchestrator command warns.
 
 Commands orchestrate — not implement.
 

package/package.json

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