@event4u/agent-config 1.20.0 → 1.22.0

package/docs/decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md

@@ -0,0 +1,126 @@
+# ADR-003 — Flat Cluster Sub-Commands and Colon-Canonical Invocation
+
+- **Status:** Accepted (2026-05-07)
+- **Phase:** Command-cluster contract (Phase 2 follow-up)
+- **Supersedes:** none — extends the locked cluster set in
+  `docs/contracts/command-clusters.md`.
+- **Related:** `roadmap-process` migration (2026-05-07) — the trigger
+  that forced the decision; `contexts/execution/roadmap-process-loop.md`
+  (the shared mechanics extracted alongside).
+
+## Context
+
+`roadmap-execute` was being replaced by an autonomous-execution surface
+with three scopes: single step, single phase, full roadmap. The
+question was where those three commands live in the cluster catalog.
+Four shapes were on the table:
+
+- **A — separate `/roadmap-process` cluster.** Two top-level clusters
+  (`/roadmap` for authoring, `/roadmap-process` for execution).
+- **B — sub-sub-commands** (`/roadmap:process:phase`). One cluster,
+  two-level dispatch.
+- **C — flat under `/roadmap`, no verb** (`/roadmap:step` ·
+  `/roadmap:phase` · `/roadmap:full`). Verb hidden in cluster
+  description.
+- **D — flat under `/roadmap`, verb fused with scope**
+  (`/roadmap:process-step` · `/roadmap:process-phase` ·
+  `/roadmap:process-full`). One cluster, one dispatch level, composite
+  sub-name carries the verb.
+
+Existing infrastructure assumed a single dispatch level: the contract
+table at `docs/contracts/command-clusters.md`, the linter
+`scripts/lint_no_new_atomic_commands.py`, and the dispatcher-shape
+checker `scripts/check_cluster_patterns.py` all parse one column of
+sub-names per cluster.
+
+## Decision
+
+1. **Cluster depth stays flat.** A cluster has exactly one level of
+   sub-commands. No sub-sub-commands. Option B is rejected.
+
+2. **Verb-and-scope sub-commands use a composite name** joined by `-`
+   (`process-step`, `process-phase`, `process-full`). The verb stays
+   visible in the autocomplete list; symmetry with sibling
+   sub-commands (`/roadmap:create`) is preserved as
+   verb-or-noun-per-sub. Option D wins over C.
+
+3. **Colon is the canonical invocation form** (`/<cluster>:<sub>`).
+   The space-separated form (`/<cluster> <sub>`) remains a
+   first-class equivalent — both forms route to the same dispatcher.
+   Autocompletion-aware UIs (Claude Code picker, IDE slash-menus,
+   shell completers) MUST surface the colon form because it stays a
+   single token.
+
+4. **Future verb+scope clusters follow the same shape.** Any future
+   cluster with multiple verbs (e.g. an authoring verb and an
+   execution verb) uses composite sub-names rather than introducing a
+   second cluster or a second dispatch level.
+
+## Rationale
+
+- **Option A (separate cluster)** scatters one domain across two
+  top-level surfaces. Users have to remember which cluster owns
+  which verb; the catalog grows without adding capability.
+- **Option B (sub-sub)** would be the first two-level dispatcher in
+  the repo. Cost: contract change in `command-clusters.md`,
+  linter change in `lint_no_new_atomic_commands.py` (parse a second
+  column), pattern-checker change in `check_cluster_patterns.py`
+  (allow nested dispatch sections), plus an ADR to set the precedent
+  — for a cohesion benefit that Option D delivers at zero
+  architectural cost.
+- **Option C (no verb)** breaks symmetry: `/roadmap:create` is a
+  verb, `/roadmap:phase` is a scope. The mental model becomes
+  inconsistent in the same cluster.
+- **Option D (composite verb-scope)** keeps the cluster flat, keeps
+  the verb visible, costs nothing in the linter or contract
+  parser (one row, four sub-names, kebab-case as before), and
+  scales to any future verb+scope cluster.
+
+The colon form was already canonical for flag-clusters
+(`/commit:in-chunks`, `/create-pr:description-only`). Promoting it
+to the canonical form for dispatcher-clusters too unifies the
+catalog: every sub-command is a single token.
+
+## Consequences
+
+- **Pro:** Zero architectural cost. The locked contract, both
+  linters, the dispatcher pattern checker, and the routing rule all
+  keep working unchanged. The cluster row in
+  `docs/contracts/command-clusters.md` extends with three new
+  sub-names.
+- **Pro:** Single-token autocompletion across the entire command
+  surface. Greppable in chat history and logs.
+- **Pro:** Domain cohesion — `/roadmap:*` covers the full
+  authoring + execution lifecycle.
+- **Con:** Sub-names get longer when the verb is non-obvious from the
+  cluster. `/roadmap:process-phase` is 24 chars vs.
+  `/roadmap-process:phase` (Option A, 23 chars) or
+  `/roadmap:phase` (Option C, 16 chars). Acceptable trade for
+  symmetry and zero contract churn.
+- **Con:** A cluster cannot grow into a true two-level surface
+  without revisiting this ADR. Rolling back to Option B is the
+  escape hatch if a future cluster genuinely needs nested verbs.
+
+## Rollback
+
+If a future cluster grows past ~8 sibling sub-commands and the
+composite-name pattern produces ambiguous or unreadable
+sub-commands, revisit by:
+
+1. Splitting the cluster into two flat clusters (Option A on a
+   case-by-case basis), or
+2. Introducing sub-sub-commands as a deliberate contract change —
+   updating `command-clusters.md`, `lint_no_new_atomic_commands.py`,
+   `check_cluster_patterns.py`, and superseding this ADR.
+
+Both moves are reversible. This ADR locks the default, not the
+ceiling.
+
+## See also
+
+- [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md)
+  — locked cluster set + sub-command naming contract.
+- [`.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md`](../../.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
+  — runtime routing semantics and the colon-canonical rule.
+- [`.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md`](../../.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md)
+  — the shared mechanics that motivated the cluster shape.

package/docs/decisions/ADR-rule-kernel-and-router.md

@@ -0,0 +1,122 @@
+# ADR — Rule Kernel and Router (Roadmap Closure)
+
+- **Status:** Accepted (2026-05-06)
+- **Closes:** `agents/roadmaps/road-to-kernel-and-router.md`
+- **Sibling roadmaps closed in the same window:**
+  `agents/roadmaps/road-to-token-optimization.md`
+  (Phase 1 shipped, Phase 2/3 deferred-with-trigger by design),
+  `agents/roadmaps/road-to-package-optimization.md`
+  (closed with null result per P1.1 binary acceptance gate).
+- **Related ADRs:** ADR-001 (kernel-swap deferred), ADR-002
+  (kernel-bucket cap raise 25k → 26k, per-rule Iron-Law overrides).
+
+## Context
+
+The agent rule set was an "always-loaded" surface: every conversation
+paid the full 193k-char rule cost regardless of task. There was no
+deterministic way to load only the policy actually relevant to the
+current intent, and no mechanical guard against rule-bucket creep.
+
+## Decision
+
+Adopt a **Kernel + Router** loading model with three tiers and three
+cost profiles, governed by a compiled router manifest and CI-enforced
+size budgets.
+
+### What shipped
+
+- **Kernel:** 9 always-loaded Iron-Law rules (`agent-authority`,
+  `ask-when-uncertain`, `commit-policy`, `direct-answers`,
+  `language-and-tone`, `no-cheap-questions`,
+  `non-destructive-by-default`, `scope-control`,
+  `verify-before-complete`). Locked set:
+  [`docs/contracts/kernel-membership.md`](../contracts/kernel-membership.md).
+- **Router:** `router.json` compiled deterministically from rule
+  frontmatter (`tier:`, `triggers:`, `routes_to:`) by
+  `scripts/compile_router.py`. Contract:
+  [`docs/contracts/rule-router.md`](../contracts/rule-router.md).
+- **Cost profiles:** `minimal` = kernel only · `balanced` = kernel +
+  tier-1 (default) · `full` = kernel + tier-1 + tier-2.
+- **Budget gates:** `task lint-rule-budget` enforces kernel ≤ 26k chars
+  and per-rule ≤ 2.5k (Iron-Law overrides up to 4.0k via ADR-002).
+  Daily snapshots in `agents/.rule-budget-history.jsonl`.
+- **Compression discipline:** P4.3 brought the auto-bucket from
+  ~75k → 59 220 chars (under the 60k target) without behaviour drift.
+
+### What we cut
+
+- **P4.1 / P4.2** — auto-rule → skill / guideline migrations.
+  Cancelled as scope-cut after P4.3 compression alone landed the
+  auto-bucket under target. The migrations were a means, not an end.
+- **road-to-package-optimization Phase 1.2 / 1.3 / Phase 2 / Phase 3**
+  — cancelled per P1.1's binary acceptance gate. The prototype
+  contradiction linter scanned 317 artefacts in 0.034 s and flagged
+  zero cross-artefact contradictions. The artefact surface is
+  empirically already well-governed on the heuristics tested; building
+  a production linter for a non-existent failure mode is not honest.
+- **road-to-token-optimization Phase 2 / Phase 3** — *not* cut, just
+  trigger-deferred by design (telemetry threshold + `/cost:report`
+  ship). Will reopen autonomously when their declared signals fire.
+
+### What stayed
+
+- All Iron-Law fences. SHA-verified preserved by
+  `scripts/iron_law_sha.py` across the kernel compression pass.
+- Behaviour parity. Golden transcripts pass under all three profiles.
+- The pre-existing `auto`-tier rules; only their compressed bodies
+  changed, never their obligation surface.
+
+## Profile semantics
+
+| Profile | Buckets loaded | Use case |
+|---|---|---|
+| `minimal` | kernel only | Tightly bounded automation, CLI shell-outs, "run this one command" |
+| `balanced` *(default)* | kernel + tier-1 | Day-to-day engineering work; matches pre-roadmap behaviour superset |
+| `full` | kernel + tier-1 + tier-2 | Architectural / cross-wing / governance sessions |
+
+Consumer projects opt in via `personal.cost_profile` in
+`.agent-settings.yml`. The install script keeps user-set values; only
+the template default is `balanced`.
+
+## Reversibility
+
+If the Kernel + Router model needs unwinding:
+
+1. Set every rule's frontmatter `tier:` to `kernel` and rebuild
+   `router.json` — every rule loads on every turn (legacy behaviour).
+2. Drop `lint-rule-budget` from `task ci`.
+3. The compiled `router.json` is a derived artefact; deleting it and
+   running `compile_router.py --no-router` returns the always-loaded
+   model.
+
+No data migration, no irreversible compression. Iron-Law SHA fences
+mean Iron Laws can be diffed against the pre-roadmap baseline at any
+point.
+
+## Final measurements (2026-05-06)
+
+| Metric | Pre-roadmap | Post-roadmap | Δ |
+|---|---:|---:|---:|
+| kernel bucket | n/a (always-loaded) | 25 590 | new gate |
+| auto bucket | ~75 000 | 59 220 | −21 % |
+| total rule chars | ~193 000 | 84 810 | −56 % |
+| rule count | 56 | 57 (added `token-optimizer-maintenance`) | +1 |
+| skills count | 134 | 135 (added `token-optimizer`) | +1 |
+
+Kernel-bucket-check: PASS. Per-rule cap: 16 rules over 2.5k target,
+all within 4.0k Iron-Law override per ADR-002. Trend snapshot
+appended to `agents/.rule-budget-history.jsonl`.
+
+## Consequences
+
+- New rule submissions must declare `tier:` + `triggers:` + (when
+  applicable) `routes_to:` in frontmatter; the router compiler
+  rejects malformed entries.
+- Editing Iron-Law-fenced bodies requires a fresh
+  `scripts/iron_law_sha.py --update` pass; CI fails on hash drift.
+- The `token-optimizer` skill is now the single consult surface for
+  token-cost decisions; editing any cited asset requires a same-commit
+  catalog update per `token-optimizer-maintenance` rule (CI-backstopped
+  by `scripts/check_token_optimizer_freshness.py`).
+- Deferred phases (token-opt P2/P3, kernel-swap from ADR-001) remain
+  reopenable on their declared triggers without further roadmap work.

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 56 rules. No configuration needed.
+This is enforced automatically by 59 rules. No configuration needed.
 
 ---
 
@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 94 active commands](../.agent-src/commands/)
+→ [Browse all 95 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/naming.md

@@ -41,7 +41,7 @@ source: package
 | Pattern | When | Examples |
 |---|---|---|
 | `{verb}-{target}` | Action commands | `create-pr`, `fix-ci`, `commit` |
-| `{target}-{verb}` | Target-first grouping | `roadmap-create`, `roadmap-execute` |
+| `{target}-{verb}` | Target-first grouping | `roadmap-create` (legacy atomic; current cluster form is `/roadmap:create` and `/roadmap:process-step|phase|full`) |
 | `{scope}-{action}` | Scoped actions | `optimize-agents`, `review-changes` |
 
 ### Guidelines

package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -0,0 +1,176 @@
+# Roadmap Progress Sync
+
+> Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response
+
+_Origin: migrated from `.agent-src.uncompressed/rules/roadmap-progress-sync.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+<!-- cloud_safe: degrade -->
+<!-- Authoring discipline applies in cloud; local script + regen are no-ops there. -->
+
+# Roadmap Progress Sync
+
+> **Enforced by:** [`scripts/roadmap_progress_hook.py`](../../scripts/roadmap_progress_hook.py)
+> on Augment + Claude Code (`PostToolUse`). Hook is primary; the prose
+> below is the specification the hook implements and the fallback when
+> the platform has no hook surface.
+
+## Iron Law — dashboard sync
+
+```
+ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
+NO EXCEPTIONS. NO "I'LL DO IT AT THE END". NO BATCHING ACROSS TURNS.
+A ROADMAP NOT IN THE DASHBOARD IS A RULE VIOLATION, NOT AN OVERSIGHT.
+```
+
+**Roadmap touch =** create the file, rename it, delete it, move it
+between `roadmaps/` ↔ `archive/` ↔ `skipped/`, add/rename/remove a
+phase, **OR** flip any checkbox (`[ ]` ↔ `[x]` ↔ `[~]` ↔ `[-]`).
+
+`agents/roadmaps-progress.md` is the read-only dashboard. Every
+unsynced edit makes it lie to the next reader. Created a roadmap
+without regenerating? The dashboard claims it does not exist. Marked
+8 steps `[x]` and forgot the regen? The dashboard says 0 done.
+
+## Iron Law — every active roadmap is trackable
+
+```
+EVERY ACTIVE ROADMAP MUST CONTAIN AT LEAST ONE TRACKABLE CHECKBOX
+(`- [ ]`) PER NON-INTRO PHASE. ROADMAPS WITHOUT EXECUTABLE STEPS
+EITHER GET A CHECKLIST OR THE `status: draft` FLAG.
+CI-ENFORCED: `scripts/check_roadmap_trackable.py` (CANNOT BE DEFERRED).
+```
+
+**Active roadmap =** any file in `agents/roadmaps/` (root, not
+`archive/` or `skipped/`) without `status: draft` frontmatter.
+
+**Trackable checkbox =** an actionable `- [ ]` line under a `## Phase N`
+or `### Phase N` heading (numeric `Phase 1`, roman `Phase II`, or
+letter-track `Phase A1` — matched by the dashboard's `PHASE_RE`).
+Tables of decisions, ICE matrices, ADR captures, and "block
+sequencing" tables are valid **rationale**, but they do not satisfy
+this rule on their own — they must be paired with at least one
+`## Phase N` section whose checkboxes execute the decision.
+Headings such as `## Phase steps`, `### Sequencing — Phase 1 …`,
+`### P0 #1 — …`, or `## Block A` do **not** count — only the
+canonical `Phase <id>` form parsed by the dashboard.
+
+**CI backstop.** `scripts/check_roadmap_trackable.py` (package-shipped,
+wire into the consumer's pre-commit / pre-push / Actions gate) fails
+when an active roadmap has zero canonical `Phase` headings or when
+any parsed phase has zero checkboxes. Last line of defence — real-time
+authoring still flips checkboxes and regenerates the dashboard the
+same response.
+
+## Status — binary `ready` (default) vs `draft`
+
+```yaml
+---
+status: draft          # hidden from the dashboard until flipped
+---
+```
+
+Two values, no synonyms. Anything else — no frontmatter at all,
+`status: ready`, an unknown value — counts as **ready** and lands
+in the dashboard.
+
+- **Ready** is the implicit default. New roadmaps are created
+  ready unless the user explicitly says draft. Ready roadmaps are
+  listed in the dashboard, count towards open/done totals, and
+  trip the "completed but not archived" warning when they close.
+- **Draft** hides the file from the dashboard entirely (not
+  counted, not listed). Use it while the roadmap is still being
+  authored, while waiting for upstream decisions, or as a
+  capture-only synthesis that has not yet been promoted to
+  executable phases. Flip to ready (or remove the field) the
+  moment the roadmap is ready to track.
+
+**Completion = archival, same response.** When the edit takes a
+roadmap to `count_open == 0` (every item is `[x]`, `[~]`, or `[-]`),
+`git mv` it into `agents/roadmaps/archive/` (or `skipped/` if no `[x]`
+at all) **before** regenerating the dashboard. A 100%-complete
+roadmap left under `agents/roadmaps/` is a rule violation, not an
+optional cleanup. See `roadmap-management` skill for the archive vs
+skipped decision table.
+
+## Agent-authored roadmaps — placement is mandatory
+
+```
+A FILE THE AGENT DROPS INTO agents/roadmaps/ MUST EITHER
+(a) PASS check_roadmap_trackable.py AND LAND IN THE DASHBOARD, OR
+(b) NOT BE IN agents/roadmaps/ AT ALL.
+NO "DECISION MATRIX" / "DESIGN NOTE" SHORTCUT.
+```
+
+When the agent autonomously creates a roadmap, it owns the placement
+in the **same response**:
+
+- **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
+- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/contexts/<name>.md`.
+- **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
+
+A non-trackable file in `agents/roadmaps/` is a rule violation — the
+trackable CI fails it, the dashboard hides it. The agent that
+created it moves it the same response. If the autonomous run also
+**finishes** the roadmap within the session (every box `[x]`/`[~]`/`[-]`),
+the completion-archival rule above fires too — same response.
+
+## Autonomous execution — checkbox cadence
+
+When executing a roadmap autonomously (multi-turn, no per-step user
+prompt), the user loses progress visibility unless checkboxes flip
+**as work lands**, not in a batch at the end. Iron Law:
+
+```
+EVERY DONE STEP FLIPS [ ] → [x] IN NEXT REPLY THAT ACKNOWLEDGES IT.
+NO "I UPDATE ROADMAP AT END OF PHASE."
+NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
+```
+
+Step counts as completed when:
+
+- Code / docs change for that step has been **written and saved** AND
+- Verification cited in the step (project CI command, targeted test, lint) has
+  **passed in this response or an earlier one** — fresh output, not memory.
+
+Then in the **same reply**: flip the checkbox, regenerate the
+dashboard, commit if commit policy allows.
+
+**Forbidden:** four turns of step work, dashboard flat, single regen at the end.
+**Required:** each turn — implement step, flip `[x]`, regen, commit (if policy allows).
+A reply that lands a verified step without flipping its checkbox is a rule violation.
+
+**In-progress marker:** when a step takes more than one reply,
+mark it `[~]` the moment work starts on it and regenerate. The
+user sees one row move from `[ ]` to `[~]` to `[x]` instead of
+silent rows. `[~]` is treated as open for `count_open` but moves
+the phase percentage forward in the dashboard.
+
+## Mechanics — triggers, regen command, self-check, failures
+
+The triggers table, the regen command (`./agent-config roadmap:progress`),
+the mandatory pre-send self-check, the failure-mode catalog, and the
+`Do NOT` list live in
+[`contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md`](../contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md).
+Pull it whenever a trigger fires — the rule above is the obligation
+surface; the mechanics file is the lookup material.
+
+## Copilot fallback
+
+GitHub Copilot has no `PostToolUse` hook surface, so
+`scripts/roadmap_progress_hook.py` cannot detect roadmap-file writes
+structurally. The dashboard at `agents/roadmaps-progress.md` will
+not regenerate on its own.
+
+The cooperative path: every time a roadmap touch fires (per the
+trigger list in the mechanics context above), the agent regenerates
+the dashboard in the same response — which is the same Iron Law the
+hook enforces, just executed manually:
+
+```bash
+./agent-config roadmap:progress
+```
+
+The hook implementation is the specification; on Copilot the agent
+runs the regenerator itself after the same triggers fire. Skipping
+it is a rule violation, not a hook gap — the Iron Law on dashboard
+sync survives the missing hook surface.

package/docs/guidelines/agent-infra/rule-type-governance.md

@@ -0,0 +1,73 @@
+# Rule Type Governance
+
+> Creating or editing rules, or auditing rule types — decides when a rule should be always vs auto
+
+_Origin: migrated from `.agent-src.uncompressed/rules/rule-type-governance.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# rule-type-governance
+
+## `always` = loaded every conversation
+
+Use ONLY when the rule applies to virtually every interaction:
+
+- Universal agent behavior (language, tone, interaction style)
+- Safety constraints (scope control, verification before completion)
+- Token/efficiency constraints
+- First-message checks that cannot wait for auto-trigger
+
+## `auto` = loaded on demand by description match
+
+Use for everything else:
+
+- Language-specific rules (PHP, JS, SQL)
+- Tool-specific rules (Docker, Git, quality tools)
+- Workflow-specific rules (commands, skill creation, E2E testing)
+- Domain-specific rules (translations, architecture)
+
+## Decision test
+
+> "Does this rule need to be active when the user asks a simple question, reviews a PR, or discusses architecture?"
+
+- Yes → `always`
+- No → `auto` with a clear trigger description
+
+## Auto description quality
+
+The `description` field IS the trigger. It must describe **when** the rule applies, not **what** it contains.
+
+- ❌  `"PHP coding standards"` — too vague, won't match reliably
+- ✅  `"Writing or reviewing PHP code — strict types, naming, Eloquent conventions"`
+
+## Hard constraint
+
+- Default to `auto`. Justify `always`.
+- If >50% of conversations don't need a rule → it must be `auto`.
+- `optimize-agents` command checks this and suggests changes.
+
+## Hardening tier — required on new or edited rules
+
+Every new rule, and every edited rule whose body changes the trigger
+or the obligation, MUST classify itself against the hardening tiers
+documented in [`rule-trigger-matrix.md`](../../agents/contexts/rule-trigger-matrix.md):
+
+| Tier | Meaning |
+|---|---|
+| `1` | Mechanically enforceable — hook acts, rule body stays minimal. |
+| `2a` | Marker nudge — hook injects signal, agent acts on it. |
+| `2b` | Structured injection / tool-call gate — hook reads/writes state, may deny. |
+| `3` | Soft, judgment-bound — no platform surface; self-check rule. |
+| `safety-floor` | Iron-Law subset, never modified. |
+| `mechanical-already` | Precedent — script enforces, rule body documents. |
+
+Classification surface: the optional `tier:` frontmatter field
+(declared in `scripts/schemas/rule.schema.json`). Recommended for new
+rules; bulk-retrofit of existing rules is tracked separately.
+
+Tier 3 dispositions are recorded centrally in
+[`agents/contexts/tier-3-dispositions.md`](../../agents/contexts/tier-3-dispositions.md)
+with a 6-month re-audit clock. New Tier 3 rules append to that list
+on landing.
+
+The `optimize-agents` command checks the tier alongside `type`/`source`
+and suggests escalations when a rule's trigger matches a hardening
+opportunity that has shipped since the rule was authored.

package/docs/guidelines/agent-infra/size-and-scope.md

@@ -33,6 +33,11 @@ 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.
+
 Reason:
 - Loaded frequently
 - Must be reliably followed
@@ -43,8 +48,10 @@ Reason:
 ## Skills
 
 - Target: **300–900 words**
-- Warning: **>1200 words**
-- Strong split signal: **>1500 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
 
 Focus:
 - scanability
@@ -57,6 +64,10 @@ 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).
 
 Commands orchestrate — not implement.