@event4u/agent-config 1.33.0 → 1.34.0

package/docs/contracts/persona-schema.md

@@ -0,0 +1,136 @@
+---
+stability: beta
+---
+
+# Persona Schema — two-tier (Core / Specialist)
+
+> **Status:** active · **Stability:** beta · **Owner:** road-to-better-skills-and-profiles Block A
+> · **Linter:** `scripts/skill_linter.py § lint_persona`
+> · **Source-of-truth dir:** `.agent-src.uncompressed/personas/`
+> · **Council verdict:** iter-1 A-OQ1 (c) — hybrid
+
+Locks the canonical persona shape: a uniform frontmatter across both
+tiers, a 5-section spine for Core, and a 7-section spine for Specialist
+(Core-5 + Critical Rules + Workflows). Existing Core personas are
+**not migrated** — the schema accepts the v1 shape that already ships.
+
+## § 1 — Frontmatter (uniform across tiers)
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `id` | string | yes | lowercase-hyphenated, must match filename stem |
+| `role` | string | yes | human-readable role name |
+| `description` | string | yes | one sentence, ≤ 160 chars |
+| `tier` | enum | yes | `core` \| `specialist` |
+| `mode` | string | optional | advisory link to a role-contract workflow mode |
+| `version` | string | yes | semver; bump on breaking changes |
+| `source` | enum | yes | `package` \| `project` |
+
+`personas:` is the consumer-side citation key (used in skill
+frontmatter); it is **not** part of a persona's own frontmatter.
+
+## § 2 — Tier definitions
+
+### `core` — always-loaded cast
+
+The six lenses every multi-lens skill leans on by default:
+`developer` · `senior-engineer` · `product-owner` · `stakeholder`
+· `critical-challenger` · `ai-agent`. Stable v1 shape; council
+verdict explicitly forbids migration to the 7-section spine — it
+would dilute the always-loaded cost without adding signal.
+
+### `specialist` — opt-in lens
+
+Domain-narrow voices a skill cites only when its specific axis is in
+play (e.g. `qa` for testability, `backend-architect` for system
+boundaries). Specialists carry the 7-section spine because their
+narrower scope justifies — and benefits from — explicit Critical
+Rules and Workflows blocks (pattern adopted from
+`alirezarezvani/claude-skills`).
+
+## § 3 — Required sections per tier
+
+### Core (5 sections, ≤ 120 lines)
+
+1. **Focus** — one paragraph, the lens.
+2. **Mindset** — bullets, default assumptions and skepticism.
+3. **Unique Questions** — ≥ 3 questions no other persona asks verbatim.
+4. **Output Expectations** — how findings are phrased.
+5. **Anti-Patterns** — what this persona must refuse to do.
+
+### Specialist (7 sections, ≤ 100 lines)
+
+1. **Focus**
+2. **Mindset**
+3. **Unique Questions** — ≥ 3, same heuristic
+4. **Output Expectations**
+5. **Anti-Patterns**
+6. **Critical Rules** — non-negotiable invariants this lens enforces
+   (e.g. "every new branch needs a failing test before the fix").
+   Bulleted, declarative, ≤ 8 items.
+7. **Workflows** — concrete review / inspection steps the persona
+   runs against the skill's input. Numbered, deterministic, ≤ 6 steps.
+
+`Composes well with` is permitted as an additional section in either
+tier (kept for v1 personas that ship it; not required, not budget-counted
+beyond the global line cap).
+
+## § 4 — Size budgets
+
+| Tier | Section count | Line cap | Rationale |
+|---|---|---|---|
+| `core` | 5 | ≤ 120 | always-loaded, stay lean |
+| `specialist` | 7 | ≤ 100 | opt-in, denser per section |
+
+The line cap is enforced by `lint-skills` against the full file
+including frontmatter and trailing blank line.
+
+## § 5 — Schema enforcement
+
+The linter (A2 work) enforces:
+
+- frontmatter shape (table in § 1)
+- tier enum
+- required sections per tier (§ 3)
+- size budget per tier (§ 4)
+- ≥ 3 bullets in `Unique Questions`
+- `id` matches filename stem
+- description ≤ 160 chars
+
+Specialist authors must use the template at
+`.agent-src.uncompressed/personas/_template-specialist/persona.md`.
+Core authors continue to use
+`.agent-src.uncompressed/templates/persona.md` (unchanged).
+
+## § 6 — Persona inventory (v1 snapshot)
+
+| ID | Tier | Mode | Status |
+|---|---|---|---|
+| `developer` | core | developer | shipped |
+| `senior-engineer` | core | reviewer | shipped |
+| `product-owner` | core | product-owner | shipped |
+| `stakeholder` | core | planner | shipped |
+| `critical-challenger` | core | reviewer | shipped |
+| `ai-agent` | core | developer | shipped |
+| `qa` | specialist | tester | shipped (existing 6-section shape; A-track migration to 7-section spine planned alongside A3 batch) |
+
+A3 adds four specialists drafted natively against the 7-section
+spine: `backend-architect` · `eloquent-tamer` · `security-engineer`
+· `frontend-engineer`.
+
+## § 7 — Versioning
+
+Section rename / add / remove → ADR + linter update + persona migrations
+in the same PR. Tier rename or new tier is breaking and requires a
+major version bump in the package release notes. Size-cap tightening
+is breaking when it forces existing personas to lose content; size-cap
+loosening is non-breaking.
+
+## See also
+
+- [`skill-domains`](skill-domains.md) — sister taxonomy for skills
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md) — workflow-mode axis personas compose with
+- `.agent-src.uncompressed/personas/README.md` — authoring entry point + Core-6 cast
+- `.agent-src.uncompressed/personas/_template-specialist/persona.md` — specialist starter
+- `.agent-src.uncompressed/templates/persona.md` — core starter (v1, unchanged)
+- `road-to-better-skills-and-profiles.md` — Block A (schema lock + extension)

