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

package/skills/adia-ui-ops/references/teach-protocol.md

@@ -0,0 +1,215 @@
+# Reference: Teach Protocol — Absorbing new knowledge into the adia-ui-ops skill
+
+**Authored:** 2026-05-22 (Phase 4 of skills-rollup-roadmap; instantiation N=5 of the extensibility pattern).
+**Why authored:** As the AdiaUI substrate accumulates new audit patterns, doc-type conventions, deploy quirks, and recipe workflows, each absorption was previously a one-off improvisation. This protocol gives every future "make sure `adia-ui-ops` knows about [pattern]" request a deterministic landing path.
+
+**Ecosystem context:** This reference is the 5th instantiation of the extensibility pattern documented in the family's `VISION-extensibility` memo. The vision separates universal components (the trigger cluster, the 7 anti-patterns, the 5-step landing procedure, the citation-vs-knowledge principle, the negative case) from skill-specific components (the decision tree's branches, the worked examples). When editing this file, preserve the universal sections verbatim where possible. The canonical N=1 instance is the `adia-ui-kit` skill's `references/teach-protocol.md`; this file is N=5.
+
+**Used by:** the `adia-ui-ops` skill, when an agent receives one of these triggers:
+
+- "make sure `adia-ui-ops` knows about [the new audit pattern / doc-type / deploy step]"
+- "train `adia-ui-ops` on [the new exe.dev quirk / lockfile drift class / staleness signal]"
+- "the skill should know about [the post-§N pattern]"
+- "absorb this lesson into adia-ui-ops"
+- "teach the skill about [the new doc-type convention]"
+
+**Companion:** `references/audit-cadence.md` (the 3-phase invocation contract that every audit-class landing must satisfy), `references/deploy-playbooks.md` (when the new knowledge is exe.dev-level), and `scripts/audit-ops-roster.mjs` (run after any §Teach landing).
+
+**Anti-companion:** `docs/journal/YYYY/MM/<date>.md` (arc-specific stories belong in the journal, not the skill — see decision tree Branch G).
+
+---
+
+## When to Use
+
+Trigger phrases (from the §Teach section in SKILL.md):
+
+- "make sure `adia-ui-ops` knows about X"
+- "train the skill on X"
+- "teach the skill about Y"
+- "the skill should be aware of Z"
+- "absorb [pattern/lesson/feedback] into adia-ui-ops"
+- "update the skill to reflect [the new audit pattern / the new doc-type / the new playbook step]"
+
+The phrases are universal across all extensible skills; the **landing target** is what's specific to this skill.
+
+## Core Principles
+
+### 1. The skill is a CITATION layer, not a KNOWLEDGE layer
+
+Per-pattern facts live in `references/audit-patterns/<name>.md`. Per-doc-type conventions live in `references/doc-types/<type>.md`. Per-host deploy quirks live in `references/deploy-playbooks.md`. The skill cites by path; it does NOT duplicate the rule body in SKILL.md prose.
+
+**Rule of thumb:** if you catch yourself writing "the orphan-detection audit checks X" in SKILL.md, stop. Is that fact in `references/audit-patterns/orphan-detection.md` already? If yes, cite the path. If no, the fact should land in the reference file first, THEN SKILL.md cites it via §ColdStartTriage table.
+
+### 2. Trigger surface is universal; landing targets are skill-specific
+
+The activation phrases — "train X on Y", "make sure X knows about Z", "absorb this into X" — are the same regardless of which skill X is. The **landing targets** vary per this skill's references/ topology (`audit-patterns/`, `doc-types/`, `recipes/`, `guidance/`, `standards/`, `deploy-playbooks.md`).
+
+### 3. The negative case (Branch G) is load-bearing
+
+Arc-specific stories ("how I diagnosed the 2026-05-19 ui-kit.exe.xyz outage") belong in `docs/journal/`, not in the skill. The skill is procedural knowledge that will be true tomorrow; arc stories are history that's already finished. Skip the §Teach landing entirely when the lesson is one-off.
+
+### 4. Preserve subdirectory taxonomy
+
+ops-repo's references/ taxonomy (`audit-patterns/` vs `doc-types/` vs `recipes/` vs `guidance/` vs `standards/`) was preserved verbatim during the v1.0.0 absorption because it's well-organized. New knowledge should fit one of these buckets; only invent a new top-level subdirectory when no existing one fits and you have ≥3 sibling files to seed it.
+
+---
+
+## The 7-branch decision tree
+
+Match the incoming knowledge to one of the seven branches. Most lands in `references/`; one lands inline in SKILL.md; one lands OUT of the skill entirely.
+
+### Branch A — New audit pattern → `references/audit-patterns/<name>.md`
+
+**When:** A new class of repo-state drift, staleness signal, or hygiene check that isn't covered by the 16 existing patterns.
+
+**Examples:**
+- "Audits should catch yaml description-length drift" → `audit-patterns/yaml-description-length.md`
+- "We need a check for components missing `.examples.html`" → `audit-patterns/missing-examples-page.md`
+
+**Landing procedure:**
+1. Author the pattern file with sections: Trigger / What it catches / Detection script / Apply-mode fix / Trip-wire CI gate / Cross-references.
+2. Add a row to `references/audit-cadence.md` §Route table (with the Promise number(s) it satisfies).
+3. Add a row to `references/audit-cadence.md` §Audit categories table.
+4. If the pattern needs a script, add it to `scripts/` of this skill or `scripts/skills/` (ecosystem-wide).
+5. Add a trigger keyword to SKILL.md frontmatter `trigger:` cluster.
+
+### Branch B — New doc-type convention → `references/doc-types/<type>.md`
+
+**When:** The substrate adopts a new canonical doc shape (ADR template variant, postmortem section, new runbook format, etc.).
+
+**Examples:**
+- "ADRs now require a `Trade-offs Considered:` section" → patch `doc-types/adr-pattern.md`
+- "We're adopting `INVESTIGATION.md` for cross-incident analysis" → new `doc-types/investigation-md.md`
+
+**Landing procedure:**
+1. Author or patch the doc-type file with sections: Purpose / Required fields / Optional fields / Example skeleton / Tooling support / Cross-references.
+2. If new doc-type, add a row to `references/audit-cadence.md` §Route table.
+3. If the convention is codified in an ADR, link the ADR.
+
+### Branch C — New recipe / multi-step workflow → `references/recipes/<name>.md`
+
+**When:** A reproducible multi-step procedure (provisioning, cold-start harvest, two-agent fix pattern, etc.) that isn't a single audit or deploy step.
+
+**Examples:**
+- "Document the 'migrate `docs/` to `.brain/`' procedure" → new `recipes/migrate-to-brain.md`
+- "The 'recommend-then-validate' pattern needs a written-down version" → already in `recipes/recommend-then-validate.md`
+
+**Landing procedure:**
+1. Author the recipe with sections: When to use / Prerequisites / Step-by-step (numbered with exact commands) / Verification / Common pitfalls / Cross-references.
+2. Add a row to `references/audit-cadence.md` §Route table.
+
+### Branch D — New deploy playbook step → patch `references/deploy-playbooks.md`
+
+**When:** exe.dev platform quirk, new VM state to handle, new service archetype, secret-rotation variant.
+
+**Examples:**
+- "Caddy v3 changed the reload behavior" → patch `deploy-playbooks.md` §Playbook-deploy + §Common failures
+- "New service `chat-ui.exe.xyz` came online" → patch §Current deployments
+
+**Landing procedure:**
+1. Patch the relevant §Playbook section (don't author a new file unless the procedure is entirely new).
+2. Update §Current deployments if a new host is on the matrix.
+3. Update §Common failures if a new symptom→cause→fix triple is known.
+
+### Branch E — New invariant / posture → inline SKILL.md §Posture or §FirstPrinciples
+
+**When:** A cross-cutting rule that affects how the skill is invoked (not a per-pattern fact).
+
+**Examples:**
+- "Apply-mode is the default; analysis-only is opt-in" → already inline as §Posture bullet
+- "AGENTS.md ceiling is now 250 lines" → patch SKILL.md §FirstPrinciples (and `audit-cadence.md` §Verification)
+
+**Landing procedure:**
+1. Inline patch to SKILL.md §Posture (small) or §FirstPrinciples (large).
+2. Add the corresponding trip-wire to `audit-cadence.md` §Verification.
+
+### Branch F — New guidance / cross-cut → `references/guidance/<name>.md`
+
+**When:** Doc-writing advice, context-budget heuristics, reliability-dial tuning, prose-vs-code authorial guidance.
+
+**Examples:**
+- "How to write good ADR titles" → patch `guidance/llm-doc-writing.md`
+- "Reliability dial settings for a SOC2-bound repo" → patch `guidance/reliability-dial.md`
+
+**Landing procedure:**
+1. Patch the relevant guidance file.
+2. Cross-reference from `audit-cadence.md` §Route if it's user-facing advice.
+
+### Branch G (NEGATIVE) — Arc-specific story → `docs/journal/YYYY/MM/<date>.md`
+
+**When:** A one-off audit-arc story, a specific incident postmortem, "how I fixed the ui-kit.exe.xyz outage on 2026-05-19" — anything tied to a specific moment in time.
+
+**Examples:**
+- "Yesterday's audit caught 47 broken links" → journal §N, not skill
+- "How we recovered from the §76 git-add-A absorption trap" → journal + Hermes skill, not adia-ui-ops
+
+**Landing procedure:**
+1. Write the journal §N entry. Done — do NOT modify the skill.
+2. If the arc surfaces a *durable* pattern, follow up with a Branch A landing AFTER the journal entry.
+
+**Why this matters:** the skill is what's true tomorrow. Arc stories age out; patterns persist. Conflating them bloats the skill with stale prose.
+
+---
+
+## The 5-step landing procedure (universal)
+
+Regardless of which branch matches, follow these 5 steps:
+
+1. **Classify the branch** — pick A-G from the tree above. If two could fit, pick the more specific (Branch A over Branch E for an audit-specific thing).
+2. **Author the content** — write the reference file or inline patch. Use existing siblings as templates for shape.
+3. **Wire the citations** — add the row to `audit-cadence.md` §Route + §Audit categories (if A); add trigger keyword to SKILL.md frontmatter; cross-link from sibling references where relevant.
+4. **Run the gates** — `node .agents/skills/adia-ui-ops/scripts/audit-ops-roster.mjs` must pass 4 axes; `node scripts/skills/audit-skill-hygiene.mjs` 0 findings; `node scripts/check-links.mjs` on staged files clean.
+5. **Bump version + CHANGELOG** — PATCH for content additions; MINOR for new branches or new top-level subdirectories; document the landing in CHANGELOG.md with branch letter.
+
+## 7 anti-patterns (the negative space)
+
+Things to NOT do during §Teach landings:
+
+1. **Don't duplicate audit-pattern body into SKILL.md.** The skill cites by path; the body lives in `audit-patterns/<name>.md`. Inline prose in SKILL.md bloats cold-start and creates two-places-to-update drift.
+2. **Don't author a "miscellaneous patterns" reference file.** If a pattern doesn't fit `audit-patterns/`, `doc-types/`, `recipes/`, `guidance/`, or `standards/`, the classification is wrong — re-read the tree.
+3. **Don't add to `audit-cadence.md` §Route without a destination file.** Every row must point at a real file. Future-promise rows ("coming soon") are zombie entries.
+4. **Don't author new top-level subdirectories under references/ for single-file additions.** Six top-level dirs are enough; seed a new one only when you have ≥3 sibling files.
+5. **Don't conflate ops with release.** Cutting versions, tagging, npm publish → `adia-ui-release`. Deploying built artifacts to VMs → `adia-ui-ops` mode 1. The hand-off boundary is the build artifact.
+6. **Don't conflate ops with authoring.** Audit work is curatorial (find drift, propose fixes); authoring work is generative (write new ADRs, new RFCs). When in doubt, separate the cycle.
+7. **Don't skip the §Teach trigger keyword in frontmatter.** New landing branches need the trigger keyword wired so future activations work.
+
+## Worked examples (calibration)
+
+### Example 1 — "Make sure adia-ui-ops knows about the EXE deploy CI gate"
+
+**Branch:** D (deploy playbook step) — patch `deploy-playbooks.md` §Playbook-deploy with the new CI gate command, and patch §Common failures with the gate's failure modes. Add `EXE deploy CI gate` to SKILL.md frontmatter trigger cluster. CHANGELOG entry "Branch D landing — EXE deploy CI gate awareness".
+
+### Example 2 — "Train adia-ui-ops on the new audit-history-ledger semantic"
+
+**Branch:** A (audit pattern) — `audit-patterns/audit-history-ledger.md` exists already; patch it. Update `audit-cadence.md` §Route + §Audit categories rows if the semantic changed. CHANGELOG entry "Branch A landing — audit-history-ledger v2 semantic".
+
+### Example 3 — "Absorb the recommend-then-validate two-agent pattern"
+
+**Branch:** C (recipe) — `recipes/recommend-then-validate.md` exists already. If the pattern evolves, patch the recipe and cross-link any peer skill. CHANGELOG entry "Branch C landing — recommend-then-validate v2".
+
+### Example 4 — "Teach the skill that ADRs now require a Trade-offs section"
+
+**Branch:** B (doc-type) — patch `doc-types/adr-pattern.md` Required fields. If the convention is codified in an ADR (e.g., ADR-0035), link it. CHANGELOG entry "Branch B landing — adr-pattern Required-fields update".
+
+### Example 5 — "The skill should know the chat-ui repo's AGENTS.md ceiling moved to 300 lines"
+
+**Branch:** E (invariant) — patch SKILL.md §FirstPrinciples + `audit-cadence.md` §Verification (Token-optimized row). CHANGELOG entry "Branch E landing — AGENTS.md ceiling 200→300 for chat-ui scope".
+
+### Example 6 — "Document the cold-start harvest workflow"
+
+**Branch:** C (recipe) — `recipes/cold-start-harvest.md` exists already. If the workflow has new steps (e.g., now uses `audit-skill-hygiene.mjs`), patch the recipe. CHANGELOG entry "Branch C landing — cold-start-harvest v2 with audit-skill-hygiene step".
+
+### Example 7 (NEGATIVE) — "How I recovered from the 2026-05-22 §76 git-add-A absorption trap"
+
+**Branch:** G (negative) — `docs/journal/2026/05/2026-05-22.md` §N. Do NOT modify adia-ui-ops. The Hermes skill `multi-agent-git-staging-discipline` already captures the procedural lesson at the right home. No CHANGELOG entry on adia-ui-ops.
+
+---
+
+## Cross-references
+
+- The family's `VISION-extensibility` memo — the universal pattern this file instantiates.
+- The `adia-ui-kit` skill's `references/teach-protocol.md` is the canonical N=1 instance.
+- Sibling forge skills with the same §Teach binding: [`adia-ui-release`](../../adia-ui-release/references/teach-protocol.md) (N=2), [`adia-ui-authoring`](../../adia-ui-authoring/references/teach-protocol.md) (N=3), [`adia-ui-a2ui`](../../adia-ui-a2ui/references/teach-protocol.md) (N=4). This is N=5.
+- `references/audit-cadence.md` — the 3-phase contract every audit-class landing must satisfy
+- `references/deploy-playbooks.md` — the destination for Branch D landings
+- `scripts/audit-ops-roster.mjs` — run after every §Teach landing

package/skills/adia-ui-ops/scripts/audit-ops-roster.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// audit-ops-roster.mjs — §SelfAudit enforcement for adia-ui-ops.
+// Axes 1–8 via the forge plugin's shared audit-axes.mjs (bin/lib/);
+// Axis 9 = absorbed-skill roster currency.
+//
+// SoT: packages/plugins/adia-ui-forge/skills/adia-ui-ops/scripts/ (ADR-0040);
+// the .agents/skills/adia-ui-ops path is a symlink into the plugin.
+//
+// Usage (from monorepo root):
+//   node "${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-ops/scripts/audit-ops-roster.mjs"
+//   …--json    (machine-readable)
+//   …--strict  (non-zero exit on drift)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  runUniversalAxes,
+  formatResults,
+} from '../../../bin/lib/audit-axes.mjs';
+
+const REPO = process.cwd();
+const SKILL_DIR = path.join(REPO, '.agents/skills/adia-ui-ops');
+const SKILL_MD = path.join(SKILL_DIR, 'SKILL.md');
+const SKILL_JSON = path.join(SKILL_DIR, 'skill.json');
+const SKILLS_ROOT = path.join(REPO, '.agents/skills');
+
+// [name, expected-redirect-path or null if already-gone]
+const ABSORBED = [
+  ['exe-dev-ops',      '.agents/skills/exe-dev-ops/SKILL.md'],
+  ['ops-repo',         '.agents/skills/ops-repo/SKILL.md'],
+  ['github-release',   null],
+  ['lockstep-release', null],
+  ['stale-audit',      null],
+];
+
+const CLEAN_STATUSES = ['absorbed-clean', 'absorbed-clean-deleted', 'redirect-ok'];
+
+function parseArgs(argv) {
+  return { json: argv.includes('--json'), strict: argv.includes('--strict') };
+}
+
+function axis9_opsRosterCurrency() {
+  const findings = [];
+  for (const [name, redirectPath] of ABSORBED) {
+    if (redirectPath === null) {
+      const dir = path.join(SKILLS_ROOT, name);
+      if (fs.existsSync(dir)) {
+        findings.push({ type: 'unexpected-directory', message: `${name}/ exists but was claimed absorbed-and-gone`, name });
+      } else {
+        findings.push({ type: 'absorbed-clean', message: `${name}: no directory — correct`, name });
+      }
+    } else {
+      const full = path.join(REPO, redirectPath);
+      if (!fs.existsSync(full)) {
+        const dir = path.dirname(full);
+        findings.push({
+          type: fs.existsSync(dir) ? 'redirect-missing' : 'absorbed-clean-deleted',
+          message: fs.existsSync(dir)
+            ? `${name}: expected redirect at ${redirectPath} — not found`
+            : `${name}: fully deleted post-soak`,
+          name,
+        });
+      } else {
+        const txt = fs.readFileSync(full, 'utf8');
+        findings.push(
+          /status:\s*redirect/m.test(txt)
+            ? { type: 'redirect-ok', message: `${name}: redirect ok`, name }
+            : { type: 'redirect-not-tagged', message: `${name}: ${redirectPath} lacks 'status: redirect'`, name }
+        );
+      }
+    }
+  }
+  const driftCount = findings.filter(f => !CLEAN_STATUSES.includes(f.type)).length;
+  return {
+    axis: 'opsRosterCurrency',
+    axis_num: 9,
+    status: driftCount > 0 ? 'drift' : 'ok',
+    findings,
+    summary: driftCount > 0 ? `${driftCount} absorbed-skill issue(s)` : 'all absorbed-skill entries clean',
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const ctx = { skillDir: SKILL_DIR, skillMd: SKILL_MD, skillJson: SKILL_JSON, repoRoot: REPO };
+  const { results: universal } = runUniversalAxes(ctx);
+  const axis9 = axis9_opsRosterCurrency();
+  const allResults = [...universal, axis9];
+  const driftCount = allResults.filter(r => r.status === 'drift').length;
+
+  if (args.json) {
+    console.log(JSON.stringify({ results: allResults, driftCount }, null, 2));
+    if (args.strict && driftCount > 0) process.exit(1);
+    return;
+  }
+
+  console.log(`[audit-ops-roster] adia-ui-ops §SelfAudit — ${driftCount} drifting axis/axes`);
+  console.log(formatResults(allResults));
+  if (driftCount === 0) console.log('\n✓ All clean.');
+  if (args.strict && driftCount > 0) process.exit(1);
+}
+
+main();

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

@@ -0,0 +1,65 @@
+{
+  "name": "adia-ui-ops",
+  "version": "1.2.4",
+  "description": "Operator skill for the AdiaUI substrate — exe.dev VM deployment + service ops AND repo memory-layer audit + curation. Use whenever the user wants to DEPLOY TO EXE.DEV / DIAGNOSE A *.exe.xyz HOST / ROTATE KEYS / PROVISION A NEW VM / AUDIT THE REPO BRAIN / SWEEP STALE CONTENT IN .brain/ / SET UP AGENTS.md / HARVEST MEMORY ENTRIES / RUN DOCS-CURRENCY AUDIT. Triggers on \"deploy to ui-kit.exe.xyz\", \"rotate SSH keys on exe.dev\", \"port 8000 unbound\", \"provision a new VM at <host>.exe.xyz\", \"set up AGENTS.md\", \"audit the .brain folder\", \"harvest a memory entry\", \"exe.dev deploy workflow\", \"memory layer needs a dedup pass\", \"run the docs-currency audit\", \"audit our docs\". Does NOT trigger for: bare \"deploy this\" without exe.dev context, cutting releases (use adia-ui-release), authoring code (use adia-ui-authoring). Absorbs exe-dev-ops + ops-repo + github-release + lockstep-release + stale-audit.",
+  "status": "stable",
+  "authors": ["kim.granlund@gmail.com"],
+  "codeowners": [],
+  "tags": ["adiaui", "ops", "infrastructure", "exe.dev", "deployment", "vm-service", "repo-brain", "memory-layer", "audit", "stale-audit", "AGENTS.md", "ADR", "postmortem", "runbook", "doc-curation", "harness-discipline"],
+  "depends_on": [],
+  "peer_skills": ["adia-ui-kit", "adia-ui-authoring", "adia-ui-release", "adia-ui-a2ui", "dogfood-sweep"],
+  "files": [
+    "SKILL.md",
+    "CHANGELOG.md",
+    "skill.json",
+    "references/INDEX.md",
+    "references/audit-cadence.md",
+    "references/deploy-playbooks.md",
+    "references/teach-protocol.md",
+    "references/audit-patterns/archive-link-sweep.md",
+    "references/audit-patterns/audit-history-ledger.md",
+    "references/audit-patterns/browser-bundle-node-imports.md",
+    "references/audit-patterns/changelog-unreleased-bloat.md",
+    "references/audit-patterns/coverage-gaps.md",
+    "references/audit-patterns/entry-file-coverage.md",
+    "references/audit-patterns/format-hygiene.md",
+    "references/audit-patterns/lockstep-versioning.md",
+    "references/audit-patterns/memory-fragmentation.md",
+    "references/audit-patterns/orphan-detection.md",
+    "references/audit-patterns/pointer-validation.md",
+    "references/audit-patterns/redundancy-detection.md",
+    "references/audit-patterns/spec-dating-sweep.md",
+    "references/audit-patterns/stale-content.md",
+    "references/audit-patterns/staleness-tooling.md",
+    "references/audit-patterns/token-waste-detection.md",
+    "references/doc-types/adr-pattern.md",
+    "references/doc-types/architecture-md.md",
+    "references/doc-types/changelog.md",
+    "references/doc-types/decisions-log.md",
+    "references/doc-types/plan-roadmap.md",
+    "references/doc-types/postmortem-pattern.md",
+    "references/genres/prose-and-writing.md",
+    "references/guidance/context-budget.md",
+    "references/guidance/llm-doc-writing.md",
+    "references/guidance/reliability-dial.md",
+    "references/recipes/adr-introduction.md",
+    "references/recipes/audit-existing-repo.md",
+    "references/recipes/cold-start-harvest.md",
+    "references/recipes/concurrent-learnings-merge.md",
+    "references/recipes/continuous-learning-loop.md",
+    "references/recipes/external-reference-verification.md",
+    "references/recipes/findings-index-readout.md",
+    "references/recipes/greenfield-setup.md",
+    "references/recipes/harvest-repo-brain.md",
+    "references/recipes/import-repo-brain-harvest.md",
+    "references/recipes/memory-organization.md",
+    "references/recipes/recommend-then-validate.md",
+    "references/recipes/self-healing-hooks.md",
+    "references/recipes/skill-stewardship-loop.md",
+    "references/standards/agents-md-spec.md",
+    "references/standards/claude-md-convention.md",
+    "references/standards/cross-tool-matrix.md",
+    "references/standards/readme-conventions.md",
+    "scripts/audit-ops-roster.mjs"
+  ]
+}

package/skills/adia-ui-release/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog — `adia-ui-release` skill
 
+## [0.2.2] — 2026-06-10
+
+### Fixed
+- **`make-ledger.mjs` no longer ships placeholders.** Auto-fill `repoSlug` from `git remote get-url origin` (was the literal `<org>/<repo>` — CodeRabbit-flagged on the v0.7.17 ledger); dropped the angle-bracket placeholder in the `dispatched` default; warn on real-write when TODO fields (`verification` / `notes` / `dispatched`) would ship. Substrate fix (branch A of the §Teach tree); root-cause fix for the nit point-patched in the v0.7.17 ledger (gen-ui-kit #102).
+
+## [0.2.1] — 2026-06-08
+
+**Two release-tooling fixes that bit the v0.7.14 lockstep cut.** Both are substrate fixes to the bundled scripts (branch A of the §Teach decision tree); no mode/capability change.
+
+### Fixed
+
+- **Package name-vs-path-form inconsistency in the standalone CHANGELOG helpers.** 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). `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/`) — it failed for all 6 a2ui packages at the v0.7.14 cut. **Both helpers now accept BOTH forms** via a new shared `scripts/package-paths.mjs` (`resolvePackageChangelog` / `resolvePackageDir`): try `packages/<arg>` first (path form, backward-compatible), and when that directory is absent fall back to `packages/a2ui/<x>` for an `a2ui-<x>` arg. Verified: name-form `a2ui-corpus` and path-form `a2ui/corpus` now resolve identically; non-a2ui packages unchanged; unknown packages still give a legible not-found.
+- **Batch tag-push triggered ZERO publish workflows.** Pushing all 10 tags in one `git push origin <10 tags>` fires a single `create` event for the whole ref-set, which GitHub Actions routinely drops — so no `publish-<pkg>.yml` ran at the v0.7.14 cut (recovered by hand via `gh workflow run`). **`release-pack.mjs` Step 8 now pushes per-package tags one-at-a-time** (umbrella last), and **Step 9 runs `dispatch-publish.mjs --verify-triggered`** — a new mode that checks whether each `publish-<pkg>.yml` already ran for its `<pkg>-vX.Y.Z` tag and re-dispatches ONLY the misses (idempotent; safe after a partial trigger; `--dry` previews without calling `gh`). The `tag-lockstep.mjs` push hint now prints the per-tag loop + the verify-triggered recovery command instead of the batch push.
+
+### Added
+
+- **`scripts/package-paths.mjs`** (new) — shared name↔path-form package resolution for the CHANGELOG helpers. Pure Node, stdlib only.
+- **`references/recovery-paths.md` §Scenario 7 — "Tags pushed but ZERO publish workflows triggered (the batch-tag-push skip)"** — shape, root cause (the GitHub batched-create-event drop), the v0.7.14 canonical case, the `--verify-triggered` recovery, the per-tag-push prevention, and the ledger fragment. Added to the §Decision flowchart; scenario count 6 → 7.
+
+### Wiring
+
+- `skill.json` — `version` 0.2.0 → 0.2.1 (PATCH — bug fixes); `scripts/package-paths.mjs` added to `files`.
+- `SKILL.md` frontmatter `version` 0.2.0 → 0.2.1 (lockstep with `skill.json`); `package-paths.mjs` added to §FileMap.
+
+## [0.2.0] — 2026-06-07
+
+**New capability — the two release CLASSES (class-A lockstep cut + class-B independent-package release).** Folds in the "two release classes" training (ADR-0040 Phase 1b), adapted to forge's portable voice. The skill now distinguishes the **class-A lockstep cut** (the whole set bumps together — modes 1–4) from a **class-B independent-package release** (a package versioned independently of the lockstep set, excluded from the lockstep gate, no umbrella tag, no demo-site deploy — new **mode 12**). The @adia-ai monorepo's `packages/plugins/*` plugins (`adia-ui-factory` / `adia-ui-forge`) are the clearly-labeled worked example throughout; the framing stays portable (an independently-versioned package *outside* the lockstep).
+
+### Added
+
+- **`references/independent-package-release.md`** (new) — the class-B procedure: the two-class comparison table, the three new-package onboarding trip-wires (lockfile · release-trip-wire package registry · CHANGELOG bracket form — all **substrate** fixes, branch A of the §Teach decision tree), the step-by-step cut, the verify-against-npm target, and the marketplace cut-over. `@adia-ai` specifics labeled as the worked example; no hard `@adia-ai`-only / absolute-path / `.brain`-runtime assumptions in executable content.
+- **SKILL.md** — **mode 12 (Independent-package release)** in the mode menu + the §Where-are-you-starting-from table; a §IndependentPackageRelease section mirroring §MigrationGuideAuthoring (the class-A vs class-B split + the three trip-wires + marketplace cut-over, with the plugins as the worked example); a class-A/class-B framing note atop §ReleaseInvariants; the mode-12 real-product verify-target row in the §PEV table (verify each package's **independent** version on the npm registry — NOT "all 9 + demo site"); §Recon classification step 10 + the mode-12 classify bullet; the `independent-package-release.md` destination added to the §Teach decision-tree branch list and to §FileMap.
+
+### Coordination notes carried in (portable voice)
+
+- **PR-merge gate** — land the package(s) on `main` via PR; resolve **every** review thread before an admin merge (an admin merge over unresolved threads is the failure this guards against).
+- **Push tags from a clean worktree** — if the shared working tree is on a peer's branch, push the per-package tags from a throwaway worktree on `origin/main`.
+
+### Wiring
+
+- `skill.json` — `version` 0.1.0 → 0.2.0 (MINOR — new capability); `independent-package-release.md` added to `files`; `description` extended with the independent-package / plugin trigger surface.
+- SKILL.md frontmatter `version` 0.1.0 → 0.2.0 (kept in lockstep with `skill.json`).
+
 ## [0.1.0] stable — 2026-06-03
 
 **Initial cut in the `adia-ui-forge` plugin.** Faithful, de-repo'd, self-contained port of the @adia-ai monorepo's maintainer `adia-ui-release` skill, with the former `adia-ui-migration` skill folded in as the producer-side migration-guide-authoring section. Preserves the release-engineering depth (the gate roster, recovery paths, peer-in-flight discipline, ledger schema, notes craft) — this is a port, not a rewrite.

package/skills/adia-ui-release/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   registry + production endpoint + GH release), not self-checks. NOT for
   consumer-side migration (sweeping a downstream app → adia-ui-factory),
   long-running VM ops, or composing / modifying UI.
