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

package/skills/adia-ui-release/references/independent-package-release.md

@@ -0,0 +1,129 @@
+# `independent-package-release.md` — class-B cut (an independently-versioned package outside the lockstep)
+
+> Loaded by **mode 12 (Independent-package release)**. Load when releasing a package
+> that versions **independently** of the lockstep set — it is excluded from the
+> lockstep-coherence gate, carries no umbrella tag, and triggers no demo-site deploy.
+> For the lockstep cut (the primary path), use `cycle-happy-path.md` (modes 1–4).
+
+> **Worked example — the @adia-ai monorepo's `packages/plugins/*`.** The concrete
+> package names, gate names, and workflow files below are **the worked example** of
+> this class, drawn from the @adia-ai monorepo's two Claude Code plugins —
+> `@adia-ai/adia-ui-factory` (versioned `0.2.x`) and `@adia-ai/adia-ui-forge`
+> (versioned `0.1.x`) — which live under `packages/plugins/*`, version
+> independently, and are EXCLUDED from the 9-package lockstep. A _different_
+> @adia-ai-style monorepo with its own independently-versioned package keeps this
+> skeleton and substitutes its own package path, exclusion comment, and publish
+> workflow. `$REPO` below = the monorepo root.
+
+## §Why a separate class — two release classes in one monorepo
+
+A lockstep monorepo can host packages that do **not** move with the lockstep set:
+plugins, tools, or any package whose release cadence is deliberately decoupled.
+These are a **class-B independent-package release**, distinct from the **class-A
+lockstep cut** the rest of this skill describes.
+
+| | Class A — lockstep cut (modes 1–4) | Class B — independent-package release (mode 12) |
+| --- | --- | --- |
+| **Versioning** | The whole set bumps together | Each package on its own version line |
+| **Lockstep gate** | Enforced (`check:lockstep` 9/9) | **Excluded** — the gate skips the package by design |
+| **Umbrella tag** | Yes (`vX.Y.Z` + per-package) | **None** — per-package tags only (versions differ) |
+| **`dist-tag` ordering** | Cross-package publish ordering matters | N/A (independent versions; no cross-package `latest` race) |
+| **Demo-site deploy** | Yes (the worked example's `ui-kit.exe.xyz`) | **None** |
+| **Publish trigger** | Tag-triggered per-package workflow | Tag-triggered per-package workflow (same mechanism) |
+
+`SKILL.md §ReleaseInvariants` govern the **class-A lockstep cut**. Class B's
+invariants are the §Posture operator-confirmation checkpoints plus the onboarding
+trip-wires below — and the same verify-against-reality discipline (verify the npm
+registry, not the workflow's reported "success").
+
+> **Worked example.** In the @adia-ai monorepo, `scripts/release/check-lockstep.mjs`
+> skips `packages/plugins/*` by design (there's a comment there saying so), and the
+> plugins publish via their own tag-triggered workflows
+> (`.github/workflows/publish-adia-ui-{factory,forge}.yml`) — exactly like the
+> framework packages but on independent versions. No umbrella tag, no `dist-tag`
+> cross-package ordering, no EXE deploy.
+
+## §New-package onboarding — the three trip-wires a FIRST independent cut hits
+
+A package that is **new to the release tooling** fails three gates the established
+set long since passed. These are **substrate** fixes (release scripts / lockfile /
+CHANGELOG), not skill edits — per the §Teach decision tree, branch A (substrate).
+The skill only *cites* them here. Onboard the package **once**; the fixes land as a
+normal substrate PR on `main` *before* tagging.
+
+1. **Lockfile.** A new workspace package isn't in the lockfile → the pre-commit
+   lockfile-check hook blocks the commit, and the publish workflow's clean install
+   (`npm ci`) fails the same way.
+   *Fix:* regenerate the lockfile only and stage it —
+   `npm install --package-lock-only && git add package-lock.json`.
+2. **Release-trip-wire package registry.** The release trip-wire (F-N1,
+   `check:release`) validates each pushed tag against a registry of known packages.
+   An unregistered tag fails the **pre-push** hook with an `unknown package` error.
+   *Fix:* register the package in that list — its tag-prefix + path.
+   *(Worked example: `scripts/release/check-release.mjs` has a hardcoded `PACKAGES`
+   array — the framework 9; add
+   `{ tagPrefix: '<name>', path: 'packages/plugins/<name>' }`.)*
+3. **CHANGELOG bracket form.** The trip-wire's entry check requires the
+   Keep-a-Changelog `## [<version>]` (brackets) heading. A bare `## <version>`
+   heading fails with a "no `## [<version>]` entry" error.
+   *Fix:* bracket the version headings.
+
+## §Procedure
+
+> The gate/workflow names below are the @adia-ai worked example; substitute your
+> monorepo's own pre-publish gate and publish workflow.
+
+0. **Re-baseline** (the multi-agent baseline assumption). `git fetch`; know HEAD +
+   whether the shared working tree is on a peer's branch.
+1. **Land the package(s) on `main`** via PR — the usual PR-merge gate: resolve
+   **every** review thread (e.g. CodeRabbit) before an admin-merge. A PR-merge gate
+   that requires resolved review threads before `gh pr merge --admin` is a hard
+   precondition — an admin merge over unresolved threads is the failure this guards
+   against. *(See `SKILL.md §Posture` / your monorepo's merge convention.)*
+2. **Pre-publish gate.** Run the per-package version-coherence check (the worked
+   example: `npm run verify:plugins` → N/N synced — `package.json` ↔ the plugin
+   manifest versions). The lockstep gate still passes for the lockstep set (the
+   independent package is excluded). Confirm the names are free on npm:
+   `npm view @adia-ai/<pkg> version` → `E404` means available.
+3. **Tag at the published commit** — `git tag <pkg>-vX.Y.Z` per package (versions
+   differ; **no umbrella tag**). The tag must point at a commit whose `package.json`
+   + bracketed CHANGELOG match: dry-run the release trip-wire over the tag list
+   (worked example: `node scripts/release/check-release.mjs <tags>` → clean) before
+   pushing. **If the shared working tree is on a peer's branch, push the tags from a
+   throwaway worktree on `origin/main`** — never carry a peer's branch state into a
+   tag push.
+4. **Push the tags** → the per-package publish workflows run the clean-install →
+   pre-publish-gate → publish sequence (worked example:
+   `npm ci → verify:plugins → npm publish --access public` with the repo's npm token).
+5. **Verify (against npm, not the workflow).** `npm view @adia-ai/<pkg> version`
+   returns the new version for each package. Watch each workflow to completion
+   (`gh run watch <id> --exit-status`) — but the registry, not the workflow's green
+   check, is the source of truth.
+6. **Marketplace cut-over** (if a plugin marketplace repo exists). Point the
+   marketplace manifest's per-plugin `source` at npm —
+   `{ "source": "npm", "package": "@adia-ai/<pkg>" }` — and `git rm -r` any vendored
+   copies (the canonical home is the monorepo). Validate the JSON, commit, push.
+   Consumers then add the marketplace + install the plugin from npm (e.g.
+   `/plugin marketplace add <org>/<repo>` → `/plugin install <pkg>@<repo>`).
+7. **Audit-history ledger** — same as class A; record the **per-package** versions
+   (independent — they differ per package).
+
+## §Verify Target
+
+The published package(s) on the **npm registry** at their independent versions, plus
+(if a marketplace exists) it references npm. **NOT** "the whole lockstep set + the
+demo site" — that's class A. Verify against the registry, never the workflow's
+reported "success."
+
+## §Gotchas — from the first independent cut (worked example: 2026-06-07, factory v0.2.2 + forge v0.1.2)
+
+- The independent package is **NOT** lockstep — never add it to the lockstep gate,
+  and never tag it with the lockstep umbrella tag.
+- Publish-workflow YAMLs are **token-bearing** — keep `persist-credentials: false`
+  on the checkout step (match the established publish workflows' action-pinning
+  convention).
+- A marketplace repo's **org + visibility is an operator call** — creating a public
+  repo is outward-facing; confirm before `gh repo create`. The repo home may differ
+  from the primary org (the marketplace manifest's `owner` field is the signal; a
+  member without org repo-create rights falls back to a personal repo).
+- Run a **secret-scan of the full history** before pushing any repo public.

package/skills/adia-ui-release/references/recovery-paths.md

@@ -1,4 +1,4 @@
-# `recovery-paths.md` — the 5 recovery scenarios
+# `recovery-paths.md` — the 7 recovery scenarios
 
 > Loaded by mode 2 (Author from scratch) when `[Unreleased]` promotion requires extension beyond the peer's early release commit; by mode 4 (Batch push); on F-N1 or pre-flight failure in mode 1; and by mode 7 (Post-release recovery — Phase 3 expansion).
 
@@ -177,6 +177,48 @@ For option 2:
 
 ---
 
+## §Scenario 7 — Tags pushed but ZERO publish workflows triggered (the batch-tag-push skip)
+
+**Shape:** The cut commit is pushed, all 10 tags (umbrella + 9 per-package) exist on `origin` — but **no `publish-<pkg>.yml` workflow ran**. `gh run list --workflow=publish-<pkg>.yml` shows no run for the new tag. npm `latest` is still the previous version. The packages are NOT on the registry at the new version. Nothing errored; the publishes simply never started.
+
+**Root cause:** GitHub's `on: push: tags:` trigger fires a single `create` event for the whole ref-set when you push many tags in **one** `git push` invocation (`git push origin <tag1> <tag2> … <tag10>` or `git push origin --tags`). GitHub Actions routinely **drops** that batched create event — so ZERO publish-on-tag workflows trigger. This is not a flake you can retry by re-pushing (the tags already exist on the remote; a no-op push fires nothing). Memory: `feedback_publish_workflow_batch_push`.
+
+**Canonical case:** the v0.7.14 cut. All 10 tags pushed in one `git push origin <10 tags>`; zero `publish-*` runs fired. Recovered by manually `gh workflow run publish-<pkg>.yml` (workflow_dispatch) for each package.
+
+**Resolution (recover):**
+
+1. Confirm the symptom — for each package: `gh run list --workflow=publish-<pkg>.yml --branch <pkg>-vX.Y.Z --limit 1`. Empty for all (or most) = the batch skip.
+2. **Re-dispatch the misses via `workflow_dispatch`** (the tags are valid refs; the workflow just never ran for them). The bundled helper does exactly this, idempotently:
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-release/scripts/dispatch-publish.mjs" \
+     --version X.Y.Z --verify-triggered
+   ```
+   `--verify-triggered` checks each `publish-<pkg>.yml` for an existing run on the `<pkg>-vX.Y.Z` tag and re-dispatches ONLY the packages with no run (so it's safe to run after a *partial* trigger too — it won't double-publish the ones that fired). `--dry` previews without calling `gh`.
+3. For a **batch push** (Scenario 2), preserve npm-latest ordering: re-dispatch + settle the OLDER version's 9 before the newer version's 9. `--after X.Y.Z-1` gates on `npm dist-tag latest` to enforce it.
+4. Wait for settle + verify against the **registry** (not the workflow's "success"): `npm view <scope>/<pkg> version` for all 9 + `npm view <scope>/web-components dist-tags.latest`.
+
+**Resolution (prevent — next cut):** push per-package tags **one-at-a-time** so each gets its own create event:
+```bash
+git push origin main
+for t in web-components-vX.Y.Z web-modules-vX.Y.Z … a2ui-validator-vX.Y.Z; do
+  git push origin "$t"
+done
+git push origin vX.Y.Z   # umbrella last — triggers nothing
+```
+`release-pack.mjs` Step 8 now does this automatically, and Step 9 runs `--verify-triggered` to fill any gap; the `tag-lockstep.mjs` push hint prints the per-tag loop + the verify-triggered command. The one-at-a-time push is the primary fix; `--verify-triggered` is the belt-and-suspenders safety net.
+
+**What to write in the ledger:**
+
+```json
+"publish_workflows": {
+  "trigger_anomaly": "Batched tag push (git push origin <10 tags>) triggered ZERO publish-on-tag workflows (the GitHub batch-push create-event skip). Recovered by dispatch-publish.mjs --verify-triggered → re-dispatched N/9 via workflow_dispatch.",
+  "dispatched": "9/9 (workflow_dispatch)",
+  "conclusions": "9/9 success — verified on npm registry, not workflow self-report"
+}
+```
+
+---
+
 ## §Decision flowchart — which scenario applies?
 
 ```text
@@ -200,6 +242,11 @@ Multiple unpushed release commits exist?
 Peer commit's CHANGELOG references a different version than its bump?
 └── Scenario 1 (version-skip correction)
 
+Tags pushed (all 10 exist on origin) but NO publish-<pkg>.yml ran +
+npm latest unchanged?
+└── Scenario 7 (batch-tag-push skip) — re-dispatch misses via
+    dispatch-publish.mjs --verify-triggered; next cut push tags one-at-a-time
+
 Working tree has uncommitted source files when you start the cycle?
 └── Apply multi-agent-baseline.md § classification taxonomy.
     Stash strays per § Discipline 4 if they're release-relevant +
@@ -210,6 +257,6 @@ Working tree has uncommitted source files when you start the cycle?
 
 ## §When this reference is "done v1"
 
-- Each of the 5 (now 6) scenarios has a documented case study in `assets/case-studies/` (Phase 3).
+- Each of the 5 (now 7) scenarios has a documented case study in `assets/case-studies/` (Phase 3).
 - The decision flowchart correctly routes the next 5 release cycles with no operator override.
 - Each scenario's ledger-template fragment is reused verbatim by the `make-ledger.mjs` helper (Phase 3) for that scenario.

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

@@ -41,6 +41,7 @@ function parseArgs(argv) {
   const args = {
     version: null, after: null, dry: false, sleepBefore: 4,
     scope: process.env.ADIA_NPM_SCOPE || DEFAULT_SCOPE,
+    verifyTriggered: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const k = argv[i];
@@ -49,13 +50,19 @@ function parseArgs(argv) {
     else if (k === '--dry') args.dry = true;
     else if (k === '--sleep-before') args.sleepBefore = parseInt(argv[++i], 10);
     else if (k === '--scope') args.scope = argv[++i];
+    else if (k === '--verify-triggered') args.verifyTriggered = true;
     else if (k === '-h' || k === '--help') {
-      console.log('Usage: node dispatch-publish.mjs --version X.Y.Z [--after X.Y.Z-1] [--dry] [--sleep-before <seconds>] [--scope @org]');
+      console.log('Usage: node dispatch-publish.mjs --version X.Y.Z [--after X.Y.Z-1] [--verify-triggered] [--dry] [--sleep-before <seconds>] [--scope @org]');
       console.log('');
-      console.log('--after  Verify npm latest is at the given version before dispatching this one.');
-      console.log('         Used in batch push to ensure publish ordering.');
-      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.');
+      console.log('--after            Verify npm latest is at the given version before dispatching this one.');
+      console.log('                   Used in batch push to ensure publish ordering.');
+      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(`--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);
     }
   }
@@ -115,12 +122,68 @@ async function sleep(ms) {
   return new Promise((res) => setTimeout(res, ms));
 }
 
+// Has publish-<pkg>.yml already run for the <pkg>-vX.Y.Z tag? Tag-triggered runs
+// report the tag in the `headBranch` field, so we filter the run list by it.
+// Returns true if at least one run exists for that tag, false otherwise.
+function triggeredForTag(pkg, version, dry) {
+  const tag = `${pkg}-v${version}`;
+  const cmd = `gh run list --workflow="publish-${pkg}.yml" --branch "${tag}" --limit 1 --json databaseId -q '.[0].databaseId // empty'`;
+  if (dry) {
+    console.log(`  [dry] ${cmd}`);
+    return false; // dry preview assumes not-triggered so the re-dispatch path is shown
+  }
+  try {
+    const out = execSync(cmd, { encoding: 'utf8' }).trim();
+    return out.length > 0;
+  } catch {
+    // gh error (auth / rate limit / missing workflow) — treat as "unknown".
+    // Conservative: report not-triggered so the miss is re-dispatched rather than
+    // silently skipped. A redundant re-dispatch is harmless (publish is idempotent
+    // per the workflow's own guard); a skipped publish is the failure we're fixing.
+    return false;
+  }
+}
+
+// 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.
+function verifyTriggeredAndRedispatch(version, dry) {
+  console.log(`\nVerifying publish-on-tag triggered for all ${PACKAGES.length} packages (v${version}):`);
+  const misses = [];
+  for (const pkg of PACKAGES) {
+    if (triggeredForTag(pkg, version, dry)) {
+      console.log(`  ✓ ${pkg} — publish run found for ${pkg}-v${version}`);
+    } else {
+      console.log(`  ✗ ${pkg} — NO publish run for ${pkg}-v${version} (batch-push skip) → will re-dispatch`);
+      misses.push(pkg);
+    }
+  }
+  if (misses.length === 0) {
+    console.log(`\n[verify-triggered] all ${PACKAGES.length} publish workflows triggered — nothing to re-dispatch.`);
+    return 0;
+  }
+  console.log(`\n[verify-triggered] ${misses.length} miss(es) — re-dispatching via workflow_dispatch:`);
+  let redispatched = 0;
+  for (const pkg of misses) {
+    if (dispatch(pkg, version, dry)) redispatched++;
+  }
+  console.log(`\n[verify-triggered] re-dispatched ${redispatched}/${misses.length} ${dry ? '(dry)' : ''}`);
+  return redispatched === misses.length ? 0 : 1;
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to run npm/gh against a non-monorepo directory.
   assertMonorepoRoot(process.cwd());
   if (args.after) checkAfter(args.after, args.scope);
 
+  // Recovery mode — verify each publish workflow triggered off its pushed tag,
+  // re-dispatch only the misses (the batch-tag-push skip). Skips the blind dispatch.
+  if (args.verifyTriggered) {
+    const rc = verifyTriggeredAndRedispatch(args.version, args.dry);
+    process.exit(rc);
+  }
+
   if (args.sleepBefore > 0 && !args.dry) {
     console.log(`Sleeping ${args.sleepBefore}s to let GH index the new tags...`);
     await sleep(args.sleepBefore * 1000);

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

@@ -16,8 +16,8 @@
 // cycles.
 
 import fs from 'node:fs';
-import path from 'node:path';
 import process from 'node:process';
+import { resolvePackageChangelog } from './package-paths.mjs';
 
 function parseArgs(argv) {
   const args = {
@@ -72,7 +72,8 @@ function buildStub(version, date, substantive, xref) {
 }
 
 function insertStub(repo, pkg, anchor, stubBlock, version, dry) {
-  const p = path.join(repo, 'packages', pkg, 'CHANGELOG.md');
+  // Accept both name-form (a2ui-corpus) and path-form (a2ui/corpus). See package-paths.mjs.
+  const p = resolvePackageChangelog(repo, pkg);
   if (!fs.existsSync(p)) {
     console.error(`  ERROR ${pkg} — CHANGELOG.md not found at ${p}`);
     return 'missing';
@@ -101,7 +102,8 @@ function main() {
   const PREV_HEADING_RE = new RegExp(`^## \\[${args.previous.replace(/\./g, '\\.')}\\] — \\d{4}-\\d{2}-\\d{2}$`, 'm');
   const stubBlock = buildStub(args.version, args.date, args.substantive, args.xref);
   const results = args.packages.map((pkg) => {
-    const p = path.join(args.repo, 'packages', pkg, 'CHANGELOG.md');
+    // Accept both name-form (a2ui-corpus) and path-form (a2ui/corpus). See package-paths.mjs.
+    const p = resolvePackageChangelog(args.repo, pkg);
     if (!fs.existsSync(p)) {
       console.error(`  ERROR ${pkg} — not found`);
       return 'missing';

package/skills/adia-ui-release/scripts/make-ledger.mjs

@@ -84,6 +84,16 @@ function parseArgs(argv) {
     args.tagCommit = execSync(`git -C "${args.repo}" rev-parse HEAD`).toString().trim();
   }
   if (!args.releaseCommit) args.releaseCommit = args.tagCommit;
+  // Auto-fill repoSlug from the git remote when not explicitly passed — avoids the
+  // '<org>/<repo>' placeholder shipping in the ledger (CodeRabbit-flagged on the
+  // v0.7.17 cut). Falls back to the placeholder if there's no origin remote.
+  if (args.repoSlug === '<org>/<repo>') {
+    try {
+      const url = execSync(`git -C "${args.repo}" remote get-url origin`).toString().trim();
+      const m = url.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?\/?$/);
+      if (m) args.repoSlug = m[1];
+    } catch { /* no remote — leave the placeholder */ }
+  }
   return args;
 }
 
@@ -130,7 +140,7 @@ function buildLedger(args) {
     note: 'TODO: paste gate-by-gate summary here. See ledger-discipline.md § canonical schema.',
   };
   ledger.publish_workflows = {
-    dispatched: '9/9 via gh workflow run --ref <pkg>-vX.Y.Z',
+    dispatched: 'TODO: dispatch method (per-package tag-push, one-at-a-time / gh workflow run)',
     conclusions: '9/9 success',
   };
   ledger.notes = args.notes.length > 0 ? args.notes : ['TODO: at least one note per cycle.'];
@@ -157,6 +167,17 @@ function writeOrPrint(ledger, args) {
   }
   fs.writeFileSync(target, content);
   console.log(`[make-ledger] wrote ${target}`);
+  // Nudge: the gate summary + notes can't be auto-derived — warn if TODO stubs
+  // would ship (the v0.7.17 ledger shipped with these; CodeRabbit-flagged).
+  const stubs = [];
+  if (/TODO/.test(ledger.verification?.note || '')) stubs.push('verification');
+  if (/TODO/.test(ledger.publish_workflows?.dispatched || '')) stubs.push('publish_workflows.dispatched');
+  if ((ledger.notes || []).some((n) => /TODO/.test(n))) stubs.push('notes');
+  if (ledger.repo === '<org>/<repo>') stubs.push('repo');
+  if (stubs.length) {
+    console.warn(`\n⚠ [make-ledger] ${stubs.length} field(s) still placeholder — FILL before committing: ${stubs.join(', ')}`);
+    console.warn(`  (repo auto-fills from the git remote; pass --note "..." + hand-edit verification / publish_workflows)`);
+  }
   console.log(`\n[next] verify the ledger:`);
   console.log(`  cat ${target} | jq .`);
   console.log(`\n[next] commit + push:`);

package/skills/adia-ui-release/scripts/package-paths.mjs

@@ -0,0 +1,44 @@
+// package-paths.mjs — package name-vs-path-form normalization for the
+// standalone CHANGELOG helpers.
+//
+// THE PROBLEM (bit all 6 a2ui packages at the v0.7.14 cut):
+//   The 6 a2ui packages live on disk under `packages/a2ui/<x>/` but carry the
+//   flat npm-name `a2ui-<x>` everywhere else in the tooling (release-pack.mjs,
+//   dispatch-publish.mjs, tag-lockstep.mjs all use the NAME form). The two
+//   standalone helpers (promote-unreleased.mjs, insert-stub.mjs) joined
+//   `packages/<arg>/CHANGELOG.md` with the raw arg, so calling them with the
+//   name form silently 404'd: `CHANGELOG.md not found at packages/a2ui-corpus/`.
+//   release-pack.mjs maps internally (`a2ui-corpus` → `packages/a2ui/corpus`),
+//   so the two forms diverged: name-form failed standalone, path-form failed
+//   when handed to the orchestrator-style callers.
+//
+// THE FIX:
+//   Accept BOTH forms. Try `packages/<arg>` first (path form, backward-compat).
+//   If that directory is absent AND the arg matches `a2ui-<x>`, fall back to
+//   `packages/a2ui/<x>`. So `a2ui-corpus` (name) and `a2ui/corpus` (path) both
+//   resolve to `packages/a2ui/corpus/`.
+//
+// Pure Node, stdlib only — keeps the scripts free of runtime deps.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Resolve a package arg to its on-disk directory under packages/, accepting
+// BOTH the name form (`a2ui-corpus`) and the path form (`a2ui/corpus`).
+// Returns the resolved relative directory (e.g. `a2ui/corpus`); does not
+// require the directory to exist (so callers can render a legible not-found
+// error against the resolved path).
+export function resolvePackageDir(repo, pkg) {
+  if (fs.existsSync(path.join(repo, 'packages', pkg))) return pkg;
+  const m = /^a2ui-(.+)$/.exec(pkg);
+  if (m) {
+    const nested = path.join('a2ui', m[1]);
+    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
+}
+
+// Resolve a package arg to its CHANGELOG.md path, accepting both forms.
+export function resolvePackageChangelog(repo, pkg) {
+  return path.join(repo, 'packages', resolvePackageDir(repo, pkg), 'CHANGELOG.md');
+}

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

@@ -20,8 +20,8 @@
 //   2  — bad args / file I/O error
 
 import fs from 'node:fs';
-import path from 'node:path';
 import process from 'node:process';
+import { resolvePackageChangelog } from './package-paths.mjs';
 
 function parseArgs(argv) {
   const args = { version: null, date: null, packages: null, dry: false, repo: process.cwd() };
@@ -52,7 +52,8 @@ function parseArgs(argv) {
 }
 
 function promote(repo, pkg, version, date, dry) {
-  const p = path.join(repo, 'packages', pkg, 'CHANGELOG.md');
+  // Accept both name-form (a2ui-corpus) and path-form (a2ui/corpus). See package-paths.mjs.
+  const p = resolvePackageChangelog(repo, pkg);
   if (!fs.existsSync(p)) {
     console.error(`  ERROR ${pkg} — CHANGELOG.md not found at ${p}`);
     return 'missing';

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

@@ -269,21 +269,50 @@ 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
+// 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.)
+// 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
+// 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.
 async function step8Push(args) {
-  console.log('\n=== Step 8 — Push main + tags ===');
+  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`, args);
+  await checkpoint(`Ready to push ${count} commit(s) + 10 tags (one-at-a-time)`, args);
   sh('git push origin main', args);
-  const tagList = [`v${args.version}`, ...PACKAGES.map((p) => `${p}-v${args.version}`)].join(' ');
-  sh(`git push origin ${tagList}`, args);
+  const perPkgTags = PACKAGES.map((p) => `${p}-v${args.version}`);
+  for (const t of perPkgTags) {
+    sh(`git push origin ${t}`, args);
+  }
+  // Umbrella tag last — triggers no workflow (convention only).
+  sh(`git push origin v${args.version}`, args);
+  console.log(`\n  ${perPkgTags.length} per-package tags + 1 umbrella pushed individually.`);
+  console.log('  NOTE: a single `git push origin <all tags>` can skip ALL publish-on-tag');
+  console.log('  triggers (the GitHub batch-push skip). Step 9 dispatches via');
+  console.log('  workflow_dispatch + verifies each triggered — see recovery-paths.md §Scenario 7.');
 }
 
 // ── Step 9 — Publish ─────────────────────────────────────────────
+// Step 8 pushed per-package tags one-at-a-time, so push-on-tag may have fired
+// 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.
 async function step9Publish(args) {
-  console.log('\n=== Step 9 — Dispatch publishes ===');
-  await checkpoint('Ready to dispatch 9 npm publishes', args);
-  sh(`node ${SCRIPT_DIR}/dispatch-publish.mjs --version ${args.version} --scope ${args.scope}`, 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);
+  // 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');

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

@@ -94,11 +94,19 @@ function main() {
   console.log(`\n[tag-lockstep] ${tags.length} tags created at ${targetSha.slice(0, 9)} ${args.dry ? '(dry)' : ''}`);
 
   if (!args.dry) {
+    const perPkg = tags.filter((t) => t !== `v${args.version}`);
     console.log(`\n[next] run F-N1:`);
     console.log(`  node scripts/release/check-release.mjs --all-pending`);
-    console.log(`\n[next] when F-N1 is 9/9 clean, push:`);
+    console.log(`\n[next] when F-N1 is 9/9 clean, push main + tags ONE-AT-A-TIME:`);
+    console.log(`  # A single \`git push origin <all tags>\` can trigger ZERO publish-on-tag`);
+    console.log(`  # workflows (the GitHub batch-push skip — it bit the v0.7.14 cut).`);
+    console.log(`  # Push each per-package tag separately so each publish-<pkg>.yml fires.`);
     console.log(`  git push origin main`);
-    console.log(`  git push origin ${tags.join(' \\\n    ')}`);
+    console.log(`  for t in ${perPkg.join(' ')}; do git push origin "$t"; done`);
+    console.log(`  git push origin v${args.version}   # umbrella last (triggers nothing)`);
+    console.log(`\n[next] VERIFY each publish actually triggered + re-dispatch any misses:`);
+    console.log(`  node "$(dirname "$0")/dispatch-publish.mjs" --version ${args.version} --verify-triggered`);
+    console.log(`  # (recovery-paths.md §Scenario 7 — tags pushed but no publish triggered)`);
   }
 }
 

package/skills/adia-ui-release/skill.json

@@ -1,7 +1,7 @@
 {
   "name": "adia-ui-release",
-  "version": "0.1.0",
-  "description": "Release engineer for an @adia-ai-style lockstep monorepo. Cuts, tags, publishes, deploys, authors release notes + audit-history ledgers — AND authors the MIGRATION GUIDE when a cut breaks an API (the producer side of migrations, folded in from the former adia-ui-migration skill). Use whenever the user wants to CUT A RELEASE / SHIP A VERSION / PUBLISH PACKAGES / BATCH-PUSH ACCUMULATED RELEASES / RECOVER FROM A VERSION-SKIP / WRITE RELEASE NOTES / PROMOTE [UNRELEASED] CHANGELOG / AUTHOR A MIGRATION GUIDE FOR A BREAKING CUT. Triggers on \"cut vX.Y.Z\", \"initiate a release\", \"publish the npm packages\", \"tag this commit and push the release\", \"batch push\", \"F-N1 warned\", \"GitHub release notes\", \"promote unreleased\", \"version skip recovery\", \"verify pre-flight gates\", \"the cycle just shipped — write up what happened\", \"author a migration guide / write the migration recipe for this breaking change\". VERIFICATION is load-bearing: every cut verifies against reality (npm registry + production endpoint + GH release), not self-checks. Carries the portable release DISCIPLINE with the @adia-ai monorepo's 9-package lockstep + demo-site deploy as the clearly-labeled worked example. Does NOT trigger for: the CONSUMER side of migration (sweeping a downstream app — the separate consumer/app-author plugin), long-running VM ops (provision/restart/key rotation), authoring new code, or generation-pipeline work.",
+  "version": "0.2.2",
+  "description": "Release engineer for an @adia-ai-style lockstep monorepo. Cuts, tags, publishes, deploys, authors release notes + audit-history ledgers \u2014 AND authors the MIGRATION GUIDE when a cut breaks an API (the producer side of migrations, folded in from the former adia-ui-migration skill). Also ships an INDEPENDENT-PACKAGE (class-B) release path for packages versioned independently of the lockstep set (excluded from the lockstep gate, no umbrella tag, no demo-site deploy \u2014 e.g. plugins). Use whenever the user wants to CUT A RELEASE / SHIP A VERSION / PUBLISH PACKAGES / BATCH-PUSH ACCUMULATED RELEASES / RECOVER FROM A VERSION-SKIP / WRITE RELEASE NOTES / PROMOTE [UNRELEASED] CHANGELOG / AUTHOR A MIGRATION GUIDE FOR A BREAKING CUT / SHIP AN INDEPENDENTLY-VERSIONED PACKAGE OR PLUGIN. Triggers on \"cut vX.Y.Z\", \"initiate a release\", \"publish the npm packages\", \"tag this commit and push the release\", \"batch push\", \"F-N1 warned\", \"GitHub release notes\", \"promote unreleased\", \"version skip recovery\", \"verify pre-flight gates\", \"the cycle just shipped \u2014 write up what happened\", \"author a migration guide / write the migration recipe for this breaking change\", \"release the plugin / ship an independently-versioned package / publish a package outside the lockstep\". VERIFICATION is load-bearing: every cut verifies against reality (npm registry + production endpoint + GH release), not self-checks. Carries the portable release DISCIPLINE with the @adia-ai monorepo's 9-package lockstep + demo-site deploy as the clearly-labeled worked example. Does NOT trigger for: the CONSUMER side of migration (sweeping a downstream app \u2014 the separate consumer/app-author plugin), long-running VM ops (provision/restart/key rotation), authoring new code, or generation-pipeline work.",
   "status": "stable",
   "authors": [
     "kim.granlund"
@@ -36,10 +36,12 @@
     "references/exe-deploy.md",
     "references/ledger-discipline.md",
     "references/migration-guide-authoring.md",
+    "references/independent-package-release.md",
     "references/teach-protocol.md",
     "scripts/bump.mjs",
     "scripts/promote-unreleased.mjs",
     "scripts/insert-stub.mjs",
+    "scripts/package-paths.mjs",
     "scripts/tag-lockstep.mjs",
     "scripts/dispatch-publish.mjs",
     "scripts/make-ledger.mjs",
@@ -64,12 +66,12 @@
     "ops-postmortem"
   ],
   "absorbs": [
-    "adia-ui-migration — DONE: producer side folded in as references/migration-guide-authoring.md + mode 11 (§MigrationGuideAuthoring). The consumer side stays in the separate consumer/app-author plugin.",
-    "release-publish / release-notes / verification-sweep — DONE in the source skill: consolidated into modes 1/3/4 (cut), 5/9 (notes), 6 (verify)."
+    "adia-ui-migration \u2014 DONE: producer side folded in as references/migration-guide-authoring.md + mode 11 (\u00a7MigrationGuideAuthoring). The consumer side stays in the separate consumer/app-author plugin.",
+    "release-publish / release-notes / verification-sweep \u2014 DONE in the source skill: consolidated into modes 1/3/4 (cut), 5/9 (notes), 6 (verify)."
   ],
   "references": [
-    "adia-ui-a2ui — corpus-freshness checks route there for remediation (verify:corpus / embeddings drift)",
-    "adia-ui-dogfood — the static-HTML probes (native-primitive-leak, shell-composition) whose findings fold into release notes",
-    "ops-postmortem — incident genre during post-publish recovery (mode 7)"
+    "adia-ui-a2ui \u2014 corpus-freshness checks route there for remediation (verify:corpus / embeddings drift)",
+    "adia-ui-dogfood \u2014 the static-HTML probes (native-primitive-leak, shell-composition) whose findings fold into release notes",
+    "ops-postmortem \u2014 incident genre during post-publish recovery (mode 7)"
   ]
 }

package/skills/dogfood-sweep/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog — dogfood-sweep
+
+## [0.1.0] stable — 2026-05-24
+
+**MINOR** — first versioned cut. Adds `skill.json` + `CHANGELOG.md` to bring
+the skill into rollup-family conventions (per META-REFACTOR-SPEC Round 0).
+No procedural changes to the 6 modes.
+
+The skill is otherwise unchanged: SKILL.md still carries all 6 modes inline
+(component visual probe / app-shell QA / HTML typo sweep / native-primitive
+leak / admin-shell composition / component anatomy + card header). The
+inversion to `references/mode-N-*.md` is Round 2+ work per the per-skill
+REFACTOR-SPEC at `docs/REFACTOR-SPEC.md`.
+
+### Reconstructed history (pre-v0.1.0)
+
+- **2026-05-04** — Added probe #6 (missing component CSS detection) to mode 1
+  after the swap-to-primitive-but-forget-the-link class slipped past a real
+  PR. The bug class: agent uses `<button-ui>` markup but forgets the
+  `<link rel="stylesheet">` for the button component CSS; element registers,
+  markup looks right, listbox renders unstyled.
+
+- **post-§3 commit** — Native-primitive-leak audit (mode 4) intent-marker
+  detection window widened from 80 → 200 chars after a peer agent found that
+  realistic preceding-line comments (indent + comment prefix + reason text +
+  closing `-->` + newline) sat at exactly the 80-char boundary and were not
+  detected.
+
+- **v2.27.4-era** — Mode 6 (Component Anatomy + Card Header Sweep) added per
+  FB-52 §11: card-ui `<header><div>` wrapper anti-pattern + missing anatomy
+  sections per `anatomy-sweep.mjs` expectations.
+
+- **Pre-versioned origin** — Mode 1 (component visual probe via Chromium)
+  authored as the initial skill. Modes 2–5 absorbed from substrate-side
+  `scripts/dev/audit-*.mjs` work over multiple cycles. The skill grew its
+  6-mode catalog organically; this v0.1.0 cut is the first time the manifest
+  reflects the actual content.