package/docs/contracts/skill-domains.md

@@ -0,0 +1,143 @@
+---
+stability: beta
+---
+
+# Skill Domains — 6-domain taxonomy
+
+> **Status:** active · **Stability:** beta · **Owner:** road-to-better-skills-and-profiles Block B
+> · **Linter:** `scripts/skill_linter.py` enforces the `domain:` field against this allow-list
+> · **Schema:** `scripts/schemas/skill.schema.json` § `domain`
+
+Locks the canonical 6-domain taxonomy that classifies every skill in
+`.agent-src.uncompressed/skills/`. Each skill MUST declare exactly one
+`domain:` value from the allow-list below in its `SKILL.md` frontmatter.
+
+## § 1 — Allow-list
+
+```
+engineering · product · quality · devops · process · discovery
+```
+
+Unknown values fail `lint-skills`. Missing `domain:` fails `lint-skills`.
+No multi-domain assignment — pick the dominant axis.
+
+## § 2 — Domain definitions
+
+### `engineering`
+
+Application and framework code authoring — controllers, models,
+services, jobs, validation, queues, mail, broadcasting, ORMs, and
+language-level idioms (PHP, async patterns, error handling). The
+"writing the app" axis. Where the agent ships features into the
+production codebase.
+
+**Examples:** `eloquent` · `laravel-validation` · `php-coder`
+
+### `product`
+
+Discovery, refinement, and ticket / prompt shaping before code is
+written. Turns a fuzzy ask into a refined backlog item, an estimated
+unit of work, or a model-ready prompt. The "what should we build"
+axis — upstream of engineering.
+
+**Examples:** `refine-ticket` · `estimate-ticket` · `refine-prompt`
+
+### `quality`
+
+Test authoring, review, and verification gates. Pest, Playwright,
+the judge family, code review, threat modelling, security audits,
+testing anti-patterns. The "is it correct, safe, and reviewable"
+axis — runs alongside or after engineering.
+
+**Examples:** `pest-testing` · `judge-bug-hunter` · `review-routing`
+
+### `devops`
+
+Infrastructure, deployment, runtime, and observability. AWS, Docker,
+Terraform, Terragrunt, CI pipelines, Traefik, Grafana, secrets,
+DevContainers, package publishing. The "how it runs in production"
+axis.
+
+**Examples:** `terraform` · `github-ci` · `docker`
+
+### `process`
+
+Workflow, orchestration, and meta-tooling. Git workflow, slash-command
+routing, subagent orchestration, agent docs, skill / rule / command
+authoring, learnings capture, branch finishing, PR mechanics. The
+"how the agent works the codebase" axis.
+
+**Examples:** `git-workflow` · `command-routing` · `subagent-orchestration`
+
+### `discovery`
+
+Audit, diagnostic, and investigative analysis. Bug hunting, blast
+radius mapping, data flow tracing, performance and security audits,
+framework-specific project analysis, hypothesis-driven debugging.
+The "understand what's there before changing it" axis.
+
+**Examples:** `bug-analyzer` · `blast-radius-analyzer` · `project-analysis-laravel`
+
+## § 3 — Boundary heuristics (when in doubt)
+
+- **engineering vs quality** — does the skill **write production code**
+  (engineering) or **assert / review** production code (quality)?
+- **engineering vs devops** — does the artifact run **inside the app**
+  (engineering) or **around the app** (devops)?
+- **product vs process** — does the skill produce a **work item**
+  (product) or **drive the workflow** that delivers work items
+  (process)?
+- **discovery vs quality** — discovery **reads to understand**;
+  quality **reads to gate / approve**. A judge skill is `quality`; a
+  blast-radius skill is `discovery`.
+- **discovery vs engineering** — if the skill ends in a production
+  edit, it's `engineering`; if it ends in a written analysis or
+  finding, it's `discovery`.
+
+Tiebreaker: pick the axis that matches the skill's **primary output
+artifact**, not its auxiliary side-effects.
+
+## § 4 — Skill assignment by domain
+
+Snapshot from B3 back-fill (regenerate via `python3 scripts/_emit_domain_table.py`).
+Source-of-truth for the assignment is each skill's `domain:` frontmatter —
+this table is a derived view, kept readable for reviewers.
+
+### engineering (36)
+
+`api-design`, `api-endpoint`, `artisan-commands`, `async-python-patterns`, `blade-ui`, `code-refactoring`, `composer-packages`, `database`, `dependency-upgrade`, `dto-creator`, `eloquent`, `error-handling-patterns`, `fe-design`, `flux`, `jobs-events`, `laravel`, `laravel-horizon`, `laravel-mail`, `laravel-middleware`, `laravel-notifications`, `laravel-pennant`, `laravel-pulse`, `laravel-reverb`, `laravel-scheduling`, `laravel-validation`, `livewire`, `migration-creator`, `multi-tenancy`, `openapi`, `performance`, `php-coder`, `php-debugging`, `php-service`, `react-shadcn-ui`, `sql-writing`, `websocket`
+
+### product (12)
+
+`dcf-modeling`, `estimate-ticket`, `feature-planning`, `funnel-analysis`, `okr-tree-modeling`, `prompt-engineering-patterns`, `prompt-optimizer`, `refine-prompt`, `refine-ticket`, `rice-prioritization`, `technical-specification`, `unit-economics-modeling`
+
+### quality (25)
+
+`adversarial-review`, `api-testing`, `authz-review`, `code-review`, `defense-in-depth`, `design-review`, `judge-bug-hunter`, `judge-code-quality`, `judge-security-auditor`, `judge-test-coverage`, `mobile-e2e-strategy`, `pest-testing`, `playwright-testing`, `quality-tools`, `readme-reviewer`, `review-routing`, `security`, `security-audit`, `skill-reviewer`, `test-driven-development`, `test-performance`, `testing-anti-patterns`, `threat-modeling`, `validate-feature-fit`, `verify-completion-evidence`
+
+### devops (13)
+
+`aws-infrastructure`, `dashboard-design`, `devcontainer`, `docker`, `github-ci`, `grafana`, `logging-monitoring`, `react-native-setup`, `secrets-management`, `sentry-integration`, `terraform`, `terragrunt`, `traefik`
+
+### process (48)
+
+`adr-create`, `agent-docs-writing`, `agents-md-thin-root`, `ai-council`, `check-refs`, `command-routing`, `command-writing`, `context-authoring`, `context-document`, `conventional-commits-writing`, `copilot-agents-optimization`, `copilot-config`, `description-assist`, `developer-like-execution`, `file-editor`, `finishing-a-development-branch`, `git-workflow`, `guideline-writing`, `jira-integration`, `learning-to-rule-or-skill`, `lint-skills`, `markitdown`, `mcp`, `mcp-builder`, `md-language-check`, `merge-conflicts`, `module-management`, `override-management`, `persona-writing`, `project-docs`, `readme-writing`, `readme-writing-package`, `receiving-code-review`, `repomix-packer`, `requesting-code-review`, `roadmap-management`, `roadmap-writing`, `rtk-output-filtering`, `rule-writing`, `script-writing`, `sequential-thinking`, `skill-improvement-pipeline`, `skill-management`, `skill-writing`, `subagent-orchestration`, `token-optimizer`, `upstream-contribute`, `using-git-worktrees`
+
+### discovery (19)
+
+`analysis-autonomous-mode`, `analysis-skill-router`, `blast-radius-analyzer`, `bug-analyzer`, `data-flow-mapper`, `deep-reading-analyst`, `existing-ui-audit`, `performance-analysis`, `project-analysis-core`, `project-analysis-hypothesis-driven`, `project-analysis-laravel`, `project-analysis-nextjs`, `project-analysis-node-express`, `project-analysis-react`, `project-analysis-symfony`, `project-analysis-zend-laminas`, `project-analyzer`, `systematic-debugging`, `universal-project-analysis`
+
+**Total: 153 skills.**
+
+## § 5 — Versioning
+
+Domain rename or new-domain proposal → ADR + lint-skills allow-list
+update + back-fill of affected skills in the same PR. Domain
+deletion is breaking and requires a major version bump in the package
+release notes.
+
+## See also
+
+- [`skill-quality`](../../.agent-src.uncompressed/rules/skill-quality.md) — frontmatter contract for skills
+- [`rule-classification`](rule-classification.md) — sister taxonomy for rules (kernel vs auto)
+- `road-to-better-skills-and-profiles.md` — Block B (taxonomy lock + back-fill + folder reorg)

