@event4u/agent-config 1.16.0 → 1.17.0

package/.agent-src/contexts/communication/rules-auto/review-routing-awareness-mechanics.md

@@ -0,0 +1,65 @@
+# Review Routing Awareness — mechanics
+
+Memory-lookup snippet, "do NOT overreach" guardrails, and anti-pattern
+catalog for the
+[`review-routing-awareness`](../../../rules/review-routing-awareness.md)
+rule. The four required-behavior steps and the "when this rule applies"
+trigger live in the rule; this file is the lookup material for the
+fallback path and the failure-mode list.
+
+## Memory-lookup fallback
+
+If neither `.github/ownership-map.yml` (or `agents/ownership-map.yml`)
+nor `.github/historical-bug-patterns.yml` (or
+`agents/historical-bug-patterns.yml`) exists, fall back to the
+engineering-memory layer via
+[`memory-access`](../../../../docs/guidelines/agent-infra/memory-access.md):
+
+```python
+from scripts.memory_lookup import retrieve
+extra = retrieve(
+    types=["ownership", "historical-patterns"],
+    keys=<changed file paths>,
+    limit=5,
+)
+```
+
+Curated memory (`agents/memory/ownership.yml`,
+`agents/memory/historical-patterns.yml`) carries the same schema as the
+project-local YAMLs and is merged into the routing output alongside
+them. If both memory and project YAMLs are absent, skip the rule and
+rely on [`reviewer-awareness`](../../../rules/reviewer-awareness.md)
+defaults. **Do not invent owners or patterns** from context.
+
+## Surface findings — worked examples
+
+When producing a review plan, include:
+
+- **Owner-mapped roles** — explicitly preferred over generic roles. If
+  the ownership map says `app/Billing/**` is owned by `finance-engineering
+  + security`, use those, not "backend + security".
+- **Historical-pattern warnings** — list every matched pattern with a
+  short label and the required control, e.g. _"Pattern: N+1 on tenant
+  listings → add an eager-load regression test"_.
+- **Confidence note** — if the ownership map is stale (last updated > 6
+  months ago per the `updated` field), say so. Ownership maps rot.
+
+## Do NOT overreach
+
+- **Never rename paths** or add ownership entries as a side effect of a
+  code change. Ownership map edits are a separate, explicit task.
+- **Never mark a change safe** only because no pattern matched. Pattern
+  absence means "no known hit", not "no risk".
+- **Never copy historical-pattern names into the diff** as code comments
+  or commit messages — they are routing metadata, not commentary.
+
+## Anti-patterns — reject them
+
+- Suggesting owners "because this looks like billing code" without
+  consulting the ownership map when one exists.
+- Inventing historical patterns from general knowledge — patterns must
+  come from the project's own registry.
+- Downgrading a matched high-severity pattern because "the author said
+  it's fine" — the pattern was registered because it bit before.
+- Treating an out-of-date map as absent. Flag staleness; do not silently
+  skip.

package/.agent-src/contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md

