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

package/skills/primitive-authoring/references/yaml-contract.md

@@ -114,13 +114,106 @@ stricter than the source is a defect, not documentation.
 
 Pipeline: `components.mjs` validates the shape per-yaml, cross-checks every
 referenced name against the full catalog on a full build, and forwards the
-lists onto `x-adiaui` → `catalog-a2ui_0_9.json`.
+lists onto `x-adiaui` → `catalog-a2ui_1_0.json`.
 `scripts/build/derive-genui-catalog.mjs` then translates them into the
-canonical v1.0 key space (yaml `Segmented` → catalog `SegmentedControl`) on
-`base.json`/`adia-pack.json`, where the vendored `@genui/core` validator
-enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier yamls
-(web-modules) carry constraints as dialect-catalog metadata only — modules
-have no v1.0 sidecar.
+canonical v1.0 key space (yaml `Segmented` → catalog `Segmented`, canonical
+per gh#2116) across the five opt-out-scoped catalogs (`adia.core.json`,
+`adia.navigation.json`, `adia.data.json`, `adia.agent.json`,
+`adia.shells.json`, gh#2211/ADR-0093), where the vendored `@genui/core`
+validator enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier
+yamls (web-modules) now carry a v1.0 sidecar too and land in `adia.shells`.
+
+Once a component earns a `component.md` (both `screenReader:` and
+`behavioral:` authored, gh#2615), a non-empty `allowedParents`/
+`allowedChildren` also generates an enforced lint rule (LLD-0016 §C4,
+gh#2647): `scripts/build/gen-composition-rules.mjs` emits `scripts/lint/
+rules/generated/composition/<name>.mjs`, which flags a markup file where
+the tag nests under (or contains) a non-declared tag. Advisory (`warn`)
+until a corpus-wide rollout promotes it (`npm run build:composition-rules`
+/ `check:composition-rules-fresh`).
+
+---
+
+## `examples:` field — a2ui example ids (semantic-id grammar, gh#2492)
+
+Each `examples[].a2ui` block is a JSON array of component nodes (the same
+`updateComponents.components[]` shape `.claude/docs/specs/a2ui-editor.md`
+documents for the editor's live doc store). That spec's line "other
+component ids are free-form (convention: `c-{n}` for generated ids)" governs
+**editor-generated** ids only — ids the editor mints when a human drags a
+component onto the canvas. It was never a license for **authored** ids
+inside a component's own yaml examples, and treating it as one produced a
+corpus-wide drift toward cryptic, positional ids (`q`, `k1`, `k1v`, `hdr`)
+that don't describe what they are once an example has more than one or two
+nodes — reported in gh#2492 against `blockquote.yaml`, `badge.yaml`,
+`aside.yaml`, `alert.yaml`, and `anchor-bar.yaml` (the last four
+corroborating it as a corpus-wide pattern, not a one-off).
+
+**Grammar — authored `a2ui.examples[]` ids only:**
+
+- **Kebab-case, role-descriptive.** The id names what the node IS or DOES in
+  the example, not its position in the array. `quote-body`, not `q` or
+  `node-2`.
+- **Unique per example.** Scoped to one `examples[]` entry, not the whole
+  yaml — reusing `header` across two examples in the same file is fine;
+  reusing an id twice inside one example is not (the renderer's flat
+  `children: string[]` lookup would collide).
+- **Compound ids read parent-then-role** for a node that belongs to a named
+  cluster: `kpi-revenue`, `kpi-revenue-value`, `kpi-revenue-label` — not
+  `k1`, `k1v`, `k1l`. This is what lets a reader studying the copy-paste-able
+  example understand the structure from the ids alone, without cross-
+  referencing the tree.
+- **Exception — the root/wrapper id may stay short when the example has
+  exactly one top-level container and the short id is still a real word**,
+  e.g. `card`, `row`, `panel`, as long as every id it contains follows the
+  grammar. A single generic wrapper doesn't need `card-wrapper-root`; a
+  wrapper's *children* still do.
+- Ids are internal wiring keys (`children: string[]` references, rendered
+  only as `data-a2ui-id`) — never user-visible copy — but they double as the
+  readable structure of the example a consumer studies, which is the whole
+  reason this grammar exists.
+
+**Before / after** (`blockquote.yaml`'s `default` example, gh#2492's
+reported repro):
+
+```jsonc
+// before
+[
+  { "id": "q", "component": "Blockquote", "cite": "…", "children": ["body"] },
+  { "id": "body", "component": "Text", "textContent": "Stay hungry. Stay foolish." }
+]
+
+// after
+[
+  { "id": "quote", "component": "Blockquote", "cite": "…", "children": ["quote-body"] },
+  { "id": "quote-body", "component": "Text", "textContent": "Stay hungry. Stay foolish." }
+]
+```
+
+```jsonc
+// before (badge.yaml chart-dashboard, positional style mixed with semantic
+// ids in the SAME example — k1/k1h/k1v alongside header-row/dash-title)
+{ "id": "k1", "component": "Card", "children": ["k1h", "k1v"] }
+
+// after
+{ "id": "kpi-revenue", "component": "Card", "children": ["kpi-revenue-label", "kpi-revenue-value"] }
+```
+
+**Enforcement**: the `EXAMPLE-ID-GRAMMAR` rule
+(`scripts/lint/rules/shared/example-id-grammar.mjs`, gh#2649 — moved out of
+the retired `scripts/verify/check-example-ids.mjs` into the shared lint
+rule bank per LLD-0016 §C3) walks every yaml's `examples[].a2ui` nodes and
+reports ids that fail the grammar (a bare 1-2 char id, a `^[a-z]\d+`
+positional pattern like `k1`/`c2`, non-kebab-case, or a within-example
+duplicate). gh#2492 Phase 2 swept the corpus-wide 526 violations across 48
+files to zero; `npm run check:example-id-grammar` keeps that promotion
+build-blocking in the `npm run check` chain (non-zero exit on any
+violation) even though the rule's own bank-default severity is
+`advisory` — a new example that violates the grammar now fails the build
+immediately, not just on a future sweep. Known gap: the checker's
+positional-pattern regex catches `letter+digits` (`k1`, `c2`) but not a
+`letter-digit-letter-digit` chain like `g1i1` — out of scope for this
+sweep (nothing flagged it), left for a future refinement.
 
 ---
 
@@ -235,7 +328,7 @@ manifest format. ADR-0066 refines it three ways:
 
 - **`origin: primitive | module` on every L0 entry** — both YAML source
   roots (web-components primitives AND web-modules composites) compile into
-  the same `catalog-a2ui_0_9.json` through one shared contract;
+  the same `catalog-a2ui_1_0.json` through one shared contract;
   `derive-catalog-tiers.mjs` stamps which root an entry came from onto
   `tier-index.json`. A module is legitimately a member of TWO rungs at two
   grains: its component API (props/events/slots) is L0, its assembled shell
@@ -283,6 +376,31 @@ props:
       - ghost
 ```
 
+### Synthesized universal props — `slot` / `hidden` / `ariaLive` / `traits`
+
+`deriveProps()` (`scripts/build/derive-genui-catalog.mjs`) prepends three
+props to every component's generated catalog schema before it ever reads a
+yaml's own `props:` block: `slot: {type: string}`, `hidden: {type:
+boolean}`, `ariaLive: {type: string}` (REQ-013 accessibility pair, gh#1353).
+**No yaml SoT declares any of these** — they're synthesized, not authored,
+and a sidecar that ever DOES declare one of these keys itself simply
+overwrites the synthesized definition.
+
+**Decided but not yet implemented:** ADR-0097
+(`docs/ops/adr/adr-0097-traits-as-a2ui-synthesized-universal-prop.md`,
+ratified via PR #2524) rules that `traits: {type: string}` becomes a fourth
+member of this synthesized set, carrying the same space-separated grammar
+as the existing HTML `[traits="…"]` declarative attribute
+(`.claude/docs/specs/traits.md`, "Method 3" — `"ripple confetti-burst"`,
+not a JSON array) — making `traits` legal on every component's A2UI wire
+schema with no renderer change, and, once wired, checked by
+`catalog-validator.js` against the live trait registry
+(`packages/web-components/traits/_catalog.json`) with a **hard FAIL on an
+unknown trait name** (the same rejection behavior the raw HTML mechanism
+already has). As of this writing `deriveProps()` still synthesizes only the
+three props above and `catalog-validator.js` has no trait-name check —
+gh#2513 tracks the build.
+
 ### `required: true` field
 
 **When to use**: only for props where omitting them makes the component meaningless or inaccessible.
@@ -397,9 +515,9 @@ section IS that call. The family stays `data-*`, undeclared in any yaml,
 with its contract documented at the shared source instead: `core/form.js`'s
 own header JSDoc (the mixin all consumers share) and the canonical
 `form-system` pattern doc (`packages/web-components/patterns/form-system/
-form-system.examples.html`, mirrored at `site-a2ui/pages/
-site__patterns__form-system.a2ui.json`) — both already enumerate the full
-family with a worked example. A future architectural pass that wants to
+form-system.examples.html`, rendered directly at `/site/patterns/form-system`)
+— both already enumerate the full family with a worked example. A future
+architectural pass that wants to
 promote this to a declared per-component contract needs its own ADR (the
 scope is a mixin-wide contract change, not a small-ticket edit); nothing
 here forecloses that, it only records today's call.
@@ -427,15 +545,15 @@ The build:
 **Downstream of the sidecars — two more derived artifacts (gh#970's release-PR stop):**
 
 ```bash
-node scripts/build/derive-genui-catalog.mjs   # genui base.json + adia-pack.json derive FROM the sidecars
+node scripts/build/derive-genui-catalog.mjs   # genui's five opt-out-scoped catalogs derive FROM the sidecars
 npm run check:genui-catalog                    # the drift gate that fails PR CI if you skip the above
 ```
 
 Any yaml change that alters a sidecar's prop schemas STALES the genui
 catalog. The main regen chain (`harvest:chunks` → `build:embeddings:chunks`
-→ `site-a2ui --stale` → `build:patterns-index`) does NOT cover it — it's a
-separate derivation with its own gate, and skipping it passes every local
-check that isn't `check:genui-catalog` itself.
+→ `build:patterns-index`) does NOT cover it — it's a separate derivation
+with its own gate, and skipping it passes every local check that isn't
+`check:genui-catalog` itself.
 
 ---
 

package/skills/site-docs-authoring/SKILL.md

@@ -47,21 +47,19 @@ skill routes to it and enforces it, it does not restate it.
 ## Verify after any change
 
 - `npm run check:links` — intra-repo links across the touched pages.
-- `node scripts/build/site-a2ui.mjs --page <route>` for every page whose
-  **markup** changed — regenerates the compiled A2UI artifact the
-  docs-transpiler produces from this source; a CSS-only fix needs no regen.
+  (Before ADR-0072 Decision 2 / gh#2410 retired site-a2ui, a markup change
+  also needed `node scripts/build/site-a2ui.mjs --page <route>` to
+  regenerate a compiled A2UI artifact. The docs site now renders each
+  route's fragment directly — no compile step, no artifact to regenerate.)
 - `npm run verify:contrast` for any new or changed token used for text or
   link contrast (that gate covers text/link AA pairs only — a non-text 3:1
   claim needs a hand-proved, cited ratio; no mechanical runner exists).
 - `npm run check:lightningcss-build` after any CSS change (`site/site.css`
   or a component's own `.css`).
 - **Visually verify any `alert-ui`/rich-slotted-content change in a
-  browser after regenerating** — a `valid:true` transpiler result and a
-  correct raw-HTML source do not prove the rendered order is correct;
-  the compiled `site-a2ui/pages/*.json` artifact is what's served, and
-  a wrong container tag (`<span>` instead of `<div>`) silently reorders
-  content while still passing schema validation. This is not optional
-  for this one content shape.
+  browser** — a wrong container tag (`<span>` instead of `<div>`) still
+  silently reorders mixed inline content on render even without a compile
+  step; this is not optional for this one content shape.
 
 A check that cannot run (missing script, no network for a build step) is a
 named blocker in the report — flag it and stop; never mark the page done on

package/hooks/hooks.json

@@ -1,44 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/sidecar-prewrite-guard\" --hook"
-          }
-        ]
-      },
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/release-pretag-docs-gate\" --hook",
-            "timeout": 90
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/forge-lint\" --hook"
-          },
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/demo-postwrite-pattern-gate\" --hook"
-          },
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/site-postwrite-derivation-gate\" --hook"
-          }
-        ]
-      }
-    ]
-  }
-}

