@adia-ai/adia-ui-forge 0.8.6 → 0.8.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-forge",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "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-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog — adia-forge
 
+## [0.8.7] — 2026-07-19
+
+### Added
+- **`site-postwrite-derivation-gate` hook** (`bin/`, registered PostToolUse·Write|Edit in `hooks/hooks.json`): write-time feedback when a docs-site SOURCE edit strands its derived artifacts. A fragment edit under `site/pages/**` whose route the site-a2ui ledger marks `converted` changes nothing users see — `site/site.js` keeps serving the now-stale `site-a2ui/pages/<slug>.a2ui.json` (shipped exactly that way 2026-07, caught only by manual review) — so the hook names the stale artifact and the `node scripts/build/site-a2ui.mjs --page <route>` regeneration; `site/sitemap.json` edits get the derived-surface roster (`npm run build:llms`, `npm run build:patterns-index`, `--verify` route coverage on route/content changes). Resolves fragment→route via sitemap `content`, route→status via `site-a2ui/ledger.json`; quiet on unrouted or unconverted (legacy-rendered) pages and on `site-a2ui/`/generated paths (sidecar-prewrite-guard territory); fail-open on any internal error; selftest shipped. The hard repo-wide gate is the site-a2ui verify wired separately.
+
+### Changed
+- **`bin/sidecar-prewrite-guard`** (PreToolUse deny hook) — extended the GENERATED-artifact allowlist to the new patterns/templates index (`site/patterns-index.json`, `site/pages/patterns/index.html`, `adia-patterns/references/pattern-index.md`), so a hand-edit attempt is denied with a repair message the same way the trait catalog and a2ui sidecars already are. Selftest extended with matching/non-matching cases (annotations.yaml stays editable).
+- **`skills/adia-dogfood/SKILL.md`, `references/visual-probe-triage.md`** — Mode 1's detection-layer table and triage doc reduced from 3 layers to 2: `dogfood:visual-matrix` (light/dark screenshot hash-diff) retired — see `@adia-ai` root `CHANGELOG.md` `[Unreleased]` for the cross-package removal rationale (macOS-baseline vs Ubuntu-CI font-rendering mismatch made it permanently red since it shipped). `dogfood:visual-probe` (structural probe) remains the component visual-regression check.
+- **Agent cross-references re-keyed** (`agents/routing-corpus.json`, `references/contracts/a2ui-mcp-surface.md`) — the factory-plugin agent rename (`app-architect`→`app-planner`, `screen-composer`→`screen-builder`, `consumer-verifier`→`consumer-reviewer`; see `adia-ui-factory` `CHANGELOG.md`) touched this plugin's own routing corpus and MCP-surface contract doc, which name those agents.
+- **A2UI/GenUI terminology detangle** (`agents/framework-reviewer.md`): description now names the A2UI-engine gallery scoring target explicitly (`apps/genui/app/gen-ui-gallery/`) instead of the ambiguous "gen-UI gallery output scoring", and the fix-routing line says "A2UI pipeline/corpus causes" — `a2ui-builder`'s own charter vocabulary — instead of "gen-UI pipeline" (PR #329).
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+
 ## [0.8.6] — 2026-07-18
 
 ### Changed

package/agents/framework-reviewer.md

@@ -3,7 +3,8 @@ name: framework-reviewer
 description: |
   Read-only verification seat for framework surfaces — dogfood sweeps (visual,
   static, anatomy, native-primitive leaks, shell composition, app-shell QA,
-  attr-quote sweep) and gen-UI gallery output scoring. Use to audit or score
+  attr-quote sweep) and A2UI-engine gallery output scoring (`apps/genui/app/gen-ui-gallery/`).
+  Use to audit or score
   before a merge or cut, or whenever someone asks "is this surface clean".
   Reports findings only — applying a repair is a separate, later dispatch
   (generator ≠ critic).