@@ -0,0 +1,78 @@
+# Roadmap Progress Sync — mechanics
+
+Mechanics, triggers, and failure-mode catalog for the
+[`roadmap-progress-sync`](../../../rules/roadmap-progress-sync.md)
+rule. The Iron Laws and status semantics live in the rule; this
+file holds the lookup material the rule pulls when a trigger fires.
+
+## How to regenerate
+
+```bash
+./agent-config roadmap:progress
+```
+
+The `./agent-config` wrapper is written into the project root by the
+package installer and delegates to the master CLI inside
+`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
+No global tooling required.
+
+## Triggers
+
+| Edit | Must run, same response |
+|---|---|
+| **Create a new roadmap file** | regenerate dashboard |
+| **Rename or delete a roadmap file** | regenerate dashboard |
+| Mark step `[x]`, `[~]`, `[-]`, or unmark back to `[ ]` | regenerate dashboard |
+| Add, rename, or remove a phase | regenerate dashboard |
+| **Last `[ ]` flips** — roadmap reaches `count_open == 0` | `git mv` → `archive/` (or `skipped/`) **then** regenerate dashboard |
+| Move roadmap between `roadmaps/` ↔ `archive/` ↔ `skipped/` | regenerate dashboard |
+
+**Batching rule:** if you edit multiple checkboxes in one response, a
+**single** regeneration at the end of that response is enough — but
+the response must not end without it. If one of those edits closes a
+roadmap, archive it first, then run the single regen.
+
+## Pre-send self-check — MANDATORY
+
+Before sending any reply that touched `agents/roadmaps/`, run this
+silent gate:
+
+1. Did this turn create, rename, delete, or move a roadmap file? → regen MUST be in the reply.
+2. Did this turn flip any checkbox in a roadmap file? → regen MUST be in the reply.
+3. Did the regen output (`✅ Wrote agents/roadmaps-progress.md · …`) actually appear this turn? → if no, run it now before sending.
+4. **Autonomous roadmap execution gate** — did this turn complete a roadmap step (code saved + verification passed) without flipping its checkbox? → flip `[x]` (or `[~]` if multi-turn) and regen before sending.
+5. **Trackable-roadmap gate** — did this turn create or substantially edit a roadmap file? → does it now contain at least one `- [ ]` per non-intro phase, **or** carry `status: draft` in frontmatter? → if neither, add the checklist or the draft flag before sending.
+
+Any "yes" + no regen run = rule violation. Rerun before sending.
+
+## Failure modes
+
+- **Created the roadmap, marked Phase 1 done across multiple turns,
+  never regenerated** — dashboard silently lies "this roadmap does
+  not exist" to the next reader. Canonical failure of this rule;
+  the rule was hardened in response to it.
+- **Regenerated yesterday, edited today, "I'll regen at session
+  end"** — session ends from a crash, regen never lands.
+- **Closed a roadmap (last `[ ]` → `[x]`) and regenerated before
+  `git mv`** — the closed roadmap reappears in "Open roadmaps".
+- **Edited the dashboard by hand to "fix it quickly"** — next regen
+  overwrites the manual edit; no audit trail of why.
+- **Autonomous run, four steps shipped across four turns, dashboard
+  flat the whole time, single regen at the end** — user lost
+  progress visibility for the entire run. Each completed step must
+  flip its checkbox in the reply that ships it.
+- **Decision-only roadmap shipped without checkboxes** — file
+  contains decisions / ICE / block-sequencing but zero `- [ ]`,
+  dashboard shows `0/0` or omits it. Pair with a `## Phase N`
+  section or mark `status: draft` (CI catches this now).
+- **Headings off-canon (`### P0 #N`, `## Block A`, `### Sequencing
+  — Phase 1`)** — `PHASE_RE` skips them, roadmap invisible to the
+  dashboard. Rename to `## Phase <id>` or mark `status: draft`.
+
+## Do NOT
+
+- Do NOT edit `agents/roadmaps-progress.md` by hand — always regenerate.
+- Do NOT defer the regen to "next commit" or "before push" — same response.
+- Do NOT rely on CI (`--check` mode) as the first line of defence — CI is last-line, not real-time.
+- Do NOT skip the regen because "only one checkbox changed" — the dashboard aggregates counts and phase percentages that shift on single edits.
+- Do NOT leave a 100%-complete roadmap in `agents/roadmaps/` "for review" — `git mv` to archive **before** regenerating, otherwise it reappears in "Open roadmaps".

package/.agent-src/contexts/communication/rules-auto/skill-quality-mechanics.md

