@adia-ai/adia-ui-forge 0.8.15 → 0.8.16

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-forge",
-  "version": "0.8.15",
+  "version": "0.8.16",
   "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,16 @@
 # Changelog — adia-forge
 
+## [0.8.16] — 2026-07-26
+
+### Fixed
+- **The cut's harvest preamble now names `.examples.html` and the two generators it feeds** (`skills/adia-release/references/cut-procedure.md` §3.0; gh#421) — the trigger list covered component yaml, `.a2ui.json`, `*.contents.html`, and `data-chunk-*`-annotated pages, so an `.examples.html` edit read as out of scope. It isn't: it feeds `.examples.md`, the `site-a2ui` converted rows, **and** the chunk harvest's source hashes. The v0.8.14 cut edited two components' `.examples.html`, ran every freshness gate the doc named, saw them clean, and still lost a CI round-trip to `🔴 stale /site/components/{menu,popover}` plus two changed-since-harvest sources. The regen block now lists `generate-examples-md.mjs`, `site-a2ui.mjs --stale`, and `check-token-semantics-sync.mjs --fix`, and the trigger list adds `styles/colors/*`.
+
+### Changed
+- **The pre-cut gate roster grows 18 → 22** (`skills/adia-release/scripts/gate-roster.mjs`) — `check:examples-md-fresh`, `verify:site-a2ui`, `verify:contrast`, and `check:token-semantics-sync` all shipped in the `npm run check` aggregate but were never in the release roster, so a gate added to CI silently never reached a cut. `verify:contrast` matters most: gh#427 widened it from 42 to 90 pairs, and without it in the roster a sub-AA token could ship past a green pre-flight. `cut-procedure.md` §3.1's transcribed table and the SKILL/gates-catalog counts moved with it — verified programmatically that the doc table and the module list are entry-for-entry identical.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+
 ## [0.8.15] — 2026-07-26
 
 ### Maintenance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.15",
+  "version": "0.8.16",
   "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",

package/skills/adia-release/SKILL.md

@@ -93,7 +93,7 @@ assumed pass, or "published" without the actual `npm view` output.
 
 ## Mechanization (bundled `scripts/`, stdlib Node, all support `--dry`)
 
