@event4u/agent-config 9.16.0 → 9.18.0

package/dist/agent-src/skills/fe-design/references/design-patterns.md

@@ -0,0 +1,227 @@
+# fe-design — design patterns
+
+> Section-level entry point of the `fe-design` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## Component Architecture
+
+### Page structure (universal shape)
+
+```
+Page layout
+├── Header (static)
+├── Navigation (interactive — active state)
+├── Content area
+│   ├── Page heading + actions (static)
+│   ├── Filters (interactive — reactive)
+│   ├── Data display (interactive — table / cards)
+│   └── Pagination (interactive)
+└── Footer (static)
+```
+
+The stack-specific mapping (Blade partial vs. Livewire component vs.
+React island vs. Vue SFC) is the apply-step's concern, not this skill's.
+
+### When to use what (kind, not framework)
+
+| Kind | When | Example |
+|---|---|---|
+| **Static partial** | No interactivity, server-rendered only | Header, footer, static info |
+| **Reusable UI component** | Props-only, no state | Button, badge, card shell |
+| **Stateful component** | Needs server interaction or local state | Forms, tables, filters |
+| **Library primitive** | Standard UI from a design system | Modal, dropdown, input, toast |
+| **Client-only micro-interaction** | No server roundtrip needed | Toggle, accordion, clipboard |
+
+### Component granularity
+
+- **One stateful component per concern** — don't build mega-components.
+- **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 a props-only UI shell when used 3+ times** — DRY applies to UI too; stateful components carry a higher bar (~4 + real state) — per-class canon: [`abstraction-thresholds`](../../../../docs/guidelines/abstraction-thresholds.md).
+- **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
+
+### Principles
+
+1. **Labels always visible** — no placeholder-only inputs
+2. **Validation on blur + submit** — immediate feedback, not on every keystroke
+3. **Error messages below the field** — red text, specific message
+4. **Required fields marked** — asterisk (*) or "(required)" label
+5. **Logical grouping** — related fields in sections with headings
+6. **Primary action prominent** — submit button stands out, cancel is secondary
+
+### Layout patterns
+
+| Fields | Layout | When |
+|---|---|---|
+| 1–3 fields | Single column | Simple forms (login, search) |
+| 4–8 fields | Two columns on desktop, single on mobile | Standard CRUD forms |
+| 8+ fields | Sections with headings or tabs/steps | Complex entity forms |
+| Related pairs | Side by side (first/last name, city/zip) | Logically paired fields |
+
+### Multi-step forms
+
+```
+Step indicator (1 — 2 — 3)
+├── Step 1: Basic info     → Next
+├── Step 2: Details        → Back / Next
+└── Step 3: Review + Submit → Back / Submit
+```
+
+- Show progress indicator (step numbers or progress bar)
+- Allow going back without losing data
+- Validate each step before allowing next
+- Show summary on final step
+
+## Table Design
+
+### Principles
+
+1. **Right-align numbers** — easier to compare
+2. **Left-align text** — natural reading direction
+3. **Sortable columns** — click header to sort
+4. **Sticky header** — visible when scrolling long tables
+5. **Row actions** — edit/delete as icon buttons or dropdown menu
+6. **Empty state** — helpful message when no data, not just blank
+
+### Responsive tables
+
+| Screen | Strategy |
+|---|---|
+| Desktop (≥1024px) | Full table with all columns |
+| Tablet (768–1023px) | Hide less important columns |
+| Mobile (<768px) | Card layout or horizontal scroll |
+
+### Pagination
+
+- Default: 25 rows per page
+- Show total count: "Showing 1–25 of 142"
+- Allow page size change (10, 25, 50, 100)
+- Prefer server-side pagination — avoid loading the full set client-side
+
+## Responsive Strategy
+
+### Breakpoints (Tailwind reference scale)
+
+| Prefix | Min width | Target |
+|---|---|---|
+| `sm:` | 640px | Large phones |
+| `md:` | 768px | Tablets |
+| `lg:` | 1024px | Small laptops |
+| `xl:` | 1280px | Desktops |
+| `2xl:` | 1536px | Large screens |
+
+### Mobile-first approach
+
+1. Design for mobile first (default styles)
+2. Add complexity at larger breakpoints
+3. Test at each breakpoint, not just desktop
+
+### Common patterns
+
+| Element | Mobile | Desktop |
+|---|---|---|
+| Navigation | Hamburger menu | Sidebar or top nav |
+| Forms | Single column | Two columns |
+| Tables | Cards or scroll | Full table |
+| Actions | Bottom sheet / FAB | Inline buttons |
+| Filters | Collapsible panel | Sidebar or inline |
+
+## Accessibility (a11y)
+
+### Minimum requirements
+
+- **Color contrast:** 4.5:1 for text, 3:1 for large text (WCAG AA)
+- **Keyboard navigation:** All interactive elements reachable via Tab
+- **Focus indicators:** Visible focus ring on all focusable elements
+- **Alt text:** All meaningful images have descriptive alt text
+- **ARIA labels:** Interactive elements without visible text need `aria-label`
+- **Semantic HTML:** Use `<button>`, `<nav>`, `<main>`, `<form>` — not `<div>` for everything
+
+### Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| `<div onclick>` | Use `<button>` |
+| Color-only status | Add icon or text alongside color |
+| Missing form labels | Add `<label for="...">` |
+| Auto-playing content | Provide pause/stop control |
+| Tiny click targets | Min 44×44px touch target |
+
+## Motion — decision-tree and rationale
+
+Before adding any animation to a UI element, run through this decision tree:
+
+**1. Should this animate at all?**
+- Used 100+ times per day (keyboard shortcut, command palette)? **No animation. Why:** animations on high-frequency interactions feel sluggish; users wait for them on every invocation. Raycast has no open/close animation by design.
+- Triggered by user action with visible result (button → state change)? **Micro-feedback only (< 160ms).** Why: quick enough to feel instant, visible enough to confirm the action.
+- Modal/overlay/sheet entering/exiting? **Animate. Why:** position change needs motion to maintain spatial continuity.
+- Background process with no user action? **No animation.** Why: unexplained motion is disorienting.
+
+**2. Which easing?**
+- Entering (element appearing)? **ease-out** (starts fast, slows to rest). Why: the element arriving quickly signals responsiveness; the deceleration feels natural as it settles.
+- Exiting (element disappearing)? **ease-in** (starts slow, accelerates out). Why: the reverse is true — fast exit signals completion.
+- **Never ease-in for entering elements.** Why: ease-in delays the initial movement — the exact moment the user is watching most closely — making it feel slow even at the same total duration.
+- **Never bounce or elastic easing in UI.** Why: bounce draws attention to the animation itself, not the content; it feels dated.
+
+**3. How long?**
+- Button/micro-feedback: 100–160ms. Tooltip: 100ms. Dropdown open: 150–200ms. Modal: 200–350ms. Page transition: 300–500ms. Above 500ms: almost never.
+- **Never animate layout properties** (width, height, top, left, padding). Why: triggers browser layout recalculation on every frame; always solvable with `transform`.
+- **Always add `@media (prefers-reduced-motion: reduce)`** — gentler animation (reduced distance/opacity), NOT display:none. Why: vestibular disorders make motion UI unusable; reducing is better than removing.
+
+**4. What to animate?**
+Animate `transform` and `opacity` only. Why: these run on the GPU compositor thread, not the main thread; they never trigger layout or paint.
+`scale(0)` → `scale(1)` is wrong. Why: nothing in the real world appears from nothing. Use `scale(0.95)` + `opacity: 0` → `scale(1)` + `opacity: 1` instead.
+
+## UX Principles
+
+1. **Feedback** — Every action gets a response (toast, loading state, success message). **Why:** users interpret no feedback as failure.
+2. **Forgiveness** — Undo beats confirmation dialogs. Users click through confirmations mindlessly. **Why:** remove destructively then show undo toast; actually delete after toast expires.
+3. **Consistency** — Same patterns for same interactions across the app. **Why:** predictability reduces cognitive load; inconsistency forces users to re-learn.
+4. **Progressive disclosure** — Show basics first, details on demand. **Why:** premature complexity overwhelms; reveal information as it becomes relevant.
+5. **Loading states** — Skeleton screens preferred over spinners. **Why:** skeletons reduce perceived wait time by showing structure immediately.
+6. **Error recovery** — Clear error messages with suggested actions. **Why:** "something went wrong" gives the user nothing to do; a specific message with a next step reduces support burden.
+
+## Craft details — typography & imagery
+
+- **`text-wrap: pretty` on body copy** — avoids widows/orphans without manual
+  breaks; cheap, no layout risk. (Display headlines: `text-wrap: balance`.)
+- **Honest placeholders over weak assets** — when the real image/illustration
+  is missing, use a striped placeholder with a monospace size label
+  (`repeating-linear-gradient(45deg, #E5E5E5 0 10px, #F5F5F5 10px 20px)` +
+  `product shot (1200×800)`) instead of a hand-drawn SVG or stock-ish filler.
+  A placeholder signals "asset needed"; a weak illustration signals nobody
+  had the asset. Never Lorem-ipsum copy in review-bound output
+  (per `output-discipline`) — use short label-style skeleton copy.
+
+## Presenting variants
+
+This skill produces ONE refined solution by default. **Plan the variation
+decision before generating** — do not reflexively emit one generic design when
+exploration was asked, nor spam options when one production answer was asked.
+
+- **Decide whether to vary (ask only if ambiguous).** For ambiguous creative
+  work, decide the variation count and the axis that varies — visual direction,
+  UX flow, interaction model, copy, density, or brand strictness. Ask about
+  count + axis only when the choice changes the work materially; for a clear
+  implementation task, proceed with one answer. (fixture: `daf-requested-variations`.)
+- **Variation floors.** When the user asks to explore, produce **two to three
+  meaningfully different** options along the stated axis — different *decisions*,
+  not the same layout recoloured. When the user asks for one production answer,
+  produce one; no decorative option spam. (fixtures: `daf-requested-variations`,
+  `daf-unwanted-variations`.)
+- **Canvas / exploration contract (host-neutral).** Presenting side-by-side
+  concepts: give each a **stable frame label**, keep frames flat (no nested
+  cards), use generous spacing, and — on tools with a canvas — export-safe
+  coordinates so the layout survives export. Same labelled-frames shape whether
+  the host has a real canvas or just stacked sections.
+- **Cost / UX tie-breaker.** Ask about the axis only when it changes the work
+  materially; otherwise choose a strong default and **document the axis used in
+  the handoff** ("explored along visual-direction; density held constant").
+
+Hand off the actual variation **mechanics** — the basic→bold method and the
+single-file tweak-panel (CSS custom properties + floating "Tweaks" panel +
+`localStorage`) — to [`design-variations`](../design-variations/SKILL.md): this
+section owns the *planning decision*, that skill owns the *execution*.