@@ -0,0 +1,62 @@
+# Skill quality — mechanics
+
+Description-triggering recipe, merge-preservation invariants, and
+compression-preservation invariants for the
+[`skill-quality`](../../../rules/skill-quality.md) rule. The minimum
+sharpness table, required sections, frontmatter contract, the
+skill-independence Iron Law, and the refactor-safety NEVER list live
+in the rule; this file is the lookup material when authoring or
+refactoring a skill.
+
+## Description Triggering
+
+Claude routes skills by reading the frontmatter `description`. Polite, generic,
+or hedged descriptions cause **undertriggering** — the skill never loads when it
+should, and the user never learns it exists.
+
+Make descriptions "pushy" — explicit about when to fire:
+
+- Start with a concrete verb phrase: `Use when ...`, `Creates ...`, `Reviews ...`.
+- Name 2+ concrete triggers — domains, symptoms, file types, user phrasing.
+- End with: `... even if they don't explicitly ask for \`<skill-name>\`.`
+- Avoid hedges: `may help with`, `can be useful for`, `covers various`.
+- **Keep it ≤ 200 characters.** `scripts/skill_linter.py` warns at
+  `description_too_long` above this. If the pushy tail pushes you over, cut
+  adjectives, drop the second example phrasing, or collapse a list — do
+  **not** drop the trigger vocabulary or the `even if ...` tail.
+
+Source: [`skills/skill-creator` in `anthropics/skills`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md).
+
+**Litmus test:** Read the description cold, without the skill's body. If you
+cannot name at least two phrasings a user would realistically type that should
+route to this skill, the description is too polite. Rewrite it.
+
+## Merge Preservation
+
+When merging or refactoring skills, the merged result MUST preserve:
+
+1. **Strongest validation** from each source skill
+2. **Strongest example** (good/bad contrast) from each source
+3. **Strongest anti-pattern** from each source
+4. **All concrete decision criteria** that differ between sources
+
+A merge is invalid if:
+- Validation got weaker than the strongest source
+- Examples were lost without replacement
+- Anti-pattern coverage decreased
+- The merged skill became a generic umbrella doc
+
+## Compression Preservation
+
+When compressing a skill, the compressed version MUST preserve:
+
+- Trigger quality (description + When to use)
+- All procedure steps that contain decisions
+- All concrete validation checks
+- All gotchas and anti-patterns
+- Strongest example (at minimum one good/bad contrast)
+
+Compression may remove:
+- Verbose explanations
+- Redundant examples (keep the strongest)
+- Commentary that doesn't affect execution

package/.agent-src/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md

