@event4u/agent-config 14.23.0 → 15.0.0

package/dist/agent-src/guidelines/cross-role-handoff.md

@@ -0,0 +1,127 @@
+# Cross-Role Handoff
+
+Wing-specific prose for senior-tier skills handing off across role
+boundaries. The mechanical contract — initiator → delegated(input) →
+output, lint rules, worktree boundary — lives in
+[`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md).
+This guideline covers **when a role hands off to another role**,
+**how to phrase the routing**, and the **L4 / C8 boundary**.
+
+## Wings at a glance
+
+The senior catalog spans four wings. Each wing owns a cognition
+cluster and emits artifacts the other wings can consume.
+
+| Wing | Cluster | Senior skills (anchor examples) |
+|---|---|---|
+| **1. Engineering** | Code, architecture, debugging, review | `architecture-review-lens`, `bug-analyzer`, `judge-bug-hunter`, `blast-radius-analyzer` |
+| **2. Product + Foundation** | Discovery, refinement, decisions | `po-discovery`, `refine-ticket`, `decision-record`, `rice-prioritization` |
+| **3. GTM + Growth** | Customers, comms, funnel, channels | `customer-research` (L1), `release-comms` (L2), `funnel-analysis` |
+| **4. Money + Strategy + Ops** | Unit economics, OKRs, capacity, risk | `unit-economics-modeling`, `okr-tree-modeling`, `dcf-modeling`, `risk-officer` |
+
+A handoff is **cross-role** when the initiator and the delegate live
+in different wings (or in different cognition clusters within the
+same wing). Same-cluster delegation is normal composition and does
+not need this guideline.
+
+## When to hand off
+
+A senior skill SHOULD hand off — not absorb — when any of the four
+fires:
+
+1. **Different cognition cluster.** The downstream step needs a
+   different mode of thinking (numbers vs. narrative; user vs.
+   system; risk vs. design). Absorbing it dilutes the skill.
+2. **Different artifact owner.** The output naturally lives under a
+   different role's catalog (e.g. `forecast-band.json` belongs to
+   Wing-4, not Wing-2).
+3. **Tier-mismatch risk.** Inlining the step would require
+   downgrading to a non-senior delegate; the cross-wing-handoff
+   linter blocks tier mismatches.
+4. **Re-use evidence.** The step is already cited by ≥ 2 other
+   senior skills; absorbing it duplicates cognition.
+
+If none fire, keep the step inline. Cross-role plumbing is not free.
+
+## How to phrase the handoff
+
+Two surfaces in the senior-skill template carry routing:
+
+- **`## Related Skills` § *WHEN NOT to use this*** — the routing
+  list. One bullet per peer that owns the cognition the user might
+  expect from this skill but is wrong to ask here. Format:
+  *"X is the actual question — route to [`<peer>`](../<peer>/SKILL.md)"*.
+- **`## Procedure` Composes line** — when the skill **does** call
+  another skill mid-procedure, declare it on a line beginning with
+  `Composes [`<peer>`](...)` so the linter can match the call site
+  to the delegate's `## Input` block.
+
+The delegated skill's `## Input` block names the fields the initiator
+must pass. Drift between the two is the failure the contract catches.
+
+## Decision tree
+
+```
+Need a downstream cognition step?
+├── Same wing + same cluster? → keep inline (normal composition).
+├── Different cluster, but no shipped senior peer?
+│   └── Implement inline; flag for next plate's audit (the cluster
+│       might need its own senior).
+├── Different cluster + shipped senior peer + ≥ 2 reuse citations?
+│   └── HAND OFF: declare in WHEN NOT block + Composes line.
+└── Cross-wing chain (≥ 3 senior steps, ≥ 30 min each)?
+    └── Use `subagent-orchestration` mode 6 (worktrees) per
+        cross-wing-handoff.md § 3.
+```
+
+## L4 / C8 composition boundary
+
+Council Q3 (2026-05-05) locks the disambiguation between L4
+`stakeholder-tradeoff` and the sibling C8 `code-review-multi-lens`:
+
+- **L4 fires** when a request crosses two stakeholder lenses
+  (engineering ↔ PO, PO ↔ ops, ops ↔ infra) and the trade-off is
+  **not yet code**. Output is a trade-off matrix + recommendation +
+  dissent log; the artifact is consumable by a roadmap or PR
+  description, not by a diff.
+- **C8 fires** when the request **is already code** — PR open, draft
+  branch under review, or a diff supplied as input. Output is a
+  multi-lens code review (security · architecture · tests · quality)
+  bound to file:line spans.
+- **C8 → L4 escalation.** A C8 verdict that surfaces a stakeholder
+  conflict — e.g. test-coverage judge fails but PO insists on
+  shipping — becomes **input to L4**. The escalation is one-way:
+  L4 produces the dissent log that decides whether C8's verdict
+  is overridden, with the override recorded in
+  [`decision-record`](../skills/decision-record/SKILL.md).
+
+The boundary keeps the two skills sharp — neither absorbs the other —
+and gives the agent a deterministic rule for which one to load when
+both look applicable.
+
+## Worked example
+
+A PO refining a ticket (Wing-2) hits a sentence like *"the cheapest
+acquisition channel is paid search, but only if CAC payback < 6 months"*:
+
+1. Wing-2 is the initiator (`refine-ticket`).
+2. The CAC question is Wing-4 cognition — `unit-economics-modeling`.
+3. `refine-ticket` hands off via:
+   - WHEN NOT entry: *"CAC / payback questions — route to
+     [`unit-economics-modeling`](../skills/unit-economics-modeling/SKILL.md)"*.
+   - Composes line in the procedure step that needs the answer.
+4. The delegate's `## Input` block lists the fields (channel,
+   cohort, time horizon); `refine-ticket` passes them.
+5. The output (`payback-band.md`) feeds the AC of the original ticket.
+
+No cluster collision, no tier mismatch, no untyped drift.
+
+## See also
+
+- [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md)
+  — the mechanical contract this guideline cites.
+- [`docs/contracts/context-spine.md`](../contracts/context-spine.md)
+  — orthogonal context-slot mechanism, often used together with a
+  handoff (e.g. delegate reads `team` slot the initiator opted in to).
+- `.agent-src.uncondensed/skills/subagent-orchestration/SKILL.md` § mode 6
+  — when the chain runs in fresh worktrees.