package/docs/decisions/ADR-005-subagent-worktrees.md

@@ -0,0 +1,120 @@
+---
+adr: 005
+status: accepted
+date: 2026-05-09
+decision: subagent-worktrees-no-auto-merge
+supersedes: —
+superseded_by: —
+phase: road-to-better-skills-and-profiles · A7
+---
+
+# ADR-005 — `do-in-worktrees` Mode: No Auto-Merge, Ranked Candidates
+
+## Status
+
+**Accepted** · 2026-05-09.
+
+## Context
+
+`road-to-better-skills-and-profiles` Block A introduces formal personas
+and specialist review lenses. Step A7 derives from council iter-1
+verdict **CC-OQ1 (a)** — adopt the AgentHub pattern from
+`claude-skills` (per-candidate git-worktree isolation) into the
+existing `subagent-orchestration` skill **without** weakening the
+[`non-destructive-by-default`](../../.agent-src.uncompressed/rules/non-destructive-by-default.md)
+Hard Floor.
+
+The AgentHub pattern in its native form is appealing: spawn N
+implementer subagents into N worktrees, let a judge rank, **auto-merge
+the winner**. The auto-merge step is where the Hard Floor objects:
+
+- A merge into a tracked branch is a destructive operation in the
+  agent-authority sense — it rewrites the working copy on a branch
+  that the user will later push.
+- "Standing autonomy" never lifts the Hard Floor. CC-OQ1 (a) is the
+  only variant that survives the floor.
+
+Mode 7 (`do-in-worktrees`) already covered the **chained handoff**
+pattern (cross-wing skill chain, each step in its own worktree).
+ADR-005 extends mode 7 with a **competitive variant** for parallel
+candidate isolation, with three guardrails that make the pattern
+Hard-Floor-safe.
+
+## Decision
+
+Augment `subagent-orchestration` mode 7 with the **competitive
+variant** under three Hard-Floor-derived rules:
+
+1. **No auto-merge.** The orchestrator never merges a candidate
+   branch into the integration branch. The user invokes the merge
+   explicitly (e.g. `/finishing-a-development-branch`), or the
+   orchestrator hands back with a numbered-options block per
+   [`user-interaction`](../../.agent-src.uncompressed/rules/user-interaction.md).
+2. **Ranked presentation.** Judge ranks candidates 1..N with a
+   one-line justification per rank. The judge does **not** apply
+   anything; ranking is the only output.
+3. **Loser worktrees stay.** The orchestrator does not delete
+   losing worktrees automatically. Cleanup happens via
+   [`finishing-a-development-branch`](../../.agent-src.uncompressed/skills/finishing-a-development-branch/SKILL.md)
+   on user request, after harvesting any salvageable partial idea.
+
+Mode 7's chained-handoff variant is unchanged. The two variants
+share the worktree-isolation primitive but differ in topology
+(sequential vs parallel) and selection (linear chain vs ranked).
+
+## Consequences
+
+### Accepted
+
+- The Hard Floor stands. No new override surface; no "auto-merge
+  under standing autonomy" branch.
+- AgentHub's exploratory benefit is preserved — N candidates run in
+  isolation, judge picks a winner, user can compare diffs.
+- `using-git-worktrees` remains the mechanics layer; mode 7 is the
+  dispatch layer. No duplication.
+
+### Trade-offs
+
+- **Higher final-step cost.** User-driven merge adds one round-trip
+  per `do-competitively`-in-worktrees run vs the AgentHub auto-merge
+  variant. This is the cost of preserving the Hard Floor.
+- **Disk usage.** Loser worktrees persist until the user cleans up.
+  The `finishing-a-development-branch` skill carries an explicit
+  worktree-prune step to bound this.
+
+## Alternatives considered
+
+- **Variant (b) — auto-merge winner under standing autonomy flag.**
+  Rejected. The Hard Floor is non-negotiable and the cost of a
+  user round-trip is small compared to the cost of merging the
+  wrong candidate. Standing autonomy narrows other rules; it does
+  not lift the Hard Floor (per `non-destructive-by-default` § Hard
+  Floor catalog).
+- **Variant (c) — keep AgentHub as a separate skill, do not touch
+  mode 7.** Rejected. The skill would duplicate the worktree
+  primitives in `using-git-worktrees` and the dispatch logic in
+  `subagent-orchestration`. Mode 7 already exists; extending it is
+  cheaper than spawning a parallel skill. Council CC-OQ1 (a)
+  agreed: *"adopts AgentHub pattern from claude-skills, respecting
+  Hard Floor"*.
+
+## Re-evaluation trigger
+
+Revisit this ADR when:
+
+- A surface-level user-research signal indicates the manual-merge
+  round-trip is the bottleneck (≥3 distinct user reports), AND
+- A reviewable proposal exists for narrowing the Hard Floor
+  (additional gates, audit trail, etc.) that does not weaken the
+  prod-data and prod-deploy floors.
+
+Both conditions must hold. Either alone is insufficient.
+
+## References
+
+- `agents/roadmaps/road-to-better-skills-and-profiles.md` § A7
+  (council iter-1 CC-OQ1 verdict (a))
+- `.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md` § Mode 7
+- `.agent-src.uncompressed/skills/using-git-worktrees/SKILL.md` (mechanics layer)
+- `.agent-src.uncompressed/rules/non-destructive-by-default.md` § Hard Floor catalog
+- `.agent-src.uncompressed/skills/finishing-a-development-branch/SKILL.md` (cleanup path)