-`release-pack.mjs` walks the cycle in two phases per invariant 3 — `--mode cut` / `--mode from-scratch` promote `[Unreleased]` (BOTH modes now — a peer's hand-authored section must be promoted whichever mode cut it, and a loud guard blocks the bump if any of the 11 packages still carries non-empty `[Unreleased]` content after promotion), run Step 4f (pre-tag coverage `--fix` with the authoritative F-N1 matcher), and stop at the release commit (PR → merge); `--mode handoff` tags/publishes/deploys from post-merge main. **`--go` is the standard invocation for an operator-initiated release** — the single authorization covers the cycle; evidence blocks print as a log; granular `--yes`/`--push`/`--publish` remain for cautious manual runs (`--push` still refuses to auto-fire past any F-N1 finding). `--mode batch` is not implemented — it hard-rejects with a pointer to [`recovery-paths.md`](references/recovery-paths.md) §Scenario 2 rather than silently misbehaving; a real batch tags each version at its own release-merge SHA, which this single-version orchestrator has no model for. Pre-flight (Step 3) runs the full 17-gate roster from the single shared list in `scripts/gate-roster.mjs` — the same list [`cut-procedure.md`](references/cut-procedure.md) §3.1 transcribes, so a subset run requires editing that one file, not two.
+`release-pack.mjs` walks the cycle in two phases per invariant 3 — `--mode cut` / `--mode from-scratch` promote `[Unreleased]` (BOTH modes now — a peer's hand-authored section must be promoted whichever mode cut it, and a loud guard blocks the bump if any of the 11 packages still carries non-empty `[Unreleased]` content after promotion), run Step 4f (pre-tag coverage `--fix` with the authoritative F-N1 matcher), and stop at the release commit (PR → merge); `--mode handoff` tags/publishes/deploys from post-merge main. **`--go` is the standard invocation for an operator-initiated release** — the single authorization covers the cycle; evidence blocks print as a log; granular `--yes`/`--push`/`--publish` remain for cautious manual runs (`--push` still refuses to auto-fire past any F-N1 finding). `--mode batch` is not implemented — it hard-rejects with a pointer to [`recovery-paths.md`](references/recovery-paths.md) §Scenario 2 rather than silently misbehaving; a real batch tags each version at its own release-merge SHA, which this single-version orchestrator has no model for. Pre-flight (Step 3) runs the full 22-gate roster from the single shared list in `scripts/gate-roster.mjs` — the same list [`cut-procedure.md`](references/cut-procedure.md) §3.1 transcribes, so a subset run requires editing that one file, not two.
 
 The pieces are callable alone: `bump.mjs` (version fields + the factory `.mcp.json` a2ui-mcp pin, invariant 8), `promote-unreleased.mjs` / `insert-stub.mjs` (CHANGELOG blocks), `tag-lockstep.mjs` (12 tags, `--delete` to move), `dispatch-publish.mjs` (publish workflows; `--verify-triggered` re-dispatches only missing runs; `--after` enforces batch ordering — dispatch output states what WAS done, never a to-do phrased as if it hadn't fired), and `pr-bridge.mjs` (the two-phase bridge: pushes the release branch, opens the PR, waits out CI, and merges ONLY on all-non-fail-soft-checks-green + zero unresolved threads + no changes-requested; any other state stops with evidence — §5.7 mechanized, `--dry` to preview the decision). All fail fast outside a monorepo root (`assert-monorepo-root.mjs`); fork-configurable via `--host` / `--scope`. All 6 CLI scripts (plus `scripts/release/check-release.mjs`) have a `selftest` mode wired into CI's Plugin bin selftests step; the 3 helper modules (`assert-monorepo-root`, `gate-roster`, `package-paths`) are exercised through the CLIs' selftests, not their own.
 

package/skills/adia-release/references/cut-procedure.md

@@ -61,16 +61,29 @@ Keep the stash held through the site deploy (Step 10) — the tarball builds fro
 
 ### 3.0 Harvest preamble (only when source content changed in the window)
 
-If `git diff <prev-tag>..HEAD --name-only` touches component yaml / `.a2ui.json` sources, `*.contents.html`, catalog/site pages with `data-chunk-*` annotations — regenerate downstream artifacts proactively (otherwise the freshness gates force a tag-move recovery later):
+If `git diff <prev-tag>..HEAD --name-only` touches component yaml / `.a2ui.json` sources, **`*.examples.html`**, `*.contents.html`, **any file under `site/`, `apps/`, `playgrounds/`, or `catalog/`** — annotated with `data-chunk-*` or not — or any `styles/colors/*` token source, regenerate downstream artifacts proactively (otherwise the freshness gates force a tag-move recovery later):
 
 ```bash
-node scripts/build/components.mjs      # catalog + per-component sidecars
-npm run harvest:chunks                 # chunk corpus from site/apps/playgrounds/catalog
-npm run build:embeddings:chunks        # embedding index (needs OPENAI_API_KEY)
-npm run build -w @adia-ai/llm          # tsc artifact build:bundle-js resolves
-npm run build:bundles                  # dist CSS+JS bundles
+node scripts/build/components.mjs             # catalog + per-component sidecars
+node scripts/build/generate-examples-md.mjs   # .examples.md from .examples.html
+node scripts/build/site-a2ui.mjs --stale      # /site/components/* converted rows
+npm run harvest:chunks                        # chunk corpus from site/apps/playgrounds/catalog
+npm run check:embeddings-fresh                # ← run this FIRST; if it passes, SKIP the rebuild below
+npm run build:embeddings:chunks               # ONLY if the line above failed (needs OPENAI_API_KEY)
+node scripts/release/check-token-semantics-sync.mjs --fix   # adia-tokens role-roster + alias-layer
+npm run build -w @adia-ai/llm                 # tsc artifact build:bundle-js resolves
+npm run build:bundles                         # dist CSS+JS bundles
 ```
 
+**The `data-chunk-*` qualifier was the trap** (gh#421). Two separate cuts lost a CI round-trip to it:
+
+- **v0.8.14** edited two components' `*.examples.html` — not yaml, not `.contents.html`, no annotation — so it read as out of scope. It isn't: `.examples.html` feeds **three** generators (`.examples.md`, the `site-a2ui` converted rows, and the chunk harvest's source hashes). Every freshness gate this doc named came back clean, and CI still failed on `🔴 stale /site/components/{menu,popover}` plus `2 source file(s) changed since harvest`.
+- **The 0.8.16 cycle** then added a brand-new `site/pages/guides/theming.html` with *no* annotations, ran `site-a2ui`, `check:links`, `verify:llms`, and `verify:patterns-index` — all clean — and CI failed anyway: `1 source file(s) NEW since harvest`.
+
+Root cause of both: `check-chunks-fresh` hashes **every** source file under the harvest globs and compares the set against the corpus record, so a new or changed file trips it whether or not the harvester extracts a chunk from it. The annotation governs what gets *harvested*, never what gets *hashed*. Hence the trigger list above names the directories, not the annotation.
+
+When only source *hashes* move and chunk content does not, `check:embeddings-fresh` stays green on its content hash — no embedding rebuild, no `OPENAI_API_KEY` needed. Both incidents above were that case, which is why the block above runs that check *before* `build:embeddings:chunks` and skips the rebuild when it passes: an unconditional rebuild makes an ordinary `.examples.html` or new-page edit fail pre-flight on any machine without the key, for no reason. Only a change that alters chunk **content** needs the rebuild.
+
 **Regen output supersedes working-tree state.** These outputs land in the release commit unconditionally, even when the same paths are also dirty from a peer — the fresh regen is authoritative; divergent uncommitted work rebases on top afterwards.
 
 ### 3.1 The full roster — every gate runs; a subset = pre-flight failure
@@ -93,7 +106,11 @@ npm run check:embeddings-fresh                 # 14 embeddings vs chunk index
 npm run check:links                            # 15 intra-repo links
 npm run eval:diff -- --engine zettel           # 16 eval floors
 npm run dogfood:status                         # 17 P0/P1 dogfood floor
-node scripts/release/check-cut-hygiene.mjs --version <mode-dependent>  # 18 README CDN-pin + version currency — CUT modes pre-flight at the PREVIOUS version (the README claim is exact-match and only moves at the Step-4 bump; Step 4g re-proves at the cut version), HANDOFF pre-flights at the CUT version (post-merge, the claim already moved)
+npm run check:examples-md-fresh                # 18 .examples.md vs .examples.html
+npm run verify:site-a2ui                       # 19 site-a2ui rows vs source fragments
+npm run verify:contrast                        # 20 WCAG AA — canvas-text AND text-on-fill
+npm run check:token-semantics-sync             # 21 adia-tokens generated refs vs token sources
+node scripts/release/check-cut-hygiene.mjs --version <mode-dependent>  # 22 README CDN-pin + version currency — CUT modes pre-flight at the PREVIOUS version (the README claim is exact-match and only moves at the Step-4 bump; Step 4g re-proves at the cut version), HANDOFF pre-flights at the CUT version (post-merge, the claim already moved)
 ```
 
 Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source, re-run the narrowest gate, then re-run the full sequence. The canonical miss: a cut that ran 7 of the gates shipped a stale-embeddings defect that surfaced a day later and cost a tag-move recovery.

package/skills/adia-release/references/gates-catalog.md

@@ -202,7 +202,7 @@ npm run check:demo-shells
 
 Add `verify:corpus` + `check:embeddings-fresh` if chunks were touched; `check:lightningcss-build` if CSS was touched; F-N1 if unpushed release tags exist.
 
-**Full pre-cut sweep** — the 17-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/gate-roster.mjs` `` (the ONE list; `release-pack.mjs` imports and runs it in full — a subset run is impossible without editing that file). ~90s wall time.
+**Full pre-cut sweep** — the 22-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3, sourced from `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/gate-roster.mjs` `` (the ONE list; `release-pack.mjs` imports and runs it in full — a subset run is impossible without editing that file). ~90s wall time.
 
 **Omnibus** — `npm run check` invokes everything. Heavy; use when re-baselining a stale checkout.
 

package/skills/adia-release/scripts/gate-roster.mjs

@@ -40,11 +40,21 @@ export const GATE_ROSTER = [
   { n: 15, cmd: 'npm run check:links',                         what: 'intra-repo links' },
   { n: 16, cmd: 'npm run eval:diff -- --engine zettel',        what: 'eval floors' },
   { n: 17, cmd: 'npm run dogfood:status',                      what: 'P0/P1 dogfood floor' },
+  // gh#421: these four live in the `npm run check` aggregate but were never
+  // in the pre-cut roster, so a gate added to CI silently never reached a
+  // cut. examples-md + site-a2ui are the two generators an `.examples.html`
+  // edit invalidates (the v0.8.14 cut lost a CI round-trip to exactly that);
+  // contrast is the AA gate that gh#427 widened from 42 to 90 pairs;
+  // token-semantics-sync keeps the adia-tokens pack's generated half honest.
+  { n: 18, cmd: 'npm run check:examples-md-fresh',             what: '.examples.md vs .examples.html' },
+  { n: 19, cmd: 'npm run verify:site-a2ui',                    what: 'site-a2ui converted rows vs source fragments' },
+  { n: 20, cmd: 'npm run verify:contrast',                     what: 'WCAG AA — canvas-text + text-on-fill pairs' },
+  { n: 21, cmd: 'npm run check:token-semantics-sync',          what: 'adia-tokens generated references vs token sources' },
   // versionArg: the runner appends ` --version X.Y.Z` (release-pack knows the
   // cut version; the roster stays a static list). Objective half of the
   // v0.7.13-retro hygiene checker — README CDN pins / "Current version"
   // claims vs the cut version; branch/worktree limbo prints as warns (H2).
-  { n: 18, cmd: 'node scripts/release/check-cut-hygiene.mjs',  what: 'README CDN-pin + version currency', versionArg: true },
+  { n: 22, cmd: 'node scripts/release/check-cut-hygiene.mjs',  what: 'README CDN-pin + version currency', versionArg: true },
 ];
 
 // -- CLI ------------------------------------------------------------------

package/skills/adia-release/scripts/release-pack.mjs

@@ -709,7 +709,7 @@ async function main() {
 // Plan-assembly selftest — spawns THIS script as a real subprocess with
 // --mode cut --dry (fully mutation-free per every step's own dry-guard) and
 // asserts the assembled plan carries the expected markers: the full
-// 17-gate roster (H3 — a subset run must be impossible without editing
+// 22-gate roster (H3 — a subset run must be impossible without editing
 // gate-roster.mjs), and the invariant-3 stop-before-PR message (cut mode
 // must never proceed to tag/push/publish on its own). A fixture temp dir
 // supplies the operator-authored content files (--commit-message-file /