@@ -0,0 +1,55 @@
+# Slash-command routing — cluster mechanics
+
+Lookup table for the `slash-command-routing-policy` rule. Lists the
+locked clusters and their sub-commands so the rule itself can stay at
+its current LOC while still reflecting the full surface. Source of
+truth for the cluster names is
+[`docs/contracts/command-clusters.md`](../../../../docs/contracts/command-clusters.md);
+this file mirrors that contract for runtime lookup. Linter:
+`scripts/check_cluster_patterns.py` (verifies dispatcher shape).
+
+## Locked clusters and sub-commands
+
+| Cluster | Phase | Sub-commands | Replaces |
+|---|:-:|---|---|
+| `/fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `/fix-ci` · `/fix-pr-comments` · `/fix-pr-bot-comments` · `/fix-pr-developer-comments` · `/fix-portability` · `/fix-references` · `/fix-seeder` |
+| `/optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills` |
+| `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap` |
+| `/chat-history` | 2 | `show` · `resume` · `clear` · `checkpoint` | `/chat-history` (legacy status) · `/chat-history-resume` · `/chat-history-clear` · `/chat-history-checkpoint` |
+| `/agents` | 2 | `audit` · `cleanup` · `prepare` | `/agents-audit` · `/agents-cleanup` · `/agents-prepare` |
+| `/memory` | 2 | `add` · `load` · `promote` · `propose` | `/memory-add` · `/memory-full` · `/memory-promote` · `/propose-memory` |
+| `/roadmap` | 2 | `create` · `execute` | `/roadmap-create` · `/roadmap-execute` |
+| `/module` | 2 | `create` · `explore` | `/module-create` · `/module-explore` |
+| `/tests` | 2 | `create` · `execute` | `/tests-create` · `/tests-execute` |
+| `/context` | 2 | `create` · `refactor` | `/context-create` · `/context-refactor` |
+| `/override` | 2 | `create` · `manage` | `/override-create` · `/override-manage` |
+| `/copilot-agents` | 2 | `init` · `optimize` | `/copilot-agents-init` · `/copilot-agents-optimize` |
+| `/judge` | 2 | `solo` · `on-diff` · `steps` | `/judge` (legacy standalone) · `/do-and-judge` · `/do-in-steps` |
+| `/commit` | 2 | flag: `--in-chunks` | `/commit-in-chunks` |
+| `/create-pr` | 2 | flag: `--description-only` | `/create-pr-description` |
+
+## Routing semantics
+
+1. The user types `/<cluster> [<sub>] [args]`.
+2. Match the cluster against the table above. If the leading token is
+   a dispatcher cluster, route to the dispatcher's `commands/<cluster>.md`
+   and let the dispatcher's "Dispatch" section pick the sub-command.
+3. If the leading token is a flag-cluster (`/commit`, `/create-pr`),
+   the cluster file is the entry point itself; flags absorb the
+   former helper command.
+4. **Legacy atomic shims** (`/fix-ci`, `/agents-audit`, …) keep working
+   for one release cycle. They emit a deprecation warning and forward
+   to the cluster invocation. New invocations should always use the
+   cluster form.
+5. If a sub-command is unknown, the dispatcher prints the menu — never
+   guess.
+
+## Removal cycle
+
+| Cycle | Active form | Shim form |
+|---|---|---|
+| `1.15.x` / `1.16.x` | Phase 1 cluster commands | Phase 1 atomic shims |
+| `1.17.0` | Phase 1 + Phase 2 cluster commands | Phase 2 atomic shims (Phase 1 atomics removed) |
+| next minor after `1.17.x` | Cluster commands only | — (Phase 2 atomics removed) |
+
+Consumers see the canonical surface as the cluster form throughout.

package/.agent-src/contexts/communication/rules-auto/ui-audit-gate-mechanics.md

@@ -0,0 +1,53 @@
+# UI-audit gate — mechanics
+
+Findings-shape spec, failure-mode catalog, and cloud-surface
+adaptation for the
+[`ui-audit-gate`](../../../rules/ui-audit-gate.md) rule. The Iron
+Law, the activation triggers, the allow-list, and the action sequence
+when the gate fires live in the rule; this file is the lookup
+material when an agent has to verify what counts as findings or
+recognise a failure mode.
+
+## What "audit findings" means
+
+`state.ui_audit` is a non-empty dict carrying at least one of:
+
+- `components_found` — `{path, name, kind, similarity?}` inventory
+  entries from [`existing-ui-audit`](../../../skills/existing-ui-audit/SKILL.md).
+- `greenfield: true` plus `greenfield_decision` ∈
+  `{scaffold, bare, external_reference}`.
+- Legacy `components` alias — back-compat for the same shape.
+
+`null`, `{}`, or a dict without those keys is **not** findings;
+emit `@agent-directive: existing-ui-audit` instead of writing code.
+
+## Failure modes
+
+- Writing the component first and "thinking about reuse later".
+- Citing a similar-looking component from memory without verifying
+  it via the audit.
+- Treating `state.ui_audit = {}` as "audit ran, found nothing" —
+  empty dict is rejected on purpose; an audit that finds nothing
+  must record either ≥1 `components_found` or the greenfield branch.
+- Bypassing the gate for "just one tile".
+
+## Interactions
+
+- [`improve-before-implement`](../../../rules/improve-before-implement.md) — runs
+  first when the request is ambiguous; this rule is the next gate.
+- [`ask-when-uncertain`](../../../rules/ask-when-uncertain.md) — "just build it"
+  does **not** drop the audit; acknowledge, run audit, continue.
+- [`directives/ui/audit.py`](../../../templates/scripts/work_engine/directives/ui/audit.py)
+  — code-layer twin; this rule covers the cases where the engine
+  is not in the loop.
+- [`existing-ui-audit`](../../../skills/existing-ui-audit/SKILL.md) — the
+  skill that produces the findings.
+
+## Cloud Behavior
+
+On cloud surfaces the engine is not shipped, so `state.ui_audit`
+does not exist. The Iron Law still applies: take the visible
+inventory of files in conversation context as the audit, and
+surface a one-line audit summary in the reply before writing the
+component. The gate is satisfied by an explicit summary, not by
+silently skipping.

package/.agent-src/contexts/communication/rules-auto/user-interaction-mechanics.md

@@ -0,0 +1,77 @@
+# User Interaction — mechanics
+
+Format examples, common failure modes, progress indicators, and
+summary patterns for the [`user-interaction`](../../../rules/user-interaction.md)
+rule. Iron Law 1 (single-source recommendation) and Iron Law 2
+(pre-send self-check) live in the rule; this file is the lookup
+material for the format details.
+
+## Common failure modes — known, named, no excuses
+
+- **End-of-turn menu skipped.** Reply answers the question fine, then ends with `> 1. Foo > 2. Bar > 3. Stop` and no `Empfehlung:`. Iron Law 1 was violated — these are numbered options, position is irrelevant.
+- **"Genuinely no preference" hedge.** Pick anyway. The agent has more context than the user on the trade-off; refusing to pick dumps the work back. Pick the safest option, name the flip-condition.
+- **"User knows the project better" hedge.** Same failure mode, different costume. The user asked for an opinion by virtue of accepting the options block; deliver it.
+- **Multi-block reply with one recommendation.** Two options blocks but only one `Empfehlung:` line — the second block is unguarded. Rule 5 of Iron Law 2 closes this.
+
+## Examples
+
+**Binary choice:**
+
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+
+**Recommendation: 1 — Interactive** — the comments touch security-sensitive code,
+so a wrong auto-fix is more expensive than approving each one. Caveat: flip to 2
+if the comments turn out to be pure formatting.
+```
+
+**Multiple choice with skip:**
+
+```
+> 1. Fix the code
+> 2. Fix the test
+> 3. Skip
+
+**Recommendation: 1 — Fix the code** — the test asserts the documented behaviour;
+the production code drifted from the contract. Caveat: pick 2 only if the contract
+itself is wrong.
+```
+
+**Confirmation with context:**
+
+```
+> Found PR #1399 on branch `chore/refactor-agent-setup-2`.
+>
+> 1. Yes, that's the right PR
+> 2. No, different PR — I'll provide the URL
+
+**Recommendation: 1 — Yes** — the branch name matches the PR title exactly.
+Caveat: flip to 2 if the PR was reopened from a different branch.
+```
+
+## When NOT to use numbered options
+
+- **Open-ended questions** where the answer is free text (e.g., "What should the class be named?").
+- **Simple yes/no** can use numbered options OR accept "ja"/"nein" directly.
+  Even for yes/no, prefer numbered options if there's additional context to show.
+
+## Progress Indicators
+
+When processing multiple items (e.g., review comments, test failures), show progress:
+
+```
+**Comment 3/7** — `filename.php:42`
+```
+
+## Summaries
+
+After completing a batch of actions, provide a summary table:
+
+```
+| # | File | Action |
+|---|---|---|
+| 1 | `file.php` | Fixed null check |
+| 2 | `test.php` | Updated assertion |
+| 3 | `config.php` | Skipped (intentional) |
+```

