@event4u/agent-config 9.1.0 → 9.3.0

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-modes-detail.md

@@ -1,10 +1,11 @@
-# Subagent Modes — worktree + live-app-judge detail
+# Subagent Modes — worktree + live-app-judge + adversarial-council detail
 
-Extended detail for the two heaviest [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md)
-modes — `do-in-worktrees` (mode 7) and `do-with-live-app-judge` (mode 8).
-Split out of the skill body to keep it under the size budget; the mode list,
-selection rules, and the six common modes stay inline in the skill. Pull this
-when you actually dispatch one of these two modes.
+Extended detail for the heaviest [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md)
+modes — `do-in-worktrees` (mode 7), `do-with-live-app-judge` (mode 8), and
+`adversarial-verification-council` (mode 9). Split out of the skill body to keep
+it under the size budget; the mode list, selection rules, and the six common
+modes stay inline in the skill. Pull this when you actually dispatch one of these
+modes.
 
 ## Mode 7 — do-in-worktrees
 
@@ -82,3 +83,37 @@ Rules:
   mechanism for this mode's judge once dependable screenshot tooling lands.
   Recorded from road-to-opt-design-polish; gate it behind the same
   `verdict_changed_outcome` adoption evidence above.
+
+## Mode 9 — adversarial-verification-council (gated — opt-in, advisory)
+
+A panel of N (default 2) **distinct-model** skeptics red-teams a real,
+already-verified change through the `judge-*` lenses. Each skeptic is prompted to
+*break* the change, returns a structured findings array (+ optional refutations),
+and the returns are reconciled by
+[`_lib/adversarial_reconcile.ts`](../../../scripts/_lib/adversarial_reconcile.ts)
+into one [`adversarial-findings.json`](../../../skills/subagent-orchestration/schemas/adversarial-findings.json)
+envelope. Scope: defect **finding coverage**, not a go/no-go decision (that is
+mode 6). Full contract: ADR-122; skeptic prompt:
+[`prompts/adversarial-verification-council.md`](../../../skills/subagent-orchestration/prompts/adversarial-verification-council.md).
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| High-risk change (security, tenant, migration, public API) where finding coverage matters, opted-in | Default flow, routine change, `subagents.adversarial_council: off`, or a plain go/no-go (use mode 6) | skeptics = ≥2 distinct models; cross-*vendor* for the registered claim + high-risk tier; cross-model Iron Law across all |
+
+Invariants:
+
+- **Advisory only — never auto-gates the change (Hard Floor).** The reconciler
+  ranks and annotates findings; a human decides what is actionable.
+- **Default-off.** `subagents.adversarial_council` (`off|ask|on`, default `off`).
+  Fires only on an explicit high-risk change under an opted-in setting.
+- **Cross-model Iron Law** across all skeptics; the registered finding-coverage
+  claim and the high-risk tier require cross-*vendor* skeptics (the backed
+  `cross-vendor-parity` signal is provider-level).
+- **Reconciliation is deterministic TS with tests** — dedup, severity-quorum
+  confidence, false-positive suppression (demote, never drop). Never
+  LLM-computed prose (ADR-122 anti-lesson).
+- **N cap** from the verify budget; no daemon / no persistent runtime; each
+  skeptic return uses the `subagent-status.json` envelope before reconciliation.
+- **Prove-or-drop.** The mode stays default-off until the
+  `adversarial-council-finding-coverage` claim is `backed` by the two-stage
+  residual-detection benchmark (roadmap Phase 4); honest-null keeps it inert.

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/contexts/execution/verify-budget.md

@@ -30,6 +30,20 @@ verification recorded as `none`, or a non-trivial change verified only
 deterministically, is a **gap** that is surfaced to the user — it never passes
 silently. This is the audit-visible enforcement of the Iron Law.
 
