@event4u/agent-config 9.2.0 → 9.3.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Bootstrap shim for the event4u agent-config suite. This plugin ships ONLY the dispatcher hooks plus one install-pointer skill — ALL content (skills, rules, commands) is installed via `npx -y @event4u/agent-config init`, which writes the file projection AND registers the same hooks in ~/.claude/settings.json. DEPRECATED as a content channel; kept so the marketplace listing stays discoverable and existing installs keep working hooks.",
-    "version": "9.2.0",
+    "version": "9.3.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -1033,6 +1033,39 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 9.3.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [9.3.0](https://github.com/event4u-app/agent-config/compare/9.2.0...9.3.0) (2026-07-16)
+
+### Features
+
+* **ergonomics:** harvest ergonomics plate — tdd cluster, fix:route, persona-improvement, hand-off examples ([e8be16f](https://github.com/event4u-app/agent-config/commit/e8be16f2a0194a6b6cb3b2ed4a9899db31067d1d))
+* **review:** wire reuse + OOP-shape lens into the review/orchestration surfaces ([067175a](https://github.com/event4u-app/agent-config/commit/067175a04c1d49c356bf8e42c4cb0f23b3d91473))
+* **hooks:** PostToolUse PR-URL reminder — reply-shape backstop for direct-answers ([1bf82a1](https://github.com/event4u-app/agent-config/commit/1bf82a1f23fd2fac7ae86fe1fae3cc6b3e0da657))
+
+### Bug Fixes
+
+* **counts:** regenerate command-flows.md (+5 commands) + map explain-run orphan into surface-map ([a6254e4](https://github.com/event4u-app/agent-config/commit/a6254e434e966eaca9e697093980dfc3cc04a8d8))
+* **hooks:** pre-push gate mirrors the full CI consistency check locally ([ebd706f](https://github.com/event4u-app/agent-config/commit/ebd706fb1e978189954ca838bc41bd3f536ee560))
+
+### Documentation
+
+* refresh guideline counts (100 -> 101) after the new dev-standard guideline ([02ac1a5](https://github.com/event4u-app/agent-config/commit/02ac1a53214b5cd22eecee873e2b81286c01a6b2))
+* **standards:** apply council findings — paradigm-appropriate + minimal-diff precedence ([474b1c6](https://github.com/event4u-app/agent-config/commit/474b1c68b8a28dd1f5302b135fbe69876696ea6f))
+* **standards:** component-oriented + OOP-first development standard ([5bd62bd](https://github.com/event4u-app/agent-config/commit/5bd62bdf14208f65ae166b954a5c7b4e49211ffa))
+* **roadmaps:** council-review + apply findings to feedback-9.2.0 followups ([dc187d4](https://github.com/event4u-app/agent-config/commit/dc187d4b83debda1c4f8c551acfc6400149da520))
+* **roadmaps:** draft feedback-9.2.0 follow-ups roadmap ([69d363d](https://github.com/event4u-app/agent-config/commit/69d363df10f5e9dd6605ba6af370ac1d477a5a92))
+* **roadmaps:** spawn adversarial-council benchmark follow-up; mark deferred arm moved ([36a69d9](https://github.com/event4u-app/agent-config/commit/36a69d9f00b4a236535ea01bf8dd36a4d82f1293))
+
+### Refactoring
+
+* **subagent-orchestration:** relocate worker-prompt contract to spawn-contract context ([de38ce1](https://github.com/event4u-app/agent-config/commit/de38ce12ff167eafe7a0631f1088ed244e2b85bf))
+
+### Chores
+
+* **harvest:** close second-sweep coverage plate — all folds verified, proposals parked, archived ([7af8a75](https://github.com/event4u-app/agent-config/commit/7af8a75305289bd1f2d36498bea362b789b0f610))
+* **roadmaps:** archive completed adversarial-verification-council roadmap ([fc34874](https://github.com/event4u-app/agent-config/commit/fc34874a608644d89ab12aa0147d5f6237a4f9ca))
+
+Tests: 7770 (+6 since 9.2.0)
+
 ## [9.2.0](https://github.com/event4u-app/agent-config/compare/9.1.0...9.2.0) (2026-07-14)
 
 ### Features

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-275-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-105-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-184-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-100-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-276-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-105-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-184-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-101-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 > **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
 

package/dist/agent-src/commands/fix/route.md

@@ -0,0 +1,49 @@
+---
+model_tier: medium
+name: fix-route
+pack: engineering-base
+tier: 2
+visibility: internal
+sub: route
+cluster: fix
+description: Classify a vaguely-described problem and dispatch to the right fix sub-command (or name the specialist skill when it is not a fix task)
+argument-hint: "[free-text problem description]"
+suggestion:
+  eligible: true
+  trigger_description: "something's broken but I'm not sure which fixer — throw me a problem and route it"
+  trigger_context: "user describes a problem without naming a specific fix sub-command"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /fix route
+
+The classify-and-dispatch front door for the `/fix` family. Adapted from the
+ecosystem source's `/smart-fix` — folded into the `fix` verb (ADR-041
+controlled-verb vocabulary) rather than a new top-level verb. It runs the
+`/fix` auto-detection over a free-text problem and routes; when the problem is
+not a fix task, it names the right specialist instead of forcing a fix sub.
+
+## Instructions
+
+1. Read the free-text problem.
+2. Run the `/fix` cluster's detection table (see the cluster head) over it:
+   CI failure → `fix ci`; broken cross-refs → `fix refs`; PR review threads →
+   `fix pr-comments`; code-comment noise → `fix comments`; seeder/FK →
+   `fix seeder`; type/lint/format errors → `fix quality`; project-leak in the
+   shared package → `fix portability`.
+3. **HIGH confidence** → route to that sub-command and follow its instructions.
+4. **Not a fix task** (a new feature, an analysis, a design question) → do NOT
+   force a fix sub; name the correct surface instead (`/feature`, a
+   `project-analysis-*` skill, `improve-before-implement`, etc.) and stop.
+5. **LOW confidence / ≥ 2 conflict** → print the fix menu and ask; in
+   non-interactive mode emit `ambiguous_routing` and stop (per the
+   non-interactive-contract). Never guess past LOW.
+
+## Rules
+
+- **Dispatch only — no fixing here.** This sub classifies and hands off; the routed sub-command does the work under its own rules.
+- **One route per turn.** Do NOT chain.
+- **Do NOT commit or push** — the routed sub-command's rules govern that.

package/dist/agent-src/commands/fix.md

@@ -2,10 +2,10 @@
 model_tier: medium
 name: fix
 disable-model-invocation: true
-argument-hint: "[ci|refs|portability|seeder|pr-comments|comments|quality] [args]"
+argument-hint: "[ci|refs|portability|seeder|pr-comments|comments|quality|route] [args]"
 pack: engineering-base
 intent: "Fix-workflow dispatcher — ci, pr-comments, refs, seeder, portability, comments, quality"
-routes_to: [fix-ci, fix-pr-comments, fix-refs, fix-seeder, fix-portability, fix-comments, fix-quality]
+routes_to: [fix-ci, fix-pr-comments, fix-refs, fix-seeder, fix-portability, fix-comments, fix-quality, fix-route]
 replaces: []
 tier: 1
 visibility: advanced
@@ -39,6 +39,7 @@ with a single entry point + sub-command dispatch.
 | `/fix pr-comments` | `commands/fix/pr-comments.md` | Fix and reply to all open review comments — **bot + human, classified per comment**; dedupes by comment id + reply marker |
 | `/fix comments` | `commands/fix/comments.md` | Review the **code comments** in the current branch's diff and simplify, shorten, or remove each one (≠ `pr-comments`, which targets GitHub review threads) |
 | `/fix quality` | `commands/fix/quality.md` | Run the quality pipeline (type-checker / linter / formatter, PHP and/or JS/TS) and fix every error — auto-detects language from changed files |
+| `/fix route` | `commands/fix/route.md` | Classify a vaguely-described problem and dispatch to the right fix sub (or name the specialist when it is not a fix task) — the `/smart-fix` front door, folded into the `fix` verb |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -84,6 +85,7 @@ into it and removed.
    > 5. pr-comments — address open review comments (bot / human / both)
    > 6. comments — simplify / shorten / remove code comments in the branch diff
    > 7. quality — run the quality pipeline and fix every error
+   > 8. route — describe the problem; I classify and dispatch
 
 ## Rules
 

package/dist/agent-src/commands/tdd/green.md

@@ -0,0 +1,32 @@
+---
+model_tier: medium
+name: tdd-green
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: tdd
+sub: green
+skills: [test-driven-development]
+description: TDD green phase — write the minimum production code to make the failing test pass; no test edits
+argument-hint: "[failing test | context]"
+suggestion:
+  eligible: true
+  trigger_description: "make the failing test pass"
+  trigger_context: "a failing test exists, ready to implement"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /tdd green
+
+Drives the **Implement** phase of
+[`test-driven-development`](../../../skills/test-driven-development/SKILL.md).
+
+## Instructions
+
+1. Write the **minimum** production code to make the failing test pass — no scope beyond the one case.
+2. Honor the Implement Forbidden block: **no `tests/**` edits** — changing the assertion to fit the code is the canonical violation; a genuinely-wrong test → STOP and ask, never silently edit.
+3. Run the test; confirm green.
+4. Output: the green run. Hand to `/tdd refactor` (or `/tdd red` for the next case).

package/dist/agent-src/commands/tdd/red.md

@@ -0,0 +1,33 @@
+---
+model_tier: medium
+name: tdd-red
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: tdd
+sub: red
+skills: [test-driven-development]
+description: TDD red phase — enumerate cases, write ONE failing test, watch it fail at an assertion (not an import error)
+argument-hint: "[behavior to test]"
+suggestion:
+  eligible: true
+  trigger_description: "write the failing test first"
+  trigger_context: "starting a new behavior test-first"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /tdd red
+
+Drives the **Design → Test-Red** phases of
+[`test-driven-development`](../../../skills/test-driven-development/SKILL.md).
+
+## Instructions
+
+1. State the behavior in one sentence; enumerate the cases (happy / boundary / error).
+2. Write ONE failing test for the first case.
+3. Run it; confirm it fails at an **assertion**, not an import/collection error.
+4. Honor the Test-Red Forbidden block: **no production edits** (diff = `tests/**` only).
+5. Output: the failing test + its observed failure reason. Hand to `/tdd green`.

package/dist/agent-src/commands/tdd/refactor.md

@@ -0,0 +1,31 @@
+---
+model_tier: medium
+name: tdd-refactor
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: tdd
+sub: refactor
+skills: [test-driven-development]
+description: TDD refactor phase — clean up (rename, deduplicate) while keeping the test green
+argument-hint: "[target | context]"
+suggestion:
+  eligible: true
+  trigger_description: "refactor while the test stays green"
+  trigger_context: "test is green, ready to clean up"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /tdd refactor
+
+Drives the **Refactor** step of
+[`test-driven-development`](../../../skills/test-driven-development/SKILL.md).
+
+## Instructions
+
+1. Refactor (rename, deduplicate, extract) ONLY while the test stays green — re-run after each change.
+2. If a change reddens the test, revert it; refactoring never changes behavior.
+3. Output: the cleaned diff + a final green run. Loop back to `/tdd red` for the next behavior.

package/dist/agent-src/commands/tdd.md

@@ -0,0 +1,50 @@
+---
+model_tier: medium
+name: tdd
+disable-model-invocation: true
+argument-hint: "[red|green|refactor] [behavior | args]"
+pack: engineering-base
+tier: 2
+visibility: internal
+description: TDD orchestrator — routes to red (failing test), green (minimum code), refactor (clean while green)
+cluster: tdd
+type: orchestrator
+auto_detect: true
+suggestion:
+  eligible: true
+  trigger_description: "write the failing test first, make the test pass, refactor while green"
+  trigger_context: "user is driving a change test-first and names a TDD phase"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /tdd
+
+Thin ergonomic split over the [`test-driven-development`](../../skills/test-driven-development/SKILL.md)
+skill — one sub-command per phase of that skill's mode contract. **No logic
+lives here**; each sub loads the skill and drives its named phase.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/tdd red` | `commands/tdd/red.md` | Design → Test-Red: enumerate cases, write ONE failing test, watch it fail at an assertion |
+| `/tdd green` | `commands/tdd/green.md` | Implement: write the minimum code to pass; no test edits |
+| `/tdd refactor` | `commands/tdd/refactor.md` | Refactor: clean up while the test stays green |
+
+## Dispatch
+
+1. Parse `/tdd <sub> [args]`. Explicit sub → route. Otherwise infer the phase
+   from observable state via the skill's mode-inference table (no test yet →
+   red; test failing at an assertion → green; green + defect → red again).
+2. Load [`test-driven-development`](../../skills/test-driven-development/SKILL.md)
+   and drive ONLY the named phase, honoring that phase's Forbidden block.
+3. LOW confidence / bare `/tdd` → show the three-row menu and ask.
+
+## Rules
+
+- **One phase per turn.** Do NOT chain red→green→refactor silently — each sub is one turn.
+- **No logic duplication.** The behavior is the skill's; these commands only select the phase.
+- **Do NOT commit or push.**

package/dist/agent-src/contexts/communication/rules-auto/guidelines-mechanics.md

@@ -10,6 +10,7 @@ before writing or reviewing code); this file is the catalog.
 | File | Topic |
 |---|---|
 | `code-clarity.md` | Cross-language clarity rules — inline single-use values, carve-outs (side effects, loops, type narrowing, debugger) |
+| `component-oriented-and-oop-development.md` | Reuse-first components (FE) + OOP-where-it-reduces-complexity (backend); carve-out index; bounded by the anti-over-engineering anchors |
 
 ## PHP (`docs/guidelines/php/`)
 

package/dist/agent-src/contexts/execution/subagent-spawn-contract.md

@@ -41,11 +41,90 @@ private-data leg stays narrow: the composer rejects inline bodies (multi-line /
 oversized entries), accepts only ref-like tokens, and caps the count. Anything
 dropped is recorded in `warnings` and surfaced — never silently widened.
 
+## Bundle resolver — bind to the existing surfaces
+
+The brief is **resolved**, not hand-built. `resolveBundle(slice)` maps a task
+slice to a concrete bundle by selecting from what the package already ships — no
+parallel registry:
+
+- **Role-profile via reused `judge-*` lenses** — a review slice → `judge-code-quality`,
+  security → `judge-security-auditor`, tests → `judge-test-coverage`, bug-hunt →
+  `judge-bug-hunter`. The lens rides as the leading persona so the subagent loads it.
+- **Role-mode** per slice kind (review → `reviewer`, tests → `tester`, plan → `planner`, …).
+- **Tier** per slice kind (`lite|medium|high`), consumed by `subagent-routing`.
+- **Knowledge refs** filtered by the **ADR-100 guard** (`filterKnowledgeByPolicy`):
+  a cross-project bundle drops `proprietary` refs; the drop is recorded.
+
+Every resolved bundle emits an auditable `(role_mode, judge_lens, tier,
+knowledge_ref_count, dropped_proprietary)` signature (`bundleAuditLine`) into the
+[`orchestration-telemetry`](orchestration-telemetry.md) object — counts + ids
+only, never bodies.
+
 ## Reference implementation
 
 [`src/scripts/_lib/subagent_spawn.ts`](../../../../src/scripts/_lib/subagent_spawn.ts)
-(`composeSpawnBrief`), covered by
-[`tests/scripts/_lib_subagent_spawn.test.ts`](../../../../tests/scripts/_lib_subagent_spawn.test.ts).
+(`composeSpawnBrief`) + [`src/scripts/_lib/subagent_bundle.ts`](../../../../src/scripts/_lib/subagent_bundle.ts)
+(`resolveBundle`, `filterKnowledgeByPolicy`, `bundleAuditLine`), covered by
+[`tests/scripts/_lib_subagent_spawn.test.ts`](../../../../tests/scripts/_lib_subagent_spawn.test.ts)
++ [`tests/scripts/_lib_subagent_bundle.test.ts`](../../../../tests/scripts/_lib_subagent_bundle.test.ts).
+
+## Worker-prompt rules — verbatim at spawn
+
+Relocated from the `subagent-orchestration` skill body (road-to-feedback-9.2.0
+Phase 2, size-budget split). Every dispatched worker prompt obeys these rules —
+they prevent the two classic handoff failures: lossy re-summarization dropping
+the user's requirements, and over-scripted prompts that break on first
+contingency.
+
+- **(a) User constraints verbatim.** Pass the user's
+  constraints/exclusions/preferences into the worker prompt **verbatim** — never
+  a paraphrase (a paraphrase silently drops requirements).
+- **(b) Describe the goal, don't script the approach.** State the outcome and
+  let the worker choose the path; over-scripting breaks on contingencies.
+- **(c) Translate environment paths.** Orchestrator-local paths do not exist in
+  the worker's sandbox — resolve/translate them at spawn.
+- **(d) Pre-declared check-in conditions.** The worker names, at spawn time, the
+  conditions under which it will halt and ask ("if login required", "if
+  multiple candidates found") — so interrupts are predictable, not surprises.
+- **(e) Attach relevant knowledge — read-only (road-to-opt-subagent-harvest
+  P3).** Before dispatch, look up the slice's key identifiers via
+  `memory_lookup` / the knowledge cards and attach the top hits to the
+  worker prompt AS LEADS — labelled per the source-discovery discipline
+  (negative facts + pointers durable; positive structure = hypothesis to
+  re-confirm, never a build input). The WRITE half stays forbidden: a
+  subagent's output is never auto-persisted into memory — promotion is
+  always the human-gated flow (ADR-098 floor). Auto-surface, never
+  auto-write.
+
+## Hand-off worked examples — step N output feeds step N+1
+
+Relocated from the `subagent-orchestration` skill (ecosystem-harvest ergonomics
+U4, size-budget split). Ordered modes (`do-in-steps`) pass each step's return
+as the next step's context; the failure this prevents is re-deriving state the
+previous step established, or dropping a decision it made.
+
+**Ordered chain (do-in-steps).** Step 1 returns a structured result; step 2's
+worker prompt embeds it verbatim as "context from step 1", never a paraphrase:
+
+```
+Step 1 (analyze) → returns: { entrypoints: [...], risk_notes: "..." }
+Step 2 (implement) worker prompt:
+  "Context from step 1 (verbatim, do not re-derive):
+     entrypoints = [...]; risk_notes = '...'
+   Your task: <goal>. Use the entrypoints above; do not re-scan."
+Step 3 (verify) worker prompt:
+  "Context: step 2 changed <files>. Assert <invariant>."
+```
+
+**Fan-out → synthesis (do-in-parallel + a synthesis step).** Each parallel
+worker returns one envelope; the synthesis step receives ALL of them as an
+ordered list and is told what to reconcile ("merge the N findings; a finding
+present in ≥2 returns is high-confidence"). The synthesis prompt names the
+cross-item comparison — it does not just concatenate.
+
+The rule both encode: **the receiving prompt embeds the prior return verbatim
+and states what to do with it** — the same verbatim-first discipline as the
+worker-prompt rules above, applied across a step boundary.
 
 ## Related
 

package/dist/agent-src/rules/architecture.md

@@ -38,6 +38,13 @@ Fires on new files, classes, controllers, modules, or any structural decision ab
 → Symfony: see [`symfony-workflow`](../skills/symfony-workflow/SKILL.md).
 → Next.js / TypeScript backends: see [`nextjs-patterns`](../skills/nextjs-patterns/SKILL.md).
 
+## Reusable components + object-oriented design
+
+- **Think in reusable units** — decompose UI into composable components; reuse the project's primitives / shared abstractions before building; extract a new unit only when the same shape repeats (audit existing first, per [`ui-audit-gate`](ui-audit-gate.md)).
+- **Object-oriented where it reduces complexity** — in an object-oriented / class-based codebase, encapsulation, single responsibility, composition over inheritance, behavior-rich domain objects, and design patterns *where they earn their place* are the high-priority default — never speculative abstraction, and never imposed on a functional / pipeline codebase (detect + defer to its paradigm). Bounded by [`minimal-safe-diff`](minimal-safe-diff.md) + [`senior-engineering-discipline`](senior-engineering-discipline.md), which **win on conflict**: a reviewer should be able to name the concrete duplication or second axis of change the abstraction removes (rule of thumb: two real repetitions before you extract).
+
+Full standard — split FE / backend, with the stack carve-out index and the anti-over-engineering deference: [`component-oriented-and-oop-development`](../docs/guidelines/component-oriented-and-oop-development.md).
+
 ## Architectural Decision Records (ADRs)
 
 When a structural decision is non-trivial (kernel membership, contract change, library swap,

package/dist/agent-src/skills/fe-design/SKILL.md

@@ -98,6 +98,7 @@ React island vs. Vue SFC) is the apply-step's concern, not this skill's.
 - **Compose with reusable UI components** for shared shells, headers, fields.
 - **Use the project's library primitives first** — never rebuild what the design system already provides (audit findings tell you which).
 - **Extract when used 3+ times** — DRY applies to UI too.
+- **Component workshop when the project is large enough** — for a real, growing shared-component library, isolate and document each reusable component in a component workshop so it stays discoverable and reused, not re-invented; skip it for a small surface of one-offs. Tool-specific setup is a carve-out (Storybook et al.) — see the implementation skill (e.g. [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Component workshop), never a generic mandate.
 
 ## Form Design
 

package/dist/agent-src/skills/judge-code-quality/SKILL.md

@@ -63,6 +63,7 @@ if the neighbors are unfashionable.
 | **Comments** | Explain *why*, not *what*. Remove comments that restate the code |
 | **Error-shape consistency** | Exceptions/results follow the same pattern as the rest of the module |
 | **Public surface** | New public API matches module's existing style and is minimal |
+| **Reuse & OO shape** | A new unit reinvents a component/abstraction the codebase already has (should compose/reuse instead); OR encapsulation/composition would genuinely cut complexity here (anemic object mutated from outside; an `if`/`switch` on a type-discriminator that a polymorphic shape would absorb) — flag **only where the duplication/branch is already present** (never "could grow later"), **in the codebase's own paradigm** (don't push a class onto functional code), never speculative abstraction (`minimal-safe-diff` wins on conflict) |
 
 ### 3. Filter out linter-land
 

package/dist/agent-src/skills/persona-improvement/SKILL.md

@@ -0,0 +1,81 @@
+---
+model_tier: inherit
+name: persona-improvement
+description: "ONLY when the user explicitly asks to refine a persona from recent corrections — persona analog of skill-improvement-pipeline; tightens a persona's Unique Questions, governance-gated."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+requires_skills:
+  - persona-governance
+---
+
+# persona-improvement
+
+The persona analog of [`skill-improvement-pipeline`](../skill-improvement-pipeline/SKILL.md):
+feed a persona a sample of recent corrections/failures where its review lens
+**should** have caught something and didn't, and tighten its `Unique Questions`
+so the lens fires next time. Access ergonomics, not new capability — it only
+sharpens an existing persona, never creates one.
+
+## When to use
+
+- The user explicitly says "improve / refine this persona" or "the <persona> lens keeps missing X".
+- A correction sample exists (review misses, repeated feedback) that a persona's questions should have surfaced.
+
+Do NOT use for:
+
+- Creating a new persona (that is `persona-governance` + the authoring flow).
+- Editing a persona's identity/scope (a breaking change → new id per `persona-governance`).
+- A one-off miss with no pattern — one anecdote is not a refinement signal.
+
+## Procedure
+
+1. **Gather the correction sample.** Collect the recent misses/corrections tied
+   to this persona's domain (from the conversation, feedback notes, or a review
+   log). If fewer than ~3 distinct misses, STOP — no pattern yet; say so.
+2. **Locate the gap.** For each miss, name the question the persona *should* have
+   asked that would have surfaced it. Cluster the misses into ≤ 2 recurring gaps.
+3. **Propose tightened `Unique Questions`.** Rewrite or add questions that close
+   the gaps — concrete and answerable-from-the-diff, not vague ("does this add a
+   second branch on the same enum?" beats "is the design good?"). Keep the
+   section ≥ 3 questions (`persona-governance` schema floor).
+4. **Governance gate (mandatory).** Before writing, confirm with
+   [`persona-governance`](../../rules/persona-governance.md): the edit is a
+   same-id refinement (not a scope/identity change — those need a new id); the
+   persona keeps ≥ 1 skill citation; the file still passes the skill linter
+   (tier/wing/section/line budget). A scope change is out of scope for this loop.
+5. **Apply + verify.** Edit only the `Unique Questions` section; run
+   `./scripts-run src/scripts/skill_linter` on the persona file and confirm
+   0 errors; show the before/after questions.
+
+## Output format
+
+1. **Correction sample** — the ≥ 3 misses, one line each.
+2. **Gaps** — the ≤ 2 recurring gaps the misses cluster into.
+3. **Before/after `Unique Questions`** — the diff, with which gap each new question closes.
+4. **Governance confirmation** — same-id refinement ✅, ≥ 1 citation intact ✅, linter 0-error ✅.
+
+## Gotcha
+
+- The most common misuse is **scope creep disguised as refinement**: adding
+  questions that widen the persona into a second domain. That is a new persona
+  (per the per-domain cap), not a refinement — STOP and route to
+  `persona-governance`, do not grow the lens sideways.
+
+## Do NOT
+
+- Do NOT refine on a single miss — a pattern needs ≥ 3.
+- Do NOT touch identity, scope, tier, or wing — same-id `Unique Questions` only; anything else is a new-id change under `persona-governance`.
+- Do NOT drop below 3 `Unique Questions` (schema floor).
+- Do NOT commit or push — apply the edit locally, surface the diff.
+
+## Related Skills
+
+- [`skill-improvement-pipeline`](../skill-improvement-pipeline/SKILL.md) — the skill-side analog this mirrors.
+- [`persona-governance`](../../rules/persona-governance.md) — the four discipline checks this loop is gated by.

package/dist/agent-src/skills/react-shadcn-ui/SKILL.md

@@ -253,6 +253,16 @@ current state on the next polish round.
 
 `DESIGN.md` `## Taste Dials` → honour: Variance → layout-family spread + asymmetry; Motion → animation budget + reduced-motion posture; Density → spacing scale + info-per-viewport. Absent → follow brief's inferred dials.
 
+## Component workshop (Storybook) — when the library is large enough
+
+Generic "isolate + document reusable components" principle → [`fe-design`](../fe-design/SKILL.md) § Component Architecture; this is the React carve-out for the tool-specific part.
+
+- **When it pays off** — real, growing shared-component library (more than a handful of reused primitives, multiple consumers, ongoing UI work): Storybook makes each component discoverable, reviewable in isolation, reused not re-invented. **Skip** for a small surface of one-offs — setup + maintenance not worth it yet.
+- **Story per reusable primitive, not per screen** — a story covers a component + its states (default / loading / empty / error / dark), mirroring the Step 3 state-coverage matrix. Screens composed, not story-fied.
+- **Reuse the token layer** — stories render under the same semantic tokens + `.dark` class; never hardcode a preview theme (Step 2 token discipline).
+- **A11y in-workshop** — run the a11y addon so isolation catches contrast / role / focus before the component reaches a screen.
+- Do NOT let stories drift from the component API — a story props-drilling values the component no longer accepts is stale documentation; keep beside the component, update in the same change.
+
 ## Do NOT
 
 - Do NOT install `shadcn-ui` from npm — primitives are scaffolded.

package/dist/agent-src/skills/subagent-orchestration/SKILL.md

@@ -68,33 +68,22 @@ line; any gate failing → in-session no-op. Never lifts a safety floor.
 
 ## Worker-prompt contract
 
-Every dispatched worker prompt obeys four rules — they prevent the two classic
-handoff failures: lossy re-summarization dropping the user's requirements, and
-over-scripted prompts that break on first contingency.
-
-- **(a) User constraints verbatim.** Pass the user's
-  constraints/exclusions/preferences into the worker prompt **verbatim** — never
-  a paraphrase (a paraphrase silently drops requirements).
-- **(b) Describe the goal, don't script the approach.** State the outcome and
-  let the worker choose the path; over-scripting breaks on contingencies.
-- **(c) Translate environment paths.** Orchestrator-local paths do not exist in
-  the worker's sandbox — resolve/translate them at spawn.
-- **(d) Pre-declared check-in conditions.** The worker names, at spawn time, the
-  conditions under which it will halt and ask ("if login required", "if
-  multiple candidates found") — so interrupts are predictable, not surprises.
-- **(e) Attach relevant knowledge — read-only (road-to-opt-subagent-harvest
-  P3).** Before dispatch, look up the slice's key identifiers via
-  `memory_lookup` / the knowledge cards and attach the top hits to the
-  worker prompt AS LEADS — labelled per the source-discovery discipline
-  (negative facts + pointers durable; positive structure = hypothesis to
-  re-confirm, never a build input). The WRITE half stays forbidden: a
-  subagent's output is never auto-persisted into memory — promotion is
-  always the human-gated flow (ADR-098 floor). Auto-surface, never
-  auto-write.
+Every dispatched worker prompt obeys five rules that prevent the two classic
+handoff failures (lossy re-summarization dropping the user's requirements;
+over-scripted prompts that break on first contingency): (a) user
+constraints **verbatim**, (b) describe the goal — don't script the approach,
+(c) translate environment paths into the worker's sandbox, (d) pre-declare
+check-in conditions, (e) attach relevant knowledge read-only (auto-surface,
+never auto-write — ADR-098 floor). The five rules verbatim:
+[`subagent-spawn-contract` § Worker-prompt rules](../../contexts/execution/subagent-spawn-contract.md).
 
 When to delegate at all is [`delegation-policy`](../../rules/delegation-policy.md);
 the spawn boundary is the [`subagent-spawn-contract`](../../contexts/execution/subagent-spawn-contract.md).
 
+## Hand-off worked examples
+
+Ordered / fan-out hand-offs embed each step's return **verbatim** in the next prompt and state what to do with it (never "continue from before" — the lossy re-summarization failure). Two worked shapes: [`subagent-spawn-contract` § Hand-off worked examples](../../contexts/execution/subagent-spawn-contract.md).
+
 ## Form gate — deterministic, BEFORE mode selection
 
 With auto-dispatch on by default (ADR-117), mode selection happens without

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.2.0"
+agent_config_version: "9.3.0"
 
 # --- Project identity ---
 project:

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-07-14T13:40:54Z`
+- Generated: `2026-07-16T03:13:57Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._