package/dist/agent-src/skills/fe-design/references/design-read-and-memory.md

@@ -0,0 +1,75 @@
+# fe-design — design read and memory
+
+> Section-level entry point of the `fe-design` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## Cross-task design memory — read DESIGN.md / PRODUCT.md first
+
+Before applying any heuristics from this reference, check the project root
+for `DESIGN.md` and/or `PRODUCT.md` (written by `design-system-capture`):
+
+- `DESIGN.md` present → use its captured radius/shadow/motion/spacing as
+  project constraints. The heuristics in this skill are **fallbacks for
+  gaps**, not overrides for captured decisions.
+- `PRODUCT.md` present → honor its interaction patterns (empty-state approach,
+  mutation feedback policy, filter persistence) in any UI design that touches
+  those surfaces.
+
+Flag any new decision for future capture: *"This establishes a new pattern —
+suggest adding to PRODUCT.md: [pattern description]."*
+
+## Register — brand vs product
+
+Before applying heuristics, determine the register (see
+[`docs/guidelines/design-modes.md`](../../../../docs/guidelines/design-modes.md)):
+brand mode (impression-first) vs product mode (task-first). Form-heavy, table-heavy,
+and dashboard surfaces are almost always product mode — favour the standard
+patterns in this skill (Form Design, Table Design) over expressive variance.
+Marketing/landing surfaces are brand mode — let the Aesthetic-direction section
+commit to a deliberate, distinctive direction.
+
+## Design Read — articulate intent before generating
+
+When this reference is cited for a UI planning task, emit one line declaring
+the design read before any heuristics are applied:
+
+```
+Reading this as: <page-kind> for <audience>, <vibe> language, leaning <design-system>.
+```
+
+**If context is incomplete:** state so and proceed exploratory — do NOT block.
+
+**Anti-Default Discipline:** Before committing to any layout or component
+pattern, cross-check your first impulse against
+[`design-antipatterns.md`](../../../../docs/guidelines/design-antipatterns.md) —
+the L1/L2 "AI landing page" layout (centered hero + 3-column grid + CTA), the
+V1 side-stripe card, the T7 default-font pick, and V2 decorative glassmorphism.
+If a tell was the first impulse, choose a different approach or explicitly
+justify why this brief calls for it. (The full pre-proposal scan is under
+*Anti-slop discipline* below.)
+
+**Carve-out — a supplied artifact is the spec, not a first impulse.** This
+discipline governs what *you* reach for. When the user hands over a finished
+artifact, the choices it makes are not your impulses and the justify-or-change
+burden does not apply to them: build them as given. The carve-out is scoped to
+decisions the artifact actually covers — anything it leaves open (a state it
+never shows, a surface it never had) is your first impulse again and gets the
+full scan. See
+[`design-fidelity-mechanics`](../../../../docs/guidelines/design-fidelity-mechanics.md)
+§ Provided-artifact precedence.
+
+## Aesthetic direction
+
+Audit-pinned tokens and components always take precedence (see `existing-ui-audit`). When the audit pins an aesthetic, honor it without deviation. When the audit shows **no pinned aesthetic** — greenfield surface, marketing landing page, brand-new feature without design-system precedent — the design brief is allowed (and expected) to commit to a deliberate direction instead of defaulting to safe centered hero + 3-column features + CTA.
+
+Typography pairings (73 curated heading/body combinations with Google
+Fonts URLs + Tailwind config) and icon-system guidance (104 Phosphor
+entries with import code) come grounded from
+[`design-intelligence`](../design-intelligence/SKILL.md)
+(`--domain typography`, `--domain icons`) — query before picking from
+memory.
+
+Pick one direction up front and let composition, typography, and color follow from it. Avoid the "neutral AI default": uniform grid, system fonts as the visible body face, purple-to-blue gradients on white, predictable spacing. A direction that fits the brand intent (editorial / brutalist / refined / playful / retro / maximal / minimal / etc.) and is consistent across the page beats hedging.
+
+Surface the chosen direction in the design brief as a one-line statement (e.g. `aesthetic: editorial-magazine — asymmetric grid, serif display + sans body, generous gutters`). The apply step (`react-shadcn-ui` / `blade-ui` / `livewire` / `flux`) reads this line and matches typography, spacing, and motion to it; if no line is present, the apply step uses project defaults.

package/dist/agent-src/skills/market-entry-analysis/SKILL.md

@@ -144,7 +144,7 @@ Horizontal SaaS, US-only, mid-market, considering EU expansion.
 
 - Step 0 — axis = geo (EU). Defer segment (stay mid-market) and vertical (stay horizontal).
 - Step 1 — candidate beachheads: DACH, Nordics, UK, Benelux. Scored: UK wins on constraint-favour (English-language sales motion translates, common-law contract familiarity), reference-reachability (5 mid-market UK customers reachable via existing channels), regulatory delta (UK-GDPR ≈ EU-GDPR floor with thinner data-residency requirement), expansion path (UK → Benelux → DACH).
-- Step 2 — Sales motion: existing AE motion translates to UK. Product delta: data-residency in EU (12 weeks). Operating cost: UK Ltd entity, VAT registration ≈ 3 months.
+- Step 2 — Sales motion: existing AE motion translates to UK. Product delta: data-residency in EU (industry-typical ~12 weeks, illustrative). Operating cost: UK Ltd entity, VAT registration (industry-typical ≈ 3 months, illustrative — not a prediction).
 - Step 3 — failure mode: "incumbent's UK channel partnerships locked us out of mid-market." Mitigation: direct-AE motion + content-led pipeline.
 - Step 4 — sequence: UK (beachhead) → Benelux (same motion, thin regulatory delta) → DACH (German-speaking sales hire required, larger TAM).
 - Step 5 — emit entry plan + compose P3 for UK-vs-incumbents positioning.

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