-version: 0.1.0
+version: 0.2.2
 ---
 
 # `adia-ui-release` — Release Engineer for an @adia-ai-style Lockstep Monorepo
@@ -18,7 +18,7 @@ version: 0.1.0
 
 > **COLD-START FAST-PATH (read first when invoked with no concrete task).**
 >
-> If the user just activated the skill with no concrete request — e.g. `use adia-ui-release`, `load the release skill`, `the skill is loaded, now what?`, or any bare-activation phrasing without a version number, a release commit, or a recovery symptom — **jump directly to `## What this skill can do — pick your mode` below and render it verbatim**. Then ask one short prompt: _"Tell me which mode + which version (e.g. `1, 0.6.22`) and I'll load the matching reference bundles."_ Do NOT begin §Recon, do NOT load any `references/*.md` bundle, do NOT assume a happy-path cycle. The user is asking _what the skill offers_, not asking the skill to _act_. Plan-Execute-Verify (§PEV) still governs once a mode is picked.
+> If the user just activated the skill with no concrete request — e.g. `use adia-ui-release`, `load the release skill`, `the skill is loaded, now what?`, or any bare-activation phrasing without a version number, a release commit, or a recovery symptom — **jump directly to `## What this skill can do — pick your mode` below and render it verbatim**. Then ask one short prompt: _"Tell me which mode + which version (e.g. `1, 0.6.22`) and I'll load the matching reference bundles."_ Do NOT begin §Recon, do NOT load any `references/*.md` bundle, do NOT assume a happy-path cycle. The user is asking _what the skill offers_, not asking the skill to _act_. Plan-Execute-Verify (`§PEV`) still governs once a mode is picked.
 >
 > If the user activated the skill **AND** has named a concrete version / mode / symptom — skip this fast-path, follow §Posture, and route to the matching mode.
 