+## Opt-in escalation — adversarial verification council (default-off)
+
+For an explicitly high-risk change (security, tenant, migration, public API)
+AND `subagents.adversarial_council != off`, the verify step MAY escalate from a
+single cross-model judge to the **adversarial-verification-council** panel
+(subagent-orchestration Mode 9, ADR-122) — recorded as `verify_mode: council`.
+
+This escalation is **strictly opt-in and advisory**: it never fires when the
+setting is `off` (the default), and the panel finds defects but **never
+auto-gates the change** (Hard Floor). It replaces neither the deterministic
+floor nor the standard judge — it adds finding-coverage on top for changes where
+a single judge is too easy to fool. Stays default-off until the
+`adversarial-council-finding-coverage` claim is `backed` (prove-or-drop).
+
 ## Why this does not weaken the floor
 
 `deterministic` is still verification — a real diff + dry-run + structural
@@ -48,3 +62,4 @@ small to carry risk, where the deterministic check is sufficient evidence.
 - [`verify-before-complete`](../../rules/verify-before-complete.md) — the Iron Law this preserves.
 - [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md) — the cross-model judge law.
 - [`orchestration-telemetry`](orchestration-telemetry.md) — where `verify_mode` is recorded.
+- [`subagent-response-contract`](subagent-response-contract.md) — a low-confidence mutating finding forces the full judge path (`forcesJudge`).

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/rules/cross-source-consistency.md

@@ -0,0 +1,92 @@
+---
+type: "auto"
+tier: "2a"
+description: "Two sources disagree (ticket text vs mockup, spec silent on a needed behavior, spec vs code) → surface + ask before proceeding, never silently guess"
+triggers:
+  - keyword: "ticket"
+  - keyword: "refine"
+  - keyword: "acceptance criteria"
+  - keyword: "AC"
+  - keyword: "mockup"
+  - keyword: "screenshot"
+  - keyword: "attachment"
+  - keyword: "roadmap"
+  - keyword: "estimate"
+  - phrase: "plan this ticket"
+  - phrase: "refine this ticket"
+  - phrase: "is this ticket clear"
+  - phrase: "implement the ticket"
+applies_to_user_types:
+  - "developer"
+  - "founder"
+  - "consultant"
+routes_to:
+  - "guideline:agent-infra/cross-source-consistency-mechanics"
+workspaces: [engineering, product]
+packs: [engineering-base, product-basic]
+---
+
+# Cross-Source Consistency
+
+When the agent works from **more than one source** — ticket text, an attached
+image / mockup / screenshot, the spec, the codebase — those sources can
+disagree. The failure this rule prevents: the agent notices (or should notice)
+the disagreement, picks one reading, and proceeds silently — **even when its
+pick is correct**. A good guess on a real contradiction still robs the user of
+the decision that was theirs to make.
+
+## The Iron Law
+
+```
+TWO PRESENT SOURCES DISAGREE → SURFACE THE DISCREPANCY AND ASK BEFORE PROCEEDING.
+A SILENT GUESS ON A REAL CONTRADICTION IS A VIOLATION — EVEN IF THE GUESS IS RIGHT.
+AN INFERRED-BUT-UNSPECIFIED BEHAVIOR IS A SCOPE EXPANSION: ASK, NEVER ADD IT SILENTLY.
+OBVIOUS-TO-THE-AGENT ≠ IN-SCOPE.
+```
+
+## What counts as a discrepancy
+
+- **(a) text ↔ image** — ticket text contradicts an attached mockup / screenshot / diagram (canonical case: text says "show birthdays **today**", the mockup shows a birthday from two days ago).
+- **(b) silent-but-needed** — the spec is silent on a behavior that is clearly required (a weekend/holiday shift, an empty state, an error path). Surface it and ask **before** implementing — do not expand scope on a plausible inference (canonical case: the spec specifies weekend-shifting only; the agent also adds public-holiday shifting without asking).
+- **(c) spec ↔ codebase/reality** — the spec contradicts what the code actually does or what a real source shows.
+- **(d) intra-ticket** — the acceptance criteria, description, and comments contradict each other.
+
+## When it fires — and when NOT
+
+**Fires** while planning, refining, estimating, roadmapping, or implementing from
+a ticket/spec that carries a second source (an attachment, a code reality, or an
+internal contradiction), gated by `consistency.cross_source` in
+`.agent-settings.yml` (`on` default · `auto` = high-confidence only · `off` = inert).
+
+**Does NOT fire** on a single clear source with no second source to compare
+against (that is plain vagueness — it belongs to `ask-when-uncertain`), on
+trivial edits, or when the user has already resolved the discrepancy this turn.
+
+## How to surface it (subordinate to the ask discipline)
+
+- **Subordinate to [`ask-when-uncertain`](ask-when-uncertain.md).** Fold the
+  discrepancy into the SAME turn's single question — batch all discrepancies for
+  one artefact into ONE numbered-options block. Never emit a second question
+  block; one-question-per-turn holds.
+- **Defer to [`scope-control`](scope-control.md)** as the permission authority
+  for the type-(b) silent-scope-expansion case.
+- **Precedes [`design-fidelity`](design-fidelity.md).** This rule fires first,
+  at decision time ("text says X, the mockup says Y — which wins?"); once the
+  user resolves it, `design-fidelity` governs build-time 1:1 fidelity.
+- **Pass the [`no-cheap-questions`](no-cheap-questions.md) Pre-Send Self-Check.**
+  Fire only on a genuine contradiction or silent-scope-expansion carrying a real
+  trade-off — never a content-free "are you sure?". Under an autonomous mandate a
+  detected discrepancy is a blocking decision and is NOT suppressed, but an
+  off-hand non-contradiction must not become a continuation prompt.
+
+The taxonomy, the scan procedure, the confidence-tiered noise control, worked
+examples, and the precedence table live in
+[`cross-source-consistency-mechanics`](../docs/guidelines/agent-infra/cross-source-consistency-mechanics.md).
+
+## See also
+
+- [`ask-when-uncertain`](ask-when-uncertain.md) — the one-question-per-turn ask discipline this folds into (missing info → ask; this adds conflicting present sources → ask).
+- [`scope-control`](scope-control.md) — the permission authority for the silent-scope-expansion (type b) case.
+- [`design-fidelity`](design-fidelity.md) — governs build-time fidelity once a text↔image conflict is resolved.
+- [`active-remediation`](active-remediation.md) — the never-silently-ignore ladder this rule mirrors for source discrepancies.
+- [`no-cheap-questions`](no-cheap-questions.md) — the floor the discrepancy ask must clear.