package/.agent-src/contexts/judges/no-consolidate-rationale.md

@@ -0,0 +1,102 @@
+---
+audience: maintainers
+status: stable
+stability: stable
+purpose: >
+  Locked decision rationale for Phase 3a of the
+  road-to-structural-optimization roadmap. The four `judge-*` skills
+  are intentionally **not** consolidated under a shared procedure
+  context. Future maintainers reading this file should not retry the
+  pattern without invalidating the data here.
+---
+
+# Why `judge-*` skills are NOT consolidated
+
+A Phase 3a spike evaluated extracting a shared procedure file
+(`contexts/judges/judge-shared-procedure.md`) loaded by all four
+`judge-*` skills. The locked Q1=A shape (separate skills + shared
+procedure context) was implemented and benchmarked. **Outcome: net
+LOC negative.** The pattern is rejected for this family.
+
+## The numbers
+
+Spike measurements on `judge-test-coverage` (the smallest persona,
+chosen per roadmap 3a.0):
+
+| State | Skill LOC | Shared LOC | Total per family of 4 |
+|---|---|---|---|
+| Baseline (4 separate) | 153 + 157 + 157 + 166 = **633** | 0 | 633 |
+| Slim attempt #1 | 138 | 134 | 4 × 138 + 134 = 686 ❌ |
+| Slim attempt #2 (aggressive) | 133 | 117 | 4 × 133 + 117 = 649 ❌ |
+
+The success-criteria threshold from the roadmap (≥ 30 % per-skill
+LOC reduction) maps to 153 → ≤ 107 for `judge-test-coverage`. The
+aggressive attempt landed at 133 — a 13 % reduction. To go further,
+each skill would have to surrender persona-specific content (analysis
+rubric, anti-pattern list, severity definitions, scope-boundary Do
+NOTs) — exactly the content that makes each persona reviewable.
+
+## Why the math doesn't work
+
+A judge skill is **not** procedurally complex. Its value is the
+persona surface:
+
+- a 6–11 row analysis table tailored to the lens (correctness, security,
+  test gaps, code quality)
+- a list of persona-specific anti-patterns and gotchas
+- a severity legend with thresholds calibrated to the lens
+- scope-boundary Do NOTs that route to sibling judges
+
+Procedural overhead (verdict semantics, validation scaffold,
+output-format frame, runtime boundary, model fallback) is small in
+absolute terms — extracting it adds a context file but only saves
+~15–25 LOC per skill. With four skills, the per-skill saving is
+amortized against the shared file once; below five or six skills,
+the structural tax dominates.
+
+The same argument applies to procedural duplication in any small
+skill family where the procedural skeleton is short and the persona
+table is the bulk of the file.
+
+## Decision
+
+Phase 3a is closed with status **DO NOT CONSOLIDATE**. The four
+`judge-*` skills remain separate, self-contained, and free of
+`load_context:` indirection. Each skill's "Procedure" section carries
+its full procedural body inline. This trades minor maintenance
+duplication for full persona isolation and zero structural tax.
+
+Phase 3b (`project-analysis-*`, 8 skills, 959 LOC) and Phase 3c
+(`skill-*`, 4 skills, 782 LOC) **continue independently** per the
+roadmap's "3b/3c continue independently" abort note. The math there
+is more favorable: 8 stack-specific analysis skills share a much
+larger procedural skeleton (project discovery, version resolution,
+docs loading, architecture mapping) than 4 judge skills do.
+
+## Reopening conditions
+
+Reopen this decision **only** if at least one of these holds:
+
+1. The `judge-*` family grows to ≥ 6 skills (procedural amortization
+   crosses break-even).
+2. A new persona-orthogonal procedural step is introduced that all
+   judges must execute identically (e.g. a CI-integrated verdict
+   reporter), and that step is non-trivial (≥ 30 LOC).
+3. The success-criteria threshold in
+   `road-to-structural-optimization.md` § 3a is renegotiated to a
+   lower per-skill LOC bar (with explicit justification — the 30 %
+   bar exists because anything less is structural noise).
+
+Until one of those holds, treat any "let's extract shared procedure
+across the judges" proposal as a regression and cite this file.
+
+## See also
+
+- [`persona-voice-rubric`](persona-voice-rubric.md) — the voice
+  preservation rubric used during the spike (still applies if a future
+  consolidation attempt needs the same check).
+- Sibling judges, all kept inline:
+  [`judge-bug-hunter`](../../skills/judge-bug-hunter/SKILL.md),
+  [`judge-code-quality`](../../skills/judge-code-quality/SKILL.md),
+  [`judge-security-auditor`](../../skills/judge-security-auditor/SKILL.md),
+  [`judge-test-coverage`](../../skills/judge-test-coverage/SKILL.md).