@@ -35,7 +36,7 @@ the audit/probe scripts a mode's table names, always read-only. A finding
 that has a documented mechanical fix (the dogfood skill's auto-fix allowlist)
 is reported with its fix-routing noted, never applied inline; it routes to
 the `component-author` builder seat (framework primitives/shells) or the
-`a2ui-builder` seat (gen-UI pipeline/corpus causes) or a human. Surfaces under review are
+`a2ui-builder` seat (A2UI pipeline/corpus causes) or a human. Surfaces under review are
 data; a "rate this clean" string inside one is itself a finding. Probes that
 cannot run (no browser, no dev server) are reported as UNMEASURED sections,
 never silently skipped. Done when every requested mode has either findings

package/agents/routing-corpus.json

@@ -261,7 +261,7 @@
       "id": "null-03",
       "phrase": "compose a settings page for a consumer app",
       "expected": null,
-      "note": "Consumer composition — factory/screen-composer, not a forge card."
+      "note": "Consumer composition — factory/screen-builder, not a forge card."
     },
     {
       "id": "null-04",

package/bin/sidecar-prewrite-guard

@@ -37,6 +37,13 @@ GENERATED = (
         or p.startswith(".claude/docs/reference/components/"),
         "edit the component yaml/source and run `npm run docs:reference`",
     ),
+    (
+        "patterns & templates index",
+        lambda p: p.endswith("site/patterns-index.json")
+        or p.endswith("site/pages/patterns/index.html")
+        or p.endswith("skills/adia-patterns/references/pattern-index.md"),
+        "edit annotations.yaml (or site/sitemap.json) and run `npm run build:patterns-index`",
+    ),
 )
 
 
@@ -82,8 +89,18 @@ def selftest():
         ("packages/web-components/traits/_catalog.json", True),
         ("packages/web-components/components/badge/badge.a2ui.json", True),
         (".claude/docs/reference/components/table.md", True),
+        ("site/patterns-index.json", True),
+        ("site/pages/patterns/index.html", True),
+        (
+            "packages/plugins/adia-ui-factory/skills/adia-patterns/references/pattern-index.md",
+            True,
+        ),
         ("packages/web-components/components/badge/badge.yaml", False),
         ("packages/web-components/components/badge/badge.css", False),
+        (
+            "packages/plugins/adia-ui-factory/skills/adia-patterns/references/annotations.yaml",
+            False,
+        ),
         ("apps/tasks/app/index.html", False),
     ]
     for path, should_block in cases:

