@adia-ai/adia-ui-forge 0.8.25 → 0.8.27

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.25",
+  "version": "0.8.27",
   "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,23 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.27] — 2026-08-05
+
+### Changed
+- **Agent seats pin explicit models** — no seat rides the caller's tier (gh#618, PR #620).
+- Release tooling: Step 4d.5 regenerates the derived genui catalog post-bump (gh#617, PR #619); publish workflows for `@adia-ai/agent`/`@adia-ai/persona` with tag↔manifest guards (v0.8.26 recovery, PR #624); `tag-lockstep` selftest derives its count from the roster.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`agents/` touched in this release window** (3 file(s), e.g. `agents/a2ui-builder.md`) — carried by the entries above.
+- **`skills/` touched in this release window** (2 file(s), e.g. `references/cut-procedure.md`) — carried by the entries above.
+
+## [0.8.26] — 2026-08-05
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the lockstep version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.26 work shipped in WCH chat-harness wave + genui conformance train; first publish of @adia-ai/agent + @adia-ai/persona. See `packages/web-modules/CHANGELOG.md#0826--2026-08-05` for details.
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`skills/` touched in this release window** (7 file(s), e.g. `adia-release/SKILL.md`) — carried by the entries above.
+
 ## [0.8.25] — 2026-07-31
 
 ### Maintenance

package/agents/a2ui-builder.md

@@ -22,7 +22,10 @@ description: |
 tools: Read, Grep, Glob, Edit, Write, Bash
 skills:
   - adia-a2ui
-model: inherit
+# Explicit pin (gh#618): never `inherit` — a Fable/planning caller would
+# silently run this seat's pipeline-tuning and eval-diagnosis work on the
+# caller's tier. Coding/execution seat → opus.
+model: opus
 ---
 
 The a2ui-builder works the pipeline to the preloaded `adia-a2ui` procedure:

package/agents/framework-reviewer.md

@@ -21,7 +21,10 @@ tools: Read, Grep, Glob, Bash
 skills:
   - adia-dogfood
   - adia-gen-review
-model: inherit
+# 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
 ---
 
 The framework-reviewer runs the preloaded sweep and review procedures and

package/agents/release-builder.md

@@ -22,7 +22,10 @@ description: |
 tools: Read, Grep, Glob, Edit, Write, Bash
 skills:
   - adia-release
-model: inherit
+# Explicit pin (gh#618): never `inherit` — this seat runs UNATTENDED cuts,
+# where a cheap caller tier would make live gate-failure judgment calls
+# with no operator watching. Execution seat with real judgment → opus.
+model: opus
 ---
 
 The release-builder runs the preloaded `adia-release` procedure under its

package/package.json

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

@@ -3,7 +3,7 @@ name: adia-release
 description: >-
   Release engineering for the @adia-ai lockstep monorepo. Use when asked to
   cut and ship a release, promote [Unreleased] CHANGELOG entries, tag and push the
-  lockstep packages to origin, publish an 11-package release (9 npm
+  lockstep packages to origin, publish a 13-package release (11 npm
   libraries + 2 Claude Code plugins), batch-push piled-up release commits,
   recover a cut that landed wrong or whose publish workflows didn't fire,
   fix a check:lockstep bump failure or an F-N1 CHANGELOG-coverage warning,
@@ -17,7 +17,7 @@ user-invocable: true
 
 # adia-release
 
-Release engineering for an @adia-ai-style lockstep monorepo: the 11 `@adia-ai/*` packages — 9 npm libraries plus the 2 Claude Code plugins under `packages/plugins/*` — version and publish together (class A; the plugins joined the lockstep 2026-07-15 after class-B independence let npm drift a full harness-reset behind the repo). Class B (independent versioning) currently has no members; the procedure is retained for future genuinely-independent packages. The substrate — `scripts/release/*`, the `check:*` gates, the tag-triggered publish workflows — encodes the invariants; this skill routes, sequences, and stops at the judgment calls.
+Release engineering for an @adia-ai-style lockstep monorepo: the `@adia-ai/*` packages on the roster (`scripts/package-paths.mjs`, the single source — 13 as of gh#607: 11 npm libraries plus the 2 Claude Code plugins under `packages/plugins/*`) version and publish together (class A; the plugins joined the lockstep 2026-07-15 after class-B independence let npm drift a full harness-reset behind the repo). Class B (independent versioning) currently has no members; the procedure is retained for future genuinely-independent packages. The substrate — `scripts/release/*`, the `check:*` gates, the tag-triggered publish workflows — encodes the invariants; this skill routes, sequences, and stops at the judgment calls.
 
 ## Authorization — one go, gates do the rest (operator ruling 2026-07-17)
 
@@ -31,7 +31,7 @@ Mechanics: `release-pack.mjs --go` auto-confirms all checkpoints (it equals `--y
 
 ## Invariants (class-A lockstep cut)
 
-1. **Lockstep coherence** — all 11 packages bump together (`check:lockstep`): `web-components`, `web-modules`, `llm`, `a2ui-{runtime,compose,corpus,mcp,retrieval,validator}`, and the plugins `adia-ui-{factory,forge}` (each plugin's `.claude-plugin/plugin.json` version moves with its package.json — `bump.mjs` handles both; `verify:plugins` gates the sync).
+1. **Lockstep coherence** — every roster package bumps together (`check:lockstep`; the roster lives in `scripts/package-paths.mjs`, currently `web-components`, `web-modules`, `llm`, `agent`, `persona`, `a2ui-{runtime,compose,corpus,mcp,retrieval,validator}`, and the plugins `adia-ui-{factory,forge}`) (each plugin's `.claude-plugin/plugin.json` version moves with its package.json — `bump.mjs` handles both; `verify:plugins` gates the sync).
 2. **PATCH-cut asymmetry** — internal `@adia-ai/*` ranges hold at `^X.Y.0` during PATCH cuts; only MINOR bumps the floor. `^0.0.x` is forbidden (pre-1.0 caret locks exact — shipped a real stale-sibling bug).
 3. **Release commits land via PR, never a direct push to `main`** (repo policy, operator ruling 2026-07-12): commit on `release/vX.Y.Z` → PR → CI → merge — THEN tag at `main`'s post-merge HEAD, not at the bump commit; post-bump fixes merge before tagging and belong in the tarball. Exception: batch push tags each version at its own release-merge SHA.
 4. **One umbrella + one per-package tag per cut** (`vX.Y.Z` + 11 × `<pkg>-vX.Y.Z`); publish workflows key off the per-package tags. Push tags **one per `git push`** — a batched multi-tag push drops the trigger event.
@@ -72,7 +72,7 @@ Every cut reports, whether it ran inline or via `release-builder`:
 
 | Field | Value |
 | --- | --- |
-| Version | X.Y.Z — 11/11 packages at this version |
+| Version | X.Y.Z — all roster packages at this version (`check:lockstep`) |
 | Commit / PR | release commit SHA, PR # (merged) |
 | Tags | umbrella `vX.Y.Z` + 11 per-package tags pushed (or: which are still pending, and why) |
 | Registry | `npm view @adia-ai/<pkg> version` per package, cited (not "publish workflow green") |
@@ -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 24-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 roster package 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 24-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/changelog-discipline.md

@@ -85,7 +85,7 @@ The inserted block:
 
 ### Maintenance
 - **Lockstep version bump only.** No source changes in this package; bumped to
-  maintain the 11-package version coherence enforced by
+  maintain the lockstep version coherence enforced by
   `scripts/release/check-lockstep.mjs`. Substantive v0.X.Y work shipped in
   <SUBSTANTIVE>. See `<XREF>` for details.
 ```
@@ -104,7 +104,7 @@ F-N1 (`node scripts/release/check-release.mjs --all-pending`) cross-checks the g
 node scripts/release/check-release.mjs --pending-version X.Y.Z --fix
 ```
 
-This is cut-procedure §Step 4f: the SAME matcher F-N1 uses at tag time (all 11 packages, the `changelogMentions` pattern set including the `.claude-plugin` leading-dot case), run against the working tree, auto-appending a verified `### Maintenance` bullet per uncovered directory. It re-checks its own output before writing — the v0.8.5 cut hand-authored "enrichment" three times that read correctly but didn't contain the literal substrings the checker matches, costing 3 PRs and 3 tag rewrites. `release-pack.mjs` cut modes run this automatically.
+This is cut-procedure §Step 4f: the SAME matcher F-N1 uses at tag time (every roster package, the `changelogMentions` pattern set including the `.claude-plugin` leading-dot case), run against the working tree, auto-appending a verified `### Maintenance` bullet per uncovered directory. It re-checks its own output before writing — the v0.8.5 cut hand-authored "enrichment" three times that read correctly but didn't contain the literal substrings the checker matches, costing 3 PRs and 3 tag rewrites. `release-pack.mjs` cut modes run this automatically.
 
 **Hand-enrichment (better prose than the auto-bullet):** add the path keyword inline where it makes the entry *more* accurate — `` `table.yaml` `` → `` `components/table/table.yaml` `` — never as a bolted-on parenthetical. Verify with `--pending-version` (no `--fix`) before committing; never assume prose satisfies the matcher.
 

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

@@ -119,7 +119,7 @@ Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source,
 
 ## §Step 4 — (Variant B, or ANY variant with uncommitted `[Unreleased]` content) Promote, bump, lockfile
 
-**Run 4a whenever a hand-authored `## [Unreleased]` section is still sitting uncommitted, not only on a strict Variant B.** `release-pack.mjs --mode cut` (a peer's pre-staged content, not yet promoted) needs it exactly as much as `--mode from-scratch` does — the v0.8.4 near-miss was `--mode cut` skipping this step entirely because the doc (and the script) only associated promotion with "from scratch". Both modes now run it and both hard-fail before the bump if any of the 11 packages still carries non-empty `[Unreleased]` content afterward.
+**Run 4a whenever a hand-authored `## [Unreleased]` section is still sitting uncommitted, not only on a strict Variant B.** `release-pack.mjs --mode cut` (a peer's pre-staged content, not yet promoted) needs it exactly as much as `--mode from-scratch` does — the v0.8.4 near-miss was `--mode cut` skipping this step entirely because the doc (and the script) only associated promotion with "from scratch". Both modes now run it and both hard-fail before the bump if any roster package still carries non-empty `[Unreleased]` content afterward.
 
 **4a. Promote** `## [Unreleased]` → `## [vX.Y.Z] — YYYY-MM-DD` per package (`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/insert-stub.mjs` ``). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
 
@@ -129,6 +129,8 @@ Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source,
 
 **4d.** `npm run check:lockstep` → `OK — all packages at X.Y.Z, all internal ranges at ^X.Y.0`.
 
+**4d.5. Regenerate the derived genui catalog** (gh#617): `node scripts/build/derive-genui-catalog.mjs`. Its `catalogId` embeds the lockstep version (`adia.base@X.Y.Z`), so the 4b bump just invalidated `packages/genui/adia-catalog/{base,adia-pack}.json` — regenerated pre-bump (§3.0) or not. The v0.8.26 cut skipped this and `check:genui-catalog` failed in CI one push later. Both files ride the release commit (Step 5 stages them).
+
 **4e. Release docs + team notes** (gated, not optional): review the entry
 files the release touches (root README/CHANGELOG, per-package READMEs —
 content currency is YOUR judgment; the gate only proves presence), then
@@ -165,6 +167,7 @@ section already names, in this order:
 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/build/derive-genui-catalog.mjs                                                   # 4d.5 — catalogId carries the bumped version (gh#617)
 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
@@ -187,6 +190,7 @@ git -C "$REPO" checkout -b "release/vX.Y.Z"
 git -C "$REPO" reset HEAD >/dev/null 2>&1
 git -C "$REPO" add package-lock.json packages/*/package.json packages/*/CHANGELOG.md \
   packages/a2ui/*/package.json packages/a2ui/*/CHANGELOG.md \
+  packages/genui/adia-catalog/base.json packages/genui/adia-catalog/adia-pack.json \
   docs/releases/vX.Y.Z.md   # + in-scope source + Step-3.0 regen outputs
 git -C "$REPO" diff --cached --stat | tail -3   # count must match the allowlist
 ```
@@ -247,7 +251,7 @@ The operator's initiating instruction covers the whole cycle — no per-step re-
 
 ## §Step 4f — Pre-tag coverage `--fix` (the retag-loop killer)
 
-After the bump + lockfile, run the AUTHORITATIVE F-N1 matcher against the working tree — same code, same `changelogMentions` patterns, all 11 packages — and let it append verified Maintenance bullets for any changed-but-unmentioned directory:
+After the bump + lockfile, run the AUTHORITATIVE F-N1 matcher against the working tree — same code, same `changelogMentions` patterns, every roster package — and let it append verified Maintenance bullets for any changed-but-unmentioned directory:
 
 ```bash
 node scripts/release/check-release.mjs --pending-version X.Y.Z --fix

package/skills/adia-release/references/notes-authoring.md

@@ -18,12 +18,12 @@ If the diff contradicts the plan (a feature deferred, a refactor split across cu
 
 ## §The GH release body (single version, ~80–200 lines)
 
-All 11 packages get the same body (`gh release create <pkg>-vX.Y.Z --notes-file …`).
+Every roster package (package-paths.mjs) gets the same body (`gh release create <pkg>-vX.Y.Z --notes-file …`).
 
 ```markdown
 ## vX.Y.Z — <one-line tagline>
 
-11-package lockstep **PATCH** cut. <One sentence on scope.>
+Lockstep **PATCH** cut (all roster packages). <One sentence on scope.>
 
 ### `@adia-ai/<substantive-pkg>`
 - **<Bold-prefix headline>.** <Why → what → inline file paths.> Closes <FEEDBACK-NN>.
@@ -50,7 +50,7 @@ Shape rules: open with the tagline, no preamble; group by `### @adia-ai/<pkg>`;
 
 npm i @adia-ai/web-components@X.Y.Z @adia-ai/web-modules@X.Y.Z
 
-11-package lockstep PATCH cut. <One sentence.>
+Lockstep PATCH cut (all roster packages). <One sentence.>
 
 ## 🔷 `@adia-ai/<pkg>` — <headline>
 <2–4 sentences.> Closes <FEEDBACK-NN>.

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

@@ -22,7 +22,7 @@ import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
 import { PACKAGE_NAMES } from './package-paths.mjs';
 
-// Instance data — fork-configurable. The npm scope the 11 packages publish under.
+// Instance data — fork-configurable. The npm scope the lockstep roster publishes under.
 // Default preserves @adia-ai behavior; override via --scope or $ADIA_NPM_SCOPE.
 const DEFAULT_SCOPE = '@adia-ai';
 

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

@@ -68,7 +68,7 @@ function buildStub(version, date, substantive, xref) {
   return `## [${version}] — ${date}
 
 ### Maintenance
-- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 11-package version coherence enforced by \`scripts/release/check-lockstep.mjs\`. Substantive v${version} work shipped in ${substantive}. See \`${xref}\` for details.
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the lockstep version coherence enforced by \`scripts/release/check-lockstep.mjs\`. Substantive v${version} work shipped in ${substantive}. See \`${xref}\` for details.
 
 `;
 }

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

@@ -46,6 +46,8 @@ export const PACKAGE_ROSTER = [
   { name: 'web-components',  dir: 'packages/web-components' },
   { name: 'web-modules',     dir: 'packages/web-modules' },
   { name: 'llm',             dir: 'packages/llm' },
+  { name: 'agent',           dir: 'packages/agent' },
+  { name: 'persona',         dir: 'packages/persona' },
   { name: 'a2ui-runtime',    dir: 'packages/a2ui/runtime' },
   { name: 'a2ui-compose',    dir: 'packages/a2ui/compose' },
   { name: 'a2ui-corpus',     dir: 'packages/a2ui/corpus' },

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

@@ -408,6 +408,13 @@ function step4PromoteAndBump(args) {
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
 
+  // Step 4d.5 — regenerate the derived genui catalog (gh#617): its catalogId
+  // embeds the lockstep version (`adia.base@X.Y.Z`), so the bump above just
+  // invalidated base.json/adia-pack.json. The v0.8.26 cut skipped this and
+  // check:genui-catalog failed in CI one push later. Step 5 stages both files.
+  console.log('\n  Step 4d.5 — regenerate derived genui catalog (catalogId carries the lockstep version):');
+  sh('node scripts/build/derive-genui-catalog.mjs', args);
+
   // Step 4e — generate docs/releases/vX.Y.Z.md (gh#399: neither this step nor
   // its staging into the release commit existed before — check-cut-hygiene's
   // "notes present" claim (Step 4g, below) went unverified until
@@ -484,6 +491,10 @@ function step5Commit(args) {
     // gh#399: Step 4e generates this but never staged it before — it landed
     // in a second PR after the release commit instead (v0.8.11 cut).
     `docs/releases/v${args.version}.md`,
+    // gh#617: Step 4d.5 regenerates these post-bump (catalogId embeds the
+    // lockstep version); unstaged, check:genui-catalog fails in CI (v0.8.26).
+    'packages/genui/adia-catalog/base.json',
+    'packages/genui/adia-catalog/adia-pack.json',
     ...PACKAGE_ROSTER.flatMap(({ name, dir, plugin }) => {
       // Roster-driven (H3): each package stages its manifest + CHANGELOG;
       // plugins also stage .claude-plugin/plugin.json (the /plugin-update

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

@@ -61,7 +61,7 @@ function main() {
   const tags = buildTagList(args.version);
 
   if (args.deleteMode) {
-    console.log(`Deleting 12 tags for v${args.version}:`);
+    console.log(`Deleting ${tags.length} tags for v${args.version}:`);
     for (const t of tags) {
       try {
         run(`git tag -d ${t}`, args.repo, args.dry);
@@ -75,7 +75,7 @@ function main() {
   }
 
   const targetSha = args.at || run('git rev-parse HEAD', args.repo, false).trim();
-  console.log(`Creating 12 tags for v${args.version} at ${targetSha.slice(0, 9)}:`);
+  console.log(`Creating ${tags.length} tags for v${args.version} at ${targetSha.slice(0, 9)}:`);
   for (const t of tags) {
     try {
       run(`git tag ${t} ${args.at || ''}`.trim(), args.repo, args.dry);
@@ -106,8 +106,12 @@ function main() {
 
 function selftest() {
   const tags = buildTagList('1.2.3');
-  if (tags.length !== 12) {
-    console.error(`selftest FAIL: expected 12 tags (umbrella + 11 per-package), got ${tags.length}`); process.exit(1);
+  // Derive from the roster (package-paths.mjs is the single source) — a
+  // hard-coded count here is exactly the drift gh#612 removed from the docs;
+  // the v0.8.26 cut caught this one when agent+persona joined (11 → 13).
+  const expected = PACKAGE_NAMES.length + 1; // umbrella + one per package
+  if (tags.length !== expected) {
+    console.error(`selftest FAIL: expected ${expected} tags (umbrella + ${PACKAGE_NAMES.length} per-package), got ${tags.length}`); process.exit(1);
   }
   if (tags[0] !== 'v1.2.3') {
     console.error('selftest FAIL: umbrella tag must be first'); process.exit(1);