@adia-ai/adia-ui-forge 0.8.10 → 0.8.12

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-forge",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "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,26 @@
 # Changelog — adia-forge
 
+## [0.8.12] — 2026-07-24
+
+### Fixed
+- **`AGENTS.md`, `adia-author/SKILL.md`, `adia-author/references/code-style.md`: primitive count corrected 127 → 125** — the actual `packages/web-components/components/*/` directory count (excluding `index.js`/`index.d.ts`/`overview.*`); `AGENTS.md` had two separate stale mentions, one already partially corrected in a prior pass and one missed.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`skills/` touched in this release window** (2 file(s), e.g. `adia-author/SKILL.md`) — carried by the entries above.
+
+## [0.8.11] — 2026-07-23
+
+### Fixed
+- **`adia-author`: dist-bundle regen joins the structural-gate sequence** (`skills/adia-author/SKILL.md`, `references/authoring-cycle.md`) — a new/changed component CSS `@import` or barrel export drifts `dist/` bundles, and the skill's verify sequence never said so; gh#390's PR failed CI's `check:css-bundles-fresh`/`check:js-bundles-fresh` exactly this way. The gate sequence and the barrel-registration step now both name `build:bundle-css`/`build:bundle-js` + the two freshness checks.
+- **`adia-release`: `release-pack.mjs --mode handoff` validates `--gh-notes-file` at parse time** — the flag was only checked at Step 10 (GH releases), AFTER tags and npm publish were irreversible; the v0.8.10 cut died there live. Selftest case added.
+- **`adia-release`: mid-Step-4 resume path documented** (`references/cut-procedure.md` §4-resume) — once any CHANGELOG promotion lands, re-invoking the orchestrator hard-errors on the idempotency guard ("already has ## [X.Y.Z]") forever; the doc now names the standalone-pieces sequence (bump → lockfile → lockstep → 4f → 4e → Step 5/5.7) instead of leaving the operator to reverse-engineer it mid-cut.
+- **`adia-release`: stub-package ownership rule** (`references/changelog-discipline.md` §Stubs) — `insert-stub.mjs` inserts, never promotes; a hand-written `[Unreleased]` in a `--stub-packages` target survives as an orphaned second block and fails the loud guard (v0.8.10 lost a cycle to this across 6 packages). Rule: the tool owns stub packages; hand-written content means the package belongs in `--substantive-packages`.
+- **`release-pretag-docs-gate`: a `cd <path> && …` command prefix now resolves the gate against THAT checkout, not the session cwd** (`bin/release-pretag-docs-gate`) — a session pinned to a stale worktree (own copy of the gate script, branch without the release's CHANGELOG sections) false-FAILed the v0.8.10 handoff even though the command explicitly cd'd to the clean primary checkout. Selftest fixtures added for the prefix resolution.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+
 ## [0.8.10] — 2026-07-20
 
 ### Added

package/bin/release-pretag-docs-gate

@@ -89,6 +89,33 @@ def classify(command):
     return None
 
 
+CD_PREFIX = re.compile(r"""^\s*cd\s+(?:--\s+)?(['"]?)([^'";&|\n]+)\1\s*(?:&&|;)""")
+
+
+def resolve_start_dir(command, cwd):
+    """A command that opens with `cd <path> && …` targets THAT checkout, not
+    the session's cwd. Live false FAIL (v0.8.10 handoff, 2026-07-20): the
+    session sat pinned in a stale worktree (its own copy of the gate script +
+    a branch with no [0.8.10] CHANGELOG sections) while the command cd'd to
+    the primary checkout on post-merge main — the gate validated the stale
+    worktree and denied a genuinely clean release. Prefer the cd target when
+    it is a real directory; otherwise fall back to the event cwd."""
+    m = CD_PREFIX.match(command or "")
+    if m:
+        # Mirror the shell: ~ expands only when the operand is UNQUOTED —
+        # `cd "~"` targets a literal ./~ (and typically fails), so resolving
+        # $HOME here would let a quoted-tilde push bypass the gate whenever
+        # $HOME lacks the gate script (review finding, PR #394).
+        target = m.group(2).strip()
+        if not m.group(1):
+            target = os.path.expanduser(target)
+        if not os.path.isabs(target) and cwd:
+            target = os.path.join(cwd, target)
+        if os.path.isdir(target):
+            return target
+    return cwd
+
+
 def find_repo_gate(start):
     """Walk up from `start` to the git root looking for the gate script —
     a release command launched from a subdirectory must not bypass the
@@ -125,10 +152,11 @@ def hook_mode():
         sys.exit(0)
     if event.get("tool_name") != "Bash":
         sys.exit(0)
-    version = classify((event.get("tool_input") or {}).get("command", ""))
+    command = (event.get("tool_input") or {}).get("command", "")
+    version = classify(command)
     if not version:
         sys.exit(0)
-    root, gate = find_repo_gate(event.get("cwd"))
+    root, gate = find_repo_gate(resolve_start_dir(command, event.get("cwd")))
     if not gate:
         sys.exit(0)  # consumer repo — nothing to enforce here
     if version == AMBIGUOUS:
@@ -214,6 +242,27 @@ def selftest():
         if gate is not None:
             print("selftest FAIL: consumer repo must yield no gate", file=sys.stderr)
             sys.exit(1)
+    # resolve_start_dir: a `cd <path> && …` prefix must win over the session
+    # cwd (the v0.8.10 pinned-worktree false FAIL); anything else falls back.
+    with tempfile.TemporaryDirectory() as td:
+        real = os.path.join(td, "checkout")
+        os.makedirs(real)
+        cases_dir = [
+            (f"cd {real} && node release-pack.mjs --mode handoff --version 0.9.0", "/elsewhere", real),
+            (f'cd "{real}" && git push origin v0.9.0', "/elsewhere", real),
+            (f"cd {td}/missing && node release-pack.mjs --mode handoff --version 0.9.0", "/elsewhere", "/elsewhere"),
+            ("node release-pack.mjs --mode handoff --version 0.9.0", "/elsewhere", "/elsewhere"),
+            ("", "/elsewhere", "/elsewhere"),
+            # Quoted tilde: bash cd's to a literal ./~, NOT $HOME — the gate
+            # must not resolve $HOME either (quoted-tilde bypass, PR #394).
+            ('cd "~" && git push origin v0.9.0', "/elsewhere", "/elsewhere"),
+        ]
+        for cmd, cwd, want in cases_dir:
+            got = resolve_start_dir(cmd, cwd)
+            if got != want:
+                print(f"selftest FAIL: resolve_start_dir({cmd!r}, {cwd!r}) = {got!r}, want {want!r}", file=sys.stderr)
+                sys.exit(1)
+
     print("selftest OK")
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "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-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 (127 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 (125 primitives exist; skipping it 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) |
@@ -101,6 +101,8 @@ npm run smoke:engines                        # green
 node scripts/dev/audit-native-primitive-leak.mjs   # 0 critical leaks
 node scripts/dev/audit-shell-composition.mjs       # 0 critical defects
 node scripts/dev/audit-template-child-conflict.mjs # 0 critical (gh#284 shape — non-null template + slots.default)
+npm run build:bundle-css && npm run build:bundle-js   # regenerate dist bundles — any component CSS/JS change drifts them
+npm run check:css-bundles-fresh && npm run check:js-bundles-fresh   # both must be clean (CI gates; gh#390's PR failed here)
 ```
 
 A failed gate is the artifact: fix at the source, re-run the narrowest gate,

package/skills/adia-author/references/authoring-cycle.md

@@ -200,7 +200,11 @@ node scripts/build/components.mjs --verify   # "clean — N files up-to-date"
 
 A primitive also needs BOTH barrel registrations — the CSS `@import` in
 `styles/components.css` AND the JS `export` in `components/index.js`
-(`scripts/audit/check-components-js-barrel.mjs` gates the second).
+(`scripts/audit/check-components-js-barrel.mjs` gates the second). Either
+registration drifts the built `dist/` bundles — regenerate them in the same
+change (`npm run build:bundle-css && npm run build:bundle-js`) and commit the
+`dist/` updates, or CI's `check:{css,js}-bundles-fresh` gates fail on the PR
+(gh#390's PR shipped without this and failed exactly there).
 
 ## Step 5 — Run the project's verification gates
 

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

@@ -22,7 +22,7 @@ Every interactive surface, form control, layout container, and content block shi
 <input type="email" />
 ```
 
-The catalog has 127 component directories under `packages/web-components/components/`. Before composing, confirm via `get_component_map` (the a2ui MCP) that the one you want exists — and what its real prop names are.
+The catalog has 125 component directories under `packages/web-components/components/`. Before composing, confirm via `get_component_map` (the a2ui MCP) that the one you want exists — and what its real prop names are.
 
 ## Layout primitives
 

package/skills/adia-release/references/changelog-discipline.md

@@ -92,6 +92,7 @@ The inserted block:
 
 - **Make the PATCH-cut asymmetry visible** when an entry mentions a dependency: version bumps to `X.Y.Z` while internal ranges hold at `^X.Y.0` — spell it as `dependencies["@adia-ai/<x>"]: ^X.Y.0 (covers X.Y.Z)` so it doesn't read as a bug.
 - **Stale stubs are an F-N1 hazard.** A "no source changes" stub on a package that DID change earns a warn; the fix is authoring (§Authoring), not stubbing.
+- **The tool owns stub packages — never hand-write their `[Unreleased]`.** `insert-stub.mjs` INSERTS a fresh dated block at the top; it does not promote or replace existing content. A hand-authored `[Unreleased]` stub in a `--stub-packages` target survives the insert as a second, orphaned block below it, and the orchestrator's loud guard then fails the whole run ("N packages still have non-empty [Unreleased]") — the v0.8.10 cut lost a full cycle to exactly this across 6 packages. Ride-along packages get NO hand-written entry at cut time: leave them untouched and list them in `--stub-packages`. (A package that deserves hand-written content isn't a stub — it belongs in `--substantive-packages`.)
 
 ## §F-N1 diff-coverage — mechanized at cut time (Step 4f)
 

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

@@ -127,6 +127,34 @@ tag-creation/tag-push/publish-dispatch commands until it passes, and
 shipped tarballs with unpromoted `[Unreleased]` CHANGELOG headers because
 this class of check ran only after tagging).
 
+**4-resume. Resuming a cut that died mid-Step-4** (v0.8.10 hit this live):
+`release-pack.mjs` always re-runs the FULL sequence from Step 1, and
+`promote-unreleased.mjs` hard-errors on already-promoted packages ("already
+has ## [X.Y.Z]") — so once ANY promotion has landed, re-invoking the
+orchestrator can never get past Step 4. That error is the idempotency guard
+working, not a corrupted state. Do NOT hand-edit CHANGELOGs back to
+`[Unreleased]` to appease it. Instead, verify the promotion state with the
+authoritative gate — `node scripts/release/check-release-docs.mjs --version
+X.Y.Z` covers every lockstep package (including the nested `a2ui/*` and
+`plugins/*` paths a shallow `packages/*` glob misses) and fails on any
+leftover `[Unreleased]` content or missing `[X.Y.Z]` heading; it will still
+flag the not-yet-generated `docs/releases/vX.Y.Z.md`, which 4e below creates.
+Then run the remaining steps as the standalone pieces the Mechanization
+section already names, in this order:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z   # 4b
+npm install --package-lock-only --no-audit --no-fund                                          # 4c
+npm run check:lockstep                                                                        # 4d
+node scripts/release/check-release.mjs --pending-version X.Y.Z --fix                          # 4f
+node scripts/release/generate-release-notes.mjs --version X.Y.Z --write                       # 4e
+node scripts/release/check-release-docs.mjs --version X.Y.Z                                   # 4e gate
+node scripts/release/check-cut-hygiene.mjs --version X.Y.Z                                    # 4g — post-bump proof
+# then Step 5 by hand (branch, stage, commit) — Step 5.5's freshness
+# trip-wire runs on the staged set exactly as on a normal cut, don't skip it —
+# and Step 5.7 via pr-bridge.mjs
+```
+
 ## §Step 5 — Stage and commit (on a release branch)
 
 The release commit lands via PR, never a direct push to `main` (repo

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

@@ -143,11 +143,29 @@ function parseArgs(argv) {
     console.error(`error: --mode must be cut|from-scratch|handoff (got: ${args.mode})`);
     process.exit(2);
   }
+  // Handoff needs the GH-notes body at Step 10 — validate at PARSE time, not
+  // there: on the v0.8.10 cut the missing flag surfaced only after tags and
+  // npm publish were already irreversible (Step 10 is the LAST step). An arg
+  // error must never cost half a shipped release.
+  if (args.mode === 'handoff') {
+    if (!args.ghNotesFile) {
+      console.error('error: --mode handoff requires --gh-notes-file (Step 10 creates the 11 GH');
+      console.error('       releases from it; tags/publish would land first, then the run would');
+      console.error('       die on the missing flag — v0.8.10 hit exactly this).');
+      process.exit(2);
+    }
+    if (!args.dry && !(fs.existsSync(args.ghNotesFile) && fs.statSync(args.ghNotesFile).isFile())) {
+      console.error(`error: GH notes file not found or not a regular file: ${args.ghNotesFile}`);
+      process.exit(2);
+    }
+  }
   return args;
 }
 
 function help() {
   console.log(`Usage:
+  node release-pack.mjs --mode handoff --version X.Y.Z --date YYYY-MM-DD \\
+    --previous-version X.Y.Z-1 --gh-notes-file /tmp/release-v$X.Y.Z.md   # REQUIRED for handoff
   node release-pack.mjs --mode cut --version X.Y.Z --date YYYY-MM-DD \\
     --previous-version X.Y.Z-1 \\
     --commit-message-file /tmp/v$X.Y.Z-commit.txt \\
@@ -734,6 +752,21 @@ function selftest() {
       process.exit(1);
     }
 
+    // Handoff without --gh-notes-file must die at PARSE time (v0.8.10: the old
+    // Step-10-only check fired after tags+publish were irreversible).
+    let handoffFailed = false;
+    let handoffOut = '';
+    try {
+      execSync(`node "${scriptPath}" --mode handoff --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 --dry`, { cwd: REPO, encoding: 'utf8' });
+    } catch (e) {
+      handoffFailed = true;
+      handoffOut = (e.stdout || '') + (e.stderr || '');
+    }
+    if (!handoffFailed || !handoffOut.includes('--gh-notes-file')) {
+      console.error('selftest FAIL: --mode handoff without --gh-notes-file must hard-reject at parse time');
+      process.exit(1);
+    }
+
     console.log('selftest OK');
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });