@adia-ai/adia-ui-factory 0.2.4 → 0.8.0

package/skills/adia-ui-kit/references/pev-rationale.md

@@ -1,137 +0,0 @@
----
-name: pev-rationale
-load-when: When you need the source citation + ecosystem-level rationale behind §Plan-Execute-Verify
-load-size-tokens: ~600
-required-for: [authoring §PEV revisions, defending the loop in a §Teach handoff, training a new skill on PEV]
----
-
-# Plan-Execute-Verify — rationale + source citation
-
-The Plan-Execute-Verify (PEV) loop is the load-bearing closure on
-every senior-skill invocation in the AdiaUI skill ecosystem. This file
-captures the rationale + source citation so the skill is self-contained
-— consumer repos don't need to reach back to the substrate's
-`BORIS-feedback.md` or `VISION-extensibility.md` to understand why
-PEV is the discipline.
-
-## The principle
-
-> "Give Claude a way to verify its work. If Claude has that feedback
-> loop, it will 2-3x the quality."
->
-> — Boris Cherny, Anthropic, 2026-05-22 (the most-cited Boris principle
-> in the AdiaUI senior-skill ecosystem)
-
-The principle is structural, not stylistic. A skill that *generates*
-without *verifying* is a skill that produces plausible-looking work
-products which may or may not be correct. Adding a verify step
-shifts the skill's output from "looks like X" to "behaves like X" —
-a strictly stronger guarantee, and one that the rest of the
-authoring discipline (PR review, ticket QA, FEEDBACK pipeline)
-relies on.
-
-## What the loop is
-
-**Plan** — name the verify-target up front. If you cannot name how
-you will know you succeeded, you do not have a plan, you have a vibe.
-The verify target must be **mechanically checkable** — a rendered
-DOM you can snapshot, a command exit-code you can assert, an audit
-output you can grep, an eval score you can compare against a floor.
-
-**Execute** — do the work. The middle is the part most people
-recognize as "the task."
-
-**Verify** — run the output against the real product or substrate.
-NOT against the skill's own self-checks. The skill might pass its
-internal P1–P5 binding-points and still produce wrong output.
-The verify step closes that gap.
-
-## What §SelfAudit checks vs what verify checks
-
-There are two distinct audit surfaces in the skill ecosystem, and
-they answer different questions:
-
-| Surface | What it checks | Where it lives |
-|---|---|---|
-| **§SelfAudit** (mechanical roster, `audit-kit-roster.mjs`) | Does the SKILL.md itself satisfy structural invariants? Are the H2 sections present? Is the cold-start band coherent? Is the §PEV binding in place (P1–P5)? | Substrate-level audit; runs in CI on the skill repo |
-| **Verify** (the loop closure for a task) | Did the OUTPUT this skill just produced actually behave as intended? Does the composed UI render? Did the eval pass the floor? Did the migration land cleanly in a consumer repo? | Per-task; runs against the artifact the skill produced |
-
-**Both are required.** §SelfAudit catches drift in the skill's own
-shape (sections missing, frontmatter wrong, citation broken). Verify
-catches drift in the work the skill produces (a generated UI that
-looks right but routes wrong; a migration sweep that landed but
-broke a downstream test).
-
-A skill that only does §SelfAudit is a skill that grades its own
-homework. A skill that only does verify is a skill with no
-structural integrity. Both gates fire on every invocation.
-
-## Why the loop is "load-bearing"
-
-The loop is load-bearing because:
-
-1. **It is the only thing that closes the gap between intent and outcome.**
-   Without verify, the agent's output is "I think I did the thing"
-   — a confidence claim from an LLM, not evidence.
-2. **It is what makes the skill trustable downstream.** A consumer
-   agent that invokes adia-ui-kit and gets back markup with no
-   verify result has no basis to ship that markup. A consumer agent
-   that gets back markup PLUS a "verified by rendering against the
-   playground" handle can ship with confidence.
-3. **It is the mechanism that converts "happy-path eval pass"
-   into actual user-facing quality.** Boris's 2-3x quality claim is
-   not about the agent being smarter — it is about the agent being
-   forced to check its own work against a real signal.
-
-## Concrete verify-targets per skill mode
-
-For adia-ui-kit specifically, the verify-target is mode-dependent:
-
-- **Modes 1–4 (composition)** — render the composed surface in a
-  real demo / playground / Playwright snapshot; compare against the
-  intent or the source mock.
-- **Mode 5 (recon / consultant)** — produce a diagnostic report
-  with verifiable findings (path + line + actual content quoted);
-  rerun the audit after any fix to confirm 0 findings.
-- **Mode 6 (feedback authoring)** — verify the ticket lands the
-  5-block structure + the omissions-defense scan completes with
-  no open accidents.
-- **Mode 14 (correction loop)** — verify the root cause is at the
-  correct layer (skill / codebase / substrate / spec); rerun the
-  failing case after the fix.
-
-The verify-target table in the cold-start band names these
-explicitly per mode.
-
-## Anti-patterns
-
-- **"Verify by self-checking the agent's own output"** — circular.
-  The agent is the writer; it cannot be the verifier of its own
-  pattern-matching.
-- **"Mechanical when available, manual when not"** — degraded
-  verify is not the same as verify. If the mechanical surface is
-  unavailable, name what's missing as a P1 finding and proceed
-  with the degraded surface only after explicit user acknowledgment.
-- **"Skip verify if the change is small"** — small changes have
-  small verify costs. Skipping verify is what produces the
-  silent-regression class that the FEEDBACK pipeline catches
-  hours/days later.
-
-## Source
-
-Boris's principle was articulated in his 2026-05-22 conversation
-about Claude's coding behavior. The principle is short ("give
-Claude a way to verify its work") but its structural implications
-are large (every skill ecosystem needs a verify step; every
-verify step needs a mechanically-checkable target). The AdiaUI
-senior-skill ecosystem encodes this as:
-
-- §PEV H2 in the cold-start band of every senior SKILL.md (P1)
-- A verify-target table naming the per-mode target (P2)
-- A §Teach cross-reference linking new knowledge back to PEV (P3)
-- PEV mentioned in the cold-start band (P4)
-- The skill.json description claiming a verify capability (P5)
-
-These 5 binding-points are mechanically checked by
-`scripts/skills/check-pev.mjs`. If they all pass, the skill is
-PEV-bound; if any fails, the skill cannot ship.