@@ -107,8 +107,8 @@ A single Markdown file at `src/agent-src/personas/{id}.md`:
 3. `## Unique questions` — 4–7 decidable questions
 4. `## Output expectations` — verdict format, severity vocabulary
 
-Length: ≤ 80 lines for a tier-core persona; longer signals the focus
-is too broad.
+Length: ≤ 120 lines for a tier-core persona (specialists ≤ 100; wings
+3–4: ≤ 140); longer signals the focus is too broad.
 
 ## Gotchas
 

package/dist/agent-src/skills/readme-reviewer/SKILL.md

@@ -132,7 +132,8 @@ Size checks:
 - **< 150 lines** — healthy
 - **150–300 lines** — expect a Table of Contents; flag if missing
 - **300–500 lines** — flag as overloaded; deep content should be in `/docs/`
-- **> 500 lines** — flag as broken entry point; hard split required
+- **> 500 lines** — flag as broken entry point; split strongly recommended
+- The enforced lint limit is **750 lines** (`lint_readme_size.ts` fails above it); the 150/300/500 bands are editorial
 
 Structure checks:
 

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

@@ -266,6 +266,16 @@ Every roadmap ends in exactly one of four states:
 
 After the last step of a roadmap is done, check completion status:
 
+0. **Completion review (Gate R2)** — last open item done → findings BEFORE
+   fixes, before any archival decision:
+   - `dispatch_r2_reviewer` builds the reviewer input; a **fresh subagent
+     without the implementation context** writes
+     `agents/evidence/reviews/<slug>.findings.md`.
+   - Work findings in priority order — each ends `fixed` / `accepted-risk` /
+     `deferred`. No code surface → explicit skip, never silent.
+   - Grammar, scope-hash binding, escape hatch:
+     [`plan-review-gates § 2`](../../../docs/contracts/plan-review-gates.md).
+
 1. **Scan the file** for all checkbox markers: `- [x]`, `- [ ]`, `- [~]`, `- [-]`.
 2. **Classify:**
    - `[x]` = completed

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