package/dist/agent-src/rules/delegation-policy.md

@@ -90,7 +90,7 @@ primitive → run in-session (clean no-op).
 
 ## See also
 
-- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — the form gate + 8 modes this selects.
+- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — the form gate + 9 modes this selects.
 - [`subagent-boundary`](../docs/contracts/subagent-boundary.md) — what a subagent owns vs never owns (task-meaning, memory, pack-surface, safety-floor bypass).
 - [`auto-orchestration-activation`](../contexts/execution/auto-orchestration-activation.md) — the gate.
 - [`reasoning-orchestrator`](../skills/reasoning-orchestrator/SKILL.md) — RDP dispatch, now gated here.

package/dist/agent-src/skills/estimate-ticket/SKILL.md

@@ -77,6 +77,8 @@ If the ticket scores low on estimability (vague AC, no out-of-scope,
 no mention of deps), set `uncertainty = Underspecified` and
 emit a single-line redirect to `/refine-ticket` at the top of the output.
 
+A **cross-source discrepancy** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`) — ticket text contradicting an attached mockup, or a clearly-needed-but-unstated behavior (weekend/holiday shift) — is not estimable as-is: it hides an open scope decision. Raise `uncertainty` and name the discrepancy in the redirect rather than sizing over a contradiction.
+
 ### 3. Apply sizing heuristics
 
 Score across four axes; each axis contributes to the final size:

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/feature-planning/SKILL.md

@@ -28,7 +28,7 @@ Do NOT use when:
 
 ## Procedure: Plan a feature
 
-1. **Gather requirements** — What problem does this solve? Who benefits? What's the expected outcome?
+1. **Gather requirements** — What problem does this solve? Who benefits? What's the expected outcome? Run a **cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`): where the source ticket carries text + an attachment/mockup, or leaves a clearly-needed behavior unstated (weekend/holiday shift, empty/error state, timezone), surface the conflict/gap as an *Open question* before drafting phases — an inferred behavior is a scope expansion to confirm, not to bake in. See [`cross-source-consistency-mechanics`](../../../docs/guidelines/agent-infra/cross-source-consistency-mechanics.md).
 2. **Analyze scope** — Which modules, routes, models, services are affected?
 3. **Write the plan** — Create a feature plan document (see template below).
 4. **Verify** — Confirm all affected areas are identified, no missing dependencies.

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/po-discovery/SKILL.md