package/skills/adia-ui-kit/references/reasoning-gate.md

@@ -1,146 +0,0 @@
----
-name: reasoning-gate
-load-when: Before any component output — the mandatory pre-generation reasoning gate. Covers the GenUI Plan template, the user-intent verification step, and the decomposition discipline
-load-size-tokens: ~1,900
-required-for:
-  - composition modes 1-4 cold-start
-  - any output the user has not pre-confirmed
----
-
-# §0 — Reasoning Gate (mandatory before any component output)
-
-Based on `ref-gen-ui-systems` and the Generative UI Reasoning Ladder.
-
-### Why the gate exists
-
-LLMs naturally jump from "Build a CRM" to emitting `<card-ui>` or A2UI
-JSON. The result is visually plausible UI that is operationally wrong —
-missing task traces, unbound components, no decision support. The ladder
-forces the reasoning that produces correct UI.
-
-**A UI is a decision surface over a domain. Components and layouts are
-the output of correct reasoning — never the starting point.**
-
-> ⚠️ **And that reasoning includes a CATALOG SEARCH.** Once you've
-> derived "what component fits this decision rung?", your next step is
-> NOT to author a novel tag. Your next step is to **search
-> `packages/web-components/components/` + `packages/web-modules/`**
-> by keyword + intent, and confirm the catalog doesn't already cover
-> it. The 122 primitives + 5 module clusters absorb the vast majority
-> of real UI problems by design. See §1 (Catalog Lookup) for the
-> prior-art-first rule and search procedure. If the catalog truly
-> doesn't cover the case, file a FEEDBACK ticket (see §Team Tickets)
-> instead of inventing a one-off — substrate gaps are signal, and
-> v0.6.18's FB-10 (`text-ui` overlay attrs) is a real example of the
-> catalog catching up to natural consumer intent.
-
-### The 19-rung ladder (condensed)
-
-```
-0.  InputContext    — what's given; what's known, inferred, missing
-1.  Intent          — why the UI exists
-2.  Domain          — entities, relationships, metrics, rules, permissions
-3.  Role            — who uses it; uiDifferentiators per role
-4.  Task            — what users accomplish; requiredInformation per task
-5.  Decision        — what users determine; possibleActions per decision
-6.  Posture         — monitoring / acting / analyzing / configuring / creating / reviewing
-7.  IA              — areas derived from tasks (not entities)
-8.  AppShell        — shell pattern derived from posture
-9.  Navigation      — primary / secondary / contextual; role-scoped
-10. Surface         — page / panel / drawer / modal / popover / card / toast
-11. View            — route-level composition of sections
-12. Section         — semantic group; taskIds or decisionIds required
-13. Component       — justified by task + decision + binding
-14. DataBinding     — fieldMap, refreshPolicy, cachePolicy
-15. Interaction     — label, input, permission, result, optimisticUpdate, errorPath
-16. State           — local / server / derived / route / session / optimistic / permission
-17. Feedback        — loading + empty + error per data-driven component
-18. RenderPlan      — what to emit and in what format
-19. Validation      — does the output satisfy the intent?
-```
-
-### The Pre-Composition Rubric (5 gates)
-
-Before any HTML or A2UI JSON output, emit a `### GenUI Plan` block.
-
-**Carry-forward rule:** if the user's prompt already answers a field,
-carry it forward directly — do not re-interrogate. Only ask about fields
-that are genuinely missing. A prompt that says "Admin UI for Claims
-Management loading from /api/claims" has already answered `domain`,
-`tasks`, `bindings`, and `shell`. Only confirm missing pieces.
-
-#### GenUI Plan (emit format)
-
-```yaml
-intent:
-  user_goal: "[What is the user trying to accomplish?]"
-
-domain:
-  entities: "[Core nouns: Claim, Policy, Adjuster, Document…]"
-  metrics: "[Key numbers: open claims count, avg resolution time…]"
-
-tasks:
-  primary: "[Verbs: Review Claim, Assign Adjuster, Approve Payout…]"
-
-decisions:
-  key: "[What must the user determine? What action follows?]"
-
-bindings:
-  # Carry forward any endpoints the user provided.
-  # For each: endpoint, method (GET/POST/SSE), fieldMap stub.
-  # Example: GET /api/claims → table-ui.data via data-stream-src
-  sources: "[endpoint X → which component(s) consume it]"
-
-design_reference:
-  # If the user provided Figma boards, screenshots, or mockups:
-  # - Extract: layout intent, visual hierarchy, key component patterns
-  # - Map: design components → nearest AdiaUI primitives
-  # - Flag: anything the board shows that AdiaUI doesn't have
-  # DO NOT copy raw colors, spacing values, or font sizes from the board.
-  # Map them to the nearest --a-* token instead.
-  source: "[Figma link / screenshot / none]"
-  mapped_components: "[design component → AdiaUI equivalent]"
-  deviations: "[anything in the board AdiaUI can't express — flag for user]"
-
-structure:
-  posture: "[monitoring | acting | analyzing | configuring | creating | reviewing]"
-  shell: "[admin-shell | chat-shell | editor-shell | simple-shell | a2ui-root]"
-  views: "[list the views/routes this UI needs — e.g. claims list, claim detail]"
-```
-
-After emitting the plan, ask: *"Does this model look correct? May I
-proceed to generate the structure?"* — but omit questions about fields
-the user already answered.
-
-Only after confirmation (or in fully autonomous mode with pre-approval)
-proceed to §1 Catalog Lookup and §2 Composition.
-
-### Non-negotiable rules (from the ladder)
-
-- **Component justification:** every component must trace to `taskIds` or
-  `decisionIds`. A component with no task or decision trace must be removed.
-- **Decision actions:** every critical decision must have `possibleActions`.
-  A decision with no action is an observation, not a supported decision.
-- **Feedback completeness:** every data-driven component requires loading,
-  empty, and error states. Not optional.
-- **Role differentiation:** when multiple roles exist, each needs
-  `uiDifferentiators`. One interface for incompatible roles is an error.
-- **No unbound UI:** every data-driven component needs an explicit binding
-  (source, fieldMap, refreshPolicy). An unbound component is a mockup.
-
-### Anti-patterns (check before declaring done)
-
-| ID | Name | Symptom |
-|---|---|---|
-| AP-01 | Premature Rendering | Output starts with component vocabulary |
-| AP-02 | Generic Dashboard Syndrome | Metrics shown with no actions |
-| AP-03 | Component-First Thinking | Reasoning starts with component names |
-| AP-04 | Unbound UI | Components have no data source |
-| AP-05 | Actionless Interface | Operational surface with no actions |
-| AP-06 | Missing Feedback States | No loading, empty, or error states |
-| AP-07 | Role Collapse | One interface for incompatible roles |
-| AP-08 | Metric Without Decision | KPI card with empty decisionIds |
-| AP-09 | Surface Without Task | Surface with empty taskIds |
-| AP-10 | State Without Owner | State with no owner or reset condition |
-
----