package/docs/decisions/ADR-006-skill-tools-python-pilot.md

@@ -0,0 +1,114 @@
+---
+adr: 006
+status: accepted
+date: 2026-05-09
+decision: skill-tools-python-pilot-pass
+supersedes: —
+superseded_by: —
+phase: road-to-better-skills-and-profiles · Block D (D1–D5)
+---
+
+# ADR-006 — Skill-Tools Python Pilot: Outcome and Decision
+
+## Status
+
+**Accepted** · 2026-05-09 · pilot **PASSED** · tools kept under
+`scripts/skill_tools/`.
+
+## Context
+
+`road-to-better-skills-and-profiles` **Block D** introduced four
+Python tools for skill / persona corpus maintenance:
+
+| ID | Tool | Purpose |
+|---|---|---|
+| D1 | `lint_skill_tools.py` | Pilot-invariant gate (stdlib-only, ≤ 200 LOC, `--json`/`--help`, `_SAMPLE`) |
+| D2 | `score_skill_relevance.py` | Rank skills for a task by keyword overlap + persona match |
+| D3 | `audit_persona_coverage.py` | Tier-aware persona-citation matrix (specialist < 3, core < 5 → flag) |
+| D4 | `suggest_skill_for_task.py` | Top-N skill + persona combos with one-line justification (wraps D2 + D3) |
+
+The pilot was gated by **iter-1 AI-Council verdict** (members:
+claude-sonnet-4-5 + gpt-4o · 2 rounds · 2026-05-01) <!-- council-ref-allowed: ADR decision trace -->
+([`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md)) <!-- council-ref-allowed: ADR decision trace -->
+under strict invariants: stdlib-only (internal package imports
+allowed), ≤ 200 LOC per tool, machine-readable output (`--json`),
+embedded `_SAMPLE`, blind-labelled eval corpora, and a kill-switch if
+< 2 / 3 functional tools pass.
+
+## Eval Outcome (D5)
+
+Corpora at `agents/eval-corpora/block-d/`. Runner:
+`scripts/skill_tools/run_block_d_eval.py`. Report:
+[`agents/eval-corpora/block-d/report.json`](../../agents/eval-corpora/block-d/report.json).
+
+| Tool | Target | Result | Verdict |
+|---|---|---|---|
+| **D2** (relevance scorer) | ≥ 85 % top-3 hit on 10 blind tasks | **10 / 10 (100 %)** | ✅ pass |
+| **D3** (persona audit) | ≥ 2 under-cited personas surfaced | **5** (`ai-agent`, `developer`, `eloquent-tamer`, `qa`, `stakeholder`) | ✅ pass |
+| **D4** (skill suggester) | ≥ 3 / 5 top-1 hits on blind corpus | **3 / 5 (60 %)** | ✅ pass (at floor) |
+| **Pilot** | ≥ 2 / 3 functional tools pass | **3 / 3** | ✅ **PASS** |
+
+D4 misses are honest: B01 ranks `livewire` over the more specific
+`livewire-architect` (close cousins; both legitimate top-1 picks);
+B03 (`description-assist` for "review trigger quality") is partial
+overlap. Both surface as `confirm-with-reviewer`-grade suggestions,
+which matches the tool's design contract.
+
+## Decision
+
+1. **Keep** the four tools under `scripts/skill_tools/` and the meta
+   linter at `scripts/lint_skill_tools.py`.
+2. **Keep** `lint-skill-tools` in the CI pipeline (`task ci` →
+   `taskfiles/ci-fast.yml`).
+3. **Keep** the eval corpora and the runner at
+   `scripts/skill_tools/run_block_d_eval.py` for regression.
+4. **Defer** the v2 refinements (anthropic round-2):
+   - `--ratio-mode` flag for D3 (absolute thresholds proved adequate
+     on first run; no false alarms on real corpus).
+   - Token-frequency reweighting for D2 (100 % top-3 hit rate leaves
+     no signal to reweight against).
+   - Council `do-competitively` mode for skill-suggester (out of
+     scope; orthogonal to the pilot).
+5. **No** promotion to a `task` subcommand or kernel-rule citation.
+   Tools stay advisory; no agent rule references them yet.
+
+## Consequences
+
+**Positive:**
+- 4 advisory tools available for future skill / persona corpus work
+  without third-party dependencies.
+- Tier-aware persona thresholds are now mechanically enforced
+  (advisory, not gated).
+- Eval corpora become the regression baseline — any future heuristic
+  edit must keep ≥ 2 / 3 tools passing.
+
+**Neutral:**
+- Tools are advisory only; no rule cites them, so they cannot
+  silently drift into a Hard-Floor or auto-execution role.
+- `task ci` gains one cheap meta-lint step (~ 50 ms).
+
+**Negative:**
+- Four new files to maintain. Mitigation: pilot-invariants linter
+  gates structural drift; tests gate semantic drift.
+- D4's 3 / 5 floor result is not a comfortable margin. If a future
+  edit drops it below 3 / 5, kill-switch fires per the council
+  verdict and the tool is removed without further debate.
+
+## Reversibility
+
+**Trigger:** any single `run_block_d_eval.py` execution that returns
+< 2 / 3 tools passing on `main` for two consecutive commits.
+**Action:** delete `scripts/skill_tools/`,
+`scripts/lint_skill_tools.py`, `tests/test_*_skill*.py`, the corpora
+dir, and the `lint-skill-tools` task entry. Mark this ADR
+`superseded_by`. ~ 30 min mechanical revert.
+
+## References
+
+- Roadmap: [`road-to-better-skills-and-profiles`](../../agents/roadmaps/archive/road-to-better-skills-and-profiles.md) Block D.
+- Council: [`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md). <!-- council-ref-allowed: ADR decision trace -->
+
+- Tools: [`scripts/skill_tools/`](../../scripts/skill_tools/).
+- Linter: [`scripts/lint_skill_tools.py`](../../scripts/lint_skill_tools.py).
+- Corpora + report: [`agents/eval-corpora/block-d/`](../../agents/eval-corpora/block-d/).
+- Tests: `tests/test_lint_skill_tools.py`, `tests/test_score_skill_relevance.py`, `tests/test_audit_persona_coverage.py`, `tests/test_suggest_skill_for_task.py`.

package/docs/decisions/INDEX.md

@@ -7,6 +7,9 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-001](ADR-001-kernel-swap-deferred.md) | Kernel Swap Deferred | accepted | 2026-05-06 | — |
 | [ADR-002](ADR-002-kernel-bucket-overrides.md) | Kernel Bucket Overrides | — | — | — |
 | [ADR-003](ADR-003-flat-cluster-subs-and-colon-syntax.md) | Flat Cluster Subs And Colon Syntax | — | — | — |
