@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/references/skill-hygiene.md

@@ -0,0 +1,135 @@
+---
+name: skill-hygiene
+load-when: Maintaining the skill's own structural integrity — token economy, capability-menu drift, cold-start path weight, reference graph audit
+load-size-tokens: ~2,000
+required-for:
+  - Teach landings
+  - periodic hygiene cuts
+  - audit-skill-hygiene.mjs failure triage
+---
+
+# §SkillHygiene — Token / structure / drift discipline for THIS skill
+
+This section is the meta-discipline that keeps THIS skill healthy. It
+mirrors §DiagnosticOutput's posture, but turned inward: the skill is
+the substrate, the agent loading it is the consumer, and "hygiene"
+means keeping the load cost honest as the skill grows.
+
+A skill is **procedural memory loaded into agent context on demand**.
+Three irreducible mechanics gate its usefulness:
+
+1. **Token cost** — every byte enters context at retrieval time. At
+   ~78K tokens, the skill consumes ~40% of a 200K context window
+   *before the agent does any work*.
+2. **Retrieval cost** — bigger skills are harder to navigate; the
+   agent risks missing or mis-loading the right section.
+3. **Maintenance cost** — each section must stay correct as the
+   substrate evolves. Drift compounds with section count.
+
+Hygiene is the practice of paying those three costs honestly.
+
+### The eight hygiene axes
+
+Each axis has a measure, a threshold, and a remediation shape. Run
+`npm run audit:skill-hygiene` (or `node scripts/skills/audit-skill-hygiene.mjs <skill>`)
+to get the mechanical report.
+
+| # | Axis | What it measures | Soft threshold | Remediation if breached |
+|---|---|---|---|---|
+| 1 | **Token economy** | Total bytes / approx tokens | warn ≥ 250K chars (~62K tokens); error ≥ 350K (~87K) | Split section out to `references/`; archive historical content; demote inline detail to citation |
+| 2 | **Structural integrity** | H2/H3 headings inside fenced code blocks; broken anchor refs | 0 unintentional fence-leaks | Ensure template-blocks don't shadow real sections; check-links covers anchor refs |
+| 3 | **Content currency** | Version-reference distribution; ticket-ref staleness | Most-cited version within 2 minor versions of latest cited | Re-grep examples against current substrate; update or archive stale references |
+| 4 | **Reference graph** | §-section cross-refs vs orphan definitions | 0 orphan definitions; ratio refs/def ≥ 2 | Either reference an orphan from somewhere, or fold it into a referenced section |
+| 5 | **Cut velocity** | Versions shipped per day | warn > 5 cuts/day | Pause + dogfood pass; high churn = risk of unvalidated content (per the FB-37 §399 lesson) |
+| 6 | **Inline vs reference economy** | Code-block density vs repo-path citations | Subjective; flag if code-blocks dominate without grounding | When teaching a recipe, cite the canonical demo URL rather than inlining a 50-LOC block |
+| 7 | **Capability menu drift** | Items in on-load capability menu vs H2 section count | drift ≤ 5 | Menu is the cold-start surface; if it's wrong, agents don't reach 80% of the skill |
+| 8 | **Cold-start path weight** | First 5 H2 sections' total chars | warn > 30K | The first 5 sections decide the agent's mental model. Heavy cold-start = expensive first-token-cost. |
+
+### When to run
+
+- **Before any MINOR cut** (`vN.M.0` bump). The MINOR-bump checkpoint
+  is the right place — patches can land quickly, but a minor cut is
+  the moment to ask "is the skill healthier after this than before?"
+- **Weekly during high-churn arcs.** The §399 lesson: 16 cuts in one
+  day produced one validated misdiagnosis (FB-37). Velocity is itself
+  a hygiene signal.
+- **After any §CorrectionLoop session that rewrites a section.** The
+  rewrite may have grown the section; audit it specifically.
+- **Cold-start of a long-running session.** A 78K-token skill is a
+  budget decision; know the cost before committing.
+
+### Discipline rules
+
+1. **Audit is a *report*, not a *gate*.** `audit:skill-hygiene` exits 0
+   by default even with findings. Use `--strict` to fail in CI, but the
+   default posture is informational. Skills grow during arcs; the audit
+   tells the operator when growth has crossed into health-debt.
+2. **Findings rank by leverage, not severity.** "Token economy +30%
+   over threshold" is high-leverage because it affects every agent that
+   loads the skill. "1 orphan §-ref" is low-leverage because nobody
+   loses anything. Prioritize accordingly.
+3. **Soft thresholds are calibrated, not absolute.** The current
+   thresholds (in `audit-skill-hygiene.mjs:THRESHOLDS`) reflect the
+   current corpus of 16 skills. Re-calibrate when the corpus shifts.
+4. **A finding without a remediation is debt, not feedback.** When the
+   audit flags something, EITHER fix it OR write a journal-section
+   defending the carve-out. Standing findings rot into background
+   noise.
+5. **Hygiene cuts are PATCH-level (vN.M.x).** Pure reorganization,
+   citation strengthening, or content archival. New sections or
+   substantive content adds are MINOR (vN.M+1.0). Don't bundle them.
+
+### Anti-patterns
+
+- **The "everything in one file" anti-pattern.** A 78K-token monolithic
+  SKILL.md is the easy default — every new section appends. Better:
+  the bulk of detail lives in `references/<topic>.md` files that the
+  agent loads on demand via `skill_view(name, file_path)`. SKILL.md
+  itself stays focused on the procedural spine.
+- **The "historical commentary inline" anti-pattern.** Every cut adds
+  a callout: "v0.6.18's FB-10 was a real example…" These age into
+  archaeology. After a few months, move them to `references/changelog-
+  archaeology.md` or delete them.
+- **The "demonstration-by-inline-recipe" anti-pattern.** A 100-LOC
+  HTML block teaches a pattern but consumes 1000 tokens per load.
+  Better: cite the canonical demo URL + show only the 5-line
+  decision skeleton inline. The agent fetches the URL if it needs
+  the full thing.
+- **The "soft-warning bloat" anti-pattern.** Adding every dogfood
+  finding as a Pitfalls-section bullet or inline callout. Findings
+  should distill into *rules* or *examples*; raw findings belong in
+  journal entries.
+- **The "promotion without demotion" anti-pattern.** New section
+  added, old section unchanged. Skills must lose mass as they gain
+  it, or token economy degrades monotonically.
+
+### The hygiene cut shape
+
+A canonical `vN.M.x` hygiene cut:
+
+```
+- Single PATCH-level bump (no new sections; pure cleanup).
+- 0+ sections archived to references/ (with cross-link kept).
+- 0+ inline recipes demoted to citation-only.
+- 0+ stale version refs updated or removed.
+- 0 substrate changes (skill-only).
+- CHANGELOG entry titled "<axis>: <finding> resolved" or similar.
+- audit:skill-hygiene before + after numbers in the CHANGELOG.
+```
+
+Example commit subject: `skill(adia-ui-kit): v2.18.2 — hygiene pass
+(token economy: 78K → 65K tokens via reference extraction)`
+
+### Cross-references
+
+- `scripts/skills/audit-skill-hygiene.mjs` — the mechanical audit.
+- `scripts/skills/check-skill-patterns-sot.mjs` — the trip-wire for
+  §Patterns citation drift (a hygiene-axis-3 prevention gate).
+- §DiagnosticOutput — same posture, applied to consumer repos
+  instead of to this skill. The two sections cross-validate:
+  hygiene-against-self is consultant-against-others.
+- Journal §399 — the FB-37 arc that surfaced cut-velocity as a
+  hygiene axis (16 cuts shipped today, one false-positive ticket
+  among them).
+
+---