package/.agent-src/contexts/judges/persona-voice-rubric.md

@@ -0,0 +1,140 @@
+---
+stability: beta
+---
+
+# Persona-Voice Rubric for `judge-*` Skills
+
+> **Audience:** authors and reviewers of any future `judge-*`
+> consolidation spike. Also loaded via `load_context:` by future
+> `judge-*` slim shapes when an A-shape ships.
+
+This rubric defines **what "persona voice" means** for the four
+`judge-*` skills (`judge-bug-hunter`, `judge-code-quality`,
+`judge-security-auditor`, `judge-test-coverage`) and **how to score
+voice preservation** when comparing a slimmed (Option-A: separate skill
++ shared procedure context) output against the current single-file
+baseline. The rubric is the measurement instrument behind the 3a.0.1
+voice gate (≥ 4.0/5) and the 0.5 author + 2-reviewer protocol (avg ≥
+3.5/5).
+
+## The five dimensions
+
+Each dimension scored independently on a 1–5 integer scale. Scorers
+record one numeric score plus one short rationale per dimension.
+
+### 1. Tone
+
+The judge's posture toward the diff. Distinctive markers per persona:
+
+| Skill | Tone marker |
+|---|---|
+| `judge-bug-hunter` | Skeptical, edge-case-first ("what input breaks this?") |
+| `judge-code-quality` | Reformist, convention-bound ("this clashes with the codebase pattern at X") |
+| `judge-security-auditor` | Adversarial, threat-modeling ("what would an attacker do here?") |
+| `judge-test-coverage` | Falsification-first ("does this test fail without the fix?") |
+
+Score 5 = posture indistinguishable from baseline. Score 1 = generic
+"reviewer voice" with no persona signal.
+
+### 2. Vocabulary
+
+Domain-specific terms the persona reaches for unprompted. Captured by
+keyword profile from the baseline SKILL.md (e.g., `judge-security-auditor`
+uses *trust boundary*, *sink*, *SSRF*, *mass assignment*;
+`judge-test-coverage` uses *uncovered branch*, *over-mocking*,
+*regression test*, *tautological assertion*).
+
+Score 5 = ≥ 80% of baseline keyword profile present in slimmed output
+on a representative diff. Score 1 = < 20% present, or vocabulary leaks
+in from a sibling persona (collision marker — see § 5 below).
+
+### 3. Prompt-shape preservation
+
+The structural skeleton of the output (Verdict, Issues, Severity,
+Required fields). Must match the baseline `Output format` block
+verbatim in field order, label spelling, and severity icon set.
+
+Score 5 = byte-identical field structure (only finding content
+differs). Score 3 = minor reorder, no missing fields. Score 1 = a
+required field dropped, renamed, or merged.
+
+### 4. Refusal patterns
+
+How the judge handles out-of-scope concerns. Each `judge-*` baseline
+explicitly **refuses** to comment on dimensions another judge owns
+(e.g., `judge-test-coverage` refuses to flag correctness or style;
+`judge-security-auditor` refuses to flag pure logic bugs).
+
+Score 5 = refusal triggers fire on the same out-of-scope inputs as
+baseline, with the same handoff phrasing ("route to `judge-X`"). Score
+1 = persona accepts an out-of-scope finding silently (mode-collision
+risk realized).
+
+### 5. Evidence-citation style
+
+How findings are anchored to the diff. Baselines all cite `path:LINE`
+with a one-line reason and (where applicable) a "what the test should
+assert" / "what the attacker would do" clause.
+
+Score 5 = every finding has the same citation shape as baseline —
+`path:LINE` plus the persona-specific clause (uncovered branch /
+threat class / pattern violated / failing input). Score 1 = findings
+are vague ("there's a problem in the validator") or use a sibling
+persona's citation shape.
+
+## Scoring template
+
+For each scored output, fill out the matrix below — once per scorer
+(author + 2 reviewers, see scoring protocol):
+
+```
+Skill under test:  judge-<persona>
+Diff sample id:    <pr-number-or-fixture-id>
+Baseline output:   <attached or hash>
+Slimmed output:    <attached or hash>
+
+| Dimension                  | Score (1–5) | Rationale (≤ 30 words)         |
+|----------------------------|-------------|--------------------------------|
+| 1. Tone                    |             |                                |
+| 2. Vocabulary              |             |                                |
+| 3. Prompt-shape preservation |           |                                |
+| 4. Refusal patterns        |             |                                |
+| 5. Evidence-citation style |             |                                |
+| **Per-scorer mean**        |             | (sum / 5, one decimal)         |
+```
+
+## Acceptance arithmetic
+
+Three independent scorers produce three per-scorer means. The 3a.0.1
+gate fires on **two** thresholds simultaneously:
+
+- **Aggregate mean** (all dimensions, all scorers) **≥ 3.5/5** —
+  matches the 0.5.1 protocol.
+- **Tone dimension specifically** mean **≥ 4.0/5** — matches the
+  3a.0.1 voice-preservation kill-criterion. Tone is the load-bearing
+  dimension; vocabulary, prompt-shape, and citation style mostly track
+  it.
+
+Either threshold missed → escalate to council per 0.5.1 (any
+individual scorer < 3.0 also escalates). Council either revises the
+slim shape (one rework only) or invokes the 3a.0.2 abort branch and
+files `contexts/judges/no-consolidate-rationale.md`.
+
+## What this rubric does NOT measure
+
+- **Verdict parity** — covered separately by 3a.3 (cosine-token
+  similarity ≤ 10% drift, 100% verdict parity).
+- **Latency budget** — covered by 3a.0.1 (≤ +50ms vs. baseline).
+- **Mode-collision proxy** — explicit security-only-diff probe under
+  3a.0.1. Failure here aborts 3a regardless of voice score.
+- **Implementation correctness** — judges read diffs, this rubric
+  reads judges. The diff under test is a fixture, not the artefact
+  graded.
+
+## References
+
+- [`docs/contracts/context-paths.md`](../../../docs/contracts/context-paths.md)
+  — locked path tree (this file lives at `contexts/judges/`).
+- [`docs/contracts/load-context-schema.md`](../../../docs/contracts/load-context-schema.md)
+  — frontmatter contract for citing this rubric from a slimmed `judge-*`
+  skill in Phase 3a.2.