@@ -56,6 +56,7 @@ When in doubt, follow §Posture below.
 | 9 | **Authoring discipline only** | Just author CHANGELOG / Slack / GH-release notes from a diff — no cutting |
 | 10 | 📚 **Teach the skill new knowledge** | Operator/peer wants the skill to absorb a new gate, recovery path, notes template, ledger field, deploy step, peer-coordination pattern, or migration recipe — load the §Teach decision tree |
 | 11 | **Author a migration guide** | The cut breaks an API (MINOR) — author the `MIGRATION GUIDE.md` section + sweep in-repo surfaces (the **producer** side of migration) |
+| 12 | **Independent-package release** | Ship a package versioned **independently** of the lockstep set (**excluded from the lockstep gate**, no umbrella tag, no demo-site deploy) — NOT the lockstep cut. Loads `independent-package-release.md` |
 
 If your mode isn't listed, reply with `freeform: <your situation>` and the skill will branch into §Recon (gather state, classify, recommend a mode).
 
@@ -74,6 +75,7 @@ Pick the row that matches your starting state. The "Loads" column lists what the
 | You just want a Slack post / GH-release body | 9 | `notes-authoring.md` |
 | You want rollup notes across many versions | 5 | `rollup-notes.md` |
 | The cut breaks an API (MINOR) — author the guide | 11 | `migration-guide-authoring.md` |