@@ -52,7 +52,10 @@ Authoring or materially rewriting a roadmap must go through
 Understand → Research → Draft per the
 [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
 rule. Inspect existing roadmaps under `agents/roadmaps/` for overlap
-or supersession before opening a new one.
+or supersession before opening a new one. **Gate C first** — "write a
+plan/roadmap" is a gated surface, so run
+[`plan-confidence-gate`](../../contexts/execution/plan-confidence-gate.md)
+before drafting (95%-conditions, marker, interview-or-degrade, C→R1 handoff).
 
 ### 1. Read the canonical template first
 
@@ -180,6 +183,14 @@ breakdown. Full shape: [`templates/roadmaps.md` rule 20](../../agent-src/templat
 Omit the section entirely when the roadmap has no such gate; run the
 § 4c gate-test before adding one.
 
+### 5c. Risk review (Gate R1) — after draft, before save
+
+- Ready (non-draft) plan → `## Risk Register` before save, self-review; seed
+  from a fresh C→R1 handoff state (never re-ask a resolved branch).
+- Product AND implementation risks ranked descending, one mitigation per row,
+  each anchored to a phase/step here; none → exact honest-null grammar.
+- Schema, staleness, grandfather, drafts-exempt: [`plan-review-gates § 1`](../../../docs/contracts/plan-review-gates.md).
+
 ### 6. Step-marker semantics — pick `[~]` (defer) vs `[-]` (cancel) honestly
 
 When authoring (and especially when rewriting a roadmap mid-flight),

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

@@ -66,7 +66,9 @@ don't need it, it is `auto`.
 ### 2. Write a trigger-style description
 
 The `description` field **is** the trigger. Describe **when** the rule
-applies, not **what** it contains. Soft cap: **200 characters**.
+applies, not **what** it contains. Hard cap: **200 characters** (the
+linter errors `description_too_long` above it); the rule schema
+(`rule.schema.json`) additionally sets `maxLength: 190`.
 
 ```yaml
 # Bad — describes content, won't match reliably:
@@ -185,7 +187,7 @@ diffing the full lint output. See
 ```yaml
 ---
 type: "auto"              # or "always"
-description: "Trigger-shaped sentence — domain + symptoms — soft cap 200 chars"
+description: "Trigger-shaped sentence — domain + symptoms — schema max 190 chars"
 alwaysApply: false        # true only if type: always
 source: package           # or project for consumer-local rules
 load_context:             # logical names only — `contexts/<area>/<file>.md`

package/dist/agent-src/skills/skill-reviewer/SKILL.md

@@ -90,7 +90,7 @@ The highest-signal content in a skill. Documents failure patterns.
 
 Skill exceeds size limits (see `docs/guidelines/agent-infra/size-and-scope.md`).
 
-**Check:** Review at >300 lines. Strongly consider split at >1200 words / >1500 words.
+**Check:** Review at >400 lines. Strongly consider split at >1200 words / >1500 words.
 **Fix:** Extract reference tables, templates, and examples into separate files
 in the skill folder, or split by responsibility.
 

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

@@ -158,8 +158,8 @@ generic descriptions cause **undertriggering**. Normative source:
 
 Three rules: name 2+ triggers (domains, symptoms, user phrasing), end with
 `... even if they don't explicitly ask for \`<skill-name>\`.`, and stay
-**≤ 200 characters** (`skill_linter.ts` warns `description_too_long` above
-that). When trimming to fit, drop adjectives or the second example phrasing
+**≤ 200 characters** (`skill_linter.ts` errors `description_too_long` above
+that — a hard cap). When trimming to fit, drop adjectives or the second example phrasing
 before you drop a trigger class or the `even if ...` tail.
 
 Canonical before/after (2026-04-21 audit baseline):

package/dist/agent-src/skills/tailwind-engineer/SKILL.md

@@ -75,7 +75,9 @@ manually. Reviewer should read intent in one pass.
 
 ### 4. Extract only when duplicated ≥ 3 times
 
-The first two repetitions are noise; the third is a pattern.
+The first two repetitions of a **utility-class string** are noise; the third
+is a pattern (the utility-class row of the per-class canon,
+[`abstraction-thresholds`](../../../docs/guidelines/abstraction-thresholds.md)).
 Extract via:
 
 | Mechanism | When |

package/dist/agent-src/skills/token-optimizer/SKILL.md

@@ -62,7 +62,7 @@ INTENT
 │
 ├── Near context limit, work not finished
 │     → cite [agent-handoff](../../domains/meta/agent-handoff/command.md)
-│       (structured handoff envelope; resume in fresh chat)
+│       (session picker + generated handoff; auto-seeds the fresh chat)
 │
 ├── Cost-aware decision (model pick, budget, stop-criterion)
 │     → cite /cost:report (when shipped) — until then, fall back to
@@ -82,7 +82,7 @@ INTENT
 | `cli-output-handling` | `src/rules/cli-output-handling.md` | `verbose`, `tail`, `grep`, `CLI` | Wrap-tail-grep contract for any verbose command |
 | `rtk-output-filtering` | `src/skills/rtk-output-filtering/SKILL.md` | `rtk`, `verbose`, `filter`, `wrap` | Project-local rtk filters; wrapper command |
 | `token-efficiency` | `src/rules/token-efficiency.md` | `redirect`, `verbose`, `concise`, `tool` | Batch + parallelize tool calls; brevity floor |
-| `agent-handoff` | `src/domains/meta/agent-handoff/command.md` | `handoff`, `fresh`, `chat`, `context` | Context envelope for fresh-chat continuation |
+| `agent-handoff` | `src/domains/meta/agent-handoff/command.md` | `handoff`, `fresh`, `chat`, `context`, `resume`, `session` | Session picker + generated handoff auto-seeding the next session |
 | `direct-answers` | `src/rules/direct-answers.md` | `brevity`, `flattery`, `severity`, `tiered` | Iron-Law brevity floor (kernel) |
 | `markitdown` | upstream: github.com/microsoft/markitdown | `PDF`, `DOCX`, `HTML`, `convert` | Document → markdown converter (authoritative-link only) |
 | `/cost:report` | TBD — an internal roadmap (local-only) § P1.2` | `cost`, `model spend`, `budget` | Per-session cost telemetry (planned) |

package/dist/agent-src/skills/ui-component-architect/SKILL.md

@@ -44,9 +44,12 @@ Do NOT use when:
 
 ## Componentization threshold — ≥4 repeats AND real state
 
-Extract a component only when an element **repeats ~4× or more AND carries real
-props/state**. One or two repeats, or a repeat with no varying props, is not a
-component — inline it. A long single-file body is **normal**, not a smell;
+Extract a **stateful component** only when an element **repeats ~4× or more AND
+carries real props/state** (the stateful-component bar of the per-class canon,
+[`abstraction-thresholds`](../../../docs/guidelines/abstraction-thresholds.md) —
+it does not lower the code-level two-repetition bar). One or two repeats, or a
+repeat with no varying props, is not a component — inline it (a props-only
+shell earns extraction at 3+ uses). A long single-file body is **normal**, not a smell;
 premature extraction (a "component" used once, or a pure-markup fragment split
 for tidiness) adds indirection without reuse and is the more common mistake
 than under-splitting. Meet BOTH conditions before you extract.

package/dist/agent-src/templates/agent-settings.md

@@ -558,10 +558,10 @@ the canonical narrative lives in
 
 | Key path | Values | Default | Description |
 |---|---|---|---|
-| `rule_loading_tier` | `minimal`, `balanced`, `full`, `custom` | `minimal` | Selects which agent surfaces are active. See [Cost profiles](#cost-profiles). |
+| `rule_loading_tier` | `minimal`, `balanced`, `full`, `custom` | `balanced` | Selects which agent surfaces are active. See [Cost profiles](#cost-profiles). |
 | `personal.ide` | `code`, `phpstorm`, `cursor` | _(empty)_ | CLI command to open files in the IDE |
 | `personal.open_edited_files` | `true`, `false` | `false` | Auto-open edited files in the IDE after edits |
-| `personal.user_name` | first name | _(empty)_ | User's first name, used to address the user personally. Captured by `/onboard`. |
+| `personal.canary_name` | first name | _(empty)_ | Per-project OVERRIDE of the name the agent addresses the user with (session-canary). The name itself lives user-globally: `identity.name` in the wizard's `settings/.agent-user.yml`, fallback `personal.canary_name` in the user-global settings. See `rules/session-canary.md`. |
 | `personal.rtk_installed` | `true`, `false` | `false` | Whether rtk (Rust Token Killer) is installed. Detected and set by `/onboard`. |
 | `personal.minimal_output` | `true`, `false` | `true` | When `true`: short bullet points during work, concise summary at end. When `false`: verbose explanations. |
 | `personal.play_by_play` | `true`, `false` | `false` | When `true`: share intermediate findings during investigation. When `false`: work silently, report only the conclusion. |
@@ -578,13 +578,11 @@ the canonical narrative lives in
 | `chat_history.max_size_kb` | integer | per profile | Max file size before overflow handling. Defaults: `minimal`→`128`, `balanced`→`256`, `full`→`512`. |
 | `chat_history.on_overflow` | `rotate`, `condense` | per profile | On overflow: `rotate` drops oldest entries; `condense` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`condense`. |
 | `chat_history.text_limits.{user,agent,tool,phase}` | integer (chars) | `user=0`, `agent=5000`, `tool=200`, `phase=200` | Per-entry-type text-length cap. `0` = verbatim, no slice. `N > 0` = collapse whitespace, slice to N chars, append `" … [+K chars]"` so the log self-reports truncation. Defaults match `DEFAULT_TEXT_LIMITS` in `scripts/chat_history.ts`. |
-| `hooks.enabled` | `true`, `false` | `false` | Master switch for the work-engine hook layer. When `false` (default) the registry stays empty and golden replay is byte-stable. See [`agents/settings/contexts/work-engine-hooks.md`](../../../agents/settings/contexts/work-engine-hooks.md). |
-| `hooks.trace` | `true`, `false` | `false` | Emit per-event trace lines on stderr. Useful for debugging; off by default because it is noisy. |
-| `hooks.halt_surface_audit` | `true`, `false` | `true` | Defense-in-depth check that every halt surfaced by the dispatcher carries the expected shape. Cheap. |
-| `hooks.state_shape_validation` | `true`, `false` | `true` | Re-run the state schema validator on `AFTER_LOAD` and `BEFORE_SAVE`. Cheap, catches drift. |
-| `hooks.directive_set_guard` | `true`, `false` | `true` | Verify the dispatcher-resolved directive set matches the input envelope intent. Cheap, catches routing drift. |
-| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via a 16-char session fingerprint, no ownership/sidecar layer. |
-| `hooks.chat_history.script` | path | `scripts/chat_history.ts` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
+| `hooks.concern_budget.{max_per_event,tier1_concerns,hard_fail}` | integer / list / `true`,`false` | `8` / `[]` / `false` | Concern budget gate for the hook dispatcher (`lint_hook_concern_budget`): caps concerns per (platform, event) cell, restricts `fail_closed: true` to the `tier1_concerns` allowlist, and `hard_fail: false` keeps the gate warn-only. |
+| `hooks.injection_scan.enabled` | `true`, `false` | `false` | PostToolUse prompt-injection scanner: scans tool output for injection signatures and warns in context (exit 2) — never blocks. |
+| `hooks.rtk_wrap.enabled` | `true`, `false` | `false` | PreToolUse RTK-wrap nudge: when `rtk` is on PATH, warns (exit 2, never blocks) to re-run a verbose CLI command wrapped with rtk. |
+| `hooks.design_slop.enabled` | `true`, `false` | `false` | PreToolUse anti-slop nudge: runs the `lint_design_slop` registry against about-to-be-written UI content and warns (exit 2, never blocks) on P0/P1 aesthetic tells. |
+| `hooks.code_graph.enabled` | `true`, `false` | `false` | PreToolUse code-graph nudge (deprecated — honest null 2026-07-28): when a code-graph index exists, warns once per session to query the graph before grep. Requires manually installing the ABI-locked parser pair. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
 | `roadmap.skip_pre_run_gate` | `true`, `false` | `true` | When `true` (default): `/roadmap:process-step\|phase\|full` skips the interactive pre-run summary and starts the loop immediately — the resolved roadmap, cadence, and council are surfaced inline so an unwanted pick can still be aborted. When `false`: the loop shows the pre-run summary with numbered options (Go / Different roadmap / Different scope / Toggle council / Abort) and waits. The gate is always shown — regardless of this flag — when the roadmap is ambiguous (multiple active, none named) or a scope / cadence conflict has no sensible default. |
 | `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap:process-step|phase|full` runs the project's quality pipeline — only relevant when `quality.local_auto_run` is `true`; when it is `false` (the default) local pipeline runs are suppressed at every cadence and remote CI is the gate. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. |
@@ -594,9 +592,9 @@ the canonical narrative lives in
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
 | `worktrees.mode` | `off`, `on`, `ask` | `ask` | Controls autonomous `git worktree` usage. `off` = skill refuses unless the user explicitly asks for a worktree that turn (then it runs); `subagent-orchestration` mode 6 falls back to mode 3. `on` = standing permission (skill skips the per-creation ask; ignore-check and clean-baseline gates still apply). `ask` = status quo — `scope-control` permission gate runs every time. |
-| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md). |
+| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. Lives in the PROJECT settings (`agent-project-settings.example.yml` § roles), not in the personal template. See [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md). |
 | `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
-| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md). |
+| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast (not in the shipped personal template — add the block when needed). Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md). |
 | `personas.ignore` | list of persona ids | `[]` | Persona ids dropped from the default cast locally. Ignored personas stay invokable via `--personas=<id>`. |
 | `onboarding.onboarded` | `true`, `false` | `false` | Whether `/onboard` has run on this project. The `onboarding-gate` rule prompts for `/onboard` when this is `false`. Missing entirely = legacy project, treated as onboarded. |
 | `commands.suggestion.enabled` | `true`, `false` | `true` | Master switch for the command-suggestion layer. `false` = the layer is silent; explicit `/commands` still work. See `rules/command-suggestion-policy.md`. |
