@adia-ai/adia-ui-forge 0.8.60 → 0.8.61

package/skills/a2ui-maintenance/references/eval-diagnostics.md

@@ -46,7 +46,7 @@ fluctuate).
 ## Phase 2 — fixes per bucket
 
 - **A. Holdout alignment** — map each intent's `expected_chunk` to the actual
-  top-1; update `packages/gen-ui/engine/corpus/evals/holdout-compose-from-chunks.jsonl`.
+  top-1; update `packages/gen-ui/engine/evals/corpus/holdout-compose-from-chunks.jsonl`.
 - **E. Measurement traps** — PascalCase→kebab (`AgentTrace` → `agent-trace`,
   not `agenttrace`); substring false positives (`pane` vs `panel`,
   `textarea-ui` contains `text-ui` — word boundaries); case sensitivity (`/i`).
@@ -82,7 +82,7 @@ the SKILL.md floors hold.
 The two `check:*-eval-regression` scripts own the floor numbers — read the source
 before quoting a number elsewhere; SKILL.md only mirrors them and can drift (it
 once silently regressed to `cov≥40` before the mechanical gate existed). Zettel's
-floors are a committed file, `evals/health/zettel-floor.json` (gh#1391) —
+floors are a committed file, `packages/gen-ui/engine/evals/health/zettel-floor.json` (gh#1391);
 `scripts/release/check-zettel-eval-regression.mjs` loads it at runtime and refuses
 to run without it, so re-baselining is a JSON diff, not a source edit. Free-form's
 floors are still `ALERT_FLOOR`/`HARD_FLOOR` constants in

package/skills/a2ui-maintenance/references/pipeline-overview.md

@@ -202,7 +202,9 @@ for any constant or decision lives in git and PR descriptions
     (`THINKING_BUDGET_MONOLITHIC_THINKING`) and `free-form-composer/
     index.js`'s ingredient-picker call, both its primary pick and its own
     paraphrase-retry (`THINKING_BUDGET_FREE_FORM`), both starting at the
-    bridge's own `DEFAULT_THINKING_BUDGET` (10000). `auto` inherits
+    bridge's own `DEFAULT_THINKING_BUDGET`, lowered to 4000 (gh#3516 slice
+    3, conductor ruling 2026-09-08) after an n=5 measurement at 10000
+    showed no measurable quality gain with real cost. `auto` inherits
     through the free-form picker call the moment it escalates that far -
     `monolithic-thinking` itself is never reachable via `auto`'s own
     escalation ladder. Every other LLM call site (`generate-pro.js`'s four

package/skills/a2ui-maintenance/references/strategy-engines.md

@@ -86,6 +86,18 @@ shows the results); `--strict` enforcement is deferred to TKT-0010
 (27% of the corpus currently fails, mostly a schema-generation gap
 around `data-*`/`span` attributes rather than corpus-content defects).
 
+## Provider thinking opt-in kill switch (gh#3516, LLD-3516 slice 1)
+
+`monolithic-thinking` and `free-form-composer` opt into provider thinking at
+a fixed strategy-level budget (`THINKING_BUDGET_MONOLITHIC_THINKING`,
+`THINKING_BUDGET_FREE_FORM`, both 4000 as of gh#3516 slice 3) via the shared
+`compose/shared/thinking-opt-in.js` helper. `ADIA_THINKING_OPT_IN=0` drops
+the `thinking`/`thinkingBudget` fields at both call sites entirely (not
+`thinking: false`, the adapter never sees the keys), giving the
+thinking-off baseline a runtime lever instead of a code revert. Unset (or
+`"1"`) keeps current behavior. This is an operations knob, not a caller
+option: no consumer threads it through `generateUI()`.
+
 ## Pitfalls
 
 - **`STRONG_MATCH_THRESHOLD` was raised 22 → 40 post-incident.** Lowering it

package/skills/demo-audit/references/admin-shell-anatomy.md

@@ -17,7 +17,7 @@ the live admin-dashboard example.
    `<select-ui avatar="…" value="…" variant="ghost">` context switcher —
    NOT `<menu-ui>` (legacy pattern) — ★ commonly mis-implemented
 4. Sidebar nav wrap around `<nav-ui>` — `<section>` (per the examples),
-   `<section-ui>` (card-style chrome), or `<admin-scroll>` all accepted;
+   `<section-ui>` (card-style chrome), or `<page-scroll>` all accepted;
    a bare `<nav-ui>` direct child overflows long lists
 5. Sidebar `<admin-statusbar slot="footer">` with `<select-ui avatar="…">`
    (user menu) — ★ commonly missing
@@ -28,17 +28,23 @@ the live admin-dashboard example.
    ★ spacer + actions commonly missing
 8. `[data-actions]` contains `<popover-ui>` + `<theme-panel slot="content">`
    (there is no `<theme-picker-ui>`)
-9. `<admin-scroll>` wrapping optional `<aside data-subnav hidden>` +
-   `<router-ui>` (or `<admin-page>` directly for non-routed)
-   **[deprecated 2026-09-01, ADR-0098]** `admin-scroll` is a wholesale
-   rename to `page-scroll` (both modes carried over); `admin-scroll` stays
-   as a working compat alias for the deprecation window only.
+9. `<page-scroll>` wrapping optional `<aside data-subnav hidden>` +
+   `<router-ui>` (or `<page-ui band>` directly for non-routed)
+   **[deleted, ADR-0098 / gh#3745]** `admin-scroll` was a wholesale
+   rename to `page-scroll` (both modes carried over); its one-release
+   deprecation window has closed and the module is deleted (gh#3745).
+   The `admin-page` family (`admin-page`/`admin-page-header`/
+   `admin-page-body`) is deleted outright per ADR-0098, no compat alias.
+   `page-scroll` wrapping `page-ui[band]` is the sole successor for the
+   routed and non-routed case alike.
 10. `<admin-page>` with `<admin-page-header>` + `<admin-page-body>`
-    **[deprecated 2026-09-01, ADR-0098]** The `admin-page` family is
-    retired deprecate-then-delete in favor of `page-ui[band]` — `page-ui`
-    is now the one canonical page-chrome primitive; this anatomy still
-    describes the pre-migration shape for auditing legacy surfaces during
-    the deprecation window.
+    **[deleted, ADR-0098]** The `admin-page` family is deleted outright,
+    no compat alias and no open deprecation window, in favor of
+    `page-ui[band]`; `page-ui` is now the one canonical page-chrome
+    primitive (item 9 above shows the live composition: `page-scroll`
+    wrapping `page-ui[band]`). This item is kept only so this anatomy
+    still recognizes the retired shape when auditing legacy surfaces
+    that predate the migration; never author it in new surfaces.
 11. `<admin-statusbar>` at content footer (version strip) — ★ commonly missing
 12. Second `<admin-sidebar slot="trailing">` (inspector rail, hidden by
     default) — strongly recommended
@@ -64,7 +70,7 @@ the live admin-dashboard example.
 | content topbar missing `[data-spacer]` / `[data-actions]` | warning — part 7 |
 | content missing trailing `<admin-statusbar>` | warning — part 11 |
 | sidebar topbar contains only plain text | warning — part 3 context switcher |
-| `<admin-scroll>` missing around `<admin-page>` | critical — part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+page wrapper the content renders flush with the topbar, no margins) — **[deprecated 2026-09-01, ADR-0098]** `admin-scroll`/`admin-page` describe the pre-migration shape; the successor is `page-scroll` wrapping `page-ui[band]` |
+| `<page-scroll>` missing around `<page-ui band>` | critical, part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+chrome wrapper the content renders flush with the topbar, no margins). **[deleted, ADR-0098 / gh#3745]** `admin-scroll` and the `admin-page` family are both deleted outright, no compat alias; the successor is `page-scroll` wrapping `page-ui[band]` |
 
 ## Opt-out contract
 

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

@@ -20,6 +20,7 @@
 import { execFileSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+import { warnIfStaleCopy } from './stale-copy-warning.mjs';
 import { PACKAGE_ROSTER } from './package-paths.mjs';
 
 // Instance data — fork-configurable. The npm scope the lockstep roster publishes under.
@@ -288,6 +289,13 @@ 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());
+  // Stale-plugin-cache self-check (ticket #3943 item 2), same primitive
+  // release-pack.mjs's own top-level check now calls.
+  warnIfStaleCopy(
+    import.meta.url,
+    process.cwd(),
+    'packages/plugins/adia-ui-forge/skills/package-release/scripts/dispatch-publish.mjs',
+  );
   if (args.after) checkAfter(args.after, args.scope);
 
   // Recovery mode — verify each publish workflow SUCCEEDED for its pushed tag

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

@@ -103,15 +103,15 @@ export const GATE_ROSTER = [
   // on the handoff re-run, since the promoted heading was already on main).
   { n: 26, cmd: 'node scripts/release/check-dx-sweep-freshness.mjs', targetVersionArg: true, what: 'DX sweep fresh + not regression-RED' },
   // gh#1135 (WS-4 SPEC REQ-06): a fresh free-form eval run feeds the health
-  // record gate 28 writes — without it, "latest" under evals/mcp/runs/ could
+  // record gate 28 writes: without it, "latest" under packages/gen-ui/engine/evals/mcp/runs/ could
   // be a stale leftover from an earlier ad-hoc run, not this cut's own state.
-  { n: 27, cmd: 'npm run eval:diff -- --engine free-form',   what: 'fresh free-form eval run (evals/health input)' },
-  // REQ-06: commits evals/health/<version>.json — the version this record
+  { n: 27, cmd: 'npm run eval:diff -- --engine free-form',   what: 'fresh free-form eval run (packages/gen-ui/engine/evals/health input)' },
+  // REQ-06: commits packages/gen-ui/engine/evals/health/<version>.json; the version this record
   // names is the CUT's target version from the start, never the
   // pre/post-bump `hygieneVersion` gate 24 needs (a claim-validation
   // concern this is not) — hence `targetVersionArg` rather than
   // `versionArg`, a distinct flag release-pack.mjs's step3PreFlight reads.
-  { n: 28, cmd: 'node scripts/release/write-eval-health.mjs', what: 'evals/health/<version>.json committed, AC-01/AC-02 run for real', targetVersionArg: true },
+  { n: 28, cmd: 'node scripts/release/write-eval-health.mjs', what: 'packages/gen-ui/engine/evals/health/<version>.json committed, AC-01/AC-02 run for real', targetVersionArg: true },
   // ADR-0048 (gh#1192) estate-split latch. Between P1 (mint @adia-ai/gen-ui)
   // and P5 (shims + roster) the tree is correct in-repo but deliberately
   // NOT publishable: the old package dirs are `private: true` stubs the

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

@@ -76,6 +76,7 @@ import { GATE_ROSTER } from './gate-roster.mjs';
 // hand-duplicating them — bump.mjs guards its own main()/selftest() behind
 // an entry-point check specifically so this import is side-effect-free.
 import { PINNED_REFS, REPO_PINNED_REFS } from './bump.mjs';
+import { warnIfStaleCopy } from './stale-copy-warning.mjs';
 
 const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
 const REPO = process.cwd();
@@ -523,18 +524,18 @@ function step1ReBaseline(args) {
 //           since neither touches (a)'s files). This is the roster's one
 //           CSS-before-JS-shaped file-write ordering dependency: gate 27
 //           (`eval:diff --engine free-form`) writes a fresh
-//           evals/mcp/runs/<ISO>/ directory; gate 28
+//           packages/gen-ui/engine/evals/mcp/runs/<ISO>/ directory; gate 28
 //           (write-eval-health.mjs) reads whichever directory under
-//           evals/mcp/runs/ SORTS LEXICALLY LAST — not specifically the
+//           packages/gen-ui/engine/evals/mcp/runs/ SORTS LEXICALLY LAST, not specifically the
 //           latest free-form run — and expects free-form.json there. Gate
 //           16 (`eval:diff --engine zettel`) writes its OWN fresh directory
 //           under that same root; if 16 and 27 ran concurrently and 16
 //           happened to finish after 27, gate 28 would silently pick 16's
 //           directory (no free-form.json) and commit
-//           evals/health/<version>.json with `engines.free-form: null` — a
+//           packages/gen-ui/engine/evals/health/<version>.json with `engines.free-form: null`, a
 //           real, silent coverage loss the roster's fixed serial order
 //           prevents today only by construction. Keeping 16 before 27
-//           before 28, uninterrupted by any other evals/mcp/runs/ writer,
+//           before 28, uninterrupted by any other packages/gen-ui/engine/evals/mcp/runs/ writer,
 //           preserves that guarantee.
 //
 // Fail-fast BETWEEN phases (a Phase 1 failure skips Phase 2 outright — no
@@ -1224,7 +1225,7 @@ function step5Commit(args) {
     // targetVersionArg comment above). Under --skip-gates the record was
     // never written (Step 3 returned early), so staging it would make the
     // whole `git add` fail on a missing pathspec (PR #1204 review).
-    ...(args.skipGates ? [] : [`evals/health/${args.version}.json`]),
+    ...(args.skipGates ? [] : [`packages/gen-ui/engine/evals/health/${args.version}.json`]),
     ...LOCKSTEP_ROSTER.flatMap(({ name, dir, plugin }) => {
       // Roster-driven (H3): each package stages its manifest + CHANGELOG;
       // plugins also stage .claude-plugin/plugin.json (the /plugin-update
@@ -1265,6 +1266,34 @@ function step5Commit(args) {
     // package.json is already staged above; web-modules' peer-pin entry
     // targets that same package.json).
     ...pinnedRefFiles(PINNED_REFS, REPO_PINNED_REFS),
+    // gh#3946 (v0.8.60 cut hygiene, item 1), root-caused for real at the
+    // v0.8.61 cut: the changelog-fragment assembly step
+    // (assemble-changelog-fragments.mjs) DELETES each consumed
+    // `changes/<pr>.md`/`changes/gh-<issue>.md` fragment (and its
+    // package-suffixed siblings) after folding it into the target
+    // CHANGELOG's own `[Unreleased]` section, a deletion of an
+    // already-tracked file is exactly the 'D' shape Step 5.6's
+    // unstagedTrackedLeftovers() guard blocks on below, same as any other
+    // tracked modification this list must stage first. The v0.8.60 fix
+    // used a shell glob (`changes/*.md`) on the WRONG theory that an
+    // unmatched glob falls through to git's own pathspec wildcard matching:
+    // that only holds when NOTHING in the directory survives. `changes/`
+    // also holds `README.md`, never a fragment, never deleted, so the shell
+    // glob reliably expands to exactly that one survivor and `git add`
+    // never sees a pathspec covering the deleted fragments at all, they
+    // stay unstaged with no error until Step 5.6's guard catches them
+    // downstream (confirmed live at the v0.8.61 cut: 194 fragments deleted,
+    // one survivor, exactly this shape). The correct form names the
+    // DIRECTORY, not a glob inside it: git enumerates the pathspec itself
+    // against its own index rather than asking the shell to enumerate the
+    // working tree first, so it stages every tracked change under
+    // `changes/` including a deletion, regardless of how many (if any)
+    // sibling files still exist on disk. bump.mjs's own PACKAGE_VERSION-
+    // literal pin writes into `packages/web-modules/index.css` too (the
+    // same drift class as the icons-cdn.js entry pinnedRefFiles() already
+    // covers above), so it needs the same explicit, hand-listed entry.
+    'changes/',
+    'packages/web-modules/index.css',
   ];
   const dedupedReleaseFiles = [...new Set(releaseFiles)];
   sh(`git add ${dedupedReleaseFiles.join(' ')}`, args);
@@ -1746,24 +1775,21 @@ async function main() {
   // Fail-fast guard: refuse to git/npm/gh/curl against a non-monorepo directory.
   assertMonorepoRoot(REPO);
   console.log(`package-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
-  // Stale-plugin-cache self-check (v0.8.32 cut, first failure): the INSTALLED
-  // plugin cache only refreshes on a version bump, so running this script from
-  // the cache mid-cycle can execute a version that predates its own guards
-  // (SKILL.md §Plugin cache). If the repo carries its own copy and the bytes
-  // differ, warn loudly — the repo copy is almost always the newer one.
-  const repoCopy = path.join(REPO, 'packages/plugins/adia-ui-forge/skills/package-release/scripts/release-pack.mjs');
-  const selfPath = new URL(import.meta.url).pathname;
-  if (fs.existsSync(repoCopy) && path.resolve(selfPath) !== path.resolve(repoCopy)) {
-    const self = fs.readFileSync(selfPath, 'utf8');
-    const repo = fs.readFileSync(repoCopy, 'utf8');
-    if (self !== repo) {
-      console.error('\n⚠  STALE-COPY WARNING: this release-pack.mjs differs from the repo\'s own copy at');
-      console.error(`   ${repoCopy}`);
-      console.error('   The installed plugin cache lags the repo between cuts (SKILL.md §Plugin cache);');
-      console.error('   the repo copy is almost certainly newer — prefer running it:');
-      console.error(`     node ${repoCopy} <same args>\n`);
-    }
-  }
+  // Stale-plugin-cache self-check (v0.8.32 cut, first failure; generalized
+  // ticket #3943 item 2): the INSTALLED plugin cache only refreshes on a
+  // version bump, so running this script from the cache mid-cycle can
+  // execute a version that predates its own guards (SKILL.md §Plugin
+  // cache). If the repo carries its own copy and the bytes differ, warn
+  // loudly: the repo copy is almost always the newer one. The comparison
+  // itself now lives in this skill's own stale-copy-warning.mjs (package-
+  // local by design, see that file's own header), a small primitive its
+  // sibling scripts share, rather than this inline block being the only
+  // copy of the pattern.
+  warnIfStaleCopy(
+    import.meta.url,
+    REPO,
+    'packages/plugins/adia-ui-forge/skills/package-release/scripts/release-pack.mjs',
+  );
   // gh#3342: --from-step10 resumes a handoff that already tagged, pushed,
   // and published — skip straight to Step 10 (GH releases + site deploy)
   // rather than a plain re-run, which would re-run the full pre-flight gate
@@ -2030,7 +2056,7 @@ async function selftest() {
       // gh#1197 — Step 5's staging pathspec must carry gate 28's committed
       // health record, or it rides untracked past the release commit
       // (v0.8.35/v0.8.36 both did, PR #1196 swept them by hand).
-      'evals/health/9.9.9.json',
+      'packages/gen-ui/engine/evals/health/9.9.9.json',
       // gh#1899 — Step 4 must regenerate the Codex plugin manifests post-bump
       // (the v0.8.48 release PR #1897 shipped stale ones without this step).
       'Step 4d.6 — regenerate Codex plugin manifests',
@@ -2075,6 +2101,18 @@ async function selftest() {
       '[dry] npm run build:bundles',
       'packages/web-components/dist',
       'packages/web-modules/dist',
+      // gh#3946 (v0.8.60 cut hygiene, item 1) - bump.mjs and the changelog
+      // assembly step both write to these two paths but neither was in
+      // Step 5's allowlist, so the v0.8.60 cut's real Step 5.6 guard refused
+      // with "244 tracked file(s) modified by this cut are still unstaged"
+      // after all 36 gates had already passed. These markers prove the
+      // `git add` pathspec this --dry run prints actually names both
+      // entries. `changes/` is the directory form (root-caused at the
+      // v0.8.61 cut, see the matching entry's own comment above), never a
+      // glob: a glob that survives one non-fragment file (changes/README.md
+      // always does) hides every deleted fragment from `git add` silently.
+      'changes/',
+      'packages/web-modules/index.css',
       // gh#2473 — Step 5.6's unstaged-tracked-files guard must actually run
       // (as a no-op) on a clean --dry plan. Its real leftover-detection
       // logic is unit-tested directly above via unstagedTrackedLeftovers();

package/skills/package-release/scripts/stale-copy-warning.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// stale-copy-warning.mjs: generalizes release-pack.mjs's own STALE-COPY
+// WARNING (ticket #3943 item 2, gh#3764 line 55) into a small helper this
+// skill's own scripts can share.
+//
+// WHY
+//
+// A script reached through an installed plugin cache
+// (`~/.claude/plugins/cache/...`) only refreshes on a version bump, so
+// running it mid-cycle can execute a version that predates the repo's own
+// copy at the same relative path. This is invisible to a repo grep: the
+// grep reads the repo's own, already-corrected file, while the running
+// process reads the cache's stale one: the filer of ticket #3943 hit this
+// exact shape twice in one night (gh#3886, and the filing session itself).
+//
+// This module names ONE detector and ONE formatter, both pure, plus a thin
+// convenience wrapper a script calls once near its own entrypoint. It never
+// errors and never exits the caller's process: per the ticket's own
+// framing, this is a documented check, not a gate: the repo copy is
+// "almost certainly newer," never provably so from bytes alone, so the
+// right response is a loud, named warning, not a failure.
+//
+// PACKAGE-LOCAL BY DESIGN (ticket #3943's own check:pr-ready finding): this
+// file lives here, inside package-release/scripts/, rather than the repo's
+// top-level scripts/lib/, because this skill publishes as its own npm
+// package (`@adia-ai/adia-ui-forge`, PACKAGE_ROSTER). A script inside that
+// package importing a file OUTSIDE its own package root resolves fine in a
+// pnpm worktree but is an unresolvable specifier once packed
+// (`npm run check:packed-imports`, which caught exactly this on the first
+// draft of this change: an escaped-root import out of the tarball). Same
+// reasoning `bump.mjs`'s own inlined `isEntryPoint()` already states for
+// not importing `scripts/lib/is-entry-point.mjs`; this file follows that
+// same precedent (its own inlined entry-point check below, no cross-
+// package import) rather than introducing a second copy of the hazard.
+// A future repo-TOOLING script under the top-level `scripts/` tree (never
+// packaged into any tarball) that wants this same pattern is free to copy
+// this file's own two pure functions there; nothing here assumes only one
+// copy may ever exist, the packaging boundary is exactly why one shared
+// copy cannot serve both sides.
+//
+// USAGE (a script inside this same package, e.g. a sibling in
+// package-release/scripts/):
+//
+//   import { warnIfStaleCopy } from './stale-copy-warning.mjs';
+//   warnIfStaleCopy(import.meta.url, REPO_ROOT, 'path/relative/to/REPO_ROOT/this-script.mjs');
+//
+// SELFTEST:
+//
+//   node packages/plugins/adia-ui-forge/skills/package-release/scripts/stale-copy-warning.mjs selftest
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Pure: compares `selfPath`'s own bytes against the repo's copy at
+ * `repoRoot/relativePath`. Returns `null` when there is nothing to warn
+ * about (no repo copy exists to compare against, `selfPath` already IS the
+ * repo copy, or the bytes agree); otherwise `{ repoCopyPath, selfPath }`,
+ * both resolved absolute paths.
+ * @param {{selfPath: string, repoRoot: string, relativePath: string, readFile?: Function, fileExists?: Function}} args
+ * @returns {{repoCopyPath: string, selfPath: string} | null}
+ */
+export function detectStaleCopy({ selfPath, repoRoot, relativePath, readFile = fs.readFileSync, fileExists = fs.existsSync }) {
+  const resolvedSelf = path.resolve(selfPath);
+  const repoCopyPath = path.resolve(repoRoot, relativePath);
+  if (!fileExists(repoCopyPath)) return null; // nothing at the repo's own path to compare against
+  if (resolvedSelf === repoCopyPath) return null; // already running the repo's own copy
+  let selfText;
+  let repoText;
+  try {
+    selfText = readFile(selfPath, 'utf8');
+    repoText = readFile(repoCopyPath, 'utf8');
+  } catch {
+    return null; // unreadable on either side; nothing this check can prove
+  }
+  if (selfText === repoText) return null;
+  return { repoCopyPath, selfPath: resolvedSelf };
+}
+
+/**
+ * Pure: renders `detectStaleCopy`'s own non-null result as the printable
+ * warning block, the same shape release-pack.mjs's own inline check used.
+ * @param {{repoCopyPath: string, selfPath: string}} hit
+ * @returns {string}
+ */
+export function formatStaleCopyWarning({ repoCopyPath, selfPath }) {
+  return [
+    '',
+    `⚠  STALE-COPY WARNING: this ${path.basename(selfPath)} differs from the repo's own copy at`,
+    `   ${repoCopyPath}`,
+    "   The installed plugin cache lags the repo between cuts (ticket #3943, gh#3764 line 55);",
+    '   the repo copy is almost certainly newer, prefer running it:',
+    `     node ${repoCopyPath} <same args>`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Convenience wrapper for a script's own top-level self-check: resolves its
+ * own path from `import.meta.url`, compares it against
+ * `repoRoot/relativePath`, and logs (never throws, never exits the caller)
+ * when the two diverge. Call this once, near the top of a script's own
+ * entrypoint, before any real work.
+ * @param {string} selfUrl the caller's own `import.meta.url`
+ * @param {string} repoRoot the target repo's own root, resolved the same way the caller resolves it for everything else
+ * @param {string} relativePath this script's own path, relative to `repoRoot`
+ * @param {{log?: Function}} [opts]
+ * @returns {boolean} whether a warning was logged
+ */
+export function warnIfStaleCopy(selfUrl, repoRoot, relativePath, { log = console.error } = {}) {
+  const selfPath = fileURLToPath(selfUrl);
+  const hit = detectStaleCopy({ selfPath, repoRoot, relativePath });
+  if (hit) log(formatStaleCopyWarning(hit));
+  return hit !== null;
+}
+
+// ---- selftest -------------------------------------------------------------
+
+function selftest() {
+  let ran = 0;
+  const assert = (cond, msg) => {
+    ran += 1;
+    if (!cond) throw new Error(`selftest failed: ${msg}`);
+  };
+
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'stale-copy-warning-'));
+  try {
+    const repoRoot = path.join(sandbox, 'repo');
+    const relativePath = path.join('scripts', 'thing.mjs');
+    const repoCopyPath = path.join(repoRoot, relativePath);
+    const cachePath = path.join(sandbox, 'cache-copy.mjs');
+    fs.mkdirSync(path.dirname(repoCopyPath), { recursive: true });
+
+    // Positive control: cache bytes differ from the repo's own copy.
+    fs.writeFileSync(repoCopyPath, 'v2 (repo, newer)\n');
+    fs.writeFileSync(cachePath, 'v1 (cache, stale)\n');
+    const diverged = detectStaleCopy({ selfPath: cachePath, repoRoot, relativePath });
+    assert(diverged !== null, 'differing bytes must be detected');
+    assert(diverged.repoCopyPath === path.resolve(repoCopyPath), 'the hit names the resolved repo copy path');
+    const warning = formatStaleCopyWarning(diverged);
+    assert(warning.includes('STALE-COPY WARNING'), 'the formatted warning names itself');
+    assert(warning.includes(repoCopyPath), 'the formatted warning cites the repo copy path');
+
+    // Negative control: bytes agree.
+    fs.writeFileSync(cachePath, 'v2 (repo, newer)\n');
+    assert(
+      detectStaleCopy({ selfPath: cachePath, repoRoot, relativePath }) === null,
+      'identical bytes must never warn',
+    );
+
+    // Negative control: the "self" path already IS the repo's own copy
+    // (release-pack.mjs's own first guard: never warn about itself).
+    assert(
+      detectStaleCopy({ selfPath: repoCopyPath, repoRoot, relativePath }) === null,
+      'running the repo copy directly must never warn',
+    );
+
+    // Negative control: no repo copy exists at all (nothing to compare
+    // against, e.g. a script the repo has since deleted).
+    assert(
+      detectStaleCopy({ selfPath: cachePath, repoRoot, relativePath: path.join('scripts', 'gone.mjs') }) === null,
+      'a missing repo copy must never warn (nothing provable)',
+    );
+
+    // warnIfStaleCopy: the convenience wrapper logs on divergence and
+    // reports it, using a real file:// URL the way a real caller's
+    // import.meta.url would.
+    fs.writeFileSync(cachePath, 'v1 (cache, stale)\n');
+    let logged = '';
+    const warned = warnIfStaleCopy(
+      new URL(`file://${cachePath}`).href,
+      repoRoot,
+      relativePath,
+      { log: (msg) => { logged += msg; } },
+    );
+    assert(warned === true, 'warnIfStaleCopy reports true when it warns');
+    assert(logged.includes('STALE-COPY WARNING'), 'warnIfStaleCopy actually logs the warning text');
+
+    // And stays silent (never throws, never exits) when bytes agree.
+    fs.writeFileSync(cachePath, 'v2 (repo, newer)\n');
+    let loggedAgain = '';
+    const clean = warnIfStaleCopy(
+      new URL(`file://${cachePath}`).href,
+      repoRoot,
+      relativePath,
+      { log: (msg) => { loggedAgain += msg; } },
+    );
+    assert(clean === false, 'warnIfStaleCopy reports false when bytes agree');
+    assert(loggedAgain === '', 'warnIfStaleCopy logs nothing when bytes agree');
+  } finally {
+    fs.rmSync(sandbox, { recursive: true, force: true });
+  }
+
+  console.log(`stale-copy-warning selftest, all assertions passed, ${ran} controls ran`);
+  return 0;
+}
+
+// Realpath-safe entry-point check, inlined rather than imported from the
+// top-level scripts/lib/is-entry-point.mjs (see the package-local-by-design
+// note above); mirrors bump.mjs's own identical inlining in this same dir.
+function isEntryPoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  const topArgv = process.argv.slice(2);
+  process.exit(topArgv[0] === 'selftest' ? selftest() : 0);
+}

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

@@ -15,6 +15,7 @@
 import { execSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+import { warnIfStaleCopy } from './stale-copy-warning.mjs';
 import { PACKAGE_ROSTER } from './package-paths.mjs';
 
 // The roster is single-sourced in package-paths.mjs (H3) — the `adia-ui-*-v*`
@@ -60,6 +61,13 @@ function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to run git against a non-monorepo directory.
   assertMonorepoRoot(args.repo);
+  // Stale-plugin-cache self-check (ticket #3943 item 2), same primitive
+  // release-pack.mjs's own top-level check now calls.
+  warnIfStaleCopy(
+    import.meta.url,
+    args.repo,
+    'packages/plugins/adia-ui-forge/skills/package-release/scripts/tag-lockstep.mjs',
+  );
   const tags = buildTagList(args.version);
 
   if (args.deleteMode) {

package/skills/primitive-authoring/references/INDEX.md

@@ -30,6 +30,7 @@ file, including the depth references those entries cross-link.
 ## Demos & doc surfaces
 
 - [composite-demo-protocol.md](composite-demo-protocol.md) — what discipline governs any `packages/web-modules/**` demo edit, beyond what the `Pattern source:` gate can see?
+- [examples-structure.md](examples-structure.md): what order do a primitive's own `<name>.examples.html` `<h2 variant="section">` blocks follow, and where does `Typography registers` sit relative to `Edge Cases` and the generated API tail?
 - [canonical-pattern-index.md](canonical-pattern-index.md) — which canonical `.contents.html` files should I survey for a given UI type? Auto-generated; regenerate via `scripts/build-canonical-pattern-index.mjs`.
 - [trait-pages.md](trait-pages.md) — which sections, in which order, must a `site/pages/traits/<name>/` detail page carry (ADR-0019 template)?
 

package/skills/primitive-authoring/references/examples-structure.md

@@ -0,0 +1,52 @@
+# `<name>.examples.html` section order convention
+
+Every primitive's own `packages/web-components/components/<name>/<name>.examples.html`
+follows one binding `<h2 variant="section">` order. gh#4159: a merged-registers sweep
+(gh#3843) found the order inconsistent across five files, `alert` had "Typography
+registers" near the top, `code`/`command` had it after the generated API tail, and
+`accordion`/`divider` had it before Edge Cases, with no reference doc anywhere stating
+which shape was correct. `site-docs-authoring`'s own `intent.md` explicitly declines
+`packages/web-components/components/*/*.examples.html` and hands it here; this file is
+that hand-off's landing spot.
+
+## Required order
+
+1. **Variant/usage sections**, one `<h2 variant="section">` per prop value, state, or
+   usage recipe the component demonstrates (`inline`, `block with language`, `grouped`,
+   …). Author-ordered; no fixed sequence among these.
+2. **`Combinations`**, sections composed together in context.
+3. **`Typography registers`**, the three-register (`scale="ui-sm"` / regular /
+   `scale="content-md"`) showcase, when the component carries one. Hand-authored, so it
+   sits with the other hand-authored sections above, immediately after `Combinations`
+   and before `Edge Cases`, never after the generated API tail.
+4. **`Edge Cases`**, boundary conditions and unusual content.
+5. **Generated API sections**, in order: `Properties`, `Events`, `Methods` (when
+   applicable), `CSS Tokens`, `Slots`, `A2UI`, `Related`.
+
+Rationale for `Typography registers` landing before `Edge Cases` rather than after the
+API tail: it is hand-authored prose+markup like `Combinations`/`Edge Cases`, not a
+generated table like `Properties`/`Events`/`CSS Tokens`; grouping it with the other
+hand-authored sections keeps the generated-vs-authored boundary at one place in the file
+instead of two.
+
+## Why this also matters for `.examples.md`
+
+`scripts/build/generate-examples-md.mjs` derives each `<name>.examples.md` from the
+`.examples.html` source. Its main loop picks only the first `MAX_FRAGMENTS` (3)
+`data-section` blocks in document order, so a section sitting far down the file (several
+variant sections deep, as most shipped components run) would normally never be selected.
+`Typography registers` is the one named exception: `processComponent()` guarantees its
+inclusion regardless of ordinal position, so this convention is about authoring
+coherence and readability, not about whether the section survives derivation at all.
+
+## Enforcement
+
+`generate-examples-md.mjs`'s own `checkSectionOrder()`, run as part of `npm run
+check:examples-md-fresh` (`--verify` mode) and the plain generate run alike, parses
+every `packages/web-components/components/*/*.examples.html`'s ordered `<h2
+variant="section">` list and reds, naming the file and both indices, when `Typography
+registers` sits after `Edge Cases`. Pre-existing violations outside a given PR's own
+lane are grandfathered via `scripts/build/examples-registers-order-baseline.json` (a
+ratchet: printed as an advisory finding, never silently dropped, and never allowed to
+grow) so the gate never regresses unrelated work; shrink that list to zero as each
+file's own section order gets fixed.

package/skills/primitive-authoring/references/shell-patterns.md

@@ -448,17 +448,18 @@ Consumers (CodeMirror layout, canvas redraw, dependent UI) listen on the shell o
 
 ### admin cluster (canonical reference)
 
-**[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-header`/
-`admin-page-body` are retired deprecate-then-delete; `admin-scroll` is
-renamed wholesale to `page-scroll`. `page-ui[band]` + `page-scroll` are
-now the canonical page-chrome pair — this cluster still describes
-`admin-shell`'s pre-migration internal composition, valid during the
-deprecation window.
-
-- **3 JS-bearing children** — `<admin-shell>` (host coordinator), `<admin-sidebar>` (resize+collapse+persist), `<admin-command>` (Cmd+K palette)
-- **7 CSS-only structural children** — `<admin-content>`, `<admin-topbar>`, `<admin-statusbar>`, `<admin-scroll>`, `<admin-page>`, `<admin-page-header>`, `<admin-page-body>`
-- **CSS bridge** — `packages/web-modules/shell/admin-shell/css/admin-shell.bespoke.css` (~240 LOC)
-- **Tests** — `admin-sidebar.test.js` 10/10, `admin-command.test.js` 9/9
+**[deprecated 2026-09-01, ADR-0098]** The inline child enumeration this section
+used to carry is retired. `admin-page`/`admin-page-header`/`admin-page-body`
+were deleted outright (no compat alias); `admin-scroll` was renamed wholesale
+to `page-scroll`, and its own one-release deprecation window has since closed,
+the module deleted (gh#3745). `page-ui[band]` + `page-scroll` are the canonical
+page-chrome pair.
+
+For `admin-shell`'s own live composition, the current bespoke children (the
+`@scope`-per-tag CSS convention landed in gh#4103), and the full 13-part
+canonical anatomy, see
+[admin-shell-anatomy.md](../../demo-audit/references/admin-shell-anatomy.md),
+kept in sync with `site/index.html`'s live example rather than restated here.
 
 ### chat cluster (replicated pattern)