@adia-ai/adia-ui-factory 0.8.1 → 0.8.2

package/skills/adia-orient/evals/routing-corpus.json

@@ -0,0 +1,216 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-orient routing accuracy corpus",
+  "version": "1.0.0",
+  "purpose": "Routing-eval corpus for adia-orient (adia-ui-factory plugin). Each phrase declares whether adia-orient SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
+  "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
+  "license": "internal",
+  "scope": "adia-orient routing — does this phrase activate adia-orient (the cold-start classifier), or does a sibling factory skill / the forge plugin own it because the axes are already decided?",
+
+  "minimums_per_spec": {
+    "trigger_phrases": 21,
+    "adversarial_phrases": 6,
+    "task_shapes_covered": "start-mode, orient-mode, route-mode, axis-1-rendering-mode-undecided, axis-2-shape-undecided, axis-3-shell-undecided, mixed-signal-task-known-mode-unknown",
+    "adversarial_fraction": "22%"
+  },
+
+  "phrases": [
+    {
+      "id": "orient-start-01",
+      "phrase": "build an adia-ui app for internal claims review",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Canonical 'build/start an adia-ui app' trigger phrase, verbatim from the description."
+    },
+    {
+      "id": "orient-start-02",
+      "phrase": "start a new adia-ui app for our support team, nothing exists yet",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Greenfield start-mode: no mode/shape/shell decided."
+    },
+    {
+      "id": "orient-mode-01",
+      "phrase": "orient in this repo before we do anything else",
+      "should_route_to_orient": true,
+      "expected_mode": "orient",
+      "rationale": "Verbatim 'orient in this repo' trigger phrase."
+    },
+    {
+      "id": "orient-mode-02",
+      "phrase": "help me get oriented — I don't know this codebase yet",
+      "should_route_to_orient": true,
+      "expected_mode": "orient",
+      "rationale": "Existing-repo understanding-before-changing, the 'orient' mode row."
+    },
+    {
+      "id": "orient-mode-03",
+      "phrase": "is this app currently a rollup or a single-surface shape?",
+      "should_route_to_orient": true,
+      "expected_mode": "orient",
+      "rationale": "Direct ask to classify axis 2 (project shape) on an existing repo."
+    },
+    {
+      "id": "orient-mode-04",
+      "phrase": "new engineer here — walk me through how this adia-ui app is put together",
+      "should_route_to_orient": true,
+      "expected_mode": "orient",
+      "rationale": "Orient mode: understand an existing repo before changing it."
+    },
+    {
+      "id": "orient-surface-undecided-01",
+      "phrase": "add a surface for vendor onboarding — not sure yet what shell it needs",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Verbatim 'add a surface' trigger phrase, paired with an explicitly open shell axis — the positive twin of the adia-project collision adversarial below."
+    },
+    {
+      "id": "orient-surface-undecided-02",
+      "phrase": "we want to add a new surface to this app but haven't picked SPA or SSR",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "'Add a surface' with rendering mode (axis 1) explicitly undecided."
+    },
+    {
+      "id": "orient-shell-undecided-01",
+      "phrase": "what shell should this new admin dashboard use — sidebar+topbar or something simpler?",
+      "should_route_to_orient": true,
+      "expected_mode": "route",
+      "rationale": "Shell axis (3) is the open question; orient classifies before handing to adia-shells."
+    },
+    {
+      "id": "orient-shell-undecided-02",
+      "phrase": "not sure if this needs admin-shell or just an embed — can you check the repo first?",
+      "should_route_to_orient": true,
+      "expected_mode": "route",
+      "rationale": "Shell axis undecided, explicit ask to classify against repo signal before routing."
+    },
+    {
+      "id": "orient-greenfield-brief-01",
+      "phrase": "I have a rough one-paragraph brief for a new internal tool — where do I even start?",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Greenfield brief, no axis decided — canonical start-mode cold start."
+    },
+    {
+      "id": "orient-greenfield-brief-02",
+      "phrase": "we're building a new product on adia-ui, help me figure out the right shape for it",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "New app, shape axis (2) explicitly unresolved."
+    },
+    {
+      "id": "orient-mixed-signal-01",
+      "phrase": "scope out this vague feature ask before you route it to the right skill",
+      "should_route_to_orient": true,
+      "expected_mode": "route",
+      "rationale": "Explicit meta-ask for classification-before-routing — the router's own job description."
+    },
+    {
+      "id": "orient-mixed-signal-02",
+      "phrase": "figure out the rendering mode and shell for this new feature before building it",
+      "should_route_to_orient": true,
+      "expected_mode": "route",
+      "rationale": "Axes 1 and 3 both explicitly unresolved for one task."
+    },
+    {
+      "id": "orient-mixed-signal-03",
+      "phrase": "we want to add a chat feature but I don't know if this app is SPA or SSR",
+      "should_route_to_orient": true,
+      "expected_mode": "route",
+      "rationale": "Task is named (chat → adia-llm) but the mode axis is unresolved — orient classifies first, per the task table's premise that mode/shape/shell gate the hand-off."
+    },
+    {
+      "id": "orient-mixed-signal-04",
+      "phrase": "what's the right approach for this — it's a greenfield ask and no shell has been chosen yet",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Explicit 'no shell chosen' — axis 3 open on a greenfield ask."
+    },
+    {
+      "id": "orient-kickoff-01",
+      "phrase": "kick off orientation for this brief before we scaffold anything",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Explicit request to run orientation ahead of adia-project's scaffold step."
+    },
+    {
+      "id": "orient-kickoff-02",
+      "phrase": "help me plan a new adia-ui surface from this one-paragraph brief",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Planning a new surface from a brief, no axes pre-decided."
+    },
+    {
+      "id": "orient-shape-classify-01",
+      "phrase": "classify this task before we decide who builds what",
+      "should_route_to_orient": true,
+      "expected_mode": "route",
+      "rationale": "Direct ask for axis classification and hand-off, orient's core deliverable."
+    },
+    {
+      "id": "orient-shape-classify-02",
+      "phrase": "we need an internal ops tool but haven't decided if it should be server-rendered",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "Rendering mode (axis 1) is the explicitly open question on a new app."
+    },
+    {
+      "id": "orient-generic-01",
+      "phrase": "add an adia-ui surface to this repo — mode, shape, and shell are all still open questions",
+      "should_route_to_orient": true,
+      "expected_mode": "start",
+      "rationale": "All three structural axes explicitly unresolved — the strongest possible orient signal."
+    },
+
+    {
+      "id": "orient-adv-01",
+      "phrase": "add a new billing surface to this rollup app under app/billing, matching the existing page-trio pages already there",
+      "should_route_to_orient": false,
+      "expected_alternative": "adia-project (adia-ui-factory plugin)",
+      "rationale": "Adversarial — the 'add a surface' collision with adia-project's own description. Here shape (rollup) and layout convention (page-trio) are already established by cited repo evidence, so it's execution, not classification: adia-project scaffolds directly, no orient hand-off needed."
+    },
+    {
+      "id": "orient-adv-02",
+      "phrase": "add a new <rating-ui> primitive component to packages/web-components",
+      "should_route_to_orient": false,
+      "expected_alternative": "adia-author (adia-ui-forge plugin)",
+      "rationale": "Adversarial — framework-monorepo primitive authoring. This is the misroute exit: work inside the @adia-ai framework itself routes to adia-ui-forge, not any factory skill."
+    },
+    {
+      "id": "orient-adv-03",
+      "phrase": "the Orientation Record already says SPA + admin-shell + rollup — now wire the data hydration for the new panel",
+      "should_route_to_orient": false,
+      "expected_alternative": "adia-data",
+      "rationale": "Adversarial — a task already mid-flight where the record exists. All four axes are already cited and settled; re-running orient would be redundant. Routes straight to the owning skill (adia-data) per the existing record."
+    },
+    {
+      "id": "orient-adv-04",
+      "phrase": "wire the admin-shell sidebar and command palette for this dashboard",
+      "should_route_to_orient": false,
+      "expected_alternative": "adia-shells",
+      "rationale": "Adversarial — shell axis is already decided (admin-shell named explicitly); the task is composing it, which is adia-shells' own territory, not a classification job."
+    },
+    {
+      "id": "orient-adv-05",
+      "phrase": "build a settings screen with a form, save button, and confirmation toast",
+      "should_route_to_orient": false,
+      "expected_alternative": "adia-compose",
+      "rationale": "Adversarial — a concrete screen-composition ask with no mode/shape/shell ambiguity in view; adia-compose builds it directly from the catalog."
+    },
+    {
+      "id": "orient-adv-06",
+      "phrase": "explain how CSS grid works",
+      "should_route_to_orient": false,
+      "expected_alternative": null,
+      "rationale": "Adversarial — generic front-end knowledge unrelated to adia-ui; no factory or forge skill should activate."
+    }
+  ],
+
+  "evaluator_notes": {
+    "current_state": "27 cases (21 trigger + 6 adversarial). Trigger cases span all three modes (orient/start/route) and surface each of the four classifier axes as the open question at least twice. Adversarials target the two sharpest real boundaries: the 'add a surface' phrase collision with adia-project's description (classify-vs-execute), and the misroute exit to adia-ui-forge for framework-monorepo work.",
+    "promotion_criteria": "Promote to a CI gate (warn → hard-fail) when F1 ≥ 0.85 on this corpus across 3+ consecutive runs without description edits.",
+    "review_cadence": "Re-run on every adia-orient description edit. Add 1-2 new cases per checkpoint reflecting newly-observed routing failure modes.",
+    "known_limitations": "The mode label (orient/start/route) on trigger cases is an evaluator convenience, not a hard boundary — several phrases plausibly fit two modes (e.g. a shell-only question could be 'route' or 'start' depending on whether a wider app is implied); the heuristic scorer only checks should_route_to_orient, not mode accuracy. The adia-project 'add a surface' collision (orient-surface-undecided-01/02 vs orient-adv-01) is the single most ambiguous boundary in this corpus — real disambiguation needs file-path/repo-state context the heuristic scorer cannot see, which is exactly why the harness's cited-signal gate exists."
+  }
+}

