@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/{adia-ui-release → adia-release}/scripts/dispatch-publish.mjs

@@ -14,14 +14,14 @@
 //   # Dry mode:
 //   node dispatch-publish.mjs --version 0.6.22 --dry
 //
-// Phase 2 of the adia-ui-release skill. Mechanizes the dispatch loop
+// Part of the adia-release skill. Mechanizes the dispatch loop
 // + handles the npm-latest ordering rule for batch pushes.
 
 import { execSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
 
-// Instance data — fork-configurable. The npm scope the 9 packages publish under.
+// Instance data — fork-configurable. The npm scope the 11 packages publish under.
 // Default preserves @adia-ai behavior; override via --scope or $ADIA_NPM_SCOPE.
 const DEFAULT_SCOPE = '@adia-ai';
 
@@ -35,6 +35,9 @@ const PACKAGES = [
   'a2ui-mcp',
   'a2ui-retrieval',
   'a2ui-validator',
+  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note).
+  'adia-ui-factory',
+  'adia-ui-forge',
 ];
 
 function parseArgs(argv) {
@@ -59,8 +62,8 @@ function parseArgs(argv) {
       console.log('--verify-triggered Instead of dispatching, check whether each per-package publish-<pkg>.yml');
       console.log('                   ALREADY has a run for the <pkg>-vX.Y.Z tag (i.e. push-on-tag fired), and');
       console.log('                   re-dispatch ONLY the misses. This is the recovery for the batch-tag-push');
-      console.log('                   skip (recovery-paths.md §Scenario 7) — a single `git push <10 tags>` can');
-      console.log('                   trigger ZERO publish workflows. Idempotent: re-dispatches nothing if all 9 fired.');
+      console.log('                   skip (recovery-paths.md §Scenario 7) — a single `git push <12 tags>` can');
+      console.log('                   trigger ZERO publish workflows. Idempotent: re-dispatches nothing if all 11 fired.');
       console.log(`--scope            npm scope the packages publish under (default: ${DEFAULT_SCOPE};`);
       console.log('                   or set $ADIA_NPM_SCOPE). The --after npm-latest check uses this scope.');
       process.exit(0);
@@ -146,7 +149,7 @@ function triggeredForTag(pkg, version, dry) {
 
 // The batch-tag-push-skip recovery: verify each per-package publish workflow
 // actually triggered off its pushed tag, and re-dispatch ONLY the misses.
-// Idempotent — re-dispatches nothing if all 9 fired.
+// Idempotent — re-dispatches nothing if all 11 fired.
 function verifyTriggeredAndRedispatch(version, dry) {
   console.log(`\nVerifying publish-on-tag triggered for all ${PACKAGES.length} packages (v${version}):`);
   const misses = [];
@@ -189,7 +192,7 @@ async function main() {
     await sleep(args.sleepBefore * 1000);
   }
 
-  console.log(`Dispatching 9 publish workflows for v${args.version}:`);
+  console.log(`Dispatching ${PACKAGES.length} publish workflows for v${args.version}:`);
   let succeeded = 0;
   for (const pkg of PACKAGES) {
     if (dispatch(pkg, args.version, args.dry)) succeeded++;
@@ -199,7 +202,7 @@ async function main() {
   if (!args.dry) {
     console.log(`\n[next] wait for workflows to settle:`);
     console.log(`  until [ "$(gh run list --workflow=publish-a2ui-validator.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`);
-    console.log(`\n[next] verify all 9 succeeded:`);
+    console.log(`\n[next] verify all 11 succeeded:`);
     console.log(`  for pkg in ${PACKAGES.join(' ')}; do`);
     console.log(`    gh run list --workflow=publish-$pkg.yml --limit 1 --json conclusion -q '.[0].conclusion'`);
     console.log(`  done`);

package/skills/{adia-ui-release → adia-release}/scripts/insert-stub.mjs

@@ -11,7 +11,7 @@
 //     --previous-version 0.6.21 \
 //     --packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
 //
-// Phase 2 of the adia-ui-release skill. Replaces the inline stub-
+// Part of the adia-release skill. Replaces the inline stub-
 // insertion pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21
 // cycles.
 

package/skills/{adia-ui-release → adia-release}/scripts/package-paths.mjs

@@ -35,6 +35,12 @@ export function resolvePackageDir(repo, pkg) {
     const nested = path.join('a2ui', m[1]);
     if (fs.existsSync(path.join(repo, 'packages', nested))) return nested;
   }
+  // Plugins live under packages/plugins/<name> but carry the flat name form
+  // (adia-ui-forge) in the release tooling — same name-vs-path split as a2ui.
+  if (/^adia-ui-/.test(pkg)) {
+    const nested = path.join('plugins', pkg);
+    if (fs.existsSync(path.join(repo, 'packages', nested))) return nested;
+  }
   return pkg; // fall through with the original arg so the not-found error names what was asked for
 }
 

package/skills/{adia-ui-release → adia-release}/scripts/promote-unreleased.mjs

@@ -11,7 +11,7 @@
 //   node promote-unreleased.mjs --version 0.6.22 --date 2026-05-22 \
 //     --packages web-components,web-modules --dry
 //
-// Phase 2 of the adia-ui-release skill. Replaces the inline heading-swap
+// Part of the adia-release skill. Replaces the inline heading-swap
 // pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21 cycles.
 //
 // Exits:

package/skills/{adia-ui-release → adia-release}/scripts/release-pack.mjs

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 // release-pack.mjs — full-cycle orchestrator for an AdiaUI lockstep release.
 //
-// Chains the 6 Phase-1/2/3 CLI helpers (bump · promote-unreleased ·
-// insert-stub · tag-lockstep · dispatch-publish · make-ledger) plus the
-// non-helper steps (lockfile · pre-flight gates · git commit · F-N1 ·
-// push · GH releases · site deploy) into one walked sequence with 3
-// operator checkpoints (before tag, before push, before publish) per
-// SKILL.md §Posture.
+// Chains the 5 CLI helpers (bump · promote-unreleased · insert-stub ·
+// tag-lockstep · dispatch-publish) plus the non-helper steps (lockfile ·
+// pre-flight gates · git commit · F-N1 · push · GH releases · site
+// deploy) into one walked sequence with 3 operator checkpoints (before
+// tag, before push, before publish) per SKILL.md operator checkpoints.
 //
 // MODES:
 //   --mode cut          (Mode 1 — peer pre-staged [Unreleased] or pure stub)
@@ -33,8 +32,8 @@
 //   --skip-gates         : (DEBUG ONLY) skip pre-flight (don't ship anything!)
 //   --skip-site          : skip the EXE deploy step (rare; for offline cycles)
 //
-// PHASE 4 of the adia-ui-release skill. Mechanizes the 11-step cycle from
-// references/cycle-happy-path.md while preserving operator judgment at
+// Part of the adia-release skill. Mechanizes the cut procedure from
+// references/cut-procedure.md while preserving operator judgment at
 // the 3 mutating-checkpoint boundaries.
 
 import { execSync } from 'node:child_process';
@@ -56,7 +55,9 @@ const DEFAULT_NPM_SCOPE = '@adia-ai';
 
 const PACKAGES = ['web-components', 'web-modules', 'llm', 'a2ui-runtime',
                   'a2ui-compose', 'a2ui-corpus', 'a2ui-mcp', 'a2ui-retrieval',
-                  'a2ui-validator'];
+                  'a2ui-validator',
+                  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note).
+                  'adia-ui-factory', 'adia-ui-forge'];
 
 function parseArgs(argv) {
   const args = {
@@ -252,7 +253,7 @@ function step5Commit(args) {
 // ── Step 6 — Tag ─────────────────────────────────────────────────
 async function step6Tag(args) {
   console.log('\n=== Step 6 — Tag at HEAD ===');
-  await checkpoint('Ready to create 10 tags (umbrella + 9 per-package)', args);
+  await checkpoint('Ready to create 12 tags (umbrella + 11 per-package)', args);
   sh(`node ${SCRIPT_DIR}/tag-lockstep.mjs --version ${args.version}`, args);
 }
 
@@ -271,15 +272,15 @@ function step7Fn1(args) {
 // ── Step 8 — Push ────────────────────────────────────────────────
 // Pushes per-package tags ONE-AT-A-TIME, not as a single batch.
 //
-// THE BATCH-PUSH SKIP (bit the v0.7.14 cut): `git push origin <10 tags>` in one
+// THE BATCH-PUSH SKIP (bit the v0.7.14 cut): `git push origin <12 tags>` in one
 // invocation fires the push-on-tag `create` event ONCE for the whole ref-set,
 // and GitHub Actions routinely drops it — ZERO publish-on-tag workflows trigger.
-// (Memory: feedback_publish_workflow_batch_push; recovery-paths.md §Scenario 7.)
+// (recovery-paths.md §Scenario 7 — the batch-tag-push publish-skip.)
 // Pushing each per-package tag separately gives the per-package publish-<pkg>.yml
 // `on: push: tags:` trigger its own create event. The umbrella tag is pushed
 // last (it triggers nothing — convention only).
 //
-// Step 9 dispatches all 9 publishes via workflow_dispatch regardless, so the
+// Step 9 dispatches all 11 publishes via workflow_dispatch regardless, so the
 // orchestrated cut does NOT rely on push-on-tag firing. The one-at-a-time push
 // is defensive (a cut aborted after Step 8 still has its publishes triggered)
 // AND keeps the standalone tag-lockstep.mjs hint honest.
@@ -287,7 +288,7 @@ async function step8Push(args) {
   console.log('\n=== Step 8 — Push main + tags (per-tag, NOT batched) ===');
   const count = shQuiet('git rev-list --count origin/main..HEAD', args).trim();
   console.log(`  commits to push: ${count}`);
-  await checkpoint(`Ready to push ${count} commit(s) + 10 tags (one-at-a-time)`, args);
+  await checkpoint(`Ready to push ${count} commit(s) + 12 tags (one-at-a-time)`, args);
   sh('git push origin main', args);
   const perPkgTags = PACKAGES.map((p) => `${p}-v${args.version}`);
   for (const t of perPkgTags) {
@@ -306,19 +307,32 @@ async function step8Push(args) {
 // for some/all packages. --verify-triggered checks which publish-<pkg>.yml runs
 // exist for the <pkg>-vX.Y.Z tags and re-dispatches ONLY the misses — closing the
 // batch-tag-push skip without double-publishing the ones that already fired.
-// Idempotent: if all 9 triggered (or none did), it does the right thing.
+// Idempotent: if all 11 triggered (or none did), it does the right thing.
 async function step9Publish(args) {
   console.log('\n=== Step 9 — Verify-triggered + re-dispatch misses ===');
-  await checkpoint('Ready to verify the 9 publish triggers + re-dispatch any misses', args);
+  await checkpoint('Ready to verify the 11 publish triggers + re-dispatch any misses', args);
   // Give GH a moment to index the runs created by the per-tag push in Step 8.
   if (!args.dry) sh('sleep 6', args);
   sh(`node ${SCRIPT_DIR}/dispatch-publish.mjs --version ${args.version} --scope ${args.scope} --verify-triggered`, args);
   console.log('\n  Waiting for publishes to settle...');
   sh(`until [ "$(gh run list --workflow=publish-a2ui-validator.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`, args);
   console.log('  ✓ publishes settled');
-  console.log('\n  Verify all 9 succeeded + npm latest:');
-  sh(`for pkg in ${PACKAGES.join(' ')}; do echo -n "$pkg: "; npm view "${args.scope}/$pkg" version 2>/dev/null; done`, args);
-  sh(`echo -n "latest: "; npm view ${args.scope}/web-components dist-tags.latest 2>/dev/null`, args);
+  // Fail-closed: the registry is the verify target (SKILL.md) — a missing or
+  // stale package aborts the cut here, before GH releases + site deploy.
+  console.log(`\n  Verify all ${PACKAGES.length} at ${args.version} + npm latest (fail-closed):`);
+  sh(
+    `fail=0; ` +
+    `for pkg in ${PACKAGES.join(' ')}; do ` +
+    `v="$(npm view "${args.scope}/$pkg" version 2>/dev/null || true)"; ` +
+    `echo "  $pkg: \${v:-MISSING}"; ` +
+    `[ "$v" = "${args.version}" ] || fail=1; ` +
+    `done; ` +
+    `latest="$(npm view ${args.scope}/web-components dist-tags.latest 2>/dev/null || true)"; ` +
+    `echo "  latest: \${latest:-MISSING}"; ` +
+    `[ "$latest" = "${args.version}" ] || fail=1; ` +
+    `[ "$fail" = 0 ] || { echo "ERROR: registry does not confirm ${args.version} across all ${PACKAGES.length} packages — fix before GH releases/deploy"; exit 1; }`,
+    args,
+  );
 }
 
 // ── Step 10 — GH releases + site deploy ──────────────────────────
@@ -341,15 +355,9 @@ async function step10GhAndSite(args) {
   }
   sh('npm run build:site', args);
   sh(`rsync -az --delete dist/ ${args.host}:/srv/adia-ui/dist/`, args);
-  sh(`curl -s -o /dev/null -w "EXE gen-ui: HTTP %{http_code}\\n" https://${args.host}/site/gen-ui/`, args);
-}
-
-// ── Step 11 — Ledger ─────────────────────────────────────────────
-function step11Ledger(args) {
-  console.log('\n=== Step 11 — Audit-history ledger ===');
-  const cmd = `node ${SCRIPT_DIR}/make-ledger.mjs --version ${args.version} --date ${args.date} --summary "<TODO: paste from commit message>" --note "Shipped via release-pack.mjs mode=${args.mode}"`;
-  sh(cmd, args);
-  console.log('\n  Edit the generated ledger to fill in scope/verification details, then commit + push.');
+  // Verify a deployed CONTENT FILE, never an SPA route — the docs site
+  // returns HTTP 200 + a blank shell for ANY unmatched route (v0.7.4 trap).
+  sh(`curl -s -o /dev/null -w "EXE host.css: HTTP %{http_code}\\n" https://${args.host}/packages/web-components/styles/host.css`, args);
 }
 
 // ── Main ─────────────────────────────────────────────────────────
@@ -357,7 +365,7 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to git/npm/gh/curl against a non-monorepo directory.
   assertMonorepoRoot(REPO);
-  console.log(`adia-ui-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
+  console.log(`adia-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
   step1ReBaseline(args);
   step3PreFlight(args);
   step4PromoteAndBump(args);
@@ -367,9 +375,8 @@ async function main() {
   await step8Push(args);
   await step9Publish(args);
   await step10GhAndSite(args);
-  step11Ledger(args);
   rl.close();
-  console.log('\n✓ release-pack complete. Don\'t forget to commit + push the ledger.');
+  console.log('\n✓ release-pack complete. Verify against the npm registry + GH releases, then author the release notes.');
 }
 
 main().catch((e) => {

package/skills/{adia-ui-release → adia-release}/scripts/tag-lockstep.mjs

@@ -8,7 +8,7 @@
 //   node tag-lockstep.mjs --version 0.6.22 --delete     # delete existing tags
 //   node tag-lockstep.mjs --version 0.6.22 --dry        # print commands without running
 //
-// Phase 2 of the adia-ui-release skill. Mechanizes the tag loop used
+// Part of the adia-release skill. Mechanizes the tag loop used
 // every cycle.
 
 import { execSync } from 'node:child_process';
@@ -25,6 +25,10 @@ const PER_PACKAGE_NAMES = [
   'a2ui-mcp',
   'a2ui-retrieval',
   'a2ui-validator',
+  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note);
+  // their `adia-ui-*-v*` tags trigger publish-adia-ui-{factory,forge}.yml.
+  'adia-ui-factory',
+  'adia-ui-forge',
 ];
 
 function parseArgs(argv) {
@@ -67,7 +71,7 @@ function main() {
   const tags = buildTagList(args.version);
 
   if (args.deleteMode) {
-    console.log(`Deleting 10 tags for v${args.version}:`);
+    console.log(`Deleting 12 tags for v${args.version}:`);
     for (const t of tags) {
       try {
         run(`git tag -d ${t}`, args.repo, args.dry);
@@ -81,7 +85,7 @@ function main() {
   }
 
   const targetSha = args.at || run('git rev-parse HEAD', args.repo, false).trim();
-  console.log(`Creating 10 tags for v${args.version} at ${targetSha.slice(0, 9)}:`);
+  console.log(`Creating 12 tags for v${args.version} at ${targetSha.slice(0, 9)}:`);
   for (const t of tags) {
     try {
       run(`git tag ${t} ${args.at || ''}`.trim(), args.repo, args.dry);

package/skills/adia-site-docs/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: adia-site-docs
+description: >-
+  Review or author pages under site/pages/{architecture,getting-started,
+  guides,patterns,reference}/ — the 34-page docs site. Use when asked to add
+  or edit a getting-started/architecture/guides/patterns/reference page,
+  review a site docs page for consistency, fix a callout that reads as plain
+  text, or explain why an inline-code chip or a demo gallery looks broken.
+  NOT for a component's own .examples.html demo (adia-author) or any
+  pure-primitive-composition training-harvest page (governed by
+  composition-and-examples.md's no-style-block rule; owner: adia-a2ui).
+disable-model-invocation: false
+user-invocable: true
+---
+
+# adia-site-docs
+
+Every page under `site/pages/{architecture,getting-started,guides,patterns,
+reference}/` shares one skeleton: `<header><h1>` + a deck `<p>`, then numbered
+`<section data-section data-property="...">` blocks, each opening
+`<h2 variant="section">` with an optional `<p data-note>` subtitle. Two
+archetypes ride it — narrative/explainer (architecture, getting-started,
+guides: prose + `<code-ui>` + tables, no live demos) and reference/gallery
+(patterns, reference: the same skeleton plus `<preview-ui>` demo rows and a
+near-universal closing "Guidance for agents" callout).
+
+Full decomposition, the 4 concrete rules, and the training-harvest-surface
+boundary this skill does NOT cover: read
+[`../../../../../.claude/docs/conventions/site-pages-authoring.md`](../../../../../.claude/docs/conventions/site-pages-authoring.md)
+in full before authoring or reviewing — it is the source of record; this
+skill routes to it and enforces it, it does not restate it.
+
+## Task shape → action
+
+| Task shape | Do |
+| --- | --- |
+| New page in an owned category | Read the convention doc's template section; copy the shared skeleton from a sibling page in the same category (narrative archetype vs. reference/gallery archetype). |
+| Callout / "meta content" block | `<alert-ui variant="warning\|info\|...">` with `<div slot="content">` (never `<span>` — the transpiler only treats `p`/`div`/`ul`/`ol` as prose; a `<span>` silently reorders mixed inline content on regen) for rich text — never a bare `data-*` attribute. A whole multi-heading section aimed at a different reader (not a short callout) is NOT `alert-ui`'s job either (wrong shape) — currently there's no working distinguishing treatment for this case beyond the heading text itself; see the convention doc's rule 2 for what's been tried and why it doesn't render. |
+| Tamed admin-shell demo | Add `class="demo-frame"` to the shell instance + a page-local `<style>` block setting only `--demo-frame-height` (and any genuinely page-specific extra). That's `site/site.css`'s `.demo-frame` utility already covering `position`/`border`/`overflow`/`.demo-body` padding. |
+| A surface needs to read as "its own distinct object" against the page background (a chip, a pill) | Reuse `--a-canvas-well-strong` (`packages/web-components/styles/colors/semantics/core.css`) — verified ≥3:1 (WCAG 2.2 SC 1.4.11) in both schemes. `--a-canvas-well` alone is for a subtly-sunken panel; a new candidate token always runs through `color:color-verify` first. |
+| "Is this page consistent?" / review request | Check the page against the convention doc's rules 1–4 by name; a finding names the specific rule violated, not just "this looks off." |
+| Anything touching a real UI primitive not already listed above | Audit `packages/web-components/components/` before inventing markup (this repo's standing rule) — a fake `data-*`/`class` convention with no CSS is exactly the defect class this skill exists to prevent. |
+
+## Verify after any change
+
+- `npm run check:links` — intra-repo links across the touched pages.
+- `node scripts/build/site-a2ui.mjs --page <route>` for every page whose
+  **markup** changed — regenerates the compiled A2UI artifact the
+  docs-transpiler produces from this source; a CSS-only fix needs no regen.
+- `color:color-verify` for any new or changed token used for text or
+  UI-component contrast — prove the ratio, don't estimate it.
+- `npm run check:lightningcss-build` after any CSS change (`site/site.css`
+  or a component's own `.css`).
+- **Visually verify any `alert-ui`/rich-slotted-content change in a
+  browser after regenerating** — a `valid:true` transpiler result and a
+  correct raw-HTML source do not prove the rendered order is correct;
+  the compiled `site-a2ui/pages/*.json` artifact is what's served, and
+  a wrong container tag (`<span>` instead of `<div>`) silently reorders
+  content while still passing schema validation. This is not optional
+  for this one content shape.
+
+A check that cannot run (missing script, no network for a build step) is a
+named blocker in the report — flag it and stop; never mark the page done on
+an assumed pass.
+
+Done when the touched page(s) pass the checks above and, for a reviewed
+page, every finding cites the specific rule in `site-pages-authoring.md` it
+violates.

package/skills/adia-site-docs/evals/audit-report.md

@@ -0,0 +1,30 @@
+# skill-review — adia-site-docs
+
+Skill: packages/plugins/adia-ui-forge/skills/adia-site-docs/SKILL.md · Standards: skill-authoring-standards · Lint: clean
+Verdict: PASS (no blocking finding)
+
+Lint verbatim: `skill-postwrite-invocation-lint · clean · .../adia-site-docs/SKILL.md`
+
+| ID | Verdict | Severity | Evidence (file:line) | Fix |
+|----|---------|----------|----------------------|-----|
+| R1 | PASS | — | SKILL.md:40 ("Never restate position/border/overflow…"), :41 (`--a-canvas-well-strong` verified ≥3:1), :43 (audit primitives before inventing markup) — each survives deletion; removing any re-admits a concrete defect class. | — |
+| R2 | PASS | — | Desc SKILL.md:4-8 front-loads verbatim user phrasings ("add or edit a … page", "review a site docs page", "fix a callout that reads as plain text"); fences use the parseable `NOT for X (owner)` form :9-12. Corpus routing (evals/routing-corpus.json) covers 16 should-fire + 6 adversarial. | — |
+| R3 | PASS w/ note | minor | Species=procedural (intent.md:3); dials explicit and agree (SKILL.md:13-14); name head `adia-site-docs` is a domain-noun, not the generic zero-derivation verb the standard prescribes for procedural — but it matches the whole plugin's `adia-<domain>` grammar (sibling adia-author is identically formed). Consistent within the estate; flagged only for the record. | Keep — estate naming convention governs; no change. |
+| R4 | PASS w/ note | minor | Load-bearing rows instantiate concrete actions (SKILL.md:38-43). Negative imperatives run to ~4 ("do NOT invent" :38, "never a bare data-*" :39, "Never restate" :40, "don't reach for a raw ramp step without color-verify" :41) — at/over the ≤3 hard-gate guideline. | Optional: demote the two style-choice negatives (:38, :41) to positive form; reserve NEVER for :39/:40 catastrophic invariants. |
+| R5 | PASS | — | Deliberately routes to `.claude/docs/conventions/site-pages-authoring.md` (SKILL.md:28-32) rather than copying rules 1-4; convention doc confirmed present with matching `### 1..4` headings. Drift pair avoided by design — the strongest dimension. | — |
+| R6 | PASS | — | Task-shape contract table up front (SKILL.md:34-43); verify steps + stopping predicate at tail (:45-58); body 59 lines (well under 500 / 5,000-token head); reference one level deep. | — |
+| R7 | PASS w/ gap | minor | Output contract present (review finding "cites the specific rule … it violates" :57-58); stopping predicate present ("Done when …" :56). No *named failure branches* (e.g. "if `check:links` cannot run → report blocker, do not mark done"). | Add one failure branch to the Verify section for a check that cannot run. |
+| R8 | PASS | — | Numeric anchors on load-bearing dims: "34-page" (:5,20), "≥3:1 (WCAG 2.2 SC 1.4.11)" (:41), "rules 1-4" (:42,57). No vague quantifiers on load-bearing lines. | — |
+
+## Additional evidence (non-scored hygiene)
+
+- **Phantom fence paths** (minor): description fences `site/pages/examples/**` and `site/pages/gen-ui/**` (SKILL.md:11); neither directory currently exists under `site/pages/` (only architecture, getting-started, guides, patterns, reference). The fence spends description budget on surfaces that are not yet present. Keep if these are planned training-harvest surfaces (intent.md:52 treats them as governed by composition-and-examples.md); otherwise trim to reclaim characters. Not blocking — the fence is still correct if/when those surfaces land, and adversarial-02 tests it.
+- **intent.md citation drift** (minor, not in payload): intent.md:64 cites `evals/evals.json`, but the shipped corpus is `evals/routing-corpus.json`. intent.md is a forge artifact, not skill payload, so it does not affect triggering — but repair the citation in the same edit to keep the record honest.
+
+## Top 3
+
+1. (minor) R7 — add one named failure branch to the Verify section (a check that cannot run → report blocker, do not mark done); procedural bodies owe an explicit failure branch, currently absent (SKILL.md:45-58).
+2. (minor) R4 — negative-imperative count sits at ~4; demote the two style-choice negatives (:38 section shape, :41 ramp step) to positive phrasing, reserving hard gates for the two real invariants (:39 fabricated data-*, :40 restated demo-frame CSS).
+3. (minor) Phantom fence — reconcile `site/pages/examples/**` and `site/pages/gen-ui/**` (SKILL.md:11): confirm they are planned surfaces or trim the fence; and fix the `evals.json` → `routing-corpus.json` citation in intent.md:64.
+
+No blocking or major findings. The skill's reference-don't-restate discipline (R5) and measured contrast anchor (R8) are its strongest features.

package/skills/adia-site-docs/evals/routing-corpus.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-site-docs routing accuracy corpus",
+  "version": "1.0.0",
+  "purpose": "Routing-eval corpus for adia-site-docs (adia-forge plugin). Each phrase declares whether adia-site-docs 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-site-docs routing — does this phrase activate adia-site-docs?",
+
+  "minimums_per_spec": {
+    "trigger_phrases": 16,
+    "adversarial_phrases": 6,
+    "task_shapes_covered": "new-page, review-page, callout-fix, demo-frame-consistency, contrast-token, sibling-boundary",
+    "adversarial_fraction": "27%"
+  },
+
+  "phrases": [
+    {
+      "id": "site-docs-review-01",
+      "phrase": "review this site docs page for consistency",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Canonical review-a-page task shape."
+    },
+    {
+      "id": "site-docs-review-02",
+      "phrase": "does this callout look like plain text to you",
+      "should_route_to_site_docs": true,
+      "expected_shape": "callout-fix",
+      "rationale": "Symptom description matching Defect 2 (fabricated data-alert)."
+    },
+    {
+      "id": "site-docs-review-03",
+      "phrase": "why is the code background not visible on this page",
+      "should_route_to_site_docs": true,
+      "expected_shape": "contrast-token",
+      "rationale": "Symptom description matching Defect 1 (inline-code contrast)."
+    },
+    {
+      "id": "site-docs-new-page-01",
+      "phrase": "add a new pattern page under site/pages/patterns",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "Explicit site/pages/patterns path mention."
+    },
+    {
+      "id": "site-docs-new-page-02",
+      "phrase": "author a new getting-started guide page",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "getting-started/ is one of this skill's 5 owned categories."
+    },
+    {
+      "id": "site-docs-new-page-03",
+      "phrase": "write a new architecture explainer page for the docs site",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "architecture/ is one of this skill's 5 owned categories."
+    },
+    {
+      "id": "site-docs-new-page-04",
+      "phrase": "create a reference page documenting the MCP tools",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "reference/ is one of this skill's 5 owned categories."
+    },
+    {
+      "id": "site-docs-demo-frame-01",
+      "phrase": "this demo page needs a tamed static frame like the other pattern pages",
+      "should_route_to_site_docs": true,
+      "expected_shape": "demo-frame-consistency",
+      "rationale": "Matches the .demo-frame consolidation rule."
+    },
+    {
+      "id": "site-docs-demo-frame-02",
+      "phrase": "add a new admin-shell demo to this patterns page without duplicating the taming CSS",
+      "should_route_to_site_docs": true,
+      "expected_shape": "demo-frame-consistency",
+      "rationale": "Direct match on rule 3 (reuse .demo-frame)."
+    },
+    {
+      "id": "site-docs-review-04",
+      "phrase": "is this site page consistent with our authoring conventions",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Direct convention-compliance ask."
+    },
+    {
+      "id": "site-docs-review-05",
+      "phrase": "audit site/pages/guides for the same callout bug we found elsewhere",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Explicit guides/ path + defect-class reference."
+    },
+    {
+      "id": "site-docs-callout-01",
+      "phrase": "this warning box on the docs page has no background at all",
+      "should_route_to_site_docs": true,
+      "expected_shape": "callout-fix",
+      "rationale": "Symptom description matching the fabricated data-alert defect."
+    },
+    {
+      "id": "site-docs-new-page-05",
+      "phrase": "what's the shared skeleton every site docs page should follow",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "Direct ask about the template decomposition this skill carries."
+    },
+    {
+      "id": "site-docs-contrast-01",
+      "phrase": "what token should a new chip-like surface use to stay readable against the page background",
+      "should_route_to_site_docs": true,
+      "expected_shape": "contrast-token",
+      "rationale": "Direct match on rule 1 (--a-canvas-well-strong)."
+    },
+    {
+      "id": "site-docs-review-06",
+      "phrase": "check the patterns pages for any other unstyled data attributes like data-alert",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Direct defect-class sweep request."
+    },
+    {
+      "id": "site-docs-new-page-06",
+      "phrase": "scaffold a new getting-started/theming-dark-mode.html page",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "Explicit new-file-under-owned-category shape."
+    },
+
+    {
+      "id": "site-docs-adversarial-01",
+      "phrase": "review this component's own demo gallery in its .examples.html file",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "packages/web-components/components/*/*.examples.html is adia-author's remit, not this skill's."
+    },
+    {
+      "id": "site-docs-adversarial-02",
+      "phrase": "fix this gen-ui training exemplar page under site/pages/examples",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "site/pages/examples/** is the pure-primitive-composition training-harvest surface governed by composition-and-examples.md + adia-a2ui, explicitly fenced out."
+    },
+    {
+      "id": "site-docs-adversarial-03",
+      "phrase": "tune the zettel retrieval threshold for the chunk corpus",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "A2UI pipeline internals belong to adia-a2ui, unrelated to site/pages authoring."
+    },
+    {
+      "id": "site-docs-adversarial-04",
+      "phrase": "add a new prop to the button-ui primitive",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "Primitive authoring is adia-author's remit."
+    },
+    {
+      "id": "site-docs-adversarial-05",
+      "phrase": "cut the next npm release for the 9 @adia-ai packages",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "Release engineering is adia-release's remit, unrelated to docs-page authoring."
+    },
+    {
+      "id": "site-docs-adversarial-06",
+      "phrase": "deploy the docs site to ui-kit.exe.xyz",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "Deploy operations are adia-deploy's remit; this skill authors content, it doesn't ship it."
+    }
+  ],
+
+  "evaluator_notes": "Adversarial phrases 1-2 specifically test the two hardest-to-distinguish fences (component .examples.html vs site/pages/patterns/*.html; site/pages/examples/** vs site/pages/{architecture,getting-started,guides,patterns,reference}/**) — both surfaces are literally *.html under similar-looking paths, so the description must lean on the explicit path lists, not just 'site pages' as a phrase."
+}