+| Releasing a package versioned independently of the lockstep set | 12 | `independent-package-release.md` — class-B procedure + onboarding trip-wires + marketplace cut-over |
 | Teaching the skill new knowledge ("make adia-ui-release aware of X") | 10 | `teach-protocol.md` — decision tree + 5-step landing + worked examples + anti-patterns |
 | Bare activation, no concrete task | — | Nothing — render this menu and stop |
 
@@ -132,6 +134,7 @@ The release is not done until the verify-target confirms the ecosystem outside t
 | 9 Notes-only | The GH release page is visible at `https://github.com/<repo>/releases/tag/v0.X.Y` |
 | 10 §Teach landing | `audit-gate-roster.mjs --strict` reports 0 drift |
 | 11 Migration guide | Every breaking item in the cut's CHANGELOG has a guide subsection; the in-repo sweep-verification grep reports 0 legacy hits; the breaking cut's demo/structural gates pass |
+| 12 Independent-package release | `npm view @adia-ai/<pkg> version` returns the new **independent** version for EACH package (NOT "all 9 + demo site") AND, if a marketplace exists, its manifest references npm. Verify against the registry, never the workflow's reported success |
 
 The pre-flight gate sequence before any cut is the target monorepo's full roster (the @adia-ai example is in `cycle-happy-path.md §Step 3.1` + `gates-catalog.md`). If a gate fails, **the failure is the artifact**. Fix at the source, re-run the narrowest gate, then re-run the full sequence. Don't declare "released" until the registry + production endpoint + GH release page confirm it. Internal gates are necessary; they are never sufficient.
 