package/scripts/forge-lint

@@ -1,315 +0,0 @@
-#!/usr/bin/env python3
-"""forge-lint — advisory authoring-smell checker for the adia-ui FRAMEWORK source (maintainer slice).
-
-This is the producer-side counterpart to the consumer plugin's app-lint: it checks the framework's
-OWN component source as a maintainer authors it (primitives in packages/web-components, composites in
-packages/web-modules) for the framework's structural invariants — light-DOM only (no attachShadow,
-no ::slotted), component CSS is `@scope`-wrapped and token-only (no raw colors, no raw px >= 3, no
-extent on :scope, no dead `--a-font`), property definitions are well-formed (no `default: true`, no
-`attr:` typo), composites use `*-ui` primitives (no native-primitive leak), and no retired shell
-shapes (ADR-0024 data-attribute forms). Foundation/token sheets (a styles/ or tokens/ dir, a
-tokens/theme/host/palette/… stem, or `/* forge-lint: foundation */`) are exempt from the CSS-literal
-and scope checks.
-
-It deliberately does NOT carry the consumer/app traps (SSR double-router, top-level kit import,
-hardcoded overlay open) — those are about CONSUMING the framework in an app and live in the
-consumer plugin. forge-lint judges only authoring structure, never whether a component is good,
-accessible, or on-spec — that lives in the skills (adia-ui-authoring / -a2ui / -gen-review / -dogfood).
-A clean forge-lint says "no structural tells," never "this is right."
-
-Shared core: the regex bank below (RAW-COLOR/PX, SCOPE-EXTENT, NATIVE-PRIMITIVE, LEGACY-SHELL,
-the _is_foundation_css exemption) is mirrored in the sibling CONSUMER plugin's
-adia-ui-factory/scripts/adia-lint. They are deliberate VENDORED copies — the catalog forbids
-cross-plugin imports (each plugin installs copy-alone) — so any change to a shared rule must be
-reconciled in BOTH files. forge-lint drops the consumer/app traps (SSR double-router, top-level
-import, hardcoded overlay open) and adds MISSING-SCOPE; that divergence is the point.
-
-Usage:
-  forge-lint <file>...        # lint files; exit 1 if any smell found, else 0
-  forge-lint -                # lint stdin as a generic source file
-  forge-lint --hook           # PostToolUse hook mode: read event JSON on stdin, lint the written
-                              #   source file, print advisory findings, ALWAYS exit 0 (never blocks)
-  forge-lint selftest         # run built-in fixtures (seeded smells + clean files + the hook exit-0 invariant)
-Stdlib only (Python 3.8+).
-"""
-import json
-import os
-import re
-import sys
-
-CODE_EXT = (".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx")
-STYLE_EXT = (".css",)
-MARKUP_EXT = (".html", ".htm", ".vue", ".svelte", ".astro", ".tsx", ".jsx")
-LINT_EXT = tuple(sorted(set(CODE_EXT + STYLE_EXT + MARKUP_EXT)))
-
-HEXCOLOR = re.compile(r"#[0-9a-fA-F]{3,8}\b")
-FUNCCOLOR = re.compile(r"\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\s*\(")
-DEAD_FONT = re.compile(r"var\(\s*--a-font\s*[,)]")
-SCOPE_EXTENT = re.compile(
-    r":scope(?:\[[^\]]*\])?\s*\{[^{}]*?\b(?:width|height|inline-size|block-size)\s*:", re.S)
-BOOL_TRUE = re.compile(r"\bdefault:\s*true\b")
-ATTR_TYPO = re.compile(r"\battr:\s*['\"]")
-NATIVE_PRIMITIVE = re.compile(r"<(?:button|input|select|textarea|dialog)(?![\w-])")  # raw native, not a *-ui
-LEGACY_SHELL = re.compile(
-    r"data-chat-(?:messages|input|empty|name)|data-editor-body|data-canvas\b|data-sidebar="
-    r"|data-pane-(?:side|grow)|<aside-ui\b|<dialog\s+data-command")  # retired shell shapes (ADR-0024)
-PX_GE = re.compile(r"(?<![\w.-])(\d+)px\b")   # integer px; fractional (1.5px) deliberately not matched
-SELECTOR_RULE = re.compile(r"(?m)^\s*[.#:\[&\w][^{}\n]*\{")  # a selector opening a rule block
-FOUNDATION_OPT_IN = re.compile(r"forge-lint:\s*foundation", re.I)
-# Genuine token/foundation SHEETS are exempt from the CSS-literal + scope checks — matched by exact
-# stem or a styles/tokens dir, NOT a path substring (so a `color-picker` component is still linted).
-FOUNDATION_STEMS = {"tokens", "token", "theme", "themes", "foundation", "foundations",
-                    "palette", "palettes", "host", "reset", "resets", "scheme", "schemes",
-                    "color", "colors"}
-
-
-def _ext(path):
-    return os.path.splitext(path or "")[1].lower()
-
-
-def _is_foundation_css(path, text):
-    """A genuine token/foundation sheet — exempt from the CSS-literal + scope checks."""
-    segs = (path or "").replace("\\", "/").split("/")
-    if "styles" in segs or "tokens" in segs:
-        return True
-    stem = os.path.splitext(segs[-1])[0].lower() if segs else ""
-    if stem in FOUNDATION_STEMS:
-        return True
-    return bool(FOUNDATION_OPT_IN.search(text[:1000]))
-
-
-def lint_text(text, path=""):
-    """Return a list of (NAME, line, snippet, why) advisory findings."""
-    ext = _ext(path)
-    findings = []
-    is_tokenish = _is_foundation_css(path, text)
-
-    # Comment stripping (gh#976): the v0.8.34 session logged ~30 RAW-PX /
-    # RAW-COLOR / LEGACY-SHELL findings whose "literal" lived inside a
-    # comment (px values and hex codes QUOTED in prose). Track /* */ state
-    # across lines and match rules against the code that remains; JS line
-    # comments (//) are stripped for CODE_EXT files too.
-    in_block = False
-
-    def _strip_comments(raw):
-        nonlocal in_block
-        out, j, n = [], 0, len(raw)
-        while j < n:
-            if in_block:
-                k = raw.find("*/", j)
-                if k == -1:
-                    return "".join(out)
-                in_block = False
-                j = k + 2
-                continue
-            k = raw.find("/*", j)
-            m = raw.find("//", j) if ext in CODE_EXT else -1
-            if m != -1 and (k == -1 or m < k):
-                out.append(raw[j:m])
-                return "".join(out)
-            if k == -1:
-                out.append(raw[j:])
-                return "".join(out)
-            out.append(raw[j:k])
-            in_block = True
-            j = k + 2
-        return "".join(out)
-
-    for i, line in enumerate(text.splitlines(), 1):
-        s = line.strip()[:90]
-        line = _strip_comments(line)
-        if not line.strip():
-            continue
-        if "attachShadow" in line:
-            findings.append(("SHADOW-DOM", i, s,
-                             "adia-ui is light-DOM — never attachShadow; it breaks the token cascade + @scope"))
-        if "::slotted(" in line:
-            findings.append(("SLOTTED", i, s,
-                             "light DOM has no ::slotted — style projected content via :scope > [slot=\"x\"]"))
-        if ext in STYLE_EXT:
-            if DEAD_FONT.search(line):
-                findings.append(("DEAD-FONT-TOKEN", i, s,
-                                 "--a-font is not a real token (resolves to UA serif) — use var(--a-font-family-ui)"))
-            if not is_tokenish:
-                for decl in line.split(";"):  # per-declaration: a literal on a line that also has a var() still counts
-                    d = decl.strip()
-                    if not d or d.startswith(("//", "/*", "*")) or "var(" in decl or "light-dark(" in decl:
-                        continue
-                    if HEXCOLOR.search(decl) or FUNCCOLOR.search(decl):
-                        findings.append(("RAW-COLOR", i, s,
-                                         "component CSS is token-only — replace the literal with var(--a-*) (foundation/token files excepted)"))
-                        break
-            if not is_tokenish and not line.lstrip().startswith("@"):  # skip @media/@container/@scope at-rules
-                for decl in line.split(";"):
-                    if "/*" in decl:                                   # author-annotated carve-out
-                        continue
-                    if any(int(v) >= 3 for v in PX_GE.findall(decl)):
-                        findings.append(("RAW-PX", i, s,
-                                         "no raw px >= 3 in component CSS — use var(--a-space-*); 1-2px hairlines exempt, annotate a deliberate exception with a comment"))
-                        break
-        if ext in CODE_EXT:
-            if BOOL_TRUE.search(line):
-                findings.append(("BOOL-DEFAULT-TRUE", i, s,
-                                 "a boolean prop defaulting true can't be turned off by absence — flip the name so absent = false; if the shape is deliberate, note that UIElement stamps the attribute on connect since gh#961 (attribute-keyed CSS is safe), and the attribute reflects truth"))
-            if ATTR_TYPO.search(line):
-                findings.append(("ATTR-TYPO", i, s,
-                                 "did you mean `attribute:`? `attr:` is silently ignored in a property definition"))
-        if (ext in MARKUP_EXT and "slot=" not in line and not s.startswith(("<!--", "//", "*", "/*"))
-                and NATIVE_PRIMITIVE.search(line)):
-            findings.append(("NATIVE-PRIMITIVE", i, s,
-                             "a composite must build from *-ui primitives (button-ui / input-ui / select-ui / textarea-ui / modal-ui) — raw natives skip focus rings, theming, and form association; a deliberate slotted trigger (with slot=) is the exception"))
-        if LEGACY_SHELL.search(line):
-            findings.append(("LEGACY-SHELL", i, s,
-                             "retired shell shape (ADR-0024, v0.4.0) — use the bespoke tag (chat-thread / chat-composer / chat-empty · admin-sidebar / admin-command · editor-canvas · pane-ui)"))
-
-    if ext in STYLE_EXT:
-        for m in SCOPE_EXTENT.finditer(text):
-            ln = text.count("\n", 0, m.start()) + 1
-            findings.append(("SCOPE-EXTENT", ln, ":scope { … width/height … }",
-                             "a primitive is size-agnostic — let the consumer own width/height; don't set extent on :scope"))
-        # MISSING-SCOPE (maintainer-authoring): a component sheet with rules but no @scope wrapper.
-        if not is_tokenish and "@scope" not in text and SELECTOR_RULE.search(text):
-            findings.append(("MISSING-SCOPE", 1, "(file has CSS rules but no @scope block)",
-                             "component CSS must be wrapped in `@scope (<tag>) { … }` so styles don't leak in light DOM (foundation/token sheets excepted; opt out with /* forge-lint: foundation */)"))
-
-    findings.sort(key=lambda f: (f[1], f[0]))
-    return findings
-
-
-def _render(path, findings):
-    out = [f"forge-lint: {len(findings)} structural smell(s) in {path or '<stdin>'}"]
-    for name, ln, snip, why in findings:
-        out.append(f"  [{name}] line {ln}: {snip}")
-        out.append(f"      → {why}")
-    return "\n".join(out)
-
-
-def _lint_path(path):
-    try:
-        with open(path, encoding="utf-8", errors="replace") as f:
-            return lint_text(f.read(), path)
-    except OSError as err:
-        msg = getattr(err, "strerror", None) or str(err)
-        return [("READ-ERROR", 1, path[:90], f"failed to read file: {msg}")]
-
-
-def _hook():
-    try:
-        event = json.load(sys.stdin)
-    except (json.JSONDecodeError, ValueError):
-        return 0
-    ti = event.get("tool_input", {}) or {}
-    path = ti.get("file_path", "") or ""
-    norm = path.replace("\\", "/")
-    if "packages/web-components/" not in norm and "packages/web-modules/" not in norm:
-        return 0  # scope anchor: framework component source only (the docstring's claim)
-    if _ext(path) not in LINT_EXT:
-        return 0  # only component source; stay quiet otherwise
-    text = ti.get("content")
-    if text is None:
-        if not os.path.isfile(path):
-            return 0
-        try:
-            with open(path, encoding="utf-8", errors="replace") as f:
-                text = f.read()
-        except OSError:
-            return 0
-    findings = lint_text(text, path)
-    if findings:
-        # PostToolUse exit-0 stdout is NOT fed to the model — only structured
-        # JSON reaches it. additionalContext delivers the advisory repair loop
-        # while preserving the never-block invariant.
-        context = (
-            _render(path, findings)
-            + "\n  (forge-lint advisory — adia-ui framework authoring smells; the skills own the judgment)"
-        )
-        print(json.dumps({
-            "hookSpecificOutput": {
-                "hookEventName": "PostToolUse",
-                "additionalContext": context,
-            }
-        }))
-    return 0  # NEVER block
-
-
-def _selftest():
-    """Built-in fixtures: each seeded smell must fire, clean files must stay quiet, --hook must exit 0."""
-    import io
-    cases = [
-        ("packages/web-components/components/x/x.css",
-         "@scope (x) {\n"
-         "  :scope { color:#f00; width:100%; font-family:var(--a-font); padding:24px; }\n"
-         "  :scope > [slot=a]::slotted(p) { margin:0; }\n"
-         "}",
-         {"RAW-COLOR", "SCOPE-EXTENT", "DEAD-FONT-TOKEN", "SLOTTED", "RAW-PX"}),
-        ("packages/web-components/styles/theme.css", ":root { --a-bg: light-dark(#fff, #000); }", set()),
-        ("packages/web-components/components/y/y.css",
-         ".y-thing { margin: 0; }\n.y-thing__row { gap: 4px; }",
-         {"MISSING-SCOPE"}),
-        ("packages/web-components/components/z/z.js",
-         "class Z extends UIElement {\n  static props = { open: { default: true }, label: { attr: 'label' } };\n"
-         "  connected() { this.attachShadow({ mode: 'open' }); }\n}",
-         {"SHADOW-DOM", "BOOL-DEFAULT-TRUE", "ATTR-TYPO"}),
-        ("packages/web-components/components/clean/clean.js",
-         "import { UIElement } from '../../core/element.js';\n"
-         "class Clean extends UIElement { connected() { this.innerHTML = '<col-ui></col-ui>'; } }",
-         set()),
-        ("packages/web-modules/shell/markup.html",
-         "<admin-shell>\n  <button>Save</button>\n  <input type=\"text\">\n  <button-ui slot=\"trigger\">ok</button-ui>\n</admin-shell>",
-         {"NATIVE-PRIMITIVE"}),
-        ("packages/web-modules/chat/legacy.html",
-         "<chat-shell>\n  <section data-chat-messages></section>\n  <chat-input-ui data-chat-input></chat-input-ui>\n</chat-shell>",
-         {"LEGACY-SHELL"}),
-    ]
-    ok = True
-    for name, text, expected in cases:
-        got = {f[0] for f in lint_text(text, name)}
-        if expected - got:
-            ok = False
-            print(f"selftest: {name} MISSING {sorted(expected - got)} (got {sorted(got)})", file=sys.stderr)
-        if not expected and got:
-            ok = False
-            print(f"selftest: {name} expected clean, got {sorted(got)}", file=sys.stderr)
-    saved_in, saved_out = sys.stdin, sys.stdout    # never-block invariant: --hook exits 0 even on smelly input
-    try:
-        sys.stdin = io.StringIO(json.dumps({"tool_input": {"file_path": "c.css",
-                                "content": ".a { color:#f00; }"}}))
-        sys.stdout = io.StringIO()
-        rc = _hook()
-        hook_out = sys.stdout.getvalue()
-    finally:
-        sys.stdin, sys.stdout = saved_in, saved_out
-    if rc != 0:
-        ok = False
-        print("selftest: --hook did not exit 0 on smelly input", file=sys.stderr)
-    if rc == 0 and hook_out and '"hookSpecificOutput"' not in hook_out:
-        ok = False
-        print("selftest: --hook stdout is not structured hookSpecificOutput JSON", file=sys.stderr)
-    print("selftest: PASS" if ok else "selftest: FAIL")
-    return 0 if ok else 1
-
-
-def main(argv):
-    if argv and argv[0] == "selftest":
-        return _selftest()
-    if "--hook" in argv:
-        return _hook()
-    args = [a for a in argv if a == "-" or not a.startswith("-")]
-    if not args:
-        print(__doc__.strip().split("\n\n", 1)[0], file=sys.stderr)
-        return 2
-    total = 0
-    for path in args:
-        if path == "-":
-            findings = lint_text(sys.stdin.read(), "<stdin>")
-            path = "<stdin>"
-        else:
-            findings = _lint_path(path)
-        if findings:
-            total += len(findings)
-            print(_render(path, findings))
-    return 1 if total else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))