@@ -81,6 +81,8 @@ not name an implementation**. Use Given / When / Then or a numbered
 list. Reject ACs that hide assumptions ("works correctly", "is fast
 enough") — replace with measurable thresholds or strike them.
 
+**Cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`): when the raw input includes a screenshot / mockup alongside the story text, check the sources against each other and surface any conflict as a `gap` / open question — never resolve it silently. Watch for: story text contradicting an attached screenshot; the AC contradicting the description; a clearly-needed behavior the input never states (weekend/holiday shift, empty/error state). Batch them into one clarifying question. Taxonomy: [`cross-source-consistency-mechanics`](../../../docs/guidelines/agent-infra/cross-source-consistency-mechanics.md).
+
 ### 5. Surface non-functional gaps
 
 Flag anything missing that downstream skills will need: success

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/refine-ticket/SKILL.md

@@ -138,6 +138,13 @@ Check the loaded ticket for clarity signals before orchestrating:
 - Is the scope one feature, or multiple tangled together?
 - Any sentence that references an existing module name, feature flag, or domain concept?
 
+**Cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`): the ticket is rarely a single source. Compare every source against the others and surface any conflict as an *Open question* — never resolve it silently:
+- **text ↔ attachment** — does the ticket text agree with every attached mockup / screenshot / diagram? (Canonical miss: text says "birthdays **today**", the mockup shows a birthday from two days ago.) If an attachment cannot be read, say so — do not assume it agrees.
+- **silent-but-needed** — is the spec silent on a clearly-needed behavior (weekend/holiday shift, empty state, error path, timezone, permissions)? Surface it and ask before it becomes an implementation assumption — an inferred behavior is a scope expansion, not a given.
+- **intra-ticket** — do the AC, description, and comments contradict each other?
+
+Fold every discrepancy into the refined output's *Open questions* section (one batched list), never a second prompt. Full taxonomy + scan procedure: [`cross-source-consistency-mechanics`](../../../docs/guidelines/agent-infra/cross-source-consistency-mechanics.md).
+
 Then run the deterministic detection helper — do **not** re-derive trigger
 logic in prose:
 

package/dist/agent-src/skills/roadmap-writing/SKILL.md

@@ -82,6 +82,20 @@ Vague goals ("improve roadmaps") force every reader to re-derive
 intent. If the goal needs three sentences, the roadmap is two
 roadmaps.
 
+### 3b. Scan sources for discrepancies before drafting phases
+
+When the roadmap originates from a ticket/spec that carries a second
+source — an attached mockup/screenshot, a code reality, or an internal
+contradiction — run the **cross-source discrepancy scan** (per
+[`cross-source-consistency`](../../rules/cross-source-consistency.md),
+gated by `consistency.cross_source`) before writing phases. A phase plan
+built over a text↔image contradiction or a silent-but-needed behavior
+(weekend/holiday shift, empty/error state) bakes the wrong assumption into
+every downstream step. Surface each discrepancy as one batched open
+question first; an inferred behavior is a scope expansion to confirm, not
+to plan silently. Taxonomy + procedure:
+[`cross-source-consistency-mechanics`](../../../docs/guidelines/agent-infra/cross-source-consistency-mechanics.md).
+
 ### 4. Phase blocks carry checkboxes
 
 Every non-intro phase contains at least one `- [ ]`. Decision tables