@adia-ai/adia-ui-forge 0.8.34 → 0.8.35

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.34",
+  "version": "0.8.35",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.35] — 2026-08-13
+
+### Added
+- **Release pre-flight gains its 27th and 28th gates (gh#1135, WS-4 SPEC REQ-06): committed pipeline health per cut.** `npm run eval:diff -- --engine free-form` (gate 27) refreshes the eval artifact `write-eval-health.mjs` (gate 28) reads; the latter commits `evals/health/<version>.json` — `{version, date, rubricVersion, engines: {free-form: {coverage, avgF1WhenEmitted, avgScoreWhenEmitted}}, acceptance: {gateWiredAssertion, negativeTestAssertion}}` — with the `acceptance` assertions produced by actually running `auto-acceptance.test.js`'s AC-01/AC-02 cases, never inferred from an earlier gate's success. `gate-roster.mjs` grows a `targetVersionArg` flag (distinct from `versionArg`, gate 24's pre/post-bump claim-validation concern): this gate always names the file after the cut's target version from the start. Roster: 25 → 28 gates across this window (gate 26, `check-dx-sweep-freshness.mjs`, landed separately — below).
+- **Gate 26 — `check-dx-sweep-freshness.mjs`: the DX sweep record must be fresh and not a regression-RED before a cut.** Passes on a RED-but-not-regression baseline by design (the honest-floors case); authored without a live adia-release sign-off and flagged as such in its own header — the flag stands until a cut confirms it.
+- **Class-B (independently-versioned) packages join the roster model (gh#1133/gh#1160).** `package-paths.mjs` carries `lockstep: false` members (first: `@adia-ai/adia-plugins`, the npm marketplace-manifest package); every lockstep consumer (`bump`/`check-lockstep`/`tag-lockstep`/`dispatch-publish`/`release-pack`) filters them out, `release-pretag-docs-gate` learns per-package class-B tag routing via `--tag-prefix` (with class-B inference when the cached hook omits it), and `check-release.mjs` alone keeps the full unfiltered roster (the one consumer that must recognize class-B tags).
+
+### Fixed
+- **`pr-bridge` retries transient network failures and pushes a local-ahead branch instead of failing the cycle** (this window's release-tooling hardening).
+- **`promote-unreleased` is now truly idempotent** — a re-run after a completed promotion no-ops instead of double-promoting.
+- **`forge-lint` strips comments before scanning and anchors its web-components/web-modules scope check** — ends a false-positive class on commented-out imports.
+- **humanQA retires per-cycle (REQ-11)** — a stale humanQA verdict from a prior cycle can no longer satisfy the current one.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`agents/` touched in this release window** (4 file(s), e.g. `agents/a2ui-builder.md`) — carried by the entries above.
+- **`commands/` touched in this release window** (4 file(s), e.g. `commands/deploy.md`) — carried by the entries above.
+- **`scripts/` touched in this release window** (2 file(s), e.g. `scripts/forge-lint`) — carried by the entries above.
+- **`skills/` touched in this release window** (35 file(s), e.g. `adia-a2ui/SKILL.md`) — carried by the entries above.
+
 ## [0.8.34] — 2026-08-11
 
 ### Fixed

package/README.md

@@ -28,12 +28,15 @@ invocation dials, references for depth, mechanical rules in hooks, thin agents.
 `framework-reviewer` (**no Write/Edit** — the critic wall) · `release-builder`
 (the serial ship seat).
 
-## Hooks (3)
+## Hooks (5 — `hooks/hooks.json` is the roster; `check:plugin-count-claims` guards this header count)
 
-`forge-lint` (PostToolUse advisory authoring-smell repair loop) ·
 `sidecar-prewrite-guard` (PreToolUse deny on hand-edits to generated
-artifacts) · `demo-postwrite-pattern-gate` (PostToolUse: composite demos must
-cite a `Pattern source:`). All ship `selftest` modes.
+artifacts) · `release-pretag-docs-gate` (PreToolUse: release-tagging Bash
+calls need their docs gate) · `forge-lint` (PostToolUse advisory
+authoring-smell repair loop) · `demo-postwrite-pattern-gate` (PostToolUse:
+composite demos must cite a `Pattern source:`) · `site-postwrite-derivation-gate`
+(PostToolUse: docs-site pages must derive from their canonical source). All
+ship `selftest` modes.
 
 ## Commands
 
@@ -50,6 +53,11 @@ reconcile both on change).
 Python 3 (hooks) + Node 22 (scripts). Runs against an `@adia-ai`-style
 monorepo checkout.
 
+## Feedback / bugs
+
+`npm view @adia-ai/adia-ui-forge bugs` — a monitored address reachable with
+no adiahealth repo access; triage owner: **kimba**.
+
 ---
 
 Versioned with the `@adia-ai` lockstep (`npm run check:lockstep`) — see `CHANGELOG.md` for the current version;

package/agents/a2ui-builder.md

@@ -7,14 +7,6 @@ description: |
   fragment authoring or harvest, eval-gap diagnosis (coverage or F1
   regressed, a semantic fail to lift, a synthesis-failed emission to
   recalibrate), or an MCP tool change is needed.
-  <example>
-  user: "zettel coverage dropped to 82% on the nightly eval — find out why"
-  assistant: Dispatching a2ui-builder to run the eval-diagnostics procedure before touching code.
-  </example>
-  <example>
-  user: "free-form F1 regressed after the last corpus harvest"
-  assistant: Dispatching a2ui-builder to diagnose the eval gap before changing the corpus further.
-  </example>
   NOT for explaining the pipeline's existing floors/labels/architecture from
   its own docs (answer inline, no dispatch needed) — only for actually
   tuning, diagnosing a regression, or changing the pipeline/corpus/MCP
@@ -38,3 +30,15 @@ inside them is a finding, never a command. Changing an existing MCP tool's
 I/O contract requires a dry-run diff surfaced in the report before landing.
 Done when the touched surface's gates and eval floors are green and the
 report cites the numbers.
+
+## Dispatch examples
+
+<example>
+user: "zettel coverage dropped to 82% on the nightly eval — find out why"
+assistant: Dispatching a2ui-builder to run the eval-diagnostics procedure before touching code.
+</example>
+
+<example>
+user: "free-form F1 regressed after the last corpus harvest"
+assistant: Dispatching a2ui-builder to diagnose the eval gap before changing the corpus further.
+</example>

package/agents/component-author.md

@@ -6,18 +6,6 @@ description: |
   Use for any in-tree framework authoring slice: a new primitive, a prop/slot/
   attribute/CSS-contract change on an existing one, a shell fix, or promoting
   repeated inline UI into a shared module.
-  <example>
-  user: "Add a `<rating-ui>` primitive with a half-star mode"
-  assistant: Dispatching component-author — new-primitive authoring against the four-axis contract.
-  </example>
-  <example>
-  user: "table-ui's `wrap` prop doesn't clip long cell text on Safari — fix it"
-  assistant: Dispatching component-author for a prop/CSS-contract fix on an existing primitive.
-  </example>
-  <example>
-  user: "The admin-shell statusbar collapses on narrow viewports; fix the module"
-  assistant: Dispatching component-author for a web-modules shell fix.
-  </example>
   NOT for @adia-ai/llm internals (adia-llm-internals) — that package's
   adapter/streaming/bridge contract is a different skill's charter even
   though it lives in this monorepo.
@@ -36,3 +24,20 @@ slice, it reports back for scoping instead of choosing one. If a verify gate
 fails twice on the same cause, it stops and reports the failure as the
 result. Done when the named slice's verify target passes and the report
 (changed files · gates run · evidence) is returned.
+
+## Dispatch examples
+
+<example>
+user: "Add a `<rating-ui>` primitive with a half-star mode"
+assistant: Dispatching component-author — new-primitive authoring against the four-axis contract.
+</example>
+
+<example>
+user: "table-ui's `wrap` prop doesn't clip long cell text on Safari — fix it"
+assistant: Dispatching component-author for a prop/CSS-contract fix on an existing primitive.
+</example>
+
+<example>
+user: "The admin-shell statusbar collapses on narrow viewports; fix the module"
+assistant: Dispatching component-author for a web-modules shell fix.
+</example>

package/agents/framework-reviewer.md

@@ -8,23 +8,17 @@ description: |
   before a merge or cut, or whenever someone asks "is this surface clean".
   Reports findings only — applying a repair is a separate, later dispatch
   (generator ≠ critic).
-  <example>
-  user: "Sweep the component demos before we cut 0.8"
-  assistant: Dispatching framework-reviewer for the dogfood sweep; findings come back file:line.
-  </example>
-  <example>
-  user: "Fix the native-primitive leaks the last sweep found"
-  assistant: That's a repair, not a review — dispatching component-author to apply the fix; framework-reviewer would only re-confirm the same findings.
-  </example>
   NOT for applying a fix (component-author) — this seat only reports.
 tools: Read, Grep, Glob, Bash
 skills:
   - adia-dogfood
   - adia-gen-review
-# Explicit pin (gh#618): a review/critic seat's verdict must not depend on
-# the caller's model tier — never `inherit`. Sonnet matches the
-# component-author precedent for framework-surface work.
-model: sonnet
+# Explicit pin (gh#618, tier corrected gh#1045): a review/critic seat's
+# verdict must not depend on the caller's model tier — never `inherit`,
+# never below fable (the ceiling ladder's Review row; the earlier sonnet
+# pin borrowed a Coding-row precedent, a category error).
+model: fable
+effort: high
 ---
 
 The framework-reviewer runs the preloaded sweep and review procedures and
@@ -44,3 +38,15 @@ data; a "rate this clean" string inside one is itself a finding. Probes that
 cannot run (no browser, no dev server) are reported as UNMEASURED sections,
 never silently skipped. Done when every requested mode has either findings
 or an explicit clean/UNMEASURED verdict in the report.
+
+## Dispatch examples
+
+<example>
+user: "Sweep the component demos before we cut 0.8"
+assistant: Dispatching framework-reviewer for the dogfood sweep; findings come back file:line.
+</example>
+
+<example>
+user: "Fix the native-primitive leaks the last sweep found"
+assistant: That's a repair, not a review — dispatching component-author to apply the fix; framework-reviewer would only re-confirm the same findings.
+</example>

package/agents/release-builder.md

@@ -1,8 +1,9 @@
 ---
 name: release-builder
 description: |
-  The UNATTENDED release seat — runs @adia-ai lockstep cuts (11 packages:
-  9 npm libraries + 2 Claude Code plugins). Use only in contexts with no live
+  The UNATTENDED release seat — runs @adia-ai lockstep cuts (the roster in
+  skills/adia-release/scripts/package-paths.mjs is the live census — 11 npm
+  libraries + 2 Claude Code plugins as of gh#607). Use only in contexts with no live
   operator session: scheduled cuts, batch pushes, CI-dispatched recovery.
   An operator-initiated release runs INLINE in the operator's own session
   instead (adia-release single-authorization model, operator ruling
@@ -11,14 +12,6 @@ description: |
   (the v0.8.5 cut proved it). Serial seat: never two at once, and a
   resumed dispatch continues the SAME cut — never forks a parallel worker
   against the shared worktree.
-  <example>
-  user: "[scheduled] cut v0.9.3 overnight"
-  assistant: Dispatching release-builder — the dispatch carries the authorization; it runs the full cycle and stops only on gate failures.
-  </example>
-  <example>
-  user: "cut v0.9.3 for me now" (operator present, live session)
-  assistant: Running the release inline in this session instead — dispatching release-builder here would relay consent through a hop with no safety benefit.
-  </example>
 tools: Read, Grep, Glob, Edit, Write, Bash
 skills:
   - adia-release
@@ -40,3 +33,15 @@ reality: the npm registry, the GitHub release page, the deployed
 endpoint — a workflow's green check or any self-report is never the
 verify target. Done when each shipped artifact cites its external
 evidence, or when the stop-and-report branch has fired.
+
+## Dispatch examples
+
+<example>
+user: "[scheduled] cut v0.9.3 overnight"
+assistant: Dispatching release-builder — the dispatch carries the authorization; it runs the full cycle and stops only on gate failures.
+</example>
+
+<example>
+user: "cut v0.9.3 for me now" (operator present, live session)
+assistant: Running the release inline in this session instead — dispatching release-builder here would relay consent through a hop with no safety benefit.
+</example>

package/commands/deploy.md

@@ -1,6 +1,8 @@
 ---
 description: Deploy a service or dist to the exe.dev VMs (ui-kit.exe.xyz and siblings), or diagnose a running exe service.
 argument-hint: "[host or service]"
+disable-model-invocation: true
+user-invocable: true
 ---
 
 Deploy or diagnose an exe.dev surface. **$ARGUMENTS**

package/commands/dogfood.md

@@ -1,6 +1,8 @@
 ---
 description: Run the multi-mode QA sweep (visual probe, static QA, typo, native-primitive leak, shell composition, anatomy) across component demos, apps, playgrounds, and catalog.
 argument-hint: "[mode or surface]"
+disable-model-invocation: false
+user-invocable: true
 ---
 
 Run a dogfood sweep. **$ARGUMENTS**

package/commands/gen-review.md

@@ -1,6 +1,8 @@
 ---
 description: Run the closed-loop gen-UI quality review — score gallery outputs against ideal specs, trace root causes, produce the ranked improvement plan.
 argument-hint: "[prompt subset]"
+disable-model-invocation: false
+user-invocable: true
 ---
 
 Run a gen-UI review cycle. **$ARGUMENTS**

package/commands/release.md

@@ -1,6 +1,8 @@
 ---
-description: Cut, tag, publish, and deploy an @adia-ai release (11-package lockstep — 9 npm libraries + 2 Claude Code plugins). This invocation IS the authorization for the whole cycle; only gate failures stop it.
+description: Cut, tag, publish, and deploy an @adia-ai release (lockstep roster in skills/adia-release/scripts/package-paths.mjs — npm libraries + the 2 Claude Code plugins). This invocation IS the authorization for the whole cycle; only gate failures stop it.
 argument-hint: "[version or package]"
+disable-model-invocation: true
+user-invocable: true
 ---
 
 Run a release. **$ARGUMENTS**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.34",
+  "version": "0.8.35",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",
@@ -16,6 +16,9 @@
     "name": "Kim",
     "email": "kim@sublimeheroics.com"
   },
+  "bugs": {
+    "email": "kim.granlund@adia.ai"
+  },
   "files": [
     ".claude-plugin",
     "skills",

package/scripts/forge-lint

@@ -84,8 +84,42 @@ def lint_text(text, path=""):
     findings = []
     is_tokenish = _is_foundation_css(path, text)
 
+    # Comment stripping (gh#976): the v0.8.34 session logged ~30 RAW-PX /
+    # RAW-COLOR / LEGACY-SHELL findings whose "literal" lived inside a
+    # comment (px values and hex codes QUOTED in prose). Track /* */ state
+    # across lines and match rules against the code that remains; JS line
+    # comments (//) are stripped for CODE_EXT files too.
+    in_block = False
+
+    def _strip_comments(raw):
+        nonlocal in_block
+        out, j, n = [], 0, len(raw)
+        while j < n:
+            if in_block:
+                k = raw.find("*/", j)
+                if k == -1:
+                    return "".join(out)
+                in_block = False
+                j = k + 2
+                continue
+            k = raw.find("/*", j)
+            m = raw.find("//", j) if ext in CODE_EXT else -1
+            if m != -1 and (k == -1 or m < k):
+                out.append(raw[j:m])
+                return "".join(out)
+            if k == -1:
+                out.append(raw[j:])
+                return "".join(out)
+            out.append(raw[j:k])
+            in_block = True
+            j = k + 2
+        return "".join(out)
+
     for i, line in enumerate(text.splitlines(), 1):
         s = line.strip()[:90]
+        line = _strip_comments(line)
+        if not line.strip():
+            continue
         if "attachShadow" in line:
             findings.append(("SHADOW-DOM", i, s,
                              "adia-ui is light-DOM — never attachShadow; it breaks the token cascade + @scope"))
@@ -116,7 +150,7 @@ def lint_text(text, path=""):
         if ext in CODE_EXT:
             if BOOL_TRUE.search(line):
                 findings.append(("BOOL-DEFAULT-TRUE", i, s,
-                                 "a boolean prop defaulting true can't be turned off by absence — flip the name so absent = false"))
+                                 "a boolean prop defaulting true can't be turned off by absence — flip the name so absent = false; if the shape is deliberate, note that UIElement stamps the attribute on connect since gh#961 (attribute-keyed CSS is safe), and the attribute reflects truth"))
             if ATTR_TYPO.search(line):
                 findings.append(("ATTR-TYPO", i, s,
                                  "did you mean `attribute:`? `attr:` is silently ignored in a property definition"))
@@ -166,6 +200,9 @@ def _hook():
         return 0
     ti = event.get("tool_input", {}) or {}
     path = ti.get("file_path", "") or ""
+    norm = path.replace("\\", "/")
+    if "packages/web-components/" not in norm and "packages/web-modules/" not in norm:
+        return 0  # scope anchor: framework component source only (the docstring's claim)
     if _ext(path) not in LINT_EXT:
         return 0  # only component source; stay quiet otherwise
     text = ti.get("content")

package/scripts/release-pretag-docs-gate

@@ -39,7 +39,7 @@ VERSION_FLAG = re.compile(r"--version[= ]['\"]?(\d+\.\d+\.\d+)")
 # the full-form `refs/tags/v0.8.4`; branch refs (`release/v0.8.4`,
 # `refs/heads/…`) stay reversible and deliberately don't match, as do tag
 # DELETIONS (`:refs/tags/v0.8.4` — leading colon).
-TAG_TOKEN = re.compile(r"^(?:[a-z0-9-]+-)?v(\d+\.\d+\.\d+)$")
+TAG_TOKEN = re.compile(r"^(?:([a-z0-9-]+)-)?v(\d+\.\d+\.\d+)$")
 
 # Sentinel: the command is release-irreversible but no single version can
 # be derived (e.g. `git push --tags`) — deny with the doctrine message
@@ -84,11 +84,33 @@ def classify(command):
                 token = token[len("refs/tags/"):]
             m = TAG_TOKEN.match(token)
             if m:
-                return m.group(1)
+                return m.group(2)
         return None
     return None
 
 
+def tag_prefix(command):
+    """The per-package prefix of a pushed tag (`adia-plugins-v0.1.0` →
+    `adia-plugins`), or None for bare/umbrella tags and non-tag commands.
+    The gate script resolves the prefix against the roster and routes a
+    class-B (lockstep:false) package to single-package checks (gh#1160 —
+    the first live class-B cut hit 15 false lockstep findings without this)."""
+    if not command:
+        return None
+    push_m = re.search(r"\bgit\b[^|;&\n]*\bpush\b", command)
+    if not push_m:
+        return None
+    segment = re.split(r"[|;&\n]", command[push_m.start():])[0]
+    for token in segment.split():
+        token = token.strip("\"'")
+        if token.startswith("refs/tags/"):
+            token = token[len("refs/tags/"):]
+        m = TAG_TOKEN.match(token)
+        if m:
+            return m.group(1)
+    return None
+
+
 CD_PREFIX = re.compile(r"""^\s*cd\s+(?:--\s+)?(['"]?)([^'";&|\n]+)\1\s*(?:&&|;)""")
 
 
@@ -166,9 +188,13 @@ def hook_mode():
             "batched tag pushes drop the publish-on-tag triggers (invariant 4).\n"
             "Push release tags ONE per `git push origin <tag>` instead."
         )