@@ -145,11 +148,13 @@ The pre-flight gate sequence before any cut is the target monorepo's full roster
 
 These hold across every release in an @adia-ai-style lockstep monorepo. Violating any of them produces a defective release. (The package counts / tag counts below are the @adia-ai monorepo's **worked example** — substitute your monorepo's own package set.)
 
+> **These govern the class-A lockstep cut (the primary path — modes 1–4).** A monorepo can also host packages versioned **independently** of the lockstep set — a **class-B independent-package release** (mode 12): versioned independently, EXCLUDED from the lockstep gate, no umbrella tag, no demo-site deploy. See **mode 12** / `references/independent-package-release.md` for the class-B invariants + the new-package onboarding trip-wires (lockfile · release-trip-wire package registry · CHANGELOG bracket form) + marketplace cut-over. *(Worked example: the @adia-ai monorepo's `packages/plugins/*` plugins — `adia-ui-factory` / `adia-ui-forge`.)*
+
 1. **Lockstep version coherence** — every `@adia-ai/*` package in the release set bumps together. In the @adia-ai monorepo that's 9 packages (`web-components`, `web-modules`, `llm`, `a2ui-compose`, `a2ui-corpus`, `a2ui-mcp`, `a2ui-retrieval`, `a2ui-runtime`, `a2ui-validator`), enforced by `check:lockstep`.
 2. **Internal `@adia-ai/*` dep ranges hold at `^0.X.0` during PATCH cuts** — only MINOR cuts bump the internal-range floor. (The "PATCH-cut asymmetry.")
 3. **Tag at HEAD, not at the bump commit** — post-bump fixes / tests / doc updates belong in the tarball. The release window's last commit is the tag point. Exception: batch push (each version tags at its own release-commit SHA).
 4. **One umbrella tag + one per-package tag per cut** — `vX.Y.Z` + `<pkg>-vX.Y.Z` per package. The publish workflows trigger off the per-package tags; the umbrella is convention. (10 tags in the @adia-ai 9-package example.)
-5. **The release trip-wire (F-N1, `check:release --all-pending`) must be per-package clean** — the umbrella tag's "doesn't match `<pkg>-v<version>`" error is expected and ignored. Warns on per-package tags require an enrichment pass (see `changelog-discipline.md` § diff-coverage enrichment).
+5. **The release trip-wire (F-N1, `check:release --all-pending`) must be per-package clean** — the umbrella tag's "doesn't match `<pkg>-v<version>`" error is expected and ignored. Warns on per-package tags require an enrichment pass (see `changelog-discipline.md` `§F-N1 diff-coverage enrichment`).
 6. **`npm dist-tag latest` is set by publish order** — for batch push, publish the older version's workflows + WAIT for completion BEFORE dispatching the newer version's. Otherwise `latest` lands on the older version.
 7. **Audit-history ledger is non-negotiable** — every cycle writes `.brain/audit-history/YYYY-MM-DD-release-vX.Y.Z.json`. Future cycles read past ledgers.
 8. **Site deploy reflects committed state** — the site build runs from the working tree, so peer-in-flight uncommitted files would leak into the deployed site if not stashed. Stash discipline is the same one used at release-commit time.
@@ -172,6 +177,25 @@ Additive cuts need no migration section — note "additive; no consumer sweep" i
 
 ---
 
+## §IndependentPackageRelease — the class-B cut (mode 12)
+
+Some packages in a lockstep monorepo are versioned **independently** of the lockstep set — their release cadence is deliberately decoupled. Shipping one is a **class-B independent-package release**, distinct from the class-A lockstep cut (modes 1–4):
+
+- **Class A — lockstep cut (modes 1–4)** — the whole set bumps together, enforced by the lockstep gate, one umbrella tag + per-package tags, cross-package `dist-tag` ordering, demo-site deploy. §ReleaseInvariants govern it.
+- **Class B — independent-package release (this mode, mode 12)** — each package on its own version line, **excluded from the lockstep gate** (the gate skips it by design), **no umbrella tag** (per-package tags only; versions differ), **no `dist-tag` cross-package race** (independent versions), **no demo-site deploy**. It still publishes via a tag-triggered per-package workflow and still verifies against the **npm registry** (never the workflow's reported "success").
+
+A package **new to the release tooling** hits three onboarding trip-wires the established set long since passed — **lockfile** (new workspace package absent from the lockfile), **release-trip-wire package registry** (an unregistered tag fails the pre-push hook), and **CHANGELOG bracket form** (the trip-wire requires Keep-a-Changelog `## [<version>]`). These are **substrate** fixes (release scripts / lockfile / CHANGELOG) — per the §Teach decision tree, branch A — landed once as a normal PR *before* tagging. If a plugin marketplace exists, a class-B cut ends with a **marketplace cut-over** (point the manifest's `source` at npm; remove vendored copies).
+
+**Load the full procedure** via the mode-12 row: `independent-package-release.md` (the two-class comparison table, the three onboarding trip-wires, the step-by-step procedure, the verify-against-npm target, and the marketplace cut-over).
+
+> **Worked example.** The @adia-ai monorepo's two Claude Code plugins —
+> `@adia-ai/adia-ui-factory` and `@adia-ai/adia-ui-forge` — live under
+> `packages/plugins/*`, version independently (factory `0.2.x`, forge `0.1.x`),
+> and are excluded from the 9-package lockstep by design. They are this mode's
+> worked example.
+
+---
+
 ## §LoadingProtocol — progressive context construction
 
 The skill seed (`SKILL.md` + `skill.json` + `CHANGELOG.md`) is the only content loaded on activation. Reference bundles load ONLY when the matched mode declares them, per the table in §Where are you starting from above. See `skill.json files` for the canonical reference list.
@@ -193,6 +217,7 @@ If the user said `freeform: <situation>` or otherwise didn't pick a mode, run th
 7. Check working-tree CHANGELOG heads for `## [Unreleased]` blocks
 8. Check uncommitted source files — would they be IN a release commit?
 9. Is this a breaking cut (removed/renamed API symbol)? → mode 11 owes a migration-guide section.
+10. Is the package being released versioned **independently** of the lockstep set (excluded from the lockstep gate)? → **mode 12** (class-B independent-package release), not a lockstep cut.
 
 Then classify:
 
@@ -202,6 +227,7 @@ Then classify:
 - **Mode 1** (cut & ship) — fits a normal cycle, no special signal
 - **Mode 6** (just verify) — operator only wants a smoke check
 - **Mode 11** (migration guide) — the cut is breaking (MINOR) and no `MIGRATION GUIDE.md` section exists yet for the version
+- **Mode 12** (independent-package release) — the package is versioned independently of the lockstep set (excluded from the lockstep gate); ship it on its own version line, no umbrella tag, no demo-site deploy
 - **Otherwise** — surface the ambiguity to the operator; recommend routing through Investigation (mode 8).
 
 After classifying, load the mode's declared reference bundle and proceed per its checklist.
@@ -212,13 +238,13 @@ After classifying, load the mode's declared reference bundle and proceed per its
 
 This section is the binding for requests of the shape "make sure `adia-ui-release` knows about X" / "train the skill on Y" / "absorb this release-pattern into adia-ui-release" / "the skill should be aware of Z".
 
-§Teach is the **extensibility posture** — narrower than the cut-&-ship modes (1-4), distinct from the verification mode (6), the recovery mode (7), the notes-only mode (9), and the migration-guide mode (11). Use it when another agent — release operator, peer skill author, dev-ops author — hands the release skill new knowledge to integrate.
+§Teach is the **extensibility posture** — narrower than the cut-&-ship modes (1-4), distinct from the verification mode (6), the recovery mode (7), the notes-only mode (9), the migration-guide mode (11), and the independent-package mode (12). Use it when another agent — release operator, peer skill author, dev-ops author — hands the release skill new knowledge to integrate.
 
 **Load the full procedure** via the mode-10 row: `teach-protocol.md`.
 
 ### The procedure in 30 seconds
 
-1. **Run the decision tree** — does the new knowledge belong in the substrate (script source — NOT a skill landing), `gates-catalog.md` (new gate), `recovery-paths.md` (new failure mode), `notes-authoring.md` or `rollup-notes.md` (notes-template variant), `ledger-discipline.md` (new ledger field), `exe-deploy.md` (new deploy step), `multi-agent-baseline.md` (new peer-coordination pattern), `migration-guide-authoring.md` (new producer-side migration recipe / manual-review class), INLINE in SKILL.md (methodology / new §SelfAudit axis / new mode), or the audit-history ledger + journal (cycle-specific arc story — NOT the skill)? The reference file branches every case with worked examples (including the negative case).
+1. **Run the decision tree** — does the new knowledge belong in the substrate (script source — NOT a skill landing), `gates-catalog.md` (new gate), `recovery-paths.md` (new failure mode), `notes-authoring.md` or `rollup-notes.md` (notes-template variant), `ledger-discipline.md` (new ledger field), `exe-deploy.md` (new deploy step), `multi-agent-baseline.md` (new peer-coordination pattern), `migration-guide-authoring.md` (new producer-side migration recipe / manual-review class), `independent-package-release.md` (new class-B onboarding trip-wire / marketplace step), INLINE in SKILL.md (methodology / new §SelfAudit axis / new mode), or the audit-history ledger + journal (cycle-specific arc story — NOT the skill)? The reference file branches every case with worked examples (including the negative case).
 2. **Five-step landing procedure** — audit before patching → author the patch → wire the activation surface → version + CHANGELOG → verify with `audit-gate-roster.mjs`.
 3. **Anti-patterns** to avoid: append-only landing, substrate duplication (re-stating what a `check:*` script does), orphan triggers, capability menu lies, MINOR + PATCH bundling, hygiene-debt deferral, one-way thinking (failing to route content to a sibling — `adia-ui-authoring` for authoring-side hygiene, `ops-postmortem` for incident write-ups, the consumer/app-author plugin for the consumer side of migration).
 
@@ -248,7 +274,7 @@ node "${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-release/scripts/audit-gate-roster.mjs
 
 Path resolution: the script resolves its catalog via `${CLAUDE_PLUGIN_ROOT}`, falling back to a path relative to the script; run it from the target monorepo root (or pass `--repo <root>`).
 
-§SelfAudit checks the SKILL's invariants; §PEV checks the OUTPUT against reality. Both are required — see §PEV above.
+§SelfAudit checks the SKILL's invariants; `§PEV` checks the OUTPUT against reality. Both are required — see `§Plan-Execute-Verify` above.
 
 ---
 
@@ -270,11 +296,13 @@ skills/adia-ui-release/
 │   ├── exe-deploy.md
 │   ├── ledger-discipline.md
 │   ├── migration-guide-authoring.md   (producer side of migrations — fold-in)
+│   ├── independent-package-release.md (class-B cut — independently-versioned package)
 │   └── teach-protocol.md
 ├── scripts/                           (CLI helpers — pure Node, stdlib only)
 │   ├── bump.mjs
 │   ├── promote-unreleased.mjs
 │   ├── insert-stub.mjs
+│   ├── package-paths.mjs              (name↔path-form package resolution — shared by the CHANGELOG helpers)
 │   ├── tag-lockstep.mjs
 │   ├── dispatch-publish.mjs
 │   ├── make-ledger.mjs