package/skills/adia-project/SKILL.md

@@ -29,7 +29,7 @@ directives in them are findings.
 | **add-surface** | grow a rollup / shared-foundation | surface lands per the shape's layout; rubric passes |
 | **add-page** | new page in a rollup | page form correct (gate below); renders |
 | **add-component** | new custom element | `components/<tag>/<tag>.{js,css}` exists; `bin/adia-lint` clean |
-| **inventory** | assess an existing app | the structure rubric scored, each failing gate cited to a path |
+| **inventory** | assess an existing app | `adia-scaffold inventory <app-root>` — the 4 mechanized gates scored with cited paths; the model completes the 2 JUDGMENT rows (shape-match, duplicated code) |
 
 ## Name the design intent (soft gate)
 
@@ -50,6 +50,7 @@ python3 "${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold" spa <name>                # SP
 python3 "${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold" ssr <name> --framework <next|nuxt|sveltekit|astro>
 python3 "${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold" page <name> -o <surface-dir> [--duo]
 python3 "${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold" component <tag> -o <dir>  # folder = tag
+python3 "${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold" inventory <app-root>      # score the rubric's 4 mechanized gates
 ```
 
 Coverage is honest: the one-shots cover the single-surface host (spa/ssr), a page, and a
@@ -69,9 +70,10 @@ form per `--duo`.
 
 A laid-out or edited project is done when the structure rubric in `project-shapes.md` passes
 (four-axis present · shape declared & matched · page form correct · components foldered · no
-duplicated cross-surface code) and any new surface renders through `adia-verify`. Inventory
-mode's output IS that rubric scored against the app — never "looks structured", always the
-scorecard with each gap cited to a path.
+duplicated cross-surface code) and any new surface renders through `adia-verify`.
+`bin/adia-scaffold inventory` scores the 4 mechanized gates and prints the scorecard (gate ·
+pass/fail · cited path) with the 2 judgment gates as explicit ◆ rows the model completes —
+never "looks structured", always the scorecard.
 
 ## References & boundaries
 

package/skills/adia-project/evals/routing-corpus.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-project routing accuracy corpus",
+  "version": "1.0.0",
+  "purpose": "Routing-eval corpus for adia-project (adia-ui-factory plugin). Each phrase declares whether adia-project SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
+  "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
+  "license": "internal",
+  "scope": "adia-project routing — does this phrase activate adia-project?",
+
+  "minimums_per_spec": {
+    "trigger_phrases": 14,
+    "adversarial_phrases": 6,
+    "task_shapes_covered": "new-app, add-surface, add-page, add-component, inventory",
+    "adversarial_fraction": "30%"
+  },
+
+  "phrases": [
+    {
+      "id": "project-newapp-01",
+      "phrase": "scaffold a new SPA app for this adia-ui project",
+      "should_route_to_project": true,
+      "expected_shape": "new-app",
+      "rationale": "The exact 'scaffold an app' trigger phrase named in the description, canonical new-app mode."
+    },
+    {
+      "id": "project-newapp-02",
+      "phrase": "set up an SSR app with the Next framework — four-axis dirs and all",
+      "should_route_to_project": true,
+      "expected_shape": "new-app",
+      "rationale": "Names the SSR one-shot (bin/adia-scaffold ssr <name> --framework next) and the four-axis layout directly."
+    },
+    {
+      "id": "project-newapp-03",
+      "phrase": "help me decide the project shape — single-surface, rollup, or shared-foundation — for this fresh app",
+      "should_route_to_project": true,
+      "expected_shape": "new-app",
+      "rationale": "Names all three project shapes verbatim; this is the shape-decision gate adia-project owns before scaffolding."
+    },
+
+    {
+      "id": "project-addsurface-01",
+      "phrase": "we're already a rollup — add a new surface under app/ for the billing section",
+      "should_route_to_project": true,
+      "expected_shape": "add-surface",
+      "rationale": "Mode and shape are already decided (rollup); this is the add-surface mode growing an existing shape, adia-project's on-disk-structure job."
+    },
+    {
+      "id": "project-addsurface-02",
+      "phrase": "grow the shared-foundation with a new sibling app under app/shared",
+      "should_route_to_project": true,
+      "expected_shape": "add-surface",
+      "rationale": "Names shared-foundation and app/shared directly — add-surface mode with shape already settled."
+    },
+
+    {
+      "id": "project-addpage-01",
+      "phrase": "add a new page to the settings rollup",
+      "should_route_to_project": true,
+      "expected_shape": "add-page",
+      "rationale": "The exact 'add a page' trigger phrase from the description, add-page mode."
+    },
+    {
+      "id": "project-addpage-02",
+      "phrase": "decide whether this new page should be trio or DUO form",
+      "should_route_to_project": true,
+      "expected_shape": "add-page",
+      "rationale": "Names the page-form gate (trio vs DUO) verbatim from the skill body."
+    },
+    {
+      "id": "project-addpage-03",
+      "phrase": "scaffold a page in the reports surface with --duo",
+      "should_route_to_project": true,
+      "expected_shape": "add-page",
+      "rationale": "Direct bin/adia-scaffold page invocation with the --duo flag named in the skill body."
+    },
+
+    {
+      "id": "project-addcomponent-01",
+      "phrase": "scaffold a new custom element folder in our app for the badge widget",
+      "should_route_to_project": true,
+      "expected_shape": "add-component",
+      "rationale": "add-component mode: a consumer-app custom element folder via bin/adia-scaffold component, not a framework primitive."
+    },
+    {
+      "id": "project-addcomponent-02",
+      "phrase": "add a component folder via adia-scaffold for the app's local <stat-card> element",
+      "should_route_to_project": true,
+      "expected_shape": "add-component",
+      "rationale": "Explicit adia-scaffold component invocation, app-local element."
+    },
+    {
+      "id": "project-addcomponent-03",
+      "phrase": "check that the new component's folder name matches its tag per convention",
+      "should_route_to_project": true,
+      "expected_shape": "add-component",
+      "rationale": "Verifies the add-component gate: components/<tag>/<tag>.{js,css} exists, folder = tag."
+    },
+
+    {
+      "id": "project-inventory-01",
+      "phrase": "audit this existing app's structure — score it against the structure rubric",
+      "should_route_to_project": true,
+      "expected_shape": "inventory",
+      "rationale": "The exact 'audit its structure' trigger phrase from the description, inventory mode."
+    },
+    {
+      "id": "project-inventory-02",
+      "phrase": "score whether our project shape still matches how the app has actually grown",
+      "should_route_to_project": true,
+      "expected_shape": "inventory",
+      "rationale": "Inventory mode: shape declared & matched is one of the rubric's named gates."
+    },
+    {
+      "id": "project-inventory-03",
+      "phrase": "check this rollup for duplicated cross-surface code",
+      "should_route_to_project": true,
+      "expected_shape": "inventory",
+      "rationale": "Names a specific structure-rubric gate ('no duplicated cross-surface code') verbatim."
+    },
+
+    {
+      "id": "project-adv-01",
+      "phrase": "add a surface for the new claims-review tool — we haven't decided mode or shell yet",
+      "should_route_to_project": false,
+      "expected_alternative": "adia-orient (adia-ui-factory plugin)",
+      "rationale": "Adversarial — the unevidenced handoff the audit flagged: 'add a surface' appears in both adia-orient's and adia-project's descriptions, but with mode/shape/shell still undecided this is cold-start orientation, not structure-laying. adia-project's add-surface mode presumes the shape is already picked."
+    },
+    {
+      "id": "project-adv-02",
+      "phrase": "scaffold a plain React app, no AdiaUI components involved",
+      "should_route_to_project": false,
+      "expected_alternative": "none",
+      "rationale": "Adversarial — 'scaffold an app' surface-matches the trigger phrase, but with no adia-ui in scope this is generic framework tooling; no AdiaUI skill should claim it."
+    },
+    {
+      "id": "project-adv-03",
+      "phrase": "restructure the framework monorepo's package layout under packages/web-components",
+      "should_route_to_project": false,
+      "expected_alternative": "adia-author (adia-ui-forge plugin)",
+      "rationale": "Adversarial — adia-project lays out a CONSUMER app's on-disk structure; restructuring the framework monorepo itself is forge-side authoring territory."
+    },
+    {
+      "id": "project-adv-04",
+      "phrase": "build the actual screen content for the new page we just scaffolded",
+      "should_route_to_project": false,
+      "expected_alternative": "adia-compose",
+      "rationale": "Adversarial — the description's own NOT-fence: 'the UI inside a screen' is adia-compose's job once adia-project has laid out where the page lives."
+    },
+    {
+      "id": "project-adv-05",
+      "phrase": "wire the host's SPA registration and CSS cascade for this app",
+      "should_route_to_project": false,
+      "expected_alternative": "adia-host",
+      "rationale": "Adversarial — host bootstrap/registration is explicitly deferred to adia-host in the description's NOT-fence."
+    },
+    {
+      "id": "project-adv-06",
+      "phrase": "wire up the state/data pattern for the new surface",
+      "should_route_to_project": false,
+      "expected_alternative": "adia-data",
+      "rationale": "Adversarial — state/data pattern choice is explicitly deferred to adia-data in the references section, distinct from structure/scaffolding."
+    }
+  ],
+
+  "evaluator_notes": {
+    "current_state": "20 cases (14 trigger + 6 adversarial). Trigger cases: 3 new-app, 2 add-surface, 3 add-page, 3 add-component, 3 inventory (all 5 modes covered).",
+    "promotion_criteria": "Promote to a CI gate (warn → hard-fail) when F1 >= 0.85 on this corpus across 3+ consecutive runs without description edits.",
+    "review_cadence": "Re-run on every adia-project description edit. Add 1-2 new cases per checkpoint reflecting newly-observed routing failure modes.",
+    "known_limitations": "project-adv-01 encodes the audit's flagged unevidenced handoff: 'add a surface' appears verbatim in both adia-orient's and adia-project's descriptions. The heuristic TF-IDF scorer cannot see whether mode/shape were already decided (that context lives in conversation state, not the phrase text alone), so this case is likely to be the corpus's most fragile — an LLM router resolves it on context adia-project's own description doesn't carry; the phrase text alone may false-positive toward adia-project until the description gains an explicit 'mode/shape already decided' qualifier."
+  }
+}

package/skills/adia-shells/SKILL.md

@@ -3,8 +3,9 @@ name: adia-shells
 description: >-
   Picks and composes an adia-ui page-chrome shell (@adia-ai/web-modules):
   admin (app frame), chat (LLM), editor (canvas+panes), simple
-  (marketing/error/landing), or embed. Use on "use a shell",
-  "sidebar + topbar layout", "embed this surface", or shell markup debugging.
+  (marketing/error), or embed. Use when asked to "use a
+  shell", "sidebar + topbar layout", "embed this surface", or on shell markup
+  debugging.
   NOT for screens inside it (adia-compose) or host/SSR wiring (adia-host).
 disable-model-invocation: false
 user-invocable: true
@@ -36,7 +37,7 @@ A composed shell is done when all five gates hold and the surface renders (`adia
 | Gate | Check | Enforcement |
 | --- | --- | --- |
 | Cluster registered | the barrel import is present; JS-bearing children resolve | self-verified |