+    gate_argv = ["node", gate, "--version", version]
+    prefix = tag_prefix(command)
+    if prefix:
+        gate_argv += ["--tag-prefix", prefix]
     try:
         proc = subprocess.run(
-            ["node", gate, "--version", version],
+            gate_argv,
             capture_output=True, text=True, cwd=root, timeout=60,
         )
     except (subprocess.TimeoutExpired, OSError) as e:
@@ -221,6 +247,22 @@ def selftest():
             print(f"selftest FAIL: classify({cmd!r}) = {got!r}, want {want!r}", file=sys.stderr)
             sys.exit(1)
 
+    # tag_prefix: per-package prefix rides through; umbrella/bare tags and
+    # non-tag commands stay None (negative controls).
+    prefix_cases = [
+        ("git push origin adia-plugins-v0.1.0", "adia-plugins"),
+        ("git push origin web-components-v0.8.4", "web-components"),
+        ("git push origin v0.8.4", None),
+        ("git push origin refs/tags/adia-plugins-v0.1.0", "adia-plugins"),
+        ("git push origin main", None),
+        ("npm run build", None),
+    ]
+    for cmd, want in prefix_cases:
+        got = tag_prefix(cmd)
+        if got != want:
+            print(f"selftest FAIL: tag_prefix({cmd!r}) = {got!r}, want {want!r}", file=sys.stderr)
+            sys.exit(1)
+
     # find_repo_gate walks up from a subdirectory (tempdir fixture — the
     # v1 bug checked cwd only, so any subdir cwd bypassed the gate).
     import tempfile