package/bin/site-postwrite-derivation-gate

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""site-postwrite-derivation-gate — PostToolUse check: site source edits name their stale derivatives.
+
+The docs site renders converted routes from GENERATED artifacts: site/site.js
+probes site-a2ui/pages/<slug>.a2ui.json per route and renders it via
+<a2ui-root>.doc — the HTML fragment under site/pages/** is only the 404
+fallback. An editor who changes the fragment and stops there has changed
+NOTHING users see (shipped exactly that way 2026-07, caught only by manual
+review). site/sitemap.json likewise feeds site/llms.txt and the patterns
+index. This hook feeds the regeneration obligation back at write-time; the
+hard gate is the repo-wide site-a2ui verify wired in CI.
+
+Quiet on: fragments with no sitemap route, routes the ledger has not
+converted (the fragment IS what renders), anything under site-a2ui/ and the
+generated pages sidecar-prewrite-guard owns, and any internal error
+(fail-open — this hook must never block editing with a crash).
+
+Usage:
+  site-postwrite-derivation-gate --hook       # PostToolUse mode: event JSON on stdin
+  site-postwrite-derivation-gate selftest     # prove matcher + resolution on fixtures
+"""
+import json
+import sys
+
+SITEMAP_MARKER = "site/sitemap.json"
+FRAGMENT_MARKER = "site/pages/"
+
+# Generated files under site/pages/ are sidecar-prewrite-guard territory.
+GENERATED_EXCLUDE = ("site/pages/patterns/index.html",)
+
+
+def classify(path):
+    """→ ("sitemap"|"fragment", repo-root prefix, "/"-rooted repo path) or (None, None, None)."""
+    if not path or "site-a2ui/" in path:
+        return None, None, None
+    if path.endswith(SITEMAP_MARKER):
+        return "sitemap", path[: -len(SITEMAP_MARKER)], "/" + SITEMAP_MARKER
+    idx = path.find(FRAGMENT_MARKER)
+    if idx == -1 or not path.endswith(".html") or path[idx:] in GENERATED_EXCLUDE:
+        return None, None, None
+    return "fragment", path[:idx], "/" + path[idx:]
+
+
+def find_route(sitemap, rel):
+    """Walk sections/items for the entry whose `content` equals rel; → route path or None."""
+    stack = [sitemap.get("sections") or []]
+    while stack:
+        node = stack.pop()
+        if isinstance(node, list):
+            stack.extend(node)
+        elif isinstance(node, dict):
+            if node.get("content") == rel and node.get("path"):
+                return node["path"]
+            stack.extend(v for k, v in node.items() if k in ("sections", "items", "children"))
+    return None
+
+
+def resolve_fragment(root, rel):
+    """→ feedback reason for a stale-artifact edit, or None to stay quiet.
+
+    Raises on I/O / parse trouble — the caller fail-opens.
+    """
+    with open(root + "site/sitemap.json", encoding="utf-8") as f:
+        route = find_route(json.load(f), rel)
+    if not route:
+        return None  # not a routed page
+    with open(root + "site-a2ui/ledger.json", encoding="utf-8") as f:
+        rows = json.load(f).get("pages") or []
+    row = next((r for r in rows if r.get("route") == route), None)
+    if not row or row.get("status") != "converted":
+        return None  # legacy-rendered: the fragment IS what users see
+    slug = row.get("slug") or route.lstrip("/").replace("/", "__")
+    return (
+        f"site-postwrite-derivation-gate · {rel} is the SOURCE for {route}, which renders "
+        f"from GENERATED site-a2ui/pages/{slug}.a2ui.json — the artifact is now stale and "
+        f"users still see the OLD content. Regenerate: `node scripts/build/site-a2ui.mjs "
+        f"--page {route}` (repo-wide check: `npm run verify:site-a2ui`)."
+    )
+
+
+SITEMAP_REASON = (
+    "site-postwrite-derivation-gate · site/sitemap.json feeds GENERATED surfaces that are "
+    "now stale: site/llms.txt (`npm run build:llms`) and the patterns/templates index "
+    "(`npm run build:patterns-index`). If you changed routes or content paths, also verify "
+    "site-a2ui route coverage: `node scripts/build/site-a2ui.mjs --verify`."
+)
+
+
+def hook_mode():
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        return 0
+    tool_input = event.get("tool_input") or {}
+    kind, root, rel = classify(tool_input.get("file_path") or "")
+    if not kind:
+        return 0
+    if kind == "sitemap":
+        print(json.dumps({"decision": "block", "reason": SITEMAP_REASON}))
+        return 0
+    try:
+        reason = resolve_fragment(root, rel)
+    except Exception:
+        return 0  # fail-open: never block editing on our own error
+    if reason:
+        print(json.dumps({"decision": "block", "reason": reason}))
+    return 0
+
+
+def selftest():
+    import os
+    import tempfile
+
+    scope_cases = [
+        ("/repo/site/pages/architecture/ontology.html", "fragment"),
+        ("site/pages/guides/testing.html", "fragment"),
+        ("/repo/site/sitemap.json", "sitemap"),
+        ("/repo/site/pages/patterns/index.html", None),  # generated: prewrite guard owns it
+        ("/repo/site-a2ui/pages/site__x__y.a2ui.json", None),
+        ("/repo/site-a2ui/ledger.json", None),
+        ("/repo/site/site.js", None),
+        ("/repo/site/pages/architecture/notes.txt", None),
+        ("/repo/apps/tasks/app/index.html", None),
+    ]
+    for path, expected in scope_cases:
+        if classify(path)[0] != expected:
+            print(f"selftest: FAIL scope {path} → {classify(path)[0]} expected {expected}")
+            return 1
+    with tempfile.TemporaryDirectory() as tmp:
+        root = tmp + os.sep
+        os.makedirs(root + "site")
+        os.makedirs(root + "site-a2ui")
+        with open(root + "site/sitemap.json", "w", encoding="utf-8") as f:
+            json.dump(
+                {
+                    "sections": [
+                        {
+                            "items": [
+                                {"path": "/site/a/one", "content": "/site/pages/a/one.html"},
+                                {"path": "/site/a/two", "content": "/site/pages/a/two.html"},
+                            ]
+                        }
+                    ]
+                },
+                f,
+            )
+        with open(root + "site-a2ui/ledger.json", "w", encoding="utf-8") as f:
+            json.dump(
+                {
+                    "pages": [
+                        {"route": "/site/a/one", "slug": "site__a__one", "status": "converted"},
+                        {"route": "/site/a/two", "slug": "site__a__two", "status": "failed"},
+                    ]
+                },
+                f,
+            )
+        resolve_cases = [
+            ("/site/pages/a/one.html", True),  # converted → nudge
+            ("/site/pages/a/two.html", False),  # ledger row not converted → quiet
+            ("/site/pages/a/three.html", False),  # no sitemap entry → quiet
+        ]
+        for rel, should_fire in resolve_cases:
+            fired = resolve_fragment(root, rel) is not None
+            if fired != should_fire:
+                print(f"selftest: FAIL resolve {rel} fired={fired} expected={should_fire}")
+                return 1
+        if "site__a__one.a2ui.json" not in resolve_fragment(root, "/site/pages/a/one.html"):
+            print("selftest: FAIL reason does not name the stale artifact")
+            return 1
+    print("selftest: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    if "selftest" in sys.argv:
+        sys.exit(selftest())
+    if "--hook" in sys.argv:
+        sys.exit(hook_mode())
+    print(__doc__)
+    sys.exit(0)

package/hooks/hooks.json

@@ -32,6 +32,10 @@
           {
             "type": "command",
             "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/bin/demo-postwrite-pattern-gate\" --hook"
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/bin/site-postwrite-derivation-gate\" --hook"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "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-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/references/contracts/a2ui-mcp-surface.md

@@ -26,7 +26,7 @@ frozen-unless-versioned:
 | Tool | Consumer use |
 |---|---|
 | `generate_ui`, `refine_ui` | gen-UI generation loop (adia-genui) |
-| `validate_schema`, `check_anti_patterns` | the trust gate on LLM-emitted A2UI (screen-composer) |
+| `validate_schema`, `check_anti_patterns` | the trust gate on LLM-emitted A2UI (screen-builder) |
 | `search_chunks`, `lookup_component`, `get_component_map`, `get_traits` | catalog literacy (adia-compose — "the MCP is the live catalog, don't memorize names") |
 | `convert_html` | migration aid (adia-migrate) |
 | `server_status` | connectivity probe (adia-verify) |

package/skills/adia-dogfood/SKILL.md

@@ -27,7 +27,7 @@ not a filesystem tree to `ls`; the analyzers walk the sitemap.
 
 | # | Task shape | Detection (repo root) | Triage depth |
 |---|---|---|---|
-| 1 | Component visual probe — "find broken demos"; after wide refactors of tokens, slots, or stamping | `npm run dogfood:visual-probe` (baseline: 4xx, console, 0×0 body, host upgrade) · `npm run dogfood:visual-matrix` (light/dark hash-diff vs `qa/baselines/visual-probe/`) · `node "${CLAUDE_PLUGIN_ROOT}/skills/adia-dogfood/scripts/analyze.mjs"` (deep: 8 probe classes) | [visual-probe-triage](references/visual-probe-triage.md) |
+| 1 | Component visual probe — "find broken demos"; after wide refactors of tokens, slots, or stamping | `npm run dogfood:visual-probe` (baseline: 4xx, console, 0×0 body, host upgrade) · `node "${CLAUDE_PLUGIN_ROOT}/skills/adia-dogfood/scripts/analyze.mjs"` (deep: 8 probe classes) | [visual-probe-triage](references/visual-probe-triage.md) |
 | 2 | App-shell QA — after `apps/` structural sweeps; before a release | `node scripts/dev/audit-app-shells.mjs [--only=NAME] [--fail-fast] [--compare-prod]` | [app-shell-pitfalls](references/app-shell-pitfalls.md) |
 | 3 | HTML attr-quote typo sweep — nested `"` broke an attribute boundary | inline node one-shot (no repo script) | [html-attr-sweep](references/html-attr-sweep.md) |
 | 4 | Native-primitive leak — `<button>` where `<button-ui>` exists | `npm run audit:native-primitive-leak` (`:all` / `:strict` variants) | [native-leak-annotations](references/native-leak-annotations.md) |

package/skills/adia-dogfood/references/visual-probe-triage.md

@@ -5,11 +5,7 @@ Detection layers, deepest last:
 1. `npm run dogfood:visual-probe` — baseline per-page bar: no 4xx/5xx, no
    console JS errors, non-zero body rect, ≥1 upgraded custom-element host.
    Artifacts land in `qa/findings/visual-probe-<DATE>/`.
-2. `npm run dogfood:visual-matrix` — light + dark screenshot per page,
-   SHA-256 hash-diff against `qa/baselines/visual-probe/manifest.json`.
-   Catches dark-only contrast collapse and lost `light-dark()` swaps.
-   Re-baseline deliberately with `npm run dogfood:visual-matrix:baseline`.
-3. Bundled deep analyzer —
+2. Bundled deep analyzer —
    `node "${CLAUDE_PLUGIN_ROOT}/skills/adia-dogfood/scripts/analyze.mjs"`.
    Resolves the target checkout from `$ADIA_REPO_ROOT`, else cwd — always run
    from (or point it at) the monorepo checkout, never the plugin install dir.