package/dist/agent-src/guidelines/design-antipatterns-triggers.json

@@ -0,0 +1,18 @@
+{
+  "description": "Routing eval for design-antipatterns guideline: should an agent pull this catalog for a given task?",
+  "should_pull": [
+    "Design a landing page for a new SaaS product",
+    "Review this UI mockup for AI-slop patterns",
+    "Create a feature card section with icons and descriptions",
+    "Generate a hero section with a big metric and supporting stats",
+    "The design looks generic — how do I make it more distinctive?",
+    "Remove the rocket emojis from the hero buttons — it looks AI-generated"
+  ],
+  "should_not_pull": [
+    "Fix the authentication bug in the login controller",
+    "Write a migration to add the user_id column to the orders table",
+    "Set up the CI pipeline for the monorepo",
+    "Draft a customer email reply for a billing issue",
+    "Analyze the test coverage for the payment module"
+  ]
+}

package/dist/agent-src/guidelines/design-antipatterns.md

@@ -0,0 +1,327 @@
+# Design Anti-Patterns — AI-Slop Catalog
+
+> Lazy-loaded reference guideline. Pull this before proposing, generating, or
+> reviewing any UI. Used by `design-intelligence`, `fe-design`, `design-review`,
+> `existing-ui-audit`.
+
+This catalog enumerates patterns that make AI-generated UI **recognizably
+AI-generated**. Every entry carries a concrete override condition — the goal is
+not prohibition but deliberateness. A pattern on this list used *knowingly* for
+a specific brief is a design decision; used *reflexively* from a default, it is
+slop.
+
+**How to use:** Before generating UI, scan the applicable category. Flag any
+pattern you were about to reach for. Either (a) choose a different approach, or
+(b) invoke the override condition and state the reason explicitly in the brief.
+
+**Agent self-check principle:** These are guidance rules, not linter rules. The
+agent reads the brief, checks its first impulse against this catalog, and adjusts
+or overrides. The enforceable subset (contrast ratio, font-size, heading
+hierarchy, reduced-motion, focus indicator) is in `lint_design_quality`
+(Phase 5).
+
+**Who owns what (boundary — avoid drift):**
+
+| Layer | Owns | Artifact |
+|---|---|---|
+| **Guidance** | Subjective taste — Visual / Typography / Color / Layout / Copy patterns, override judgment, the originality self-test | this catalog |
+| **Enforcement** | Objective floors — Q1–Q6 (WCAG contrast, font-size, line-length, reduced-motion, heading hierarchy, focus indicator) as exit-code-2 CI | `lint_design_quality` |
+| **Detection** | Deterministic *aesthetic-tell* flags (P0–P3, rebuttable via DESIGN.md) — the pattern-detectable subset of the entries below | `lint_design_slop` |
+| **Audit method** | HOW to test WCAG (keyboard nav, ARIA, screen-reader procedures) | `accessibility-auditor` |
+| **Stack manifestation** | Concrete Tailwind class / hex bans, shadcn defaults | `tailwind-engineer`, `react-shadcn-ui` (per `framework-neutrality-in-generic-skills`) |
+| **Register** | Brand mode vs product mode — which patterns apply | `docs/guidelines/design-modes.md` |
+
+This catalog is the canonical *index*; it states the pattern stack-agnostically.
+The stack-specific bans live in the apply skills and link back here by entry ID.
+The objective floors are cited from the linter, never re-eyeballed by an agent.
+
+**Deterministic detector backing** (`lint_design_slop`, dependency-free, zero
+runtime token cost): a pattern-detectable subset of these entries has a
+deterministic rule that `design-review` cites instead of re-deriving (rule ids
+`slop-<id>-*`, registry in `src/scripts/design_slop_rules.ts`). These are
+**flags / rebuttable presumptions**, never hard blocks — a consumer `DESIGN.md`
+that declares the pattern as intentional suppresses the flag.
+
+Which entries those are is **not** enumerated here. The enumeration lives in
+[§ Detector status](#detector-status) below, where every entry carries exactly
+one status and `lint_design_antipattern_parity` checks the `backed` rows against
+the registry on every run. A second hand-maintained list in this paragraph is
+precisely the drift the gate exists to prevent, so there is only one.
+
+## Current-generation tells (generation-dated — review 2026-Q4)
+
+Default-template signatures rotate as model defaults rotate; naming the
+*current* one is more actionable than a timeless list. The entries below stay
+in their own categories — this section only tracks which combination reads as
+*this year's* generated default, so the first-impulse check has one dated
+pointer instead of a scattered mental list. As of **2026-07**:
+
+- **This generation — "warm editorial":** cream/sand background + serif display
+  + brass/clay/terracotta accent (catalog **C5** + **T2** + **T7** Instrument
+  Serif). This is now the reflexive "sophisticated / premium" reach — exactly
+  the role the purple/cyan gradient played for the previous generation.
+- **Previous generation — "gradient dark":** purple/violet + cyan-on-dark with
+  gradient text (**C1** + **C2**). Still a tell, now dated rather than current.
+
+**Review trigger:** re-confirm this section whenever a new frontier-model
+generation ships a visibly different default aesthetic. It is a *when-does-it-
+rotate* note, not a new pattern — never add a tell here that lacks a catalog
+entry in the sections below.
+
+### The three census columns — class, remediation, verification
+
+`Class` says what KIND of rule an entry is; **status** (§ Detector status) says
+how its enforcement is wired. The two axes are independent, and a reader who
+conflates them draws the wrong conclusion in both directions: a `floor` may be
+`judgment-only` because nothing can detect it yet, and a `style-preference` may
+be `backed` because it happens to be trivially greppable. Detectability is not
+authority.
+
+- **Class** — one of `floor` (an objective threshold, accessibility or
+  correctness) · `invariant` (a structural rule that must hold) ·
+  `craft-presumption` (a default a competent designer usually follows,
+  overridable on evidence) · `style-preference` (taste) ·
+  `reference-constraint` (bound to a supplied reference, brand, or `DESIGN.md`).
+  The two soft classes lose to a supplied reference artifact, a coherent
+  incumbent, and a project `DESIGN.md` — asserted on the resolver in
+  `src/scripts/_lib/ui_authority.ts` rather than stated here as prose.
+- **Remediation** — the order to try, worst-first: `delete` before `reduce`
+  before `retune`, with `replace` where the pattern has a direct substitute.
+- **Verification** — how a fix is checked: `static` (readable from the source)
+  · `render` (needs the rendered surface) · `feel` (perceptual, per the `feel`
+  evidence type in `docs/contracts/evidence-artifact-types.md`) · `judgment`.
+
+### Consistency Locks & layout caps (taste-dials roadmap)
+
+Within-project invariants + repetition caps. Override = declare the value in
+`DESIGN.md` (`## Consistency Locks` / a brutalist or uniform-grid style note).
+
+| # | Pattern | Why it reads as AI-generated | Override condition | Class | Remediation | Verification |
+|---|---|---|---|---|---|---|
+| V8 | Shape Lock — ≥ 4 distinct corner-radius scales in one surface | A fragmented radius system reads as no shape decision | Declare the radius scale in `DESIGN.md`; a genuine multi-tier scale documents each tier | invariant | reduce → retune | static |
+| C6 | Colour Lock — ≥ 3 distinct saturated accent hue families | No single accent identity; reads as default-palette sprawl | Brand genuinely uses a multi-accent system, declared in `DESIGN.md` / `brand-to-tokens` | invariant | reduce → retune | static |
+| C7 | Theme inversion — a light island mid-dark surface (or vice versa) not driven by the theme system | Mid-surface inversion breaks the theme rhythm | Intentional inverted callout with a documented reason — **judgment-only**, design-review calls it (deterministic detection is unreliable) | craft-presumption | delete → retune | judgment |
+| L9 | Section monotony — ≥ 8 sections, < 4 distinct layout families | Uniform section rhythm collapses scannability | Deliberately uniform grid (e.g. a gallery), declared as such | craft-presumption | retune | render |
+| L10 | Zigzag — > 2 consecutive image-left/text-right two-column sections | The alternating-zigzag landing-page tell | A genuinely sequenced walkthrough where alternation aids comprehension | craft-presumption | delete → retune | static |
+
+---
+
+## Visual
+
+| # | Pattern | Why it reads as AI-generated | Override condition | Class | Remediation | Verification |
+|---|---|---|---|---|---|---|
+| V1 | A colored accent border above 1px — the side stripe (`border-left` / `border-right`), a fully colored border on all four sides, or a gradient `border-image` | The single most recognizable AI-UI signature; every scaffold-default card uses it. Widened 2026-09-03: the side stripe was the 2024 form, the four-sided colored or gradient card border is the current one, and the entry as written reached only the first | Brand token explicitly defines the accent border; document the decision in the design brief. A 1px neutral border, a `border-color`-only focus treatment, and `transparent` / `currentColor` at any width are not accents and do not flag | craft-presumption | delete → retune | static |
+| V2 | Glassmorphism as decoration (`backdrop-blur` + `bg-white/10`) with no functional depth hierarchy | Model defaults to it for "premium feel"; result looks like 2021 Material You clip-art | Element genuinely sits above a complex, blurred background layer; use sparingly and only for top-level floating surfaces | craft-presumption | delete → reduce | static |
+| V3 | Ghost card: `border: 1px solid` + box-shadow ≥ 16px spread together | The combination creates visual noise — the ghost card signals no confident decision about depth | Choose either border OR shadow to indicate depth; never both on the same surface | invariant | delete → reduce | static |
+| V4 | Over-rounded small cards or badges: `border-radius` > 16px on elements < 200px wide | Excessive rounding on small surfaces looks toy-ish; standard cap is 12–16px | Pill shape (`border-radius: 9999px`) is intentional on single-line tags/chips only | craft-presumption | retune | static |
+| V5 | Hand-drawn or illustrated SVG icons mixed with crisp icon-system icons | Visual register collision; instantly reads as "generated asset" | Intentional illustrative section (hero illustration, empty-state art); isolate from the icon system | invariant | replace | render |
+| V6 | Repeating diagonal stripes as a background texture | A cliché background default; reads as generated CSS art | Brand explicitly uses pattern backgrounds (e.g., a textile brand); document the stripe definition | style-preference | delete | static |
+| V7 | Nested cards: a card inside a card inside a card | Depth hierarchy collapses; user cannot parse elevation intent | A truly three-level hierarchy (e.g., project → board → card); ensure each level has distinct visual weight | invariant | delete → reduce | render |
+| V9 | Noise or grain texture laid over a gradient as a "premium" surface default | The visual sibling of V6's diagonal stripes — a generated-CSS-art texture reached for to make a flat gradient look considered, applied because it is available rather than because the surface needed a texture | The texture is part of a documented brand surface treatment (a print-inspired or analog-photographic identity) with the grain opacity defined as a token, not chosen per surface | style-preference | delete | render |
+
+---
+
+## Typography
+
+| # | Pattern | Why it reads as AI-generated | Override condition | Class | Remediation | Verification |
+|---|---|---|---|---|---|---|
+| T1 | Flat type hierarchy: body and headings use the same optical weight and nearly the same size | Type hierarchy is invisible; user cannot scan the page | Deliberately minimal aesthetic where all text is body-weight; must be an explicit brand decision | craft-presumption | retune | render |
+| T2 | Oversized italic serif as the primary hero headline | The "AI startup landing page" template; seen on ~60% of AI-generated marketing pages | Brand adopts editorial-magazine aesthetic with a documented italic serif rationale | style-preference | replace | render |
+| T3 | Icon tile (small rounded-square container) above heading | The universal AI feature-card template; reads as scaffold | Listed features genuinely benefit from visual-icon-then-title affordance AND the icons are custom, not library defaults | style-preference | delete | static |
+| T4 | Eyebrow / ALL-CAPS label above every section heading | Overuse collapses the emphasis; maximum is 1 eyebrow per 3 sections (countable: grep tracking classes) | Used for genuine section-type differentiation with meaningful vocabulary (not just "FEATURES", "PRICING") | craft-presumption | delete → reduce | static |
+| T5 | Repeated section kickers ("Our mission", "What we offer", "Why choose us") | Filler vocabulary; every AI-generated page has the same three section titles | Every kicker is substantive and uses brand-specific vocabulary, not generic marketing speak | craft-presumption | replace | judgment |
+| T6 | Crushed letter-spacing on display text (`letter-spacing` < −0.04em) | Below −0.04em glyphs collide optically; reads as "designer-ish effect" with no grounding | Intentional tight display treatment with a documented minimum floor; verify at the actual render size | floor | retune | static |
+| T7 | Overused fonts without a stated reason: Inter, Roboto, DM Sans, Geist, Space Grotesk, Instrument Serif | These are the default AI-coding-tool font picks; every generated UI uses one of them | **Register-scoped.** In the **brand** register: the brand has explicitly adopted one of these AND there is a documented reason. In the **product** register: a single reliable family is the sanctioned strategy ([`design-modes`](design-modes.md) § The two registers), so one of these is legitimate on a **stated** product-register choice — the register itself is the reason, and it must be stated (DESIGN.md, the surface brief, or `design-slop-disable`). Neither register admits an *undeclared* pick. | reference-constraint | replace | judgment |
+| T8 | Single typeface for everything | Missed typographic contrast opportunity; in the **brand** register an unexamined single family reads as "I did not think about fonts" | **Register-scoped like T7.** Intentional mono-typeface aesthetic (e.g., terminal-inspired), stated in the brief — *or* the **product** register, where one reliable family is the sanctioned strategy ([`design-modes`](design-modes.md) § The two registers) and contrast is carried by weight and scale rather than by a second family. | reference-constraint | retune | judgment |
+| T9 | All-caps body paragraphs or field labels | Reduces legibility below WCAG AA for sustained reading; reads as flair over function | Short UI labels (e.g., button text in a brutalist layout); never for body paragraphs | floor | delete → retune | static |
+| T10 | Wide letter-spacing on body text (`letter-spacing` > 0.05em) | Reduces readability for sustained reading; reserved for display use | Display text (headlines, pull quotes) where intentional tracking is a brand element | craft-presumption | retune | static |
+
+---
+
+## Color
+
+| # | Pattern | Why it reads as AI-generated | Override condition | Class | Remediation | Verification |
+|---|---|---|---|---|---|---|
+| C1 | Purple/violet + cyan-on-dark palette as the primary scheme | The most recognizable AI-UI color combination in 2024–2026; instantly signals "generated" | Brand color system genuinely defines a violet primary; must come from `brand-to-tokens`, not from model defaults | style-preference | replace | static |
+| C2 | Gradient text via `background-clip: text` as a primary accent | Overused to the point of invisibility; also has rendering edge cases on some platforms | Headline treatment in a brand that explicitly uses gradient identity (e.g., a product whose logo is a gradient) | style-preference | delete | static |
+| C3 | Glowing colored accents on dark mode (bright neon `box-shadow` or `text-shadow`) | Looks like a 2020 gaming UI; reads as an AI attempt at "moody" | Brand explicitly defines neon accents with a documented usage rule (e.g., error or alert states in a security product) | style-preference | delete → reduce | static |
+| C4 | Gray text on colored background without WCAG AA check | Muted gray chosen for "elegance" often fails 4.5:1 contrast; the failure is invisible until audited | Any use — always verify the contrast ratio; if it fails, either darken the text or lighten/darken the background | floor | retune | static |
+| C5 | Cream/sand body background (OKLCH L 0.84–0.97, C < 0.06) with brass/clay/oxblood accents | The 2025 "premium-consumer" AI palette; every generated "sophisticated" product uses this exact combination | Brand has an explicit warm-neutral design language documented in `brand-to-tokens`; the palette is first-party, not a default reach | style-preference | replace | static |
+
+---
+
+## Layout
+
+| # | Pattern | Why it reads as AI-generated | Override condition | Class | Remediation | Verification |
+|---|---|---|---|---|---|---|
+| L1 | Hero metric template: giant number, small label, 3–4 stats in a row, gradient | The default SaaS dashboard hero; appears on ~70% of AI-generated dashboard screens | Data storytelling genuinely requires a primary metric with supporting context; must vary the arrangement | craft-presumption | retune | render |
+| L2 | Three identical feature cards in a grid with the same visual weight | The scaffold-default; no visual rhythm, no hierarchy among features | Product genuinely has three equally weighted features; must still vary padding, or use a different composition | craft-presumption | retune | render |
+| L3 | Monotonous spacing: one spacing value (usually 24px) used for everything | Spacing is rhythm; uniform spacing collapses the hierarchy of proximity | Intentional grid where every element has equal weight; must document the grid definition | craft-presumption | retune | static |
+| L4 | Numbered section markers (01 / 02 / 03) as a primary section-order device | Universal AI-generated marketing page tell; seen on virtually every generated landing page | A genuinely numbered process or sequenced guide where the step number carries meaning beyond decoration | style-preference | delete | static |
+| L5 | Line length > 80ch in body copy without column constraint | Reduces readability; WCAG recommends 45–75 characters; beyond 80 the eye struggles to track | Data-dense dashboards where column width is driven by tabular data, not narrative text | floor | retune | render |
+| L6 | `position: absolute` dropdown inside `overflow: hidden` container | Dropdown clips; a common AI-generated layout bug | Refactor: use `<dialog>`, the Popover API, or `position: fixed` / portal to escape the stacking context | invariant | replace | render |
+| L7 | Content that overflows its container | Text truncation or reflow failures at non-default viewport widths; reads as untested | Never acceptable in production output; test at 320px, 768px, 1280px minimally | invariant | retune | render |
+| L8 | Z-index values of 99, 999, 9999 without a semantic z-index scale | Magic numbers; the first time two elements compete, the scale breaks | Establish a named semantic z-index scale (`--z-modal: 400`, `--z-toast: 500`, etc.) and use it | invariant | replace | static |
+
+---
+
+## Motion
+
+| # | Pattern | Why it reads as AI-generated | Override condition | Class | Remediation | Verification |
+|---|---|---|---|---|---|---|
+| M1 | Bounce or elastic easing curves on UI elements | Bounce draws attention to the animation itself; UI motion should serve the action, not perform | Intentional playful affordance (game UI, onboarding celebration state); must be brief and non-repeating | invariant | replace | feel |
+| M2 | Animating layout properties (width, height, top, left, padding) | Triggers browser layout recalculation; janky on mid-range devices; always solvable with `transform` | Never — use `transform: scaleX()` for width-like effects, `transform: translateY()` for position | floor | replace | static |
+| M3 | Animating `<img>` element on hover (scale, filter, transform) | Triggers composite + image decode; often causes content shift | Animate the card's background, border, or shadow instead; leave the image static | invariant | replace | render |
+| M4 | `transition: all` shorthand | Animates every property including layout, color, opacity simultaneously; unpredictable and expensive | Enumerate only the properties that should animate: `transition: transform 200ms ease-out, opacity 200ms` | invariant | replace | static |
+| M5 | Missing `@media (prefers-reduced-motion: reduce)` alternative for any animation | Accessibility violation; vestibular disorders make animated UI unusable | Never acceptable; always add a `prefers-reduced-motion` variant — gentler animation (reduced distance/opacity) is preferred over `display: none` | floor | delete → retune | static |
+| M6 | Every section fading and rising into view on scroll | The most recognisable interaction tell of the current generation; a reveal applied per section carries no information — the reader has already scrolled to the content, so the animation delays what they asked for | The reveal carries meaning: a stepped narrative where each beat must land before the next, or a long-form article using position to signal progress. A reveal on *every* section is a default, not a decision | craft-presumption | delete → reduce | feel |
+| M7 | A radial highlight tracking the pointer across a dark hero | A `mousemove` handler feeding a radial gradient; it draws the eye to the cursor, which is the one thing on the page the user already knows the position of | The spotlight is the interaction — a genuine reveal mechanic, a canvas inspection tool, an accessibility magnifier. Ambience is not a purpose | style-preference | delete | feel |
+| M8 | An interactive control that reduces its own opacity on hover | Reads as the element retreating from the pointer rather than responding to it, and a fade is the one hover treatment that *reduces* legibility at the moment the user is committing to the target — see the six interaction states in [`design-review`](../skills/design-review/SKILL.md) | The fade communicates a real state change (an item being dismissed, a layer being peeled back). Hover must stay legible; brightness, background or border carry hover without spending contrast | craft-presumption | retune | feel |
+
+---
+
+## Copy
+
+| # | Pattern | Why it reads as AI-generated | Override condition | Class | Remediation | Verification |
+|---|---|---|---|---|---|---|
+| CP1 | Em-dash (`—`) overuse | The #1 syntactic LLM signature; appears in AI copy at 3–5× the frequency of human editorial copy; maximum 2 per 500 words | Specific editorial voice that uses em-dashes deliberately; count them before shipping | craft-presumption | delete → reduce | static |
+| CP2 | Marketing buzzwords: streamline, empower, supercharge, world-class, enterprise-grade, seamlessly, robust, leverage | These words carry no information; an AI-slop test: replace each with nothing — the sentence still communicates the same thing | No override; if a word can be deleted without loss, delete it | craft-presumption | delete | static |
+| CP3 | Aphoristic manufactured contrast ("We don't do X. We do Y." / "Not just A, but B.") | A generated sentence rhythm that sounds like brand writing but carries no specificity | Aphoristic copy is legitimate when the contrast reveals a genuine product distinction; test by asking whether the Y side says something concrete | style-preference | delete → replace | judgment |
+| CP4 | "Theater" framing — copy that announces what the product does without saying how or why | "The platform for modern teams." communicates nothing; it is content-shaped noise | Every tagline must pass the "so what" test: can a skeptic follow it with "but how?" and get a concrete answer? | craft-presumption | replace | judgment |
+| CP5 | Emoji-decoration in UI markup — 🚀/✅/🎉 prepending headings, buttons, list items, or CTAs (`🚀 Get Started`) | Performative-enthusiasm coating; the default-startup-template tell. No emoji is better than decorative emoji | Brand/`DESIGN.md` declares a systematic emoji strategy, or the emoji is functional (status indicator, category marker tied to real meaning) | craft-presumption | delete | static |
+| CP6 | Stock render subject named instead of the product's own subject matter — "floating abstract shapes", "gradient mesh", "glowing orb", "particle field", "futuristic HUD" | These name the default thing a render becomes when nobody decided what it is about; same delete-test as CP2, applied to art direction — swap the phrase for what the product actually shows and the brief says more | The subject IS abstract by decision (a generative-art surface, a data-driven field whose data is named), and the brief says which decision and why | craft-presumption | replace | judgment |
+
+---
+
+## Quality floors — measurable thresholds
+
+These are not stylistic — they are objective quality failures detectable without
+aesthetic judgment. The `lint_design_quality` CI linter enforces a subset of
+these. The rest are agent self-checks.
+
+| # | Threshold | Measurement | CI-enforced? |
+|---|---|---|---|
+| Q1 | Text contrast ≥ 4.5:1 normal / ≥ 3:1 large text (WCAG AA) | `contrastRatio(text, bg) < threshold` | Yes (`lint_design_quality`) |
+| Q2 | Body `font-size` ≥ 14px (floor); ≥ 16px strongly preferred | Computed `font-size` on `p`, `li`, `td` | Yes |
+| Q3 | Line length ≤ 75 characters (prose) | Character count before soft wrap | Yes |
+| Q4 | All `@keyframes` / `animation` have a `prefers-reduced-motion` alternative | CSS `@media` check | Yes |
+| Q5 | Heading levels not skipped (h1→h3 direct, not h1→h4) | DOM heading sequence | Yes |
+| Q6 | All interactive elements have a `:focus-visible` indicator | CSS rule check | Yes |
+| Q7 | Display `letter-spacing` floor: ≥ −0.04em (tighter reads cramped) | Computed tracking | Agent self-check |
+| Q8 | `line-height` ≥ 1.3 on body text | Computed `line-height` | Agent self-check |
+| Q9 | Small-card `border-radius` cap: 12–16px (not 24px+) | Computed `border-radius` on elements < 200px | Agent self-check |
+| Q10 | Body background: avoid OKLCH L 0.84–0.97, C < 0.06 (cream/sand) unless brand-defined | Color space calculation | Agent self-check |
+| Q11 | Padding floors: ≥ 8px (inline elements), ≥ 16px (card/panel bodies) | Computed padding | Agent self-check |
+| Q12 | Justified text only with CSS hyphenation (`hyphens: auto`) | Presence of `text-align: justify` without `hyphens` | Agent self-check |
+| Q13 | Outward-artifact hygiene: no system internals — absolute workspace paths, skill/tool names, generator traces, config keys — in comments, metadata, or EXIF of deliverables that leave the workspace (HTML decks, prototypes, exports), unless the user asks for build provenance | Comment/metadata scan of the emitted artifact | Agent self-check |
+
+Q13 is **output hygiene only** — it never restricts chat-side transparency to
+the operator (what skills/tools ran stays fully answerable in conversation).
+Converged via council (claude-sonnet-4-5 + gpt-4o, 2026-07-06): shared floor
+here, referenced by artifact-producing skills, deliberately not a PII-rule
+extension. Deterministic detection in `lint_design_slop` (path/trace grep) is
+possible but deferred until a real incident.
+
+---
+
+## Detector status
+
+Every catalog entry above carries exactly one status. This table is the single
+enumeration of what the deterministic detector covers, and
+`src/scripts/lint_design_antipattern_parity.ts` checks it on every CI run: a
+`backed` row whose id is not in the registry fails, a registry rule whose
+`catalogId` is not `backed` here fails, and an entry missing from this table
+fails. `Q*` floors are excluded — they are owned by `lint_design_quality` and
+are listed in § Quality floors.
+
+| Status | Meaning |
+|---|---|
+| `backed` | a deterministic rule exists in `design_slop_rules.ts` |
+| `floor` | measurable and enforced, but as a `Q*` objective floor in `lint_design_quality`, not as an aesthetic tell |
+| `judgment-only` | needs structural or aesthetic judgment a text pass cannot make; `design-review` decides it |
+| `deferred` | pattern-detectable but a design-system opinion rather than a floor; deliberately not shipped |
+| `candidate` | a numeric threshold stated in the entry, not yet detected — a status that must resolve to `backed` or `judgment-only`, never persist |
+
+| Entry | Status | Note |
+|---|---|---|
+| V1 | backed | |
+| V2 | judgment-only | decoration-vs-intent is the tell; a text pass cannot read intent |
+| V3 | backed | |
+| V4 | backed | |
+| V5 | judgment-only | icon register collision is a visual-style comparison |
+| V6 | backed | |
+| V7 | judgment-only | DOM-structure nesting depth, measured too false-positive-prone |
+| V8 | backed | |
+| V9 | judgment-only | texture-over-gradient is a compositional judgment, and the pre-registered clean corpus contains no grain-over-gradient near-miss, so an M1 = 0 for a detector here would be a vacuous pass rather than measured precision |
+| C1 | judgment-only | the tell is the combination *as the primary scheme*; which colours are primary is a judgment |
+| C2 | backed | |
+| C3 | backed | |
+| C4 | floor | WCAG contrast, Q1 |
+| C5 | backed | |
+| C6 | judgment-only | demoted 2026-08-13 at M1 = 4 of 32 clean files; the rule counted every saturated hue, so one accent plus a semantic danger colour reached its threshold — which is correct design, not the tell this entry describes |
+| C7 | judgment-only | theme inversion may be deliberate emphasis |
+| T1 | judgment-only | requires comparing optical weight across the document |
+| T2 | judgment-only | requires knowing which element is the hero |
+| T3 | judgment-only | icon-tile stack; DOM-structure analysis, too false-positive-prone |
+| T4 | backed | |
+| T5 | judgment-only | copy phrase-list; that mechanism is council-rejected |
+| T6 | backed | |
+| T7 | backed | |
+| T8 | deferred | typeface count is a design-system opinion, not a floor |
+| T9 | backed | |
+| T10 | backed | |
+| L1 | judgment-only | composite structural template |
+| L2 | judgment-only | three-identical-card grid; DOM-structure analysis |
+| L3 | deferred | spacing-multiple uniformity is a design-system opinion |
+| L4 | backed | |
+| L5 | floor | line length, Q3 |
+| L6 | judgment-only | requires an ancestor relation a flat text pass cannot establish |
+| L7 | judgment-only | requires a render |
+| L8 | backed | |
+| L9 | backed | |
+| L10 | backed | |
+| M1 | backed | |
+| M2 | backed | |
+| M3 | backed | |
+| M4 | backed | |
+| M5 | floor | reduced-motion alternative, Q4 |
+| M6 | judgment-only | two independent reasons, both measured: the scanner classifies no engine for plain `.ts` / `.js` (`lint_design_slop.ts` § enginesForExt), which is where a reveal hook normally lives; and the clean corpus contains zero `IntersectionObserver`, so an M1 = 0 would measure nothing. Promotion needs both closed first: a corpus carrying a legitimate near-miss for the signal, and a recorded decision on whether the scanner reaches `.ts` / `.js` |
+| M7 | judgment-only | same two reasons as M6: no engine for `.ts` / `.js`, and zero `mousemove` and zero `radial-gradient` in the clean corpus |
+| M8 | judgment-only | the corpus carries no `:hover { opacity }` at all, and its only `opacity` occurrences sit inside a `@keyframes` block, so it cannot separate a hover fade from a legitimate transition |
+| CP1 | backed | |
+| CP2 | backed | |
+| CP3 | judgment-only | copy phrase-list; that mechanism is council-rejected |
+| CP4 | judgment-only | copy phrase-list; that mechanism is council-rejected |
+| CP5 | backed | |
+| CP6 | backed | copy-engine phrase list, same mechanism as CP2; a CSS engine cannot see subject matter |
+
+---
+
+## The AI-slop originality self-test
+
+Before finalizing any UI design, run this two-tier check:
+
+1. **Category test:** Could someone guess the aesthetic from the product
+   category alone? (e.g., "SaaS → dark mode + purple gradient" /
+   "fintech → navy + gold" / "health → teal + rounded sans"). If yes,
+   rework the concept.
+
+2. **Anti-reference test:** Could someone still guess it after knowing the
+   category AND having seen 3 references you explicitly avoided? If yes,
+   dig deeper. A direction that is merely "not the worst cliché" is still
+   a cliché.
+
+The bar: a visitor should ask "how was this made?", not "which AI made this?"
+
+---
+
+## See also
+
+- `design-intelligence` — corpus-grounded style/color/typography selection
+- `fe-design` — stack-agnostic heuristics (form, table, responsive, a11y)
+- `design-review` — structured UI/UX review methodology
+- `existing-ui-audit` — mandatory pre-step: inventory before designing
+- `fe-design` § Motion — animation heuristics (should-it, which-easing, how-long), and the home of the interaction-layer guidance M6 and M8 name. Corrected 2026-09-03: this line used to point at `motion-choreographer`, which is a text-to-video prompt builder (`packs: [ai-video]`) and carries none of what the line described
+- `typography-system` — modular-scale construction and pairing
+- `accessibility-auditor` — WCAG audit method
+- `brand-to-tokens` — first-party brand token extraction (the legitimate override source for most anti-patterns above)

package/dist/agent-src/guidelines/design-asset-discipline.md

@@ -0,0 +1,38 @@
+# Design Assets & Imagery — ownership, delivery, honesty
+
+> What a visual artifact may ship as an asset, who delivers it, and what counts as fabricated evidence
+
+_Split out of [`design-fidelity-mechanics`](design-fidelity-mechanics.md) § Asset & imagery discipline, which carries the obligation surface and routes here. The split is the per-file depth ceiling doing its job, exactly as it was for [`design-handover-extraction`](design-handover-extraction.md): the mechanics file crossed 16k when the artefact-maturity axis was migrated into it, and compressing this material to fit would have cost the ownership sentence ADR-205 rests on and the fixture ids that make each bullet falsifiable._
+
+Visual artifacts carry **real assets or honest placeholders — never fabricated
+brand evidence**. The design-surface instance of the no-invented-facts floor.
+
+- **Copy owned assets through the project's accepted path.** Reference or copy
+  project-owned assets (logos, icons, fonts, images) via the target project's
+  asset directory/pipeline — never hotlink a design-system's internal URL, never
+  bulk-copy a huge source folder. (fixtures: `daf-missing-asset`, `daf-external-asset-url`.)
+- **Third-party asset delivery is self-hosted by default — this section owns that
+  decision.** An asset whose delivery path crosses a third party (a webfont from
+  a font CDN, an icon set from a CDN, a hosted stylesheet) transmits the
+  **visitor's IP address** to that third party on every page view. Deliver it
+  through the target project's own route instead — the framework's font/asset
+  primitive, a bundled package, or a locally-served file. A third-party hotlink
+  is emitted **only** on an explicit consumer opt-in, and the opt-in is stated
+  with what it transmits — never chosen silently because it is the shorter line.
+  A discovery URL is not a delivery URL: keeping a font's browse/share link as
+  *where to find it* is fine. Ownership: this bullet is the single owner of the
+  third-party delivery decision ([`ADR-205`](../decisions/ADR-205-webfont-delivery-ownership.md));
+  emitters (`typography-system`, UI-apply directives, brand-asset paths) are
+  consumers and point here rather than restating it. (fixture:
+  `daf-webfont-delivery`.)
+- **Real imagery where inspection matters.** On visual pages/decks, use actual
+  product / place / object / state imagery where the image IS the proof (a
+  product screenshot, a real dashboard state). Decorative atmosphere is not proof
+  — never pass a stock-like or invented image off as the real product. An
+  invented product screenshot is fabricated evidence. (fixture: `daf-invented-screenshot`.)
+- **Icons follow the iconography floor** — no emoji-as-icon in serious UI, no
+  hand-rolled icon when a set exists; see the `iconography` skill § Iconography floor.
+- **Ask before adding material — no unrequested filler.** Never generate copy,
+  placeholder sections, or decorative blocks the user did not ask for to "complete"
+  a design. Brief silent on a region → surface the gap (`ask-when-uncertain`)
+  or leave an honest placeholder; never invent filler to fill space.

package/dist/agent-src/guidelines/design-canon.md

@@ -0,0 +1,63 @@
+# Design Canon — named-systems grounding index
+
+> Lazy-loaded reference. Pull this when a brief names (or a project's
+> `components.json`/deps signal) a published design system, type, or colour
+> reference — so the design is **grounded in named canon**, not improvised.
+> Used by `design-intelligence`; cross-linked from `typography-system`,
+> `iconography`, `design-tokens`, `brand-to-tokens`, `icon-consistency`.
+
+This is a thin **index** — names, one-line summaries, and a "pull this when"
+trigger. It deliberately does **not** bundle the multi-megabyte specs; fetch
+the live spec only when the trigger fires (the canonical URLs below are the
+fetch targets). Precedence (per `brand-source-of-truth`): **consumer brand
+tokens > confirmed session decisions > named canon (this index) > generated
+corpus.** Canon is a gap-filler, never an override of a registered brand value.
+
+## Design systems
+
+| System | Signature traits (one-line) | Pull this when |
+|---|---|---|
+| **Material 3** (Google) | Dynamic colour from a seed (HCT), tonal palettes, elevation by tint not shadow, expressive motion (emphasized easing). | brief says "Material" / "Android"; deps `@mui/material`, `@angular/material`, `react-native-paper`. Spec: m3.material.io |
+| **Apple HIG** | Platform-native clarity/deference/depth, SF type + Dynamic Type, system materials/vibrancy, restrained motion, large touch targets. | brief targets iOS/iPadOS/macOS/visionOS, "native Apple feel". Spec: developer.apple.com/design |
+| **Fluent 2** (Microsoft) | Neutral-forward, acrylic/reveal materials, Segoe/Fluent type ramp, depth via subtle shadow, enterprise density. | brief says "Fluent"/"Windows"/"Office"; deps `@fluentui/*`. Spec: fluent2.microsoft.design |
+| **Carbon** (IBM) | 2px grid, IBM Plex type, strong data-viz system, productive vs expressive themes, accessibility-first. | brief says "Carbon"/"IBM"/data-heavy enterprise; deps `@carbon/*`. Spec: carbondesignsystem.com |
+| **Ant Design** | Dense enterprise/admin, comprehensive component set, token-based theming (v5), wireframe-driven. | brief says "Ant"/admin console/CRUD-heavy; deps `antd`. Spec: ant.design |
+| **Atlassian** | Product-suite consistency, ADS tokens, calm neutral + bold primary, strong empty/loading patterns. | brief says "Atlassian"/Jira-like; deps `@atlaskit/*`. Spec: atlassian.design |
+
+Grounding rule: surface the matching one-liner, then **offer to pull the live
+spec** before committing to the system's conventions. Never reproduce a brand
+book's marks; ground against the *system's* documented principles.
+
+## Typography craft (foundry + theory)
+
+A one-line index — point `typography-system` here; do not inline the content.
+
+- **Theory:** Butterick's *Practical Typography* (practicaltypography.com — line-length, measure, hierarchy rules), *Thinking with Type*.
+- **Calibration / "in use":** Typewolf, Fonts In Use (real pairings, not defaults).
+- **Quality foundries** (beyond the AI-default fonts the anti-slop catalog T7 flags): Klim, Lineto, Colophon, Commercial Type, Grilli Type; libre: League of Movable Type, Google Fonts (chosen deliberately, not reflexively).
+- Pull when: a brief calls for a distinctive type voice, or to escape the Inter/Roboto/Geist default.
+
+## Colour references
+
+Names + when-to-use — not the palettes themselves.
+
+- **Accessibility / contrast:** WCAG contrast checkers (e.g. APCA, WebAIM) — verify text/non-text contrast (ties to `lint_design_quality` Q1 + anti-slop C4). Pull on any colour decision that must clear AA.
+- **Culturally-specific palettes:** Nippon Colors (traditional Japanese), Chinese Colors — pull when the brand/audience is culturally situated and a Western default palette would read as generic.
+- **Systematic palette tools:** the design systems above ship their own token palettes — prefer the system's palette over an ad-hoc picker when a system is in play.
+
+## Icon systems
+
+Each design system ships a matching icon set — prefer it when that system is in
+play (consistency over novelty, per `icon-consistency`): **Material Symbols**
+(Material 3, variable weight/fill/grade), **SF Symbols** (Apple HIG, weight-
+matched to SF text), **Fluent UI System Icons** (Fluent), **Carbon icons**
+(Carbon). Outside a named system, the `iconography` skill resolves a single
+Iconify set (Lucide / Phosphor / Heroicons / Tabler) — pick one and stay in it.
+Pull when: choosing or auditing an icon library.
+
+## See also
+
+- `docs/guidelines/design-antipatterns.md` — the anti-slop catalog (T7 default-font tell, C1/C5 palette tells) this canon helps you escape.
+- `brand-source-of-truth` / `brand-consistency` — the precedence this index obeys.
+- `design-intelligence` — the consumer that surfaces these on a brief signal.
+- **Reference, don't vendor** (`domain-adoption-policy`): palette hex tables, font-width CSVs, easing/motion constant libraries, print-CSS recipes, and device-frame recipes are **referenced from maintained upstreams, never forked** into this suite — a vendored data table rots, fork-drifts, and couples the suite to one aesthetic. Corpus assets (palettes, easing tables, device frames) stay upstream references, not forks.