@@ -615,8 +613,8 @@ the canonical narrative lives in
 | `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`, `/roadmap-create`). Council commands themselves are unaffected. |
 | `verbosity.post_action_reports` | `off`, `minimal`, `full` | `minimal` | Multi-line status / summary blocks after a successful action. `off` = no report; `minimal` = one-line confirmation; `full` = bullet list. |
 | `verbosity.intent_announcements` | `true`, `false` | `false` | Intent announcements ("Let me check…", "Now I will…", "Found it") in skill bodies. `false` = act and emit the result. |
-| `telegraph.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely telegraph-speak grammar applies in chat. `off` = no telegraph grammar; `prose_only` = telegraph in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = telegraph everywhere except Iron-Law literals. Compile-time toggle (`telegraph.speak`) lands in Phase 8. |
-| `telemetry.artifact_engagement.enabled` | `true`, `false` | `false` | Master switch for the artefact engagement log. Default-off; zero file IO and zero token cost when `false`. Maintainer-targeted; consumers leave it off. |
+| `telegraph.speak_scope` | `off`, `prose_only`, `aggressive` | `off` | How widely telegraph-speak grammar applies in chat. `off` = no telegraph grammar; `prose_only` = telegraph in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = telegraph everywhere except Iron-Law literals. The compile-time toggle `telegraph.speak` ships as `false` (dormant) — the projector gates the rule on `speak`, never on `speak_scope`. |
+| `telemetry.artifact_engagement.enabled` | `true`, `false` | `false` | Master switch for the artefact engagement log. Not in the shipped template — a missing `telemetry:` section means disabled (the recording rule no-ops). Default-off; zero file IO and zero token cost when `false`. Maintainer-targeted; consumers leave it off. |
 | `telemetry.artifact_engagement.granularity` | `task`, `phase-step`, `tool-call` | `task` | Boundary at which events are recorded. `tool-call` is expensive — opt-in only. |
 | `telemetry.artifact_engagement.record.consulted` | `true`, `false` | `true` | When `true`: record artefacts loaded into context. |
 | `telemetry.artifact_engagement.record.applied` | `true`, `false` | `true` | When `true`: record artefacts cited or driving a decision. |
@@ -666,8 +664,8 @@ The `rule_loading_tier` setting selects which agent surfaces are active. See
 
 | Profile | Description |
 |---|---|
-| `minimal` | Rules, skills, and commands only. **Includes the learning loop.** Default. |
-| `balanced` | `minimal` + Runtime dispatcher for skills that declare a shell command. |
+| `minimal` | Rules, skills, and commands only. **Includes the learning loop.** |
+| `balanced` | `minimal` + Runtime dispatcher for skills that declare a shell command. Default. |
 | `full` | `balanced` + Tool adapters (GitHub / Jira, read-only, opt-in). |
 | `custom` | Ignore profile — every matrix value must be set explicitly. |
 

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.16.0"
+agent_config_version: "9.18.0"
 
 # --- Project identity ---
 project:
@@ -156,7 +156,11 @@ review_routing:
 # Leave empty to fall back to inferred mode switching.
 roles:
   # One of: developer, reviewer, tester, po, incident, planner.
-  default: ""
+  # Key names match what role-mode-adherence and /mode read/write.
+  default_role: ""
+
+  # Set by /mode at runtime; empty = rule inert (no guessed mode).
+  active_role: ""
 
   # If set, the agent refuses work outside the default contract
   # until the user explicitly switches modes with `/mode <name>`.

package/dist/agent-src/templates/persona.md

@@ -14,7 +14,7 @@
 4. Pass the Unique-Questions heuristic — ≥ 3 questions that no other
    persona asks verbatim. If you cannot write three unique questions,
    the persona is redundant; drop it.
-5. Stay within the size budget: **Core ≤ 120 lines, Specialist ≤ 80 lines**.
+5. Stay within the size budget: **Core ≤ 120 lines, Specialist ≤ 100 lines** (wings 3–4: ≤ 140).
 6. Run `task sync` and `task ci` before commit.
 
 ## Template
@@ -88,7 +88,7 @@ Before considering a persona complete:
 
 - [ ] **Unique Questions heuristic** — ≥ 3 questions that no other
   persona asks verbatim. The linter enforces this.
-- [ ] **Size budget** — Core ≤ 120 lines, Specialist ≤ 80 lines.
+- [ ] **Size budget** — Core ≤ 120 lines, Specialist ≤ 100 lines (wings 3–4: ≤ 140).
 - [ ] **Portability** — no project names, domains, stacks, teams.
 - [ ] **English only** — all content in English.
 - [ ] **One sentence description** — ≤ 160 chars, starts with a voice

package/dist/agent-src/templates/roadmaps.md

@@ -6,7 +6,7 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
 
 ## Rules for Roadmaps
 
-1. **Be precise and concise.** Aim for 500–1000 lines max. If larger, split into multiple files.
+1. **Be precise and concise.** Lightweight default: ≤ 600 lines (see rule 15). Only a declared `complexity: structural` roadmap may exceed that, capped at 1000 lines — if larger, split into multiple files.
 2. **Checkboxes are mandatory, not decorative.** Every active roadmap MUST contain at least one `- [ ]` per non-intro phase. Decision tables, ICE matrices, and block-sequencing tables capture the *why*; checkboxes capture the *what to do next*. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` — the dashboard cannot count it, the next reader thinks no work is planned. Enforced by [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md) Iron Law #2.
    - **Glyph semantics:** `[ ]` open · `[x]` done · `[~]` **deferred** (planned for later — blocks silent archive per `roadmap-progress-sync` Iron Law 3) · `[-]` **cancelled** (won't do — explicit drop). Pick `[~]` vs `[-]` honestly; the former carries follow-up-roadmap obligations, the latter does not. Optional inline annotations: `<!-- deferred: reason -->` / `<!-- cancelled: reason -->` on the same line.
    - **Status is binary: `ready` (default) or `draft`.** New roadmaps are created **ready** unless the user explicitly says draft — `ready` is implicit and need not be written. Drafts declare it via frontmatter at the top of the file (`---\nstatus: draft\n---`) and are hidden from the dashboard until the flag is removed or flipped to `ready`. Use `draft` while the roadmap is still being authored, while waiting for upstream decisions, as a capture-only synthesis that has not been promoted to executable phases, or as a follow-up roadmap (see rule 17 below) that is not yet ready to surface. There are no other status values; legacy banners like `**Status: directional**` are removed.
@@ -239,6 +239,18 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     full CI pipeline — per `roadmap-ci-steps-policy` a `verify:` must not
     be a full-suite gate.
 
+24. **Ready roadmaps carry a `## Risk Register` (Gate R1).** Every
+    ready (non-draft) roadmap ends with a schema-valid Risk Register —
+    marker line (`<!-- risk-review: v1 | reviewed: YYYY-MM-DD |
+    reviewer: <id> -->`), ranked rows (most → least risky), a
+    `Mitigation` and an in-document `Anchored under` reference per row.
+    No material risks → the **exact** honest-null grammar; a bare "no
+    risks" sentence fails. Schema, staleness rule, and the grandfather
+    clause for pre-gate roadmaps:
+    [`plan-review-gates § 1`](../../docs/contracts/plan-review-gates.md).
+    `status: draft` roadmaps are exempt until flipped to ready. Enforced
+    by `lint_plan_risk_register` at pre-push + CI.
+
 ---
 
 ## Quality Gates (remote CI by default)