package/skills/adia-ui-kit/references/spec-to-ui-reasoning.md

@@ -0,0 +1,394 @@
+---
+name: spec-to-ui-reasoning
+load-when: User input is a PRD, spec, mockup, schema, role/user-story, feature list, or component request — i.e., any UI composition prompt that arrives BEFORE the AdiaUI primitive vocabulary is in scope. The pre-composition reasoning gate.
+load-size-tokens: ~3,200
+required-for:
+  - Mode 1-4 composition when input is PRD / spec / unstructured product intent
+  - §SpecToUi (kit mode 15) — pre-composition reasoning gate
+  - Any composition where the user has not yet named the primitives or surface shape
+companion-rubric: "agents-ux-wireframing-ascii (in core-skills-best-practices)"
+companion-skill: "ref-gen-ui-systems (the 19-rung Reasoning Ladder)"
+---
+
+# Spec-to-UI Reasoning — Pre-Composition Gate for Kit Modes 1-4
+
+> **The kit's central pre-composition pitfall:** an agent reads a PRD or spec, recognizes a few keywords ("dashboard," "settings," "triage"), and jumps directly to AdiaUI primitive vocabulary — `<admin-shell>` + `<table-ui>` + `<filter-bar-ui>`. That is **AP-01 Premature Rendering** (canonical Reasoning Ladder anti-pattern). Components emitted before intent, domain, role, task, and decision have been resolved are structurally suspect — they are pattern-matched from prompt vocabulary, not derived from user need.
+
+This reference is the kit's **Mode 1-4 specific operationalization** of two canonical specs:
+
+1. **The 19-rung Generative UI Reasoning Ladder** — authored at `~/.claude/skills/ref-gen-ui-systems/references/reasoning-ladder.md`. Defines the pipeline `InputContext → Intent → Domain → Role → Task → Decision → ExperiencePosture → InformationArchitecture → AppShell → Navigation → Surface → View → Section → Component → DataBinding → Interaction → State → Feedback → RenderPlan → Validation`.
+
+2. **The agents-ux-wireframing-ascii rubric** — authored at `~/.claude/skills/core-skills-best-practices/references/agents-ux-wireframing-ascii.md`. Defines the 5 wireframe levels, 10 scoring dimensions, canonical notation grammar, and 10 anti-patterns specific to the wireframing discipline boundary.
+
+This reference does NOT duplicate those specs. It cites them as authoritative, then adds **kit-specific extensions** the canonical specs do not cover.
+
+---
+
+## §When to load this reference
+
+Trigger phrases that fire §SpecToUi mode (kit mode 15):
+
+- **PRD / spec input**: "build a Y based on this PRD", "the spec says...", "we have a product brief that requires...", "here's the design doc"
+- **Vague brief**: "build a dashboard for X", "we need a Y interface", "users should be able to..."
+- **Mockup input**: "match this Figma", "convert this wireframe", "here's a screenshot"
+- **Schema input**: "given this data model, build UI for it", "we have these tables/entities"
+- **Role / user story input**: "as a sales manager I want...", "the user is a manager who needs to..."
+- **Feature list input**: "the screen has feature A, feature B, feature C"
+- **Component request input**: "add a table here" (only when upstream reasoning has not been resolved)
+
+If the user has already produced or signed off on a wireframe / decision spec / domain model, **skip this reference** and proceed to §0 (Reasoning Gate) + §1 (Catalog Lookup). The kit's existing pipeline starts at Rung 6 (ExperiencePosture); this reference covers Rungs 0-5 + the wireframe checkpoint between Rungs 5 and 13.
+
+---
+
+## §The pipeline (canonical, with kit anchors)
+
+```
+Tier 0: Foundation
+  Rung 0  InputContext       — Annotate raw input: known / inferred / missing / assumptions
+  Rung 1  Intent             — userGoal · businessGoal · operationalGoal · successCriteria · failureModes · scope
+
+Tier 1: Domain Reasoning
+  Rung 2  Domain             — Entities · relationships · metrics · events · permissions · freshness
+  Rung 3  Role               — uiDifferentiators (non-empty per role when multiple roles exist)
+  Rung 4  Task               — requiredInformation per task; tasks are NOT features
+  Rung 5  Decision           — requiredSignals + possibleActions (both non-empty for critical decisions)
+
+  ↓ WIREFRAME CHECKPOINT (load agents-ux-wireframing-ascii rubric) ↓
+  Tier 2 + Tier 3 produce a wireframe artifact scored against the rubric's 10 dimensions.
+  Skipping this checkpoint = AP-01 Premature Rendering at the protocol level.
+
+Tier 2: Structure  [Region + Interaction wireframes]
+  Rung 6  ExperiencePosture     — Maps to AdiaUI shell selection (table below)
+  Rung 7  InformationArchitecture — Derived from tasks, not entities
+  Rung 8  AppShell              — Selected from posture + IA (admin-shell / chat-shell / editor-shell / simple-shell)
+  Rung 9  Navigation            — Role-scoped; primary / secondary / contextual
+
+Tier 3: Surface Design  [State + Responsive wireframes]
+  Rung 10 Surface             — page / panel / drawer / modal / popover / card / toast / command-menu
+  Rung 11 View                — Route-level composition of sections
+  Rung 12 Section             — Semantic group; requires taskIds OR decisionIds
+
+  ↓ WIREFRAME OUTPUT CONTRACT (rubric Dimensions 1-5 are [gate]) ↓
+  Region layout + ownership + state coverage + responsive behavior produced
+  as a wireframe artifact BEFORE proceeding to primitive selection.
+
+Tier 4: Operational Model — kit's §0 + §1 + §2 + §3 take over from here
+  Rung 13 Component           → kit §1 Catalog Lookup + §2 Composition
+  Rung 14 DataBinding         → kit §State (references/state.md)
+  Rung 15 Interaction         → kit §2 Composition (actions, error paths)
+  Rung 16 State               → kit §State (signals, controllers)
+  Rung 17 Feedback            → kit §3 Validation (loading/empty/error per data-driven component)
+
+Tier 5: Output
+  Rung 18 RenderPlan          → kit §2 Composition output
+  Rung 19 Validation          → kit §3 Validation + §PEV verify-target table
+```
+
+**Full procedure for Rungs 0-12** — see [`~/.claude/skills/ref-gen-ui-systems/references/reasoning-ladder.md`](../../../../.claude/skills/ref-gen-ui-systems/references/reasoning-ladder.md). The rest of THIS reference covers the kit-specific mappings the canonical spec does not provide.
+
+---
+
+## §Kit-specific mapping: Shell ↔ ExperiencePosture (Rung 6 → Rung 8)
+
+The canonical Rung 6 (ExperiencePosture) defines 8 postures. AdiaUI's 4 substrate shells map onto them as follows:
+
+| Rung 6 Posture | Primary AdiaUI Shell | Secondary fit | Why |
+|---|---|---|---|
+| **monitoring** | `<admin-shell>` (sidebar + content + statusbar) | `<simple-shell>` for single-surface monitoring | Statusbar carries freshness indicators; sidebar groups areas |
+| **acting** | `<admin-shell>` (queues in page-body) | `<editor-shell>` (when actions are content-editing) | Page-body holds queues + bulk-action toolbars |
+| **analyzing** | `<admin-shell>` (charts + drilldowns) | `<editor-shell>` for canvas-style analysis | Reading-column rhythm via `<section-ui>` works for charts; full-bleed via `[data-full-bleed]` for canvas |
+| **configuring** | `<admin-shell>` (forms in page-body) | `<simple-shell>` for one-page settings | `<section-ui>` reading-column + `<field-ui>` grouping |
+| **creating** | `<editor-shell>` (canvas + toolbar + inspector) | `<chat-shell>` for AI-assisted creation | Editor toolbar + sidebar inspector + canvas |
+| **reviewing** | `<editor-shell>` (diff/approve canvas) | `<admin-shell>` (review queue + detail panel) | Diff surface + history sidebar |
+| **debugging** | `<editor-shell>` (logs/inspector canvas) | `<admin-shell>` (log queue + detail) | Inspector pattern + filterable log surface |
+| **exploring** | `<chat-shell>` (search + thread) | `<simple-shell>` for browse-without-chat | Thread surface for discovery + search input |
+
+**Multi-posture products** (monitoring + acting + analyzing combined): default to `<admin-shell>` and lean on sub-shells (`<editor-shell>` for nested creation/review surfaces).
+
+**Mistake**: choosing a shell from the prompt's keyword instead of the user's posture. "Dashboard" prompts often imply `<admin-shell>` but a single-screen KPI summary is `<simple-shell>`.
+
+---
+
+## §Kit-specific mapping: Decision ↔ Primitive (Rung 5 → Rung 13)
+
+When Rung 5 (Decision) is resolved, the canonical decision shape maps onto AdiaUI primitives:
+
+| Decision type | requiredSignals shape | possibleActions shape | Primary primitive | Verify-target |
+|---|---|---|---|---|
+| **Triage** ("which X needs action now?") | Priority field + deadline field + assignment field | assign / open detail / mark resolved | `<table-ui>` + `<row-ui>` + `<button-ui>` action menu | Row click → drawer/modal; bulk-action toolbar via `<table-toolbar-ui>` |
+| **Comparison** ("which X is best for Y?") | Multi-axis metric set | select / drill / save | `<table-ui>` (sortable) OR `<grid-ui>` of `<card-ui>` | Sort affordances + selection state |
+| **Status check** ("is X healthy?") | Aggregate metric + freshness | drill / acknowledge / alert | `<stat-ui>` + `<chart-ui>` + `<badge-ui>` | Statusbar + page-header alert region |
+| **Drilldown** ("why is X like this?") | Detail entity + related history | open / annotate / link | `<drawer-ui>` OR `<panel-ui>` + `<list-ui>` history | Drawer auto-managed via MutationObserver |
+| **Assignment** ("who should do X?") | Owner candidates + load + skill | assign / reassign / unassign | `<combobox-ui>` + `<avatar-ui>` candidates | Optimistic update + rollback path |
+| **Creation** ("make a new Y") | Required-field set + validation rules | submit / save-draft / cancel | `<form>` + `<field-ui>` + `<button-ui>` | Validation states + error path per `<field-ui>` |
+| **Configuration** ("set behavior for Z") | Setting set + scopes + permissions | save / reset / preview | `<settings-page>` shell + `<field-ui>` groups | Section-ui rhythm + dirty-state tracking |
+| **Authentication / identity** ("who am I?") | Credential set + factor | sign-in / sign-up / reset | `<auth-card-ui>` + `<field-ui>` + `<otp-input-ui>` | Per-flow path; see `references/flows-auth.md` |
+
+**Mistake**: choosing a primitive from the user's vocabulary ("they said table, so I'll use `<table-ui>`") instead of from the decision shape. A "list of things to look at" can be `<table-ui>`, `<grid-ui>` of `<card-ui>`, OR `<list-ui>` — the choice depends on whether the decision is triage (sort by priority), comparison (multi-axis), or browse (no triage).
+
+---
+
+## §Wireframe checkpoint — what to produce before primitive selection
+
+> **Wireframes contain semantic labels, NOT AdiaUI primitive vocabulary.** A wireframe with `<admin-shell>`, `<table-ui>`, or `<card-ui>` inside its boxes is collapsing Rung 8 (AppShell) + Rung 13 (Component) into a single artifact — that's AP-07 (Component collapse too early) per the canonical rubric. The wireframe is a **pre-component** structural reasoning artifact: regions, ownership, state, responsive behavior. Primitive selection happens AFTER the wireframe is scored, at Rung 13 (kit §1 Catalog Lookup).
+
+### What goes INSIDE a wireframe
+
+Use the **rubric's canonical notation grammar** (text-native, line-based, diffable):
+
+```txt
++-----+       persistent region                  Semantic labels only:
+|     |                                            "Header" "Sidebar" "Main"
++-----+                                            "Lead Queue" "KPI Strip"
+                                                   "Filter Panel" "Inspector"
+[Control]    interactive control
+{State}      data/state surface                  Annotations only:
+<Section>    semantic component (NOT AdiaUI tag)   [owns: scroll]
+                                                   [state: local]
+→            transition or flow                   {loading} {empty} {error}
+↓            focus/flow descent                   [collapse: narrow]
+...          repeated content                     ! risk: <description>
+/            responsive alternative
+!            risk or unresolved issue
+```
+
+### What stays OUT of a wireframe
+
+Wireframes never contain:
+
+- **AdiaUI tag names** — `<admin-shell>`, `<table-ui>`, `<card-ui>`, `<button-ui>` are Rung 13 vocabulary. Use semantic labels: "App shell," "Lead queue," "Filter panel," "Action."
+- **HTML markup** — no `<div>`, `<section>`, `<form>`, no attributes, no nesting syntax. Wireframes are layout AST in ASCII, not markup.
+- **CSS / styling decisions** — no colors, typography, spacing tokens, brand expression, animation. Those are Tier 5 (RenderPlan) decisions; smuggling them collapses reasoning layers.
+- **Final density / pixel measurements** — coarse spatial relationships only. Visual fidelity is design-tier work, not wireframe-tier.
+
+A wireframe that contains any of the above is no longer a wireframe — it's a partial composition pretending to be one. That's AP-08 (Prose pretending to be wireframe) at the kit-protocol level.
+
+### CORRECT vs INCORRECT — minimal worked example
+
+**CORRECT** (semantic labels, ownership annotations, state coverage):
+
+```txt
++--------------------------------------------------+
+| Header: product · search · user menu             |
++----------+---------------------------------------+
+| Sidebar  | Main [scroll: page] [owns: route]     |
+| - Inbox  | +----------------+ +-----------------+|
+| - Reports| | KPI Summary    | | SLA Risk        ||
+|          | +----------------+ +-----------------+|
+|          | +----------------------------------+ |
+|          | | Lead Queue [owns: selection]     | |
+|          | | [Filter] [Sort] [Bulk Action]    | |
+|          | | Row · Row · Row                  | |
+|          | | {empty} "No leads match filters" | |
+|          | | {error} "Could not load leads"   | |
+|          | +----------------------------------+ |
++----------+---------------------------------------+
+
+! unresolved: should filter panel persist on tablet?
+```
+
+**INCORRECT** (AdiaUI tag vocabulary leaking into the wireframe — premature component collapse):
+
+```txt
+<admin-shell>                          ← AP-07: Rung 8 vocab in wireframe
+  <admin-sidebar>                      ← AP-07: composing instead of regioning
+    <nav-item-ui>Inbox</nav-item-ui>   ← AP-07: Rung 13 primitive in wireframe
+  </admin-sidebar>
+  <admin-content>
+    <table-ui rows="...">              ← AP-07: Rung 13 primitive selected without scoring
+      <table-toolbar-ui>...</table-toolbar-ui>
+    </table-ui>
+  </admin-content>
+</admin-shell>
+```
+
+The second form skips the wireframe checkpoint entirely — it's a half-rendered composition, not a structural reasoning artifact. Score the first against the 6 [gate] rubric dimensions; if all ≥ 3/5, THEN proceed to Rung 13 (kit §1 Catalog Lookup) to convert semantic labels into AdiaUI primitives.
+
+### The 5 wireframe levels
+
+Before any AdiaUI primitive enters the composition, produce a wireframe artifact scored against the **agents-ux-wireframing-ascii rubric**. The rubric's 5 levels:
+
+| Level | When required | Output (semantic, no AdiaUI tags) |
+|---|---|---|
+| **Region** | Every Mode 1-4 composition with a shell/multi-area surface | ASCII layout: persistent regions ("Header" / "Sidebar" / "Main" / "Statusbar") + page-local regions + primary actions + scroll ownership. Semantic labels only. |
+| **Interaction** | Compositions with flows, modals, drawers, command palettes, state transitions | ASCII flow: triggers, transitions, focus movement, dismissal behavior. Use `→` / `↓` / `[Control]` / `{State}`. |
+| **State** | Every data-driven region (tables, charts, lists, forms) | Default + `{loading}` + `{empty}` + `{error}` variants minimum |
+| **Responsive** | Compositions with shells (admin / editor / chat — they collapse non-trivially) | WIDE / MEDIUM / NARROW variants showing what persists / collapses / becomes sheet/modal |
+| **Component** | Compositions handed off to multi-agent implementation OR composed of nested composites | Semantic component tree with `[owns: ...]` annotations. STILL semantic labels (`<LeadQueue owns="selection">`), NOT AdiaUI tags. AdiaUI primitive mapping happens after this level, at Rung 13. |
+
+**Minimum bar for Mode 1-4 composition**: Region + State levels. Add Interaction when the composition includes modals/drawers/command palettes. Add Responsive when shells are involved. Add Component when handing off to nested composite authoring.
+
+### Rubric's 6 gate dimensions
+
+All must be ≥ 3/5 before primitive emission ([gate] = mechanically checkable):
+
+- **D1** — Intent-to-structure traceability (every region traces to task/decision/data-group/action-group)
+- **D2** — Structural hierarchy clarity (containment unambiguous; component tree derivable)
+- **D3** — Interaction ownership (focus / selection / dismissal / mutation owners explicit)
+- **D4** — State coverage (loading + empty + error per data-driven region minimum)
+- **D5** — Responsive decomposition (wide / medium / narrow OR explicit out-of-scope marker)
+- **D9** — Reviewability and diffability (text-native, line-based, diffable — not images, not markup)
+
+### Rubric's 4 review dimensions
+
+Score for context but do not block ([review] = judgment-based):
+
+- **D6** — Density and information priority
+- **D7** — Semantic component mapping
+- **D8** — Annotation discipline
+- **D10** — Appropriate fidelity (smaller wireframes for smaller tasks)
+
+**Full rubric** — see [`~/.claude/skills/core-skills-best-practices/references/agents-ux-wireframing-ascii.md`](../../../../.claude/skills/core-skills-best-practices/references/agents-ux-wireframing-ascii.md). Includes full notation grammar, per-level worked examples, all 10 rubric anti-patterns, and 7-phase operating procedure.
+
+### Level-boundary discipline (load-bearing — easy to violate)
+
+The rubric's 5 wireframe levels are NOT interchangeable. Each uses different notation. The most common protocol-execution failure is **embedding implementation tags inside Level 1 region boxes** — see KP-04 below for the kit-specific anti-pattern. Sister skill `adia-ui-authoring` v1.7.1+ ships the same level-boundary discipline at its §Phase 2.5 (composite-demo authoring).
+
+**Per-level notation reference** (what goes inside boxes at each level):
+
+| Level | Box content uses | Examples |
+|---|---|---|
+| 1 Region | Semantic labels for what the region IS | "Plan card", "KPI strip", "Dunning banner", "Lead Queue", "Filter Panel" |
+| 2 Interaction | Arrows + semantic labels | `[Search Input] → focus → Command Menu` |
+| 3 State | Semantic labels per state | `DEFAULT` / `EMPTY` / `ERROR` headings with regions described semantically |
+| 4 Responsive | Semantic labels per breakpoint | `WIDE` / `MEDIUM` / `NARROW` with what collapses/stacks |
+| 5 Semantic Component | `<Thing>` tree form (separate artifact below Level 1) | Tree of named semantic components with ownership annotations |
+
+**Annotations consistent across levels:** `[owns: ...]`, `[Control]`, `{State}`, `[trigger: ...]`, `[commit: ...]`, `!` unresolved.
+
+**Level 5 separation rule:** the Level 5 semantic-component tree is a **SEPARATE artifact below the Level 1 region wireframe**, NOT embedded inside Level 1 boxes. Smuggling `<Thing>` syntax into Level 1 boxes collapses the reasoning prematurely AND makes the Level 1 wireframe unreadable for operator review who doesn't know the design system's tag names.
+
+### Literacy gate precondition (NEW in kit v3.7.0)
+
+When the wireframe checkpoint passes (all 6 [gate] dimensions ≥ 3/5) and the task targets the `nailed` tier of kit §PEV verify, **the next step is the literacy gate, NOT immediate primitive selection.** Load [`component-literacy.md`](component-literacy.md) before kit §1 Catalog Lookup.
+
+The literacy gate fires in conjunction with primitive selection — it forces a CSS read for each primitive AND each embedded composite BEFORE locking the selection. Sister skill `adia-ui-authoring` v1.8.0 ships the same gate as §Phase 2.5a. The artifact (`<task>.preflight.yaml`) is required for `nailed` tier of kit §PEV; optional for `structurally-verified-only`. The CSS-illiteracy postmortem (`.brain/postmortems/2026-05-24-component-css-illiteracy.md`) is the load-bearing rationale.
+
+---
+
+## §Entry-point patterns — where does the user's input enter the ladder?
+
+The canonical `entry-points.md` reference defines 7 entry-point patterns. Kit Mode 1-4 most commonly enters at:
+
+| Input shape | Enters at | Process |
+|---|---|---|
+| **PRD / product brief** | Rung 2 Domain (Intent derivable from goal + success criteria) | Extract intent → entities → roles → derive tasks from features (features ≠ tasks) → derive decisions → continue through wireframe |
+| **Vague brief** ("build a dashboard for X") | Rung 1 Intent (resolve before proceeding) | Ask 1-2 clarifying questions about user goal + success criteria → derive domain → continue |
+| **Schema / data model** | Rung 2 Domain (entities are given) | Resolve domain from schema → derive role + task + decision → wireframe → primitives |
+| **Mockup / Figma / wireframe** | Rung 13 Component (visual is given); validate upward | Read upward: what task/decision does this surface? Are the wireframe checkpoint outputs derivable? If not, the mockup is suspect. |
+| **Role + user story** | Rung 3 Role (role is given) | Resolve intent + domain → derive task from story → decision → wireframe → primitives |
+| **Feature list** | Rung 4 Task (features ≠ tasks; decompose) | "Lead inbox" is NOT a task; "triage leads to identify which need action today" is. Decompose features into tasks → decisions → primitives. |
+| **Component request** ("add a table here") | Rung 13 Component (validate upward) | Resolve task + decision the table supports BEFORE accepting the component. If upstream contradicts the table, the table changes — not the upstream. |
+
+**The Core Rule**: regardless of entry point, **validate upward before proceeding downward.** A component request at Rung 13 cannot be accepted until Rungs 1-5 are resolved. If upstream reasoning contradicts the requested component, the component changes — not the reasoning.
+
+**Full procedure for each entry pattern** — see [`~/.claude/skills/ref-gen-ui-systems/references/entry-points.md`](../../../../.claude/skills/ref-gen-ui-systems/references/entry-points.md).
+
+---
+
+## §Bridges to existing kit references
+
+Once the ladder Rungs 0-12 have produced their outputs (intent + domain + role + task + decision + wireframe), hand off to the kit's existing pipeline:
+
+| Ladder output | Kit reference | Use for |
+|---|---|---|
+| Rung 5 Decision shape | [`references/decision-model.md`](decision-model.md) | Mapping decision shape to A2UI decisions block; required-signals field map |
+| Rung 6 Posture | [`references/patterns-shells.md`](patterns-shells.md) §Shell-selection-by-posture | Shell choice rationale |
+| Rung 7 IA + Rung 8 AppShell | [`references/patterns-shells.md`](patterns-shells.md) | Admin/chat/editor/simple shell composition |
+| Rung 9 Navigation | [`references/patterns-shells.md`](patterns-shells.md) §Navigation | Sidebar nav + nav-item-ui selected state |
+| Rung 10 Surface | [`references/patterns-recipes.md`](patterns-recipes.md) + [`references/patterns-layout.md`](patterns-layout.md) | Surface taxonomy (page / panel / drawer / modal / popover / card / toast) |
+| Rung 11 View + Rung 12 Section | [`references/patterns-recipes.md`](patterns-recipes.md) | Route-level composition + section-ui rhythm |
+| Rung 13 Component | [`references/catalog-lookup.md`](catalog-lookup.md) + [`references/composition.md`](composition.md) + [`references/component-literacy.md`](component-literacy.md) (literacy gate) + the 8 `patterns-*.md` bundles | Primitive selection + composition contract + CSS-literacy precondition |
+| Rung 13.5 Phase 4 author checklist | [`references/common-gotchas-consumer.md`](common-gotchas-consumer.md) | The four recurring consumer-side traps even AFTER literacy fires: composite grammar bypass / parent CSS override / mixed control sizes / `minmax(min, 1fr)` vs container queries. Sister-aligned with `adia-ui-authoring` v1.8.2. |
+| Rung 14 DataBinding | [`references/state.md`](state.md) | Signals, controllers, BaseController, data sources |
+| Rung 15 Interaction | [`references/composition.md`](composition.md) §Actions + [`references/state.md`](state.md) §Optimistic | Action shape + error path + optimistic update |
+| Rung 16 State | [`references/state.md`](state.md) | 7-category taxonomy with ownership |
+| Rung 17 Feedback | [`references/composition.md`](composition.md) §Validation + kit §3 checklist | Loading + empty + error per data-driven component |
+| Rung 18 RenderPlan | [`references/composition.md`](composition.md) | HTML + A2UI JSON output |
+| Rung 19 Validation | kit §3 Validation + §PEV verify-target table | Mode 1-4 verify path |
+
+---
+
+## §Anti-patterns specific to PRD-driven composition
+
+Beyond the rubric's 10 anti-patterns (which cover the wireframing discipline itself), kit Mode 1-4 has 3 PRD-specific failure modes:
+
+### KP-01 — Feature-as-task collapse
+
+**Symptom**: PRD lists "Lead inbox with priority sorting"; agent treats "Lead inbox" as a task and emits `<table-ui>` immediately.
+
+**Root cause**: features in PRDs conflate task + component. "Lead inbox" is a feature naming the surface; the task is "triage incoming leads to identify which need action today." Different tasks produce different primitives — triage vs comparison vs browse all are "lists" but have different optimal primitives.
+
+**Correction**: decompose every PRD feature into 1-N task statements per the canonical entry-point Pattern 2. Then resolve decisions per task. Then primitives.
+
+### KP-02 — Shell-vocabulary primacy
+
+**Symptom**: PRD says "dashboard" → agent emits `<admin-shell>` without resolving posture. PRD says "settings page" → `<settings-page>` shell. PRD says "chat interface" → `<chat-shell>`.
+
+**Root cause**: shell vocabulary in PRDs is a description of the surface category, NOT a directive about the shell to use. A "dashboard for executives reviewing weekly" is monitoring posture → admin-shell. A "dashboard for analysts comparing quarters" is analyzing posture → admin-shell with full-bleed sections (or editor-shell). A "dashboard for the CEO at 7am scanning headlines" is monitoring posture → simple-shell with stat-cards. Same word, different shells.
+
+**Correction**: read the user's posture (monitoring / acting / analyzing / configuring / creating / reviewing / debugging / exploring) from the PRD's goals + actions + frequency, NOT from the shell vocabulary.
+
+### KP-03 — Skipping the wireframe checkpoint
+
+**Symptom**: PRD reasoning produces a clean Rungs 0-5 trace, then agent jumps to `<admin-shell>` + `<table-ui>` + `<chart-ui>` without producing a wireframe artifact.
+
+**Root cause**: the wireframe rubric's central failure mode (premature visual collapse) at the kit-protocol level. The wireframe is a load-bearing intermediate, not a deliverable artifact — skipping it means the agent commits to component vocabulary without resolving region layout + state coverage + responsive behavior + ownership.
+
+**Correction**: produce a wireframe artifact (minimum Region + State levels) BEFORE primitive emission. Score against the 6 [gate] rubric dimensions. If any gate dimension scores < 3, return to the ladder and resolve the gap.
+
+### KP-04 — AdiaUI tag vocabulary inside the wireframe
+
+**Symptom**: agent produces a wireframe artifact, but the boxes contain `<admin-shell>`, `<table-ui>`, `<button-ui>`, or HTML markup (`<div>`, `<section>`, `<form>`) instead of semantic labels.
+
+**Root cause**: collapsing Rung 8 (AppShell) and Rung 13 (Component) into a single artifact. The wireframe is supposed to be a **pre-component** structural reasoning surface; using primitive vocabulary inside it short-circuits the entire ladder Tier 2-3 (Structure + Surface).
+
+**Correction**: wireframes use **semantic labels only** — "App shell," "Sidebar," "Lead Queue," "Inspector" — plus the rubric's notation grammar (`+--+` regions, `[Control]` controls, `{State}` data states, `<Section>` semantic components, `[owns: ...]` ownership, `!` unresolved). AdiaUI tag mapping happens AFTER the wireframe is scored, at kit §1 Catalog Lookup. See §Wireframe checkpoint above for the CORRECT-vs-INCORRECT worked example.
+
+---
+
+## §Verify-target — when is the pre-composition gate satisfied?
+
+The §SpecToUi gate is satisfied when:
+
+- [ ] Rung 0 InputContext annotated (known / inferred / missing / assumptions)
+- [ ] Rung 1 Intent stated (userGoal + businessGoal + successCriteria)
+- [ ] Rung 2 Domain entities listed
+- [ ] Rung 3 Role(s) with non-empty uiDifferentiators (when multiple roles)
+- [ ] Rung 4 Tasks decomposed (features ≠ tasks)
+- [ ] Rung 5 Decisions with non-empty requiredSignals + non-empty possibleActions
+- [ ] Wireframe artifact produced at Region + State minimum (other levels per task risk)
+- [ ] All 6 [gate] rubric dimensions score ≥ 3/5
+
+Once satisfied, the §SpecToUi mode hands off to §0 Reasoning Gate (which now has its precondition met) + §1 Catalog Lookup + §2 Composition.
+
+If the gate is NOT satisfied, the kit's §Plan-Execute-Verify loop has failed at the Plan step — there is no plan, only vibes. Returning to the ladder is not optional.
+
+---
+
+## §References
+
+**Canonical sources (do not duplicate; cite + extend):**
+
+- [`~/.claude/skills/ref-gen-ui-systems/references/reasoning-ladder.md`](../../../../.claude/skills/ref-gen-ui-systems/references/reasoning-ladder.md) — 19 rungs full procedure
+- [`~/.claude/skills/ref-gen-ui-systems/references/entry-points.md`](../../../../.claude/skills/ref-gen-ui-systems/references/entry-points.md) — 7 entry-point patterns
+- [`~/.claude/skills/ref-gen-ui-systems/references/composable-hierarchy.md`](../../../../.claude/skills/ref-gen-ui-systems/references/composable-hierarchy.md) — 6-layer composable system
+- [`~/.claude/skills/ref-gen-ui-systems/references/anti-patterns.md`](../../../../.claude/skills/ref-gen-ui-systems/references/anti-patterns.md) — 10 named anti-patterns
+- [`~/.claude/skills/core-skills-best-practices/references/agents-ux-wireframing-ascii.md`](../../../../.claude/skills/core-skills-best-practices/references/agents-ux-wireframing-ascii.md) — wireframing rubric (5 levels + 10 dimensions + 10 anti-patterns + 7-phase procedure)
+
+**Kit references this section hands off to:**
+
+- [`patterns-shells.md`](patterns-shells.md) — Shell composition (Rung 8 → 9)
+- [`patterns-recipes.md`](patterns-recipes.md) — Surface + view recipes (Rung 10 → 11)
+- [`patterns-layout.md`](patterns-layout.md) — Layout-tier composition
+- [`decision-model.md`](decision-model.md) — Decision shape → A2UI decisions block
+- [`state.md`](state.md) — DataBinding + State + Feedback (Rungs 14-17)
+- [`catalog-lookup.md`](catalog-lookup.md) + [`composition.md`](composition.md) — Component selection + emission (Rung 13)
+
+**Companion kit modes:**
+
+- §0 Reasoning Gate (kit) — fires AFTER §SpecToUi resolves Rungs 0-5
+- §1 Catalog Lookup (kit) — fires AFTER wireframe checkpoint
+- §2 Composition (kit) — fires AFTER primitive selection
+- §3 Validation (kit) — Mode 1-4 verify-target gate
+- §CorrectionLoop (kit) — when output is wrong, return upward through the ladder to find the layer of origin