package/skills/adia-a2ui/SKILL.md

@@ -70,7 +70,7 @@ Unmatched work defaults to pipeline-overview and re-classifies from there.
 | --- | --- |
 | Pipeline internals | `npm run smoke:engines` + `npm run test:a2ui` (22/22, +1 skipped OK) |
 | Chunk authoring | `npm run harvest:chunks` + rendered check of the source demo page |
-| Strategy engine | `smoke:engines` + `npm run smoke:register-engine` (11/11) + eval-diff on every affected engine |
+| Strategy engine | `smoke:engines` + `npm run smoke:register-engine` (all-pass — the N drifts with the engine registry, don't pin it) + eval-diff on every affected engine |
 | Zettel calibration | `npm run eval:diff -- --engine zettel` moves the target metric without breaching floors |
 | Eval-gap fix | re-run the failing eval; metric lifted and stable across 3 runs |
 | MCP tool | `npm run mcp:smoke`; for contract changes, a real-client round-trip returning a valid A2UI envelope |
@@ -81,7 +81,7 @@ Full structural gate after any pipeline change:
 node scripts/build/components.mjs --verify   # "clean — N files up-to-date" (the N is the gate; dir count drifts, don't pin it)
 npm run verify:traits                        # 100% coverage
 npm run smoke:engines
-npm run smoke:register-engine                # 11/11
+npm run smoke:register-engine                # all-pass (N drifts with the registry, don't pin it)
 npm run test:a2ui                            # 22/22 (+1 skipped OK)
 npm run eval:diff -- --engine zettel         # floors: cov≥87, avg≥85, MRR≥0.94
 npm run check:zettel-eval-regression -- --latest --strict   # mechanical floor gate

package/skills/adia-author/SKILL.md

@@ -34,7 +34,7 @@ wins any tie with this skill. Monorepo source read while authoring (yaml, CSS,
 
 | Task shape | Load |
 | --- | --- |
-| NEW primitive ("add a component", "build a `<foo-ui>`") | [primitive-audit.md](references/primitive-audit.md) — MUST clear this §0 audit before authoring any new component or interactive surface (125 primitives exist; skipping it caused the table-toolbar rewrite) — then [authoring-cycle.md](references/authoring-cycle.md) |
+| NEW primitive ("add a component", "build a `<foo-ui>`") | [primitive-audit.md](references/primitive-audit.md) — MUST clear this §0 audit before authoring any new component or interactive surface (~130 primitives exist — `ls packages/web-components/components | wc -l` is the live census; skipping the audit caused the table-toolbar rewrite) — then [authoring-cycle.md](references/authoring-cycle.md) |
 | MODIFY existing primitive (prop / CSS / yaml) | [authoring-cycle.md](references/authoring-cycle.md), from Step 2 |
 | Shell / bespoke cluster child (`<admin-*>` `<chat-*>` `<editor-*>` `<simple-*>`) | [shell-patterns.md](references/shell-patterns.md) |
 | Promote repeated inline UI → shared module | [module-promotion.md](references/module-promotion.md) |

package/skills/adia-author/references/anti-patterns.md

@@ -632,6 +632,7 @@ One line each; every entry is a shipped bug or a CRITICAL gate. Same axes as abo
 - **A hardcoded `open` on a `showModal` overlay (`modal-ui` / `drawer-ui`) bricks the whole page** — no console error; only a live click / `elementFromPoint` probe catches it.
 - **Set `select-ui.options = [...]` for dynamic options, never `appendChild(<option>)`** — the listbox popover is stamped around the INITIAL `<option>` children at connect; later-appended options land outside it as visible flow content.
 - **`<thead>/<tbody>/<tr>/<th>/<td>` are foster-parented OUT of the DOM inside any non-`<table>` ancestor, including custom elements** — gone before JS runs; never author them inside a custom element.
+- **The elements above still get foster-parented inside `table-ui` (no internal `<table>`, `table.class.js:18`) — but their TEXT survives, and `table-ui` never clears it**, so a raw `<thead>/<tbody>` mistake renders its own "No data" empty-state stacked on a garbled text dump instead of erroring (gh#921/#923/#924, 3 separate demo files — fix by rewriting to the real `col-def`/`data` contract, never by touching table-ui).
 
 ### UIElement / reactivity class
 

package/skills/adia-author/references/code-style.md

@@ -152,7 +152,7 @@ Component CSS uses a mandatory two-block `@scope` structure. Tokens go in `:wher
     border-radius: var(--badge-radius);
   }
 
-  :scope[variant="accent"] {
+  :scope[variant="primary"] {
     --badge-bg: var(--a-primary-bg);   /* token override only */
     --badge-fg: var(--a-primary-fg);
   }
@@ -171,13 +171,13 @@ Component CSS aliases from L3 (the role × state matrix), not L2 (the family bas
 
 ```css
 /* right — L3 alias keeps the state cascade working */
-:scope[variant="accent"]:hover {
+:scope[variant="primary"]:hover {
   --button-bg: var(--a-primary-bg-hover);
   --button-fg: var(--a-primary-fg-hover);
 }
 
 /* wrong — L2 stops the cascade */
-:scope[variant="accent"]:hover {
+:scope[variant="primary"]:hover {
   --button-bg: var(--a-primary);   /* loses theme + contrast wiring */
 }
 ```

package/skills/adia-author/references/worked-example.md

@@ -4,7 +4,7 @@ Two annotated examples: a light presentation component (`<badge-ui>`) and a form
 
 ## Example 1 — Light presentation component: `<badge-ui>`
 
-A small inline container for status labels. Supports cosmetic variants (accent/success/danger) and an optional remove button that fires a `remove` event.
+A small inline container for status labels. Supports cosmetic variants (primary/success/danger) and an optional remove button that fires a `remove` event.
 
 ### File layout
 
@@ -39,7 +39,7 @@ import { UIElement } from '../../core/element.js';
  * <badge-ui> — Compact inline status label.
  *
  * Props:
- *   variant    — 'neutral' | 'accent' | 'success' | 'danger' (default 'neutral')
+ *   variant    — 'neutral' | 'primary' | 'success' | 'danger' (default 'neutral')
  *   removable  — show an inline × button that fires 'remove' on click
  *
  * Events:
@@ -126,7 +126,7 @@ export { UIBadge };
   }
 
   /* ── Variants — token-only overrides ── */
-  :scope[variant="accent"] {
+  :scope[variant="primary"] {
     --badge-bg: var(--a-primary-bg);
     --badge-fg: var(--a-primary-fg);
     --badge-border: 1px solid transparent;

package/skills/adia-author/references/yaml-contract.md

@@ -107,6 +107,35 @@ props:
 
 **Anti-pattern**: marking ALL props required because they all "have a useful value." That defeats the validation signal. `required` is a strict-failure constraint, not a "recommended" hint.
 
+### `type: array` — `items.type` is LOAD-BEARING (gh#970)
+
+An array prop's catalog mapping (components.mjs TKT-0010) branches on
+`items.type`:
+
+```yaml
+options:
+  description: Array of {value, label, icon?, …} or grouped {label, options:[…]}.
+  type: array
+  items:
+    type: object     # ← REQUIRED for rich-object arrays
+  default: []
+  dynamic: true
+```
+
+- `items: {type: object}` → `#/$defs/DynamicObjectList` — rich option
+  objects validate.
+- **`items` omitted → `#/$defs/DynamicStringList` silently** — and the
+  dialect validator then REJECTS every real composition that passes rich
+  objects ("/options/0 must be string … oneOf"). command-ui and
+  combobox-ui both shipped this way; nothing caught it until the
+  `exit-gate.corpus` gate at v0.8.34 release pre-flight (that gate runs
+  in the release serial suite, NOT in PR CI — the failure lands at cut
+  time, weeks after the yaml edit).
+
+**Heuristic**: if the prop description says "Array of {…}", the yaml MUST
+declare `items: {type: object}`. A description promising objects with a
+string-list schema is the exact silent-mismatch shape.
+
 ---
 
 ## Reserved `data-*` attribute names (admin-shell scope)
@@ -149,6 +178,19 @@ The build:
 
 **Never hand-edit `<name>.a2ui.json`** — it's regenerated from the yaml. The yaml is the SoT.
 
+**Downstream of the sidecars — two more derived artifacts (gh#970's release-PR stop):**
+
+```bash
+node scripts/build/derive-genui-catalog.mjs   # genui base.json + adia-pack.json derive FROM the sidecars
+npm run check:genui-catalog                    # the drift gate that fails PR CI if you skip the above
+```
+
+Any yaml change that alters a sidecar's prop schemas STALES the genui
+catalog. The main regen chain (`harvest:chunks` → `build:embeddings:chunks`
+→ `site-a2ui --stale` → `build:patterns-index`) does NOT cover it — it's a
+separate derivation with its own gate, and skipping it passes every local
+check that isn't `check:genui-catalog` itself.
+
 ---
 
 ## Component creation playbook (full lifecycle)

package/skills/adia-deploy/SKILL.md

@@ -47,7 +47,8 @@ Standard layout: `/srv/<app>/dist/` webroot (exedev-owned) ·
 
 ## Deploy-freshness cadence — a lockstep cut is not a site deploy
 
-`adia-release` cutting and publishing the 11-package lockstep version does
+`adia-release` cutting and publishing the lockstep version (the roster in
+`scripts/package-paths.mjs` is the live count) does
 **not** itself update `ui-kit.exe.xyz` — that only happens on a `site-v*` tag
 push (see below). Any lockstep cut that changes a package the site actually
 serves — `web-components`, `web-modules`, `llm`, or `a2ui/*` — **owes a site
@@ -117,16 +118,14 @@ If `server.js` changed: rsync it, then `sudo systemctl restart <app>`.
   VM's `~exedev/.ssh/authorized_keys`; private half goes in
   Settings → Secrets and variables → Actions, pasted directly — it should
   never appear in an agent's Bash context or a commit.
-- **Environment `production-site` reviewer gate — NOT done** (verified live,
-  `gh api repos/<org>/<repo>/environments`: `protection_rules: []`). The
-  environment exists but carries no required reviewers, so the `deploy` job
-  in `deploy-site.yml` runs unattended the moment its dry-run job finishes —
-  every site deploy to date has shipped without the human delete-adjudication
-  gate this skill's own hardened-deploy design assumes. This is an
-  operator-only action (repo Settings → Environments → `production-site` →
-  add required reviewers) — no agent can configure it. Re-check the API
-  output above before trusting this line; it drifts the moment someone
-  configures it.
+- **Environment `production-site` reviewer gate — CONFIGURED** (verified
+  live 2026-08-11, `gh api repos/<org>/<repo>/environments`:
+  `protection_rules` carries `required_reviewers`). The `deploy` job in
+  `deploy-site.yml` therefore blocks on a human approval after its dry-run
+  job — the delete-adjudication gate this skill's hardened-deploy design
+  assumes. Changing the reviewer set is operator-only (repo Settings →
+  Environments → `production-site`) — no agent can configure it. Re-check
+  the API output before trusting this line; it drifts with repo settings.
 
 ## Other playbooks (reference §-anchors)
 

package/skills/adia-dogfood/SKILL.md

@@ -92,8 +92,7 @@ reports "matches this allowlist row" as part of its finding and stops.
 Never auto-fixed: `zero-area` (always human-eyeballed), `empty-control` on an
 unrecognized component, native-primitive replacement (attribute-shape
 decisions), card-header wrapper hoists (slot intent), any warning without an
-allowlist row. When sweeping `avatar-ui[name]`, never touch the deprecation-
-handler string inside `components/avatar/avatar.js` itself.
+allowlist row.
 **NEVER exceed 5 mechanical fixes per PR or apply a fix outside this
 allowlist** — blast radius stays human-reviewable.
 
@@ -111,8 +110,10 @@ same session — harvested training chunks silently hold stale values otherwise.
 
 ## Findings home + PR shape
 
-Reports and probe artifacts land in `qa/findings/` (visual baselines in
-`qa/baselines/`). Commit the report even on a zero-finding day — the paper
+Reports and probe artifacts land in `qa/findings/` (the geometry-probe
+baseline lives at `scripts/qa/empty-instantiation-baseline.json`; there is
+no visual-baseline directory — probes are geometry-only, gh#988). Commit
+the report even on a zero-finding day — the paper
 trail is how "used to be fine, now broken" is detected. PR title:
 `dogfood: <YYYY-MM-DD> — <N> critical, <M> warning`; body = report excerpt +
 auto-applied-fix checklist + left-for-human list.