package/skills/adia-ui-kit/references/reasoning-methodologies.md

@@ -1,112 +0,0 @@
----
-name: reasoning-methodologies
-load-when: When the user's request is ambiguous or novel — covers general-purpose reasoning priors (first-principles, root-cause, rate-limiting, decomposition over generation) that pre-empt jumping to skill-specific output
-load-size-tokens: ~1,300
-required-for:
-  - novel-task triage
-  - audit-mode root-cause analysis
-  - pre-output reasoning
----
-
-# §ReasoningMethodologies — General-purpose priors that pre-empt skill content
-
-These are the reasoning postures every phase of this skill assumes you
-bring. They are not AdiaUI-specific — they are the priors that make this
-skill's phase map produce correct output. If you skip them, the skill
-phases produce locally-correct steps that compose into wrong outcomes.
-
-### 1. Decomposition over generation
-
-**If you can't explain the problem, you can't solve it.** Before writing
-a single component, name:
-
-- What this UI is *for* (the user task, not "a dashboard").
-- The first-principles decomposition (entities → tasks → decisions →
-  display + input affordances → component primitives).
-- Which decisions are *load-bearing* (changing them rewrites everything
-  below) vs *cosmetic* (changing them is a one-line override).
-
-Component selection is the **output** of decomposition, not the input.
-If the user says "build a table", the table is a hint about display
-shape, not a specification. Resolve the entity + the decisions it
-supports before reaching for `<table-ui>` — you may find `<feed-ui>` or
-`<kanban-ui>` was the right primitive.
-
-### 2. Root cause analysis before patching
-
-When a symptom appears (component renders wrong, state out of sync, CSS
-override doesn't take, ticket from a consumer), find the *root* before
-proposing a fix. The chain usually runs:
-
-```
-Symptom  →  Proximate cause  →  Mechanism  →  Root cause
-"button   "wrong --a-fg-     "token wrong  "consumer set
- wrong     resolves"          for variant"  --a-fg in :root
- color"                                      overriding the
-                                             variant scope"
-```
-
-The proximate cause justifies a workaround. The root cause justifies a
-substrate fix or a documented convention. **Skill-authoring should fix
-substrate or document discipline; never teach workarounds.**
-
-### 3. Rate-limiting factors
-
-For any system, name the *irreducible mechanic* that gates correctness
-or performance. Examples in this skill's domain:
-
-- The icon loader needs Phosphor installed *before* `static
-  requiredIcons` runs. Rate-limiter: install order.
-- `<table-ui>` paired with `<table-toolbar-ui>` works because the
-  toolbar dispatches scoped events. Rate-limiter: event scoping.
-- 9-package lockstep is enforced because internal `^MAJOR.MINOR.0` deps
-  lock to exact in npm pre-1.0. Rate-limiter: semver pre-1.0 semantics.
-
-Whenever a recipe in this skill exists, it exists because of a
-rate-limiting mechanic. Name the mechanic; *then* the recipe makes
-sense and can be adapted.
-
-### 4. First-principles audit before adopting a pattern
-
-When the repo already has a pattern (hand-rolled skeleton, custom
-shell, bespoke route mount), don't reflexively replace it with the
-substrate equivalent. Audit:
-
-- **Why does this pattern exist?** (predates substrate capability? a
-  deliberate carve-out? a workaround for a bug that's since shipped?)
-- **What does substrate now provide?** (loading prop? slot? token?
-  primitive?)
-- **What does replacement cost?** (1-line, 1-file, N-files, regression
-  surface, behavior delta.)
-- **What does keeping it cost?** (drift accumulates, future agents
-  cargo-cult the workaround, doc-currency suffers.)
-
-Adopt-or-keep is a *decision*, not a default. Document the decision in
-the diagnostic report — see §DiagnosticOutput.
-
-### 5. 5-way reachability check
-
-For any artifact (component, chunk, page, primitive, token) that is
-*supposed to be canonical*, verify it is reachable from at least these
-five surfaces — every miss is a class of bug:
-
-1. **Sitemap / index** — listed where consumers look.
-2. **Corpus / search index** — discoverable by name/keyword.
-3. **Harvester / generator output** — chunked or indexed by tooling.
-4. **Imports / module graph** — actually loaded by something.
-5. **Self-doc** — its own README/yaml/examples reference it.
-
-If a "canonical" artifact is reachable from <5, it isn't canonical;
-it's a draft, a dead branch, or a doc-currency miss. This is the gap
-class §Recon hunts for.
-
-### 6. Explain before you act
-
-Before any non-trivial change (substrate edit, migration sweep,
-diagnostic report), write the *why* in plain English. If you can't
-write the why in two sentences, you don't understand the change well
-enough to make it. The §0 GenUI Plan, the §Recon report, the
-§DiagnosticOutput, and every commit message in this repo follow this
-discipline.
-
----

package/skills/adia-ui-kit/references/recon.md

@@ -1,192 +0,0 @@
----
-name: recon
-load-when: Consultant-posture inventory — landing in a brownfield consumer repo and getting the 60-second read of what shipped, what state it's in, what gaps exist
-load-size-tokens: ~2,100
-required-for:
-  - mode 5 (consultant) first turn
-  - audit output authoring
----
-
-# §Recon — 60-second inventory for a brownfield repo
-
-Run this **before** §Setup any time you land in a repo you didn't author.
-The goal is not to be exhaustive — it's to assemble enough context that
-your subsequent edits respect the repo's existing intent, conventions,
-and adoption state.
-
-### Why this exists
-
-Without recon, brownfield work produces three predictable failures:
-
-1. **Convention violation** — you write `[data-actions]` when the repo
-   has adopted `slot="action"`, or vice versa.
-2. **Substrate duplication** — you hand-roll a skeleton when the repo's
-   installed `@adia-ai/web-components` already ships `loading` on
-   `<stat-ui>` / `<table-ui>`.
-3. **ADR ignorance** — you propose a legacy shell shape that ADR-0024
-   retired, because the repo's own docs hint at it without flagging the
-   retirement.
-
-The §Recon checklist below catches all three classes in roughly 60
-seconds of disciplined inspection.
-
-### The Recon checklist (in order)
-
-Each step has an exact command and a one-line interpretation rule.
-
-**1 — Identify the repo's agent-entry file**
-
-```bash
-ls AGENTS.md CLAUDE.md .cursorrules 2>/dev/null
-```
-
-If present: **read it in full** before doing anything else. It usually
-contains hard rules, peer-agent baseline, and reading-order pointers.
-**If absent: this is itself a finding** — propose scaffolding from
-`assets/templates/` in §DiagnosticOutput.
-
-**2 — Identify the project tier**
-
-```bash
-ls package.json README.md .claude/docs/ specs/ .brain/ 2>/dev/null
-test -d apps && echo "monorepo-app-tier" || echo "single-package"
-test -d packages && echo "monorepo-substrate-tier" || true
-```
-
-Determine: substrate repo (publishes `@adia-ai/*`), consumer app (uses
-`@adia-ai/*`), or library (re-exports / wraps). Each implies different
-recon depth.
-
-**3 — Read the installed AdiaUI versions (and confirm declarations exist)**
-
-```bash
-# (a) What's declared in package.json?
-node -e "const p=require('./package.json'); const deps={...p.dependencies, ...p.devDependencies}; const adia=Object.entries(deps).filter(([k])=>k.startsWith('@adia-ai/')); console.log(JSON.stringify(Object.fromEntries(adia), null, 2))"
-
-# (b) What's installed in node_modules?
-ls node_modules/@adia-ai/ 2>/dev/null
-# For each: cat node_modules/@adia-ai/<pkg>/package.json | grep '"version"'
-
-# (c) CRITICAL CHECK — do imports exist for packages that aren't declared?
-# (This is the manifest-gap detection — see §GapDetection Gap class 0.)
-grep -rEn "from ['\"]@adia-ai/" --include='*.ts' --include='*.js' \
-  --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
-  src/ 2>/dev/null | head -10
-```
-
-Note the **3-tuple**: declared / installed / latest-published. Drift
-between any two is a gap class (see §GapDetection).
-
-**Halt-condition (Gap class 0):** if step (c) returns matches but step
-(a) returns `{}` empty, the manifest is gapped — source imports
-`@adia-ai/*` but `package.json` declares nothing. Vite will fail at
-`npm run dev` with "could not be resolved" / "Are they installed?" on
-the bare specifiers. **Do not compose any further UI** until the
-operator declares + installs the deps. See §GapDetection Gap class 0
-for the remediation shape. The 2026-05-23 `claims-ui-v9` incident is
-the canonical worked example: 5 imports against 0 declared deps,
-vite scanner halted dev-server boot.
-
-**4 — Read the canonical specs and ADRs**
-
-```bash
-ls .claude/docs/specs/ .claude/docs/ADRs/ .brain/adrs/ 2>/dev/null
-# Read the spec INDEX if present:
-test -f .claude/docs/specs/INDEX.md && head -80 .claude/docs/specs/INDEX.md
-# Scan ADR titles:
-for f in .brain/adrs/*.md .claude/docs/adrs/*.md; do head -3 "$f" 2>/dev/null; done
-```
-
-Specifically look for: which ADRs *exist*, which ones *describe
-retirement* of legacy shapes, which ones *introduce new canonical
-shapes*. Adoption state of each is a gap candidate.
-
-**5 — Read the most recent journal entry (if any)**
-
-```bash
-ls .claude/docs/journal/ .brain/journal/ 2>/dev/null
-find .claude/docs/journal/ -name '*.md' 2>/dev/null | sort | tail -3
-```
-
-The newest journal entry tells you what was last in flight, what was
-last shipped, and what hand-offs are open. If a peer agent is mid-arc,
-recon should pick up there.
-
-**6 — Inventory the actual UI surface**
-
-```bash
-# Find all admin/editor/chat shells in use:
-grep -rEn '<admin-shell|<editor-shell|<chat-shell|<chrome-shell' \
-  --include='*.html' --include='*.js' --include='*.jsx' \
-  --include='*.tsx' --include='*.vue' --include='*.svelte' .
-
-# Find raw <main> / <header> / <aside> patterns (likely legacy):
-grep -rEn '<main[ >]|<aside[ >]|<header[ >]' \
-  --include='*.html' . | head -20
-
-# Find hand-rolled skeletons (likely substrate-replaceable):
-grep -rEn 'skeleton|placeholder.*loading|class=".*loading"' \
-  --include='*.css' --include='*.html' . | head -20
-```
-
-These three grep families together map: **which shells exist**, **what
-hasn't been adopted yet**, **what has been hand-rolled**. Each finding
-is a candidate for §GapDetection.
-
-**7 — Check for hand-rolled primitives that substrate now provides**
-
-This is the highest-leverage finding class. Examples to look for:
-
-| Hand-rolled symptom (grep) | Substrate replacement (since) |
-|---|---|
-| `class=".*toast"` + custom CSS | `<feed-ui>` toast API (v0.6.11+) |
-| `class=".*skeleton"` + custom CSS | `loading` prop on `<stat-ui>` / `<table-ui>` (v0.6.18+) |
-| Custom `<div role="dialog">` | `<dialog-ui>` / `<drawer-ui>` |
-| Custom CSS / `@media` for breakpoints | `@bp` responsive attrs on `grid-ui` / `col-ui` / `row-ui` / `text-ui` / `block-ui` — `columns="2 4@md"`, `gap="2 4@md"`, `justify="start between@md"` |
-| Inline color hex / rgb | `--a-chrome-*` / `--a-data-*` semantic tokens |
-| Custom `<button class="primary">` | `<button-ui variant="primary">` |
-
-Each match here is a §GapDetection capability-drift finding. **Do not
-fix in recon** — note it for the report.
-
-**8 — Check doc currency**
-
-```bash
-# When was README / .claude/docs/ last touched?
-find README.md .claude/docs/ -name '*.md' -mtime -30 2>/dev/null | head -5
-# Are there obvious stale references? (versions, tags, retired shapes)
-grep -rEn 'v0\.[0-5]\.[0-9]+|@agent-ui-kit|AgentElement|--agent-' \
-  README.md .claude/docs/ 2>/dev/null | head -10
-```
-
-Stale doc references usually correlate with stale code. Note them.
-
-**9 — Run whatever verification gates exist**
-
-```bash
-# If the repo has its own gates, run them — they encode its conventions.
-test -f package.json && grep -E '"check:|"verify:|"smoke:|"lint:' package.json
-# Common shapes:
-npm run check 2>&1 | tail -20  # if check exists
-npm run lint 2>&1 | tail -5    # if lint exists
-```
-
-A failing gate is itself a finding. A *missing* gate (e.g. consumer has
-no `check:lockstep` equivalent) is also a finding.
-
-### Recon stop-conditions
-
-Stop the inventory when you can answer all of these:
-
-- What is this repo (tier, framework, rendering model)?
-- What AdiaUI versions does it consume (declared / installed / latest)?
-- Which ADRs has it adopted? Which has it not?
-- What shells / patterns are in use? What's hand-rolled?
-- Where is the doc currency (fresh, stale, missing)?
-- Are there peer agents mid-arc, or open hand-offs in the journal?
-
-Once you have answers to all six, proceed to §GapDetection. **Do not
-proceed to §Setup or §0 until the user has confirmed your
-§DiagnosticOutput** — otherwise you're authoring without context.
-
----