+| [ADR-004](ADR-004-rule-governance-pruning.md) | Rule Governance Pruning | accepted | 2026-05-08 | — |
+| [ADR-005](ADR-005-subagent-worktrees.md) | Subagent Worktrees No Auto Merge | accepted | 2026-05-09 | — |
+| [ADR-006](ADR-006-skill-tools-python-pilot.md) | Skill Tools Python Pilot Pass | accepted | 2026-05-09 | — |
 
 ## Unnumbered (legacy)
 

package/docs/personas.md

@@ -0,0 +1,115 @@
+# Personas
+
+Personas are **review lenses** the host agent adopts when running a
+skill — not sub-agents, not execution modes. Each persona shapes
+*what* the agent looks for in a diff, plan, or artifact; the host
+identity, tools, and workflow stay the same.
+
+This page catalogs the 11 personas shipped with `event4u/agent-config`
+and explains how `personas:` (lens axis) interacts with `/mode`
+(role-mode axis).
+
+## Catalog
+
+| ID | Role | Tier | Lens summary |
+|---|---|---|---|
+| `developer` | Developer | core | Pragmatic implementer voice — what's the smallest correct change? |
+| `senior-engineer` | Senior Engineer | core | Long-horizon impact — what does this look like in 6 months? |
+| `product-owner` | Product Owner | core | Outcome over output — does this move the user metric? |
+| `stakeholder` | Stakeholder | core | Risk and politics — who owns the rollback if this fails? |
+| `critical-challenger` | Critical Challenger | core | Devil's-advocate voice — what assumption is load-bearing here? |
+| `ai-agent` | AI Agent | core | Tool-economy voice — token cost, prompt clarity, automation seam. |
+| `qa` | QA | specialist | Test coverage and regression gates. |
+| `backend-architect` | Backend Architect | specialist | Service-layer boundaries, transaction scope, contract changes. |
+| `eloquent-tamer` | Eloquent Tamer | specialist | N+1, query shape, ORM idioms that melt the database. |
+| `security-engineer` | Security Engineer | specialist | OWASP-shaped failure modes, secret leakage, trust boundaries. |
+| `frontend-engineer` | Frontend Engineer | specialist | Component lifecycle, reactive state, hydration boundaries. |
+
+Tier rules:
+
+- **Core (6)** — always-loaded cast. 5 sections (Focus · Mindset · Unique Questions · Output Expectations · Anti-Patterns), ≤ 120 lines.
+- **Specialist (5)** — opt-in lenses. 7 sections (Core-5 + Critical Rules + Workflows), ≤ 100 lines.
+
+Schema contract: [`docs/contracts/persona-schema.md`](contracts/persona-schema.md).
+
+## When to invoke a persona
+
+- **A skill cites it.** Skills declare `personas:` in frontmatter; the
+  agent adopts the listed personas while running the skill. No user
+  action needed. Example: `judge-security-auditor` cites
+  `security-engineer` — invoking the skill applies the lens.
+- **You want a second pass on existing work.** Pick the specialist
+  whose checklist matches the diff: `eloquent-tamer` for ORM heavy
+  changes, `frontend-engineer` for component changes,
+  `backend-architect` for service-seam changes.
+- **Adversarial review.** `critical-challenger` for the devil's-advocate
+  voice; `security-engineer` for abuse-case framing.
+
+Invocation example (when supported by the host tool):
+
+```text
+--personas=backend-architect,security-engineer
+```
+
+The host agent reads the persona's `Critical Rules` and `Workflows`
+sections (specialist tier) or `Mindset` and `Unique Questions` (core
+tier) and merges them into its review pass.
+
+## `personas:` vs `/mode` — two different axes
+
+| Axis | What it controls | Example |
+|---|---|---|
+| `/mode` (role-mode) | Which **contract** the agent operates under for a turn — what outputs are mandatory, what work is refused | `/mode reviewer` refuses to write production code |
+| `personas:` (lens) | Which **review checklists** the agent overlays on a skill's procedure | `personas: [security-engineer]` adds OWASP-shaped checks to whatever skill is running |
+
+The two compose. `/mode reviewer` + `personas: [security-engineer,
+backend-architect]` = a review-only turn that applies both the
+security-abuse-case lens and the service-seam lens on top of the
+review contract.
+
+Personas are **not** a replacement for `/mode`. A persona cannot
+refuse work or change output contracts; that is `/mode`'s job.
+
+## Skill citations
+
+Specialist personas need at least one skill citation to earn their
+slot. Current cite map:
+
+| Persona | Cited by |
+|---|---|
+| `qa` | `judge-test-coverage` |
+| `critical-challenger` | `adversarial-review`, `requesting-code-review`, `receiving-code-review` |
+| `developer` · `senior-engineer` · `product-owner` · `ai-agent` | `refine-ticket`, `refine-prompt`, `estimate-ticket` |
+| `backend-architect` | `authz-review`, `api-design`, `blast-radius-analyzer` |
+| `eloquent-tamer` | `eloquent`, `database` |
+| `security-engineer` | `judge-security-auditor`, `threat-modeling`, `authz-review` |
+| `frontend-engineer` | `existing-ui-audit`, `fe-design` |
+
+Add a citation by appending `personas: [<id>]` to the skill's
+frontmatter — never overwrite an existing list, append.
+
+## Override pattern
+
+Consumers can override any package-shipped persona via the standard
+override mechanism:
+
+- **Frontmatter override** — change `tier`, `mode`, `description`
+  while keeping the package body. Frontmatter wins.
+- **Body override** — full replace. Drop a same-named file under
+  `agents/personas/<id>.md`; the package version is shadowed.
+
+See [`override-management`](../.agent-src/skills/override-management/SKILL.md)
+for the mechanics.
+
+## Anti-patterns
+
+- **Personas as agents.** Personas are lenses, not sub-agents. They do
+  not spawn processes or run tools independently.
+- **Personas as modes.** They do not change the host's contract or
+  refuse work. Use `/mode` for that.
+- **Specialist sprawl.** Cap is "≤ 4 specialists per plate" by the
+  council A-OQ2 verdict. New specialists need ≥ 1 skill citation
+  before merging.
+- **Core-tier mutation.** Core personas are versioned (`version` in
+  frontmatter); breaking changes need a new ID, not an in-place
+  rewrite.

package/package.json

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