-| Canonical nesting | parent→child structure matches the shell's reference (e.g. `admin-page` only inside `admin-scroll`; `admin-page-header` wraps `<header-ui>`, not a raw `<header>`) | self-verified against the reference |
+| Canonical nesting | parent→child structure matches the shell's reference (e.g. `admin-page` only inside `admin-scroll`; shell children never wrapped in `<col-ui>`/`<row-ui>` — the grid reads tag selectors) | self-verified against the reference |
 | No legacy shapes | no retired data-attribute forms | mechanized: `adia-lint` `LEGACY-SHELL` |
 | No native-primitive leak | controls are `*-ui`, not raw `<button>`/`<input>` | mechanized: `adia-lint` `NATIVE-PRIMITIVE` |
 | One route owner | SSR uses the framework outlet, not `<router-ui>` | self-verified |
@@ -44,6 +45,25 @@ A composed shell is done when all five gates hold and the surface renders (`adia
 The plugin's `bin/adia-lint` mechanizes the two marked gates on write; the other three are
 checked against the per-shell reference before declaring done.
 
+## Deliverable — the ShellComposition record
+
+Composing a shell emits this record — it materializes the pick table's "decide on a cited
+signal" demand and the five-gate table's results, in the same row order:
+
+```text
+Shell:                     admin | chat | editor | simple | embed | none  — signal: <file / dep / marker, or the user's explicit words>
+Barrel import:             <e.g. '@adia-ai/web-modules/shell'>
+Cluster registered:        pass | fail  — reference: <shell-<name>.md section checked>
+Canonical nesting:         pass | fail  — reference: <shell-<name>.md section checked>
+No legacy shapes:          pass | fail  — adia-lint: <LEGACY-SHELL output>
+No native-primitive leak:  pass | fail  — adia-lint: <NATIVE-PRIMITIVE output>
+One route owner:           pass | fail  — reference: <shell-<name>.md section checked>
+Reference consulted:       <shell-<name>.md>
+```
+
+The two mechanized gates cite `adia-lint`'s actual output; the three self-verified gates cite
+the reference section checked against, never an assumption.
+
 ## Shared conventions (every shell; the per-shell reference carries the specifics)
 
 - **Register by cluster barrel**, not piecemeal: `import '@adia-ai/web-modules/shell'` (or

package/skills/adia-shells/evals/routing-corpus.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-shells routing accuracy corpus",
+  "version": "1.0.0",
+  "purpose": "Routing-eval corpus for adia-shells (adia-ui-factory plugin). Each phrase declares whether adia-shells SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
+  "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
+  "license": "internal",
+  "scope": "adia-shells routing — does this phrase activate adia-shells?",
+
+  "minimums_per_spec": {
+    "trigger_phrases": 14,
+    "adversarial_phrases": 6,
+    "task_shapes_covered": "pick-admin, pick-chat, pick-editor, pick-simple, pick-embed, shell-debugging, shell-selection-generic",
+    "adversarial_fraction": "30%"
+  },
+
+  "phrases": [
+    {
+      "id": "shells-admin-01",
+      "phrase": "I need a sidebar + topbar layout with a command palette for this app",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-admin",
+      "rationale": "The exact 'sidebar + topbar layout' trigger phrase named in the description — this is the fence-test the audit flagged: it must land on adia-shells (picking page-chrome), not adia-compose (which builds screen content, not the frame around it)."
+    },
+    {
+      "id": "shells-admin-02",
+      "phrase": "set up the full app frame — sidebar(s) plus topbar plus command palette — for the dashboard",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-admin",
+      "rationale": "Restates the admin-shell decision-table signal ('full app frame — sidebar(s) + topbar + command palette + pages') in the requester's own words."
+    },
+    {
+      "id": "shells-chat-01",
+      "phrase": "build an LLM conversation surface with a thread and a composer",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-chat",
+      "rationale": "Matches chat-shell's decision-table signal: an LLM conversation surface (thread + composer)."
+    },
+    {
+      "id": "shells-chat-02",
+      "phrase": "wire up the chat-shell's thread and composer chrome",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-chat",
+      "rationale": "Names chat-shell directly and asks for its chrome, not the conversation content inside it."
+    },
+    {
+      "id": "shells-editor-01",
+      "phrase": "I need a design tool with a center canvas and resizable side panes",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-editor",
+      "rationale": "Matches editor-shell's decision-table signal: a design tool — center canvas + resizable side panes."
+    },
+    {
+      "id": "shells-editor-02",
+      "phrase": "add focus mode to the editor-shell's canvas + panes layout",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-editor",
+      "rationale": "Focus mode is an editor-shell chrome feature named in the skill body, not screen content."
+    },
+    {
+      "id": "shells-simple-01",
+      "phrase": "scaffold a minimal centered chrome for the marketing landing page",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-simple",
+      "rationale": "Matches simple-shell's decision-table signal: marketing/error/landing/auth — minimal centered chrome."
+    },
+    {
+      "id": "shells-simple-02",
+      "phrase": "pick a shell for the auth error page — it just needs minimal centered chrome",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-simple",
+      "rationale": "Explicit shell-selection ask against the simple-shell signal."
+    },
+    {
+      "id": "shells-embed-01",
+      "phrase": "embed this surface into a host page — size and center the light-DOM element",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-embed",
+      "rationale": "The exact 'embed this surface' trigger phrase named in the description, matched to embed-shell's decision-table row."
+    },
+    {
+      "id": "shells-embed-02",
+      "phrase": "wire the embed-shell cluster for the widget we're dropping into a third-party site",
+      "should_route_to_shells": true,
+      "expected_shape": "pick-embed",
+      "rationale": "Names embed-shell directly; cluster registration is shell-selection/composition territory."
+    },
+    {
+      "id": "shells-debug-01",
+      "phrase": "the sidebar's [collapsed] attribute doesn't collapse the admin-shell layout — help me debug the shell markup",
+      "should_route_to_shells": true,
+      "expected_shape": "shell-debugging",
+      "rationale": "The exact 'shell markup debugging' trigger phrase named in the description, tied to the shared state-is-an-attribute convention."
+    },
+    {
+      "id": "shells-debug-02",
+      "phrase": "adia-lint flagged a legacy <aside data-sidebar> shape in our shell — fix the markup",
+      "should_route_to_shells": true,
+      "expected_shape": "shell-debugging",
+      "rationale": "Legacy data-attribute shapes are called out explicitly in the skill body as retired shell-tier vocabulary; fixing them is shell markup debugging."
+    },
+    {
+      "id": "shells-generic-01",
+      "phrase": "use a shell for this new app frame",
+      "should_route_to_shells": true,
+      "expected_shape": "shell-selection-generic",
+      "rationale": "The literal 'use a shell' trigger phrase from the description with no shell yet named — canonical cold-start-within-shells ask."
+    },
+    {
+      "id": "shells-generic-02",
+      "phrase": "which shell fits an app that needs both a big canvas and side panes",
+      "should_route_to_shells": true,
+      "expected_shape": "shell-selection-generic",
+      "rationale": "A decision-cue question aimed at the pick-the-shell table without naming a shell — still adia-shells' job, not a specific-shell shape."
+    },
+
+    {
+      "id": "shells-adv-01",
+      "phrase": "compose the screens that go inside the admin-shell's page area",
+      "should_route_to_shells": false,
+      "expected_alternative": "adia-compose",
+      "rationale": "Adversarial — the audit's core fence question, resolved the other direction: screens INSIDE an already-chosen shell are adia-compose's job per the description's own NOT-fence."
+    },
+    {
+      "id": "shells-adv-02",
+      "phrase": "wire the SSR host so the framework's route outlet renders inside the shell",
+      "should_route_to_shells": false,
+      "expected_alternative": "adia-host",
+      "rationale": "Adversarial — host/SSR route-outlet wiring is explicitly carved out to adia-host in both the description and the shared-conventions section (NEVER mount <router-ui> under SSR — the framework outlet owns the route)."
+    },
+    {
+      "id": "shells-adv-03",
+      "phrase": "the admin-shell's sidebar-collapse behavior regressed — fix the bug in packages/web-modules source",
+      "should_route_to_shells": false,
+      "expected_alternative": "adia-author (adia-ui-forge plugin)",
+      "rationale": "Adversarial — a shell BUG in the framework monorepo itself (editing packages/web-modules source) is forge-side authoring, not factory-side shell selection/composition."
+    },
+    {
+      "id": "shells-adv-04",
+      "phrase": "wire the state/data hydration for the shell's sidebar list",
+      "should_route_to_shells": false,
+      "expected_alternative": "adia-data",
+      "rationale": "Adversarial — data/state pattern choice is adia-data's territory; adia-shells only reflects state as an attribute the consumer already owns."
+    },
+    {
+      "id": "shells-adv-05",
+      "phrase": "add the LLM streaming client to power the chat-shell's composer",
+      "should_route_to_shells": false,
+      "expected_alternative": "adia-llm",
+      "rationale": "Adversarial — the chat LLM client/proxy contract is explicitly deferred to adia-llm in the shell's own references section, even though it's chat-shell-adjacent."
+    },
+    {
+      "id": "shells-adv-06",
+      "phrase": "scaffold a brand new app's on-disk structure before we even pick a shell",
+      "should_route_to_shells": false,
+      "expected_alternative": "adia-project",
+      "rationale": "Adversarial — app structure/scaffolding precedes shell selection and belongs to adia-project; no shell has been named or implied."
+    }
+  ],
+
+  "evaluator_notes": {
+    "current_state": "20 cases (14 trigger + 6 adversarial). Each of the 7 task shapes (5 named shells + shell-debugging + shell-selection-generic) has 2 trigger cases.",
+    "promotion_criteria": "Promote to a CI gate (warn → hard-fail) when F1 >= 0.85 on this corpus across 3+ consecutive runs without description edits.",
+    "review_cadence": "Re-run on every adia-shells description edit. Add 1-2 new cases per checkpoint reflecting newly-observed routing failure modes.",
+    "known_limitations": "The audit's core open question — whether 'sidebar + topbar layout' reaches adia-shells or gets pulled toward adia-compose — is encoded as shells-admin-01/02 (positive) and shells-adv-01 (the compose-side adversarial); the heuristic TF-IDF scorer may not separate 'layout' (shell chrome) from 'screen'/'form'/'dashboard' (compose content) as cleanly as an LLM router would, since both descriptions share UI-layout vocabulary."
+  }
+}