@adia-ai/adia-ui-forge 0.8.55 → 0.8.57

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.55",
+  "version": "0.8.57",
   "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-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",
@@ -16,5 +16,6 @@
     "framework-authoring",
     "release-engineering",
     "maintainer"
-  ]
+  ],
+  "hooks": "./adapters/claude/hooks.json"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.55",
+  "version": "0.8.57",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — 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-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.57] — 2026-09-01
+
+### Removed
+- **`package-release`'s release-roster gate 19 (`verify:site-a2ui`) retired with the site-a2ui mechanism itself (ADR-0072 Decision 2, gh#2410 active drain).** `gate-roster.mjs` drops the gate 19 entry (33 gates → 32; gate number left unassigned rather than renumbering 20+, per the roster's own no-renumber discipline for gate identities cited in shipped release notes); `cut-procedure.md` §3.1's transcription and its `.examples.html`-generator trigger prose updated to match. The `site-postwrite-derivation-gate` hook's fragment-staleness half (the site-a2ui regeneration nudge) is removed; its sitemap-staleness half (`site/sitemap.json` → `build:llms`/`build:patterns-index`), unrelated to site-a2ui, is unchanged. `a2ui-maintenance`'s `pipeline-overview.md` and `site-docs-authoring`'s `SKILL.md`/`primitive-authoring`'s `yaml-contract.md` no longer instruct regenerating a compiled A2UI artifact that no longer exists.
+
+### Fixed
+- **Plugin passes `author-cross-harness-plugins`'s cross-harness validator, modulo one documented, permanent, irreconcilable exception (gh#2668).** `${CLAUDE_PLUGIN_ROOT}`/`$ARGUMENTS`/the `` !`command` `` auto-injection syntax removed from shared `gen-ui-review/SKILL.md`, the four `commands/*.md` bodies, and their linked reference docs (`demo-audit/references/visual-probe-triage.md`, `package-release/references/{cut-procedure,changelog-discipline,gates-catalog,recovery-paths}.md`, `gen-ui-review/references/loop-protocol.md`) — portable `<plugin-root>` prose / "named in the current request" phrasing throughout; command frontmatter, including `package-release`/`site-deployment`'s deliberate `disable-model-invocation: true` (AGENTS.md-ruled), is untouched since the validator never scans command frontmatter. `hooks/hooks.json` moved to `adapters/claude/hooks.json` (unchanged, `${CLAUDE_PLUGIN_ROOT}`-based); new root `hooks.json` mirrors the same event/matcher/action signature with monorepo-root-relative command paths for Codex's convention-discovered hook surface — an unverified-but-honest fallback documented in `HARNESS-NOTES.md`. **The one exception:** every skill's `disable-model-invocation:`/`user-invocable:` frontmatter — required, explicitly, by this repo's own blocking `check:skills` gate (`plugin-estate-v2.md`'s species-pinning charter) — collides head-on with the validator's opposite requirement on the exact same file, and Codex is hard-pinned to read root `skills/` directly (no adapter escape). The repo's own charter is not weakened; `npm run check:cross-harness-plugins` (`scripts/verify/check-cross-harness-plugins.mjs`, wrapping the vendored `scripts/verify/vendor/validate_cross_harness.py`) treats only this one exact finding shape as accepted (logged as INFO) and still fails on every other portability class. Full reasoning in `HARNESS-NOTES.md`.
+
+### Changed
+- **`forge-lint` rewritten as a thin Node CLI (`forge-lint.mjs`) consuming a shared generated lint-rule bank, retiring the Python script (gh#2638, LLD-0016, ADR-0099).** The framework-authoring structural checks (SHADOW-DOM, SLOTTED, RAW-COLOR, RAW-PX, SCOPE-EXTENT, DEAD-FONT-TOKEN, BOOL-DEFAULT-TRUE, ATTR-TYPO, NATIVE-PRIMITIVE, LEGACY-SHELL, MISSING-SCOPE) now live as individually-fixtured rule modules under `scripts/lint/rules/` in the repo root, built into `scripts/lint/generated/rule-bank.mjs` and vendored byte-identically into this plugin, `adia-ui-factory`, and the gen-ui MCP's factory vendor tree (`npm run build:lint-rules`, freshness gated by `npm run check:lint-rules-fresh`). `hooks/hooks.json`'s PostToolUse command changes from `python3 ".../forge-lint" --hook` to `node ".../forge-lint.mjs" --hook`; the CLI contract, exit codes, and PostToolUse never-block invariant are unchanged. `npm run check:lint-rules-selftest` proves finding-parity against the retired script's own `selftest()` fixtures. New `npm run lint` (`scripts/lint/lint-repo.mjs`) runs the full bank against every git-tracked lintable file — standalone for now, not yet wired into `npm run check` (a first repo-wide run surfaced 330 error-severity pre-existing findings that need triage first — gh#2646). The suppression comment (`/* adia-lint-disable <rule-id> — <reason> */`) is now load-bearing, not cosmetic: it drops the matching finding, and a bare disable with no reason is itself a finding (`SUPPRESS-NO-REASON`).
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+- **`prompts/` touched in this release window** (4 file(s), e.g. `prompts/demo-audit.md`) — carried by the entries above.
+
+## [0.8.56] — 2026-08-31
+
+### Added
+- **New `component-md-authoring` skill (gh#2615).** Authors the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — typed directly into the yaml's new `screenReader:`/`behavioral:` fields (component.md itself is a generated shell, never hand-edited). Sits next to `primitive-authoring` in `packages/plugins/adia-ui-forge/skills/`; Codex (`agents/openai.yaml`) and Hermes/Pi (`__init__.py`) manifests regenerated to register it.
+- **`primitive-authoring`'s `yaml-contract.md` gains a semantic-id grammar for `examples[].a2ui` component ids (gh#2492 Phase 1).** The `.claude/docs/specs/a2ui-editor.md:170` "free-form" id convention was written for editor-generated ids only, not authored yaml examples — reading it as license for both produced a corpus-wide drift toward cryptic, positional ids (`q`, `k1`, `k1v`) reported against `blockquote.yaml`, `badge.yaml`, `aside.yaml`, `alert.yaml`, and `anchor-bar.yaml`. New `## examples: field` section documents the grammar (kebab-case, role-descriptive, unique per example, a short-real-word root/wrapper exception) with before/after examples; `a2ui-editor.md:170` amended to scope its own claim to editor-generated ids and cross-reference the new grammar. Phase 2 (a separate dispatch) sweeps the corpus to match.
+- **Phase 2 (gh#2492): the corpus-wide sweep landed and `check-example-ids.mjs` flips from advisory to `npm run check:example-ids:strict` in the `npm run check` chain.** 526 violations across 48 yamls (`packages/web-components`, `packages/web-modules`) renamed to the Phase 1 grammar — see `packages/web-components/CHANGELOG.md` and `packages/web-modules/CHANGELOG.md` for the file list. `yaml-contract.md`'s `## examples: field` section updated to describe the gate as enforced, plus a noted known gap (the checker's positional regex doesn't catch a `letter-digit-letter-digit` chain like `g1i1`, out of scope for this sweep since nothing flagged it). `check-example-ids.mjs` itself gained an entrypoint guard (`if (import.meta.url === ...)`) — the CLI's `main()` was running as a side effect of importing `checkExampleIds` as a library function, which the sweep tooling does.
+
+### Fixed
+- **`package-release`'s Step 5 staging allowlist was missing the factory README's own prose echo of the generation-MCP pin — bump.mjs's `A2UI_MCP_PIN` rewrites both `adia-ui-factory/.mcp.json` and its README, but Step 5 only ever staged `.mcp.json`, so the README edit rode uncommitted through every cut (gh#2473).** `release-pack.mjs`'s Step 5 now also stages `packages/plugins/adia-ui-factory/README.md`. Added a new Step 5.6 unstaged-tracked-files guard right after staging (numbered 5.6, not 5.5 — `cut-procedure.md`'s own §Step 5.5 already names a different, pre-existing manual freshness trip-wire): it fails the cut loudly if any tracked file bump.mjs or a cut-hygiene step touched is still modified-in-the-worktree after Step 5's allowlist ran, so the next allowlist gap is caught at cut time instead of discovered by hand later. `selftest` extended with a direct unit test of the new `unstagedTrackedLeftovers()` parser (plain modifies/deletes, staged-only and untracked exclusions, C-quoted paths, rename/copy new-side reporting) plus a marker asserting the guard's `--dry` code path runs.
+
+### Changed
+- **`package-release`: gate 4 retries once on host-contention timeout (Mode A, gh#2195, #2362)**; `cut-procedure.md` fails fast on a pnpm-shaped `node_modules` in Step 1 and adds Step 12 (restore the pnpm dev layout after a cut) (#2197, #2202); `gates-catalog.md` follows.
+- **`a2ui-maintenance` references follow the A2UI runtime.** `data-model-reactivity.md`, `surface-lifecycle.md`, and `pipeline-overview.md` describe the vendored v1 data model after ADR-0078 P3/P4 (walker retirement, #2271), the `v0_9`→`v1_0` dialect rename (gh#2212, #2241), and the five opt-out-scoped catalogs (gh#2211, #2233, #2216).
+- **`primitive-authoring` references absorb the ADR-drift harvest (#2441) and ADR-0063 wave 2 (#2443)**: `anti-patterns.md`, `api-contract.md`, `authoring-cycle.md`, `code-style.md`, `form-control-sizing.md`, `token-contract.md`, and `yaml-contract.md` now state the ratified spellings (`no-*` negation prefix, `closable`, `outlined`, `status=completed`) and the amended ADR-0047/0056/0059/0061 rulings inline.
+- **`HARNESS-NOTES.md`** pointer for non-Claude harnesses (gh#2449).
+
+### Fixed
+- **`generate-release-notes.mjs` (gh#2474): two bugs found and hand-fixed live during the v0.8.56 cut, now fixed at the source.** (1) When a CHANGELOG `[X.Y.Z]` section carries two same-named `### Changed`/`### Fixed` blocks (one at cut time, another added by a later hand-fix), the generator now merges them into one heading in first-occurrence order before demoting to `####` — the duplicate `####` heading that tripped CodeRabbit's MD024 (db13eaebb) can't recur. (2) The Slack post's per-package headline now prefers a bullet starting with `- **BREAKING` over document order, falling back to the first bullet only when none is BREAKING (b378b5fd9). Added `mergeDuplicateHeadings()`, unit coverage in `scripts/release/generate-release-notes.test.js`, and `selftest` regression cases for both. `scripts/release/generate-release-notes.mjs`.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+- **`skills/` touched in this release window** (14 file(s), e.g. `a2ui-maintenance/SKILL.md`) — carried by the entries above.
+
 ## [0.8.55] — 2026-08-28
 
 ### Changed

package/README.md

@@ -36,7 +36,7 @@ same decomposition scoped to A2UI catalog/tier cohesion, never touches corpus or
 `framework-checker` (fable, **no Write/Edit** — read-only corpus-wide cohesion
 audit: color tokens, typography, state naming, attrs-as-api, implementation patterns).
 
-## Hooks (5 — `hooks/hooks.json` is the roster; `check:plugin-count-claims` guards this header count)
+## Hooks (5 — `adapters/claude/hooks.json` is the roster; `check:plugin-count-claims` guards this header count)
 
 `sidecar-prewrite-guard` (PreToolUse deny on hand-edits to generated
 artifacts) · `release-pretag-docs-gate` (PreToolUse: release-tagging Bash

package/__init__.py

@@ -11,6 +11,11 @@ def register(ctx):
         path=Path(os.path.join(_HERE, "skills", "a2ui-maintenance", "SKILL.md")),
         description="Maintains the A2UI pipeline (packages/gen-ui/a2ui/): the chunk corpus, compose strategies (zettel, chunk-zettel, free-form, monolithic), retrieval, validator, calibration, evals, the a2ui MCP server. Use to author/harvest/fix chunks, tune STRONG_MATCH or zettel thresholds, validate an A2UI document, diagnose an eval gap/regression or lift a semantic fail, change MCP tools (generate_ui, compose_from_chunks, check_anti_patterns, refine_composition), scan anti-patterns, run pipeline ops, or when a contract can't express a shape. NOT for app screens (screen-composition), runtime gen-UI features (gen-ui-wiring), primitive authoring (primitive-authoring), or gallery scoring (gen-ui-review).",
     )
+    ctx.register_skill(
+        name="component-md-authoring",
+        path=Path(os.path.join(_HERE, "skills", "component-md-authoring", "SKILL.md")),
+        description="Author the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — and keep it PR-fresh. Use when a component's states, composed children, aria behavior, or error/empty/ loading handling changes and it already has (or should grow) a `component.md`, or when asked to \"add component.md for X\" / \"write the screen-reader spec for X\" / \"why did check:component-md-fresh fail\". NOT the yaml prop/slot/event/token contract itself (primitive-authoring owns that — this skill only owns the two authored yaml fields, `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui corpus/retrieval wiring (a2ui-maintenance); NOT a component's CSS token audit (component-token-audit).",
+    )
     ctx.register_skill(
         name="cross-harness-authoring-standards",
         path=Path(os.path.join(_HERE, "skills", "cross-harness-authoring-standards", "SKILL.md")),

package/commands/demo-audit.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Run a dogfood sweep. **$ARGUMENTS**
+Run a dogfood sweep against the mode/surface named in the current request (all, if unscoped).
 
 Invoke **`demo-audit`**; run the requested modes (all, if unscoped), then
 triage findings per its severity contract. Detection is script-driven; the

package/commands/gen-ui-review.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Run a gen-UI review cycle. **$ARGUMENTS**
+Run a gen-UI review cycle, scoped to the prompt subset named in the current request (if any).
 
 Invoke **`gen-ui-review`** and run its loop: derive ideal → decompose actual
 → score → root-cause → plan. Corpus fixes route to `a2ui-maintenance`.

package/commands/package-release.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 ---
 
-Run a release. **$ARGUMENTS**
+Run a release for the version/package named in the current request.
 
 Invoke **`package-release`** and run its cut procedure end-to-end: pre-flight
 gates → cut → tag → publish → deploy → notes. This command's invocation is

package/commands/site-deployment.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 ---
 
-Deploy or diagnose an exe.dev surface. **$ARGUMENTS**
+Deploy or diagnose the exe.dev host/service named in the current request.
 
 Invoke **`site-deployment`** and follow its playbook for the named host; verify
 against the live endpoint before reporting done.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.55",
+  "version": "0.8.57",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — 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/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-forge"
-version: "0.8.55"
+version: "0.8.57"
 description: "Maintain the adia-ui (@adia-ai) framework itself — 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-ui-kit-factory (the consumer/app-author plugin)."
 manifest_version: 1

package/prompts/demo-audit.md

@@ -3,7 +3,7 @@ description: "Run the multi-mode QA sweep (visual probe, static QA, typo, native
 argument-hint: "[mode or surface]"
 ---
 
-Run a dogfood sweep. **$ARGUMENTS**
+Run a dogfood sweep against the mode/surface named in the current request (all, if unscoped).
 
 Invoke **`demo-audit`**; run the requested modes (all, if unscoped), then
 triage findings per its severity contract. Detection is script-driven; the

package/prompts/gen-ui-review.md

@@ -3,7 +3,7 @@ description: "Run the closed-loop gen-UI quality review — score gallery output
 argument-hint: "[prompt subset]"
 ---
 
-Run a gen-UI review cycle. **$ARGUMENTS**
+Run a gen-UI review cycle, scoped to the prompt subset named in the current request (if any).
 
 Invoke **`gen-ui-review`** and run its loop: derive ideal → decompose actual
 → score → root-cause → plan. Corpus fixes route to `a2ui-maintenance`.

package/prompts/package-release.md

@@ -3,7 +3,7 @@ description: "Cut, tag, publish, and deploy an @adia-ai release (lockstep roster
 argument-hint: "[version or package]"
 ---
 
-Run a release. **$ARGUMENTS**
+Run a release for the version/package named in the current request.
 
 Invoke **`package-release`** and run its cut procedure end-to-end: pre-flight
 gates → cut → tag → publish → deploy → notes. This command's invocation is

package/prompts/site-deployment.md

@@ -3,7 +3,7 @@ description: "Deploy a service or dist to the exe.dev VMs (ui-kit.exe.xyz and si
 argument-hint: "[host or service]"
 ---
 
-Deploy or diagnose an exe.dev surface. **$ARGUMENTS**
+Deploy or diagnose the exe.dev host/service named in the current request.
 
 Invoke **`site-deployment`** and follow its playbook for the named host; verify
 against the live endpoint before reporting done.

package/scripts/forge-lint.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * forge-lint.mjs — thin Node CLI consuming the vendored generated rule bank
+ * (lint-rules.generated.mjs, LLD-0016 §C5) for the adia-ui FRAMEWORK source
+ * (maintainer slice): the same structural-smell checks forge-lint (Python)
+ * ran, now run: 'shared' + 'forge-only' scope rules only — no consumer/app
+ * traps (SSR, hardcoded overlay open, LLM key, genui). See ADR-0099 for why
+ * this replaced the Python script as the hooks.json entry point.
+ *
+ * Usage:
+ *   forge-lint.mjs <file>...   lint files; exit 1 if any error-severity finding, else 0
+ *   forge-lint.mjs -           lint stdin as a generic source file
+ *   forge-lint.mjs --hook      PostToolUse hook mode: read event JSON on stdin, lint the
+ *                              written source file, print advisory findings, ALWAYS exit 0
+ *   forge-lint.mjs selftest    run the inherited parity fixtures + the hook exit-0 invariant
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { makeLinter, ext, LINT_EXT, RULES } = await import(join(__dirname, 'lint-rules.generated.mjs'));
+
+/**
+ * Repo-root-relative parity fixtures are only reachable when this CLI is
+ * running from inside the monorepo checkout (the plugin's own source tree,
+ * not a packed/vendored install elsewhere) — walk up from this file looking
+ * for scripts/lint/rule-bank.selftest.mjs rather than a fixed `../..` depth,
+ * since this same CLI shape is vendored to more than one directory depth
+ * (ADR-0099). A vendored copy outside the monorepo has no fixtures to find
+ * and `selftest` reports that plainly instead of crashing.
+ */
+function findParityFixtures() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i += 1) {
+    const candidate = join(dir, 'scripts/lint/rule-bank.selftest.mjs');
+    if (existsSync(candidate)) return candidate;
+    dir = join(dir, '..');
+  }
+  return null;
+}
+
+const SCOPE_ANCHOR = ['packages/web-components/', 'packages/web-modules/'];
+const { lintText } = makeLinter(RULES, { scopes: ['shared', 'forge-only'] });
+
+function render(path, findings) {
+  const out = [`forge-lint: ${findings.length} structural smell(s) in ${path || '<stdin>'}`];
+  for (const f of findings) {
+    out.push(`  [${f.name}] line ${f.line}: ${f.snippet}`);
+    out.push(`      → ${f.why}`);
+  }
+  return out.join('\n');
+}
+
+function lintPath(path) {
+  try {
+    return lintText(readFileSync(path, 'utf8'), path);
+  } catch (err) {
+    return [{ name: 'READ-ERROR', line: 1, snippet: path.slice(0, 90), why: `failed to read file: ${err.message}` }];
+  }
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function hook() {
+  let event;
+  try {
+    event = JSON.parse(await readStdin());
+  } catch {
+    return 0;
+  }
+  const ti = event.tool_input || {};
+  const path = ti.file_path || '';
+  const norm = path.replace(/\\/g, '/');
+  if (!SCOPE_ANCHOR.some((a) => norm.includes(a))) return 0;
+  if (!LINT_EXT.includes(ext(path))) return 0;
+  let text = ti.content;
+  if (text === undefined || text === null) {
+    if (!existsSync(path)) return 0;
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch {
+      return 0;
+    }
+  }
+  const findings = lintText(text, path);
+  if (findings.length) {
+    const context = render(path, findings)
+      + '\n  (forge-lint advisory — adia-ui framework authoring smells; the skills own the judgment)';
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context },
+    }) + '\n');
+  }
+  return 0; // NEVER block
+}
+
+async function selftest() {
+  const fixturesPath = findParityFixtures();
+  if (!fixturesPath) {
+    console.log('selftest: SKIP — no monorepo checkout found (parity fixtures live in scripts/lint/, not vendored)');
+    return 0;
+  }
+  const { PARITY_CASES } = await import(fixturesPath);
+  let ok = true;
+  for (const { name, text, expected, scopes } of PARITY_CASES) {
+    if (scopes && !(scopes.includes('forge-only'))) continue; // this CLI's own cases only
+    const got = new Set(lintText(text, name).map((f) => f.name));
+    const missing = [...expected].filter((e) => !got.has(e));
+    if (missing.length) {
+      ok = false;
+      console.error(`selftest: ${name} MISSING ${JSON.stringify(missing)} (got ${JSON.stringify([...got])})`);
+    }
+    if (expected.size === 0 && got.size) {
+      ok = false;
+      console.error(`selftest: ${name} expected clean, got ${JSON.stringify([...got])}`);
+    }
+  }
+  // never-block invariant
+  const savedWrite = process.stdout.write.bind(process.stdout);
+  let hookOut = '';
+  process.stdout.write = (chunk, ...rest) => { hookOut += chunk; return true; };
+  const stdinMock = Buffer.from(JSON.stringify({ tool_input: { file_path: 'packages/web-components/c.css', content: '.a { color:#f00; }' } }));
+  const origStdin = process.stdin;
+  Object.defineProperty(process, 'stdin', { value: (async function* () { yield stdinMock; })(), configurable: true });
+  let rc;
+  try {
+    rc = await hook();
+  } finally {
+    process.stdout.write = savedWrite;
+    Object.defineProperty(process, 'stdin', { value: origStdin, configurable: true });
+  }
+  if (rc !== 0) {
+    ok = false;
+    console.error('selftest: --hook did not exit 0 on smelly input');
+  }
+  if (rc === 0 && hookOut && !hookOut.includes('"hookSpecificOutput"')) {
+    ok = false;
+    console.error('selftest: --hook stdout is not structured hookSpecificOutput JSON');
+  }
+  console.log(ok ? 'selftest: PASS' : 'selftest: FAIL');
+  return ok ? 0 : 1;
+}
+
+async function main(argv) {
+  if (argv[0] === 'selftest') return selftest();
+  if (argv.includes('--hook')) return hook();
+  const args = argv.filter((a) => a === '-' || !a.startsWith('-'));
+  if (!args.length) {
+    console.error('usage: forge-lint.mjs <file>...  |  forge-lint.mjs -  |  forge-lint.mjs --hook  |  forge-lint.mjs selftest');
+    return 2;
+  }
+  let total = 0;
+  for (let path of args) {
+    const findings = path === '-' ? lintText(await readStdin(), '<stdin>') : lintPath(path);
+    if (path === '-') path = '<stdin>';
+    if (findings.length) {
+      total += findings.length;
+      console.log(render(path, findings));
+    }
+  }
+  return total ? 1 : 0;
+}
+
+process.exit(await main(process.argv.slice(2)));