@adia-ai/adia-ui-factory 0.8.56 → 0.8.57

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.56",
+  "version": "0.8.57",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework \u2014 orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",
@@ -15,5 +15,6 @@
     "web-components",
     "app-authoring",
     "consumer"
-  ]
+  ],
+  "hooks": "./adapters/claude/hooks.json"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.56",
+  "version": "0.8.57",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "adia-gen-ui": {
       "command": "npx",
-      "args": ["-y", "@adia-ai/mcp@0.8.56", "gen-ui"]
+      "args": ["-y", "@adia-ai/mcp@0.8.57", "gen-ui"]
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog — adia-ui-kit-factory
 
+## [0.8.57] — 2026-09-01
+
+### 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 `app-migration`, `theme-audit`, `screen-composition`, `project-scaffolding`, `app-planning`, `surface-qa`, and `find-unused` SKILL.md bodies, all eight `commands/*.md` bodies, and their linked reference docs (`surface-qa/references/verification.md`, `find-unused/references/recon-and-audits.md`) — portable `<plugin-root>` prose / "named in the current request" phrasing throughout; `screen-composition`/`app-planning`'s Claude-only auto-injected context block became an explicit "run this yourself" instruction, since Codex has no equivalent auto-injection surface. `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 a monorepo-root-relative command path 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`.
+
+### Docs
+- **`skills/pattern-catalog/references/pattern-index.md` regenerated for `page-scroll`'s addition (gh#2639, ADR-0098 Fork 4).** `build:patterns-index`'s re-extraction picked up `admin-dashboard.contents.html`/`admin-shell.contents.html`'s tag-list changes under the page-chrome consolidation (`admin-page*` → `page-ui[band]`, `admin-scroll` → `page-scroll`).
+
+### Changed
+- **`adia-lint` rewritten as a thin Node CLI (`adia-lint.mjs`) consuming a shared generated lint-rule bank, retiring the Python script (gh#2638, LLD-0016, ADR-0099).** The consumer-app structural checks (the forge-shared rules plus SSR-DOUBLE-ROUTER, SSR-TOPLEVEL-IMPORT, HARDCODED-OPEN, SHELL-NESTING, SHELL-RESIZE, LLM-KEY-IN-CLIENT, GENUI-UNVALIDATED, GENUI-DOC-CONFLICT) 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-forge`, 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 ".../adia-lint" --hook` to `node ".../adia-lint.mjs" --hook`; the CLI contract (including `-h`/`--help`), 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. The gen-ui MCP factory server's `lint` tool (`audit_structure`) now spawns the Node CLI directly instead of shelling through `python3`.
+
+### 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.
+- **`agents/` touched in this release window** (1 file(s), e.g. `agents/surface-qa-agent.md`) — carried by the entries above.
+- **`prompts/` touched in this release window** (8 file(s), e.g. `prompts/app-audit.md`) — carried by the entries above.
+
 ## [0.8.56] — 2026-08-31
 
 ### Added

package/README.md

@@ -111,7 +111,7 @@ attributes vs. the shipped component contracts), and `adia-theme-audit.mjs`
 
 ## MCP
 
-`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.56` (tool SoT:
+`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.57` (tool SoT:
 `packages/gen-ui/mcp/TOOLS.md` — the `gen-ui` section; stability rule in
 `references/contracts/`; pin lives in `.mcp.json` — `check:plugin-count-claims`
 guards this README copy against it). The server is `adia-mcp gen-ui`,

package/agents/surface-qa-agent.md

@@ -39,7 +39,7 @@ a surface can pass the browser gate and still be a keyword-driven premature
 render (D1) that never traced to a resolved plan. Every claim in the
 proof cites its evidence (the probe JSON, the screenshot path, the element
 inspected). The structure row's evidence comes from running
-`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adia-lint"` over the surface's files via
+`node "${CLAUDE_PLUGIN_ROOT}/scripts/adia-lint.mjs"` over the surface's files via
 Bash — the PostToolUse hook never fires for a seat that writes nothing. A
 gate that cannot run (no dev server, Playwright missing) is reported
 UNMEASURED with the reason, never silently skipped; a dispatch without a

package/commands/app-audit.md

@@ -6,9 +6,11 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Probe the project context. **$ARGUMENTS**
+Probe the project context named in the current request (a directory, if given).
 
-Run `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adia-info" $ARGUMENTS` and present
+Run `python3 "<plugin-root>/scripts/adia-info" [dir]` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT`
+in Claude Code; the plugin's installed directory in Codex) with the directory named in the
+current request, and present
 the JSON as a short read: each field with the signal it derived from and
 the decision it drives (screen-composition §Current project context carries the
 field→decision table). An `installedVersion` that is null or mismatched vs

package/commands/app-migration.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Migrate this codebase. **$ARGUMENTS**
+Migrate this codebase to the target version named in the current request.
 
 Invoke **`app-migration`**: read the shipped guide for the span
 (`node_modules/@adia-ai/web-components/MIGRATION.md` — install/upgrade the

package/commands/app-planning.md

@@ -6,10 +6,11 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Orient in this repo. **$ARGUMENTS**
+Orient in this repo, answering the path or question named in the current request.
 
 Invoke **`app-planning`** and produce the Orientation Record in the skill's
 own contract shape (Rendering mode · Project shape · Shell · Task ·
 Screen plan (start mode) · → Route · Verify target · Open questions), each
 axis citing its signal. Self-check the record with
-`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/record-lint" -` before returning it.
+`python3 "<plugin-root>/scripts/record-lint" -` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in
+Claude Code; the plugin's installed directory in Codex) before returning it.

package/commands/find-unused.md

@@ -6,12 +6,12 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Find what this app is not using. **$ARGUMENTS**
+Find what this app is not using, scoped to the target version named in the current request.
 
 Invoke **`find-unused`**: enumerate every `@adia-ai/*` package each manifest
 declares (never assume `web-components`), recon the three versions that differ
-per package — declared range, installed, and the target: **the version in
-`$ARGUMENTS` when one was given, registry latest only as the default**. Read
+per package — declared range, installed, and the target: **the version named in the current request
+when one was given, registry latest only as the default**. Read
 every `node_modules/@adia-ai/*/CHANGELOG.md` section across the
 installed→target span, then run all four audits — inert opt-in layers, redundant local
 workarounds, retired enum values sitting in persisted state, and shipped

package/commands/gen-ui-wiring.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Build a gen-UI experience. **$ARGUMENTS**
+Build the gen-UI experience or surface named in the current request.
 
 Invoke **`gen-ui-wiring`** and run its generate → validate → render → iterate
 loop; generated A2UI is validated as data before it is serialized, and the

package/commands/project-scaffolding.md

@@ -6,10 +6,11 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Scaffold an adia-ui surface. **$ARGUMENTS**
+Scaffold the adia-ui surface named in the current request.
 
 Invoke **`project-scaffolding`** to classify the project shape and target, then use
-`${CLAUDE_PLUGIN_ROOT}/scripts/adia-scaffold` for the mechanical skeleton. Shapes
+`<plugin-root>/scripts/adia-scaffold` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in Claude
+Code; the plugin's installed directory in Codex) for the mechanical skeleton. Shapes
 the bin doesn't one-shot (rollup, shared-foundation) are composed per the
 project-shapes reference. `inventory <app-root>` scores an existing app
 against the structure rubric (4 mechanized gates with cited paths + the 2

package/commands/surface-qa.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Verify a composed surface. **$ARGUMENTS**
+Verify the composed surface named in the current request.
 
 Dispatch the **surface-qa-agent** agent on the named surface/URL — the exit
 gate runs ISOLATED from whatever context built the surface (generator ≠

package/commands/theme-audit.md

@@ -6,9 +6,9 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Audit a theme stylesheet. **$ARGUMENTS**
+Audit the theme stylesheet named in the current request.
 
-Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/adia-theme-audit.mjs" --theme <file>
+Run `node "<plugin-root>/scripts/adia-theme-audit.mjs" --theme <file>
 --app <root>` (add `--json`/`--json-out <path>` for a structured report,
 `--strict` to exit non-zero on any `high`-confidence finding, `--class
 1,2,3,4` to narrow scope). No `@adia-ai/web-components` resolvable from

package/hermes-mcp.yaml

@@ -6,5 +6,5 @@ mcp_servers:
     command: "npx"
     args:
       - "-y"
-      - "@adia-ai/mcp@0.8.56"
+      - "@adia-ai/mcp@0.8.57"
       - "gen-ui"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-factory",
-  "version": "0.8.56",
+  "version": "0.8.57",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "keywords": [
     "adia-ui",

package/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-factory"
-version: "0.8.56"
+version: "0.8.57"
 description: "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation."
 manifest_version: 1

package/prompts/app-audit.md

@@ -3,9 +3,11 @@ description: "Probe this repo's adia-ui project context — declared vs installe
 argument-hint: "[dir]"
 ---
 
-Probe the project context. **$ARGUMENTS**
+Probe the project context named in the current request (a directory, if given).
 
-Run `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adia-info" $ARGUMENTS` and present
+Run `python3 "<plugin-root>/scripts/adia-info" [dir]` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT`
+in Claude Code; the plugin's installed directory in Codex) with the directory named in the
+current request, and present
 the JSON as a short read: each field with the signal it derived from and
 the decision it drives (screen-composition §Current project context carries the
 field→decision table). An `installedVersion` that is null or mismatched vs

package/prompts/app-migration.md

@@ -3,7 +3,7 @@ description: "Migrate consumer code across @adia-ai versions (or port a foreign
 argument-hint: "[target version]"
 ---
 
-Migrate this codebase. **$ARGUMENTS**
+Migrate this codebase to the target version named in the current request.
 
 Invoke **`app-migration`**: read the shipped guide for the span
 (`node_modules/@adia-ai/web-components/MIGRATION.md` — install/upgrade the

package/prompts/app-planning.md

@@ -3,10 +3,11 @@ description: "Orient in an existing adia-ui app — classify rendering mode, pro
 argument-hint: "[path or question]"
 ---
 
-Orient in this repo. **$ARGUMENTS**
+Orient in this repo, answering the path or question named in the current request.
 
 Invoke **`app-planning`** and produce the Orientation Record in the skill's
 own contract shape (Rendering mode · Project shape · Shell · Task ·
 Screen plan (start mode) · → Route · Verify target · Open questions), each
 axis citing its signal. Self-check the record with
-`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/record-lint" -` before returning it.
+`python3 "<plugin-root>/scripts/record-lint" -` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in
+Claude Code; the plugin's installed directory in Codex) before returning it.

package/prompts/find-unused.md

@@ -3,12 +3,12 @@ description: "Find what a clean @adia-ai upgrade left unused — opt-in layers n
 argument-hint: "[target version]"
 ---
 
-Find what this app is not using. **$ARGUMENTS**
+Find what this app is not using, scoped to the target version named in the current request.
 
 Invoke **`find-unused`**: enumerate every `@adia-ai/*` package each manifest
 declares (never assume `web-components`), recon the three versions that differ
-per package — declared range, installed, and the target: **the version in
-`$ARGUMENTS` when one was given, registry latest only as the default**. Read
+per package — declared range, installed, and the target: **the version named in the current request
+when one was given, registry latest only as the default**. Read
 every `node_modules/@adia-ai/*/CHANGELOG.md` section across the
 installed→target span, then run all four audits — inert opt-in layers, redundant local
 workarounds, retired enum values sitting in persisted state, and shipped

package/prompts/gen-ui-wiring.md

@@ -3,7 +3,7 @@ description: "Author a generative-UI experience — wire the a2ui runtime, gener
 argument-hint: "[experience or surface]"
 ---
 
-Build a gen-UI experience. **$ARGUMENTS**
+Build the gen-UI experience or surface named in the current request.
 
 Invoke **`gen-ui-wiring`** and run its generate → validate → render → iterate
 loop; generated A2UI is validated as data before it is serialized, and the

package/prompts/project-scaffolding.md

@@ -3,10 +3,11 @@ description: "Scaffold a new adia-ui app, page, or component skeleton (scripts/a
 argument-hint: "[spa|ssr|page|component|inventory|selftest] [name or app-root]"
 ---
 
-Scaffold an adia-ui surface. **$ARGUMENTS**
+Scaffold the adia-ui surface named in the current request.
 
 Invoke **`project-scaffolding`** to classify the project shape and target, then use
-`${CLAUDE_PLUGIN_ROOT}/scripts/adia-scaffold` for the mechanical skeleton. Shapes
+`<plugin-root>/scripts/adia-scaffold` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in Claude
+Code; the plugin's installed directory in Codex) for the mechanical skeleton. Shapes
 the bin doesn't one-shot (rollup, shared-foundation) are composed per the
 project-shapes reference. `inventory <app-root>` scores an existing app
 against the structure rubric (4 mechanized gates with cited paths + the 2

package/prompts/surface-qa.md

@@ -3,7 +3,7 @@ description: "Run the consumer-side exit gate on a composed surface — dispatch
 argument-hint: "[url or surface] [key selectors]"
 ---
 
-Verify a composed surface. **$ARGUMENTS**
+Verify the composed surface named in the current request.
 
 Dispatch the **surface-qa-agent** agent on the named surface/URL — the exit
 gate runs ISOLATED from whatever context built the surface (generator ≠

package/prompts/theme-audit.md

@@ -3,9 +3,9 @@ description: "Classify a consumer app's theme.css against what the adia-ui frame
 argument-hint: "[--theme <file>] [--app <root>]"
 ---
 
-Audit a theme stylesheet. **$ARGUMENTS**
+Audit the theme stylesheet named in the current request.
 
-Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/adia-theme-audit.mjs" --theme <file>
+Run `node "<plugin-root>/scripts/adia-theme-audit.mjs" --theme <file>
 --app <root>` (add `--json`/`--json-out <path>` for a structured report,
 `--strict` to exit non-zero on any `high`-confidence finding, `--class
 1,2,3,4` to narrow scope). No `@adia-ai/web-components` resolvable from

package/references/authoring-components.md

@@ -109,4 +109,4 @@ The mechanizable smells the framework audits — these seed the phase-(c) hook a
 | Hardcoded `open` on `<modal-ui>`/`<drawer-ui>` | drive via `.open = true` |
 | `new URL('…', import.meta.url)` literal for a corpus path | hold the path in a variable first |
 
-Run the plugin's `scripts/adia-lint` on changed files, the framework's `audit:*` gates when you have the repo, and `mcp__a2ui__check_anti_patterns` / `validate_schema` on generated markup.
+Run the plugin's `scripts/adia-lint.mjs` on changed files, the framework's `audit:*` gates when you have the repo, and `mcp__a2ui__check_anti_patterns` / `validate_schema` on generated markup.

package/references/composed-surface-rubric.md

@@ -72,5 +72,5 @@ Verdict: <shippable | blocked: D#…>
 
 _Provenance: the two-axis COMPOSE/REALIZE defect-quadrant model is adapted from a component-grading
 rubric; the audit tool names and slot contracts here are the factory plugin's own (`adia-lint`,
-`adia-probe`, the current primitive catalog). Verify a named audit rule against `scripts/adia-lint`'s
+`adia-probe`, the current primitive catalog). Verify a named audit rule against `scripts/adia-lint.mjs`'s
 actual rule set before citing it._

package/references/shell-admin.md

@@ -89,7 +89,7 @@ SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only th
 
 - **Piecemeal import** → `AdminSidebar`/`AdminCommand` unregistered; `.toggle()/.show()` undefined. Import the barrel.
 - **Wrapping shell children in `<col-ui>`/`<row-ui>`** → breaks the grid (it reads tag selectors). Generics go _inside_ `admin-content`/`admin-page-body`.
-- **Raw `<header>` vs `<header-ui>` inside `<admin-page-header>`**: both work — the shell CSS targets `admin-page-header > :is(header, header-ui)` identically (css/admin-shell.templates.css:39), and the CHANGELOG's canonical composition uses raw `<header>`. Pick either; just don't wrap the header in a layout primitive.
+- **Raw `<header>` vs `<header-ui>` inside `<admin-page-header>`**: always use `<header-ui>`. The shell CSS targets `admin-page-header > :is(header, header-ui)` identically for geometry (css/admin-shell.templates.css:39), but only `<header-ui>` has the shadow DOM that routes `slot="heading"` / `slot="description"` / `slot="icon"` / `slot="action"` children — a raw `<header>` matches the CSS rhythm but silently drops every named slot.
 - **`[resizable]` without a child `<div data-sidebar-resize>`** → no drag handle.
 - **Hardcoded `[collapsed]`** → won't auto-clear on resize; use `.collapse()/.expand()`.
 - **Multiple `<admin-page>` in one `<admin-scroll>`** → single-axis scroll breaks; one page per scroll.

package/scripts/adia-lint.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * adia-lint.mjs — thin Node CLI consuming the vendored generated rule bank
+ * (lint-rules.generated.mjs, LLD-0016 §C5) for adia-ui CONSUMER apps: the
+ * same structural-smell checks adia-lint (Python) ran, now run 'shared' +
+ * 'consumer-only' scope rules — keeps the SSR/hardcoded-open/LLM-key/genui
+ * traps forge-lint drops. See ADR-0099 for why this replaced the Python
+ * script as the hooks.json entry point.
+ *
+ * Usage:
+ *   adia-lint.mjs <file>...   lint files; exit 1 if any error-severity finding, else 0
+ *   adia-lint.mjs -           lint stdin as a generic source file
+ *   adia-lint.mjs --hook      PostToolUse hook mode: read event JSON on stdin, lint the
+ *                             written source file, print advisory findings, ALWAYS exit 0
+ *   adia-lint.mjs -h/--help   print usage, exit 0
+ *   adia-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, not a packed/vendored install
+ * elsewhere — walk up from this file rather than a fixed `../..` depth,
+ * since this 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 { lintText } = makeLinter(RULES, { scopes: ['shared', 'consumer-only'] });
+const USAGE = 'usage: adia-lint.mjs <file>...  |  adia-lint.mjs -  |  adia-lint.mjs --hook  |  adia-lint.mjs selftest';
+
+function render(path, findings) {
+  const out = [`adia-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 segs = path.replace(/\\/g, '/').split('/');
+  if (segs.some((s) => ['node_modules', 'dist', 'build', '.next', 'coverage'].includes(s))) 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  (adia-lint advisory — adia-ui authoring smells; the skills + a2ui MCP 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('consumer-only')) continue;
+    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])}`);
+    }
+  }
+  const savedWrite = process.stdout.write.bind(process.stdout);
+  let hookOut = '';
+  process.stdout.write = (chunk) => { hookOut += chunk; return true; };
+  const stdinMock = Buffer.from(JSON.stringify({ tool_input: { file_path: 'x.css', content: '@scope (x) {\n :scope { color:#f00; }\n}' } }));
+  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');
+  }
+
+  // REQ-05 (gh#1136): -h/--help exits 0 and prints usage.
+  for (const flag of ['-h', '--help']) {
+    const saved = console.log;
+    let helpOut = '';
+    console.log = (msg) => { helpOut += msg + '\n'; };
+    let rcHelp;
+    try {
+      rcHelp = await main([flag]);
+    } finally {
+      console.log = saved;
+    }
+    if (rcHelp !== 0) {
+      ok = false;
+      console.error(`selftest: ${flag} did not exit 0`);
+    }
+    if (!helpOut.startsWith('usage:')) {
+      ok = false;
+      console.error(`selftest: ${flag} did not print usage`);
+    }
+  }
+
+  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();
+  if (argv.includes('-h') || argv.includes('--help')) {
+    console.log(USAGE);
+    return 0;
+  }
+  const args = argv.filter((a) => a === '-' || !a.startsWith('-'));
+  if (!args.length) {
+    console.error(USAGE);
+    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)));