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

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/commands/release.md

@@ -1,10 +1,12 @@
 ---
-description: Cut, tag, publish, and deploy an @adia-ai release (11-package lockstep — 9 npm libraries + 2 Claude Code plugins). Stops for sign-off before every irreversible step.
+description: Cut, tag, publish, and deploy an @adia-ai release (11-package lockstep — 9 npm libraries + 2 Claude Code plugins). This invocation IS the authorization for the whole cycle; only gate failures stop it.
 argument-hint: "[version or package]"
 ---
 
 Run a release. **$ARGUMENTS**
 
 Invoke **`adia-release`** and run its cut procedure end-to-end: pre-flight
-gates → cut → tag → publish → deploy → notes, stopping for operator sign-off
-at each irreversible step. The skill owns the discipline; don't restate it here.
+gates → cut → tag → publish → deploy → notes. This command's invocation is
+the operator's single authorization for the entire cycle (§Authorization,
+operator ruling 2026-07-17) — run inline, don't re-ask per step; stop only
+on a gate failure. The skill owns the discipline; don't restate it here.

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.5",
+  "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-a2ui/SKILL.md

@@ -1,11 +1,16 @@
 ---
 name: adia-a2ui
 description: >-
-  Maintains the A2UI pipeline (packages/a2ui/): chunk corpus, compose
-  strategies, calibration, evals, the a2ui MCP. Use when asked to author/fix
-  chunks, tune STRONG_MATCH, lift eval fails, change MCP tools, run pipeline
-  ops, or when a component's A2UI contract can't express a content shape.
-  NOT for app screens (adia-compose).
+  Maintains the A2UI pipeline (packages/a2ui/): the harvested chunk corpus,
+  compose strategies (zettel, chunk-zettel, free-form, monolithic), retrieval,
+  validator, calibration, evals, the a2ui MCP server. Use when asked 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,
+  add or change MCP tools (generate_ui, compose_from_chunks,
+  check_anti_patterns, refine_composition), scan anti-patterns, run pipeline
+  ops, or when a component's A2UI contract can't express a content shape. NOT
+  for app screens (adia-compose), runtime gen-UI app features (adia-genui),
+  primitive authoring (adia-author), or gallery scoring (adia-gen-review).
 disable-model-invocation: false
 user-invocable: true
 ---
@@ -73,7 +78,7 @@ Unmatched work defaults to pipeline-overview and re-classifies from there.
 Full structural gate after any pipeline change:
 
 ```bash
-node scripts/build/components.mjs --verify   # "clean — N files up-to-date" (127 component dirs)
+node scripts/build/components.mjs --verify   # "clean — N files up-to-date" (the N is the gate; dir count drifts, don't pin it)
 npm run verify:traits                        # 100% coverage
 npm run smoke:engines
 npm run smoke:register-engine                # 11/11
@@ -109,3 +114,19 @@ intent → retrieval (chunk / composition search)
 Every change touches exactly one stage; identify which before patching. History
 for any constant or decision lives in git and PR descriptions
 (`git log -S STRONG_MATCH_THRESHOLD -- packages/a2ui`).
+
+## Pipeline Change Record — the output contract
+
+Every change reports:
+
+| Field | Value |
+| --- | --- |
+| Stage touched | retrieval \| strategy engine (zettel/chunk-zettel/free-form/monolithic) \| composer \| validator \| MCP surface |
+| Narrowest gate run | the specific check for the touched stage, + result |
+| Full sequence | `npm run smoke:engines` + `npm run test:a2ui` result |
+| Floors before → after | cov/avg/MRR (zettel) or cov/avg/F1 (free-form) or cov/avg (monolithic) |
+| Re-baseline | no / yes — if yes, the PR that ratified the new floor |
+
+Done when every row is filled and the cited gates are green. NOT done: a
+floor number changed with no before/after comparison, or a threshold tweak
+with no root-cause note for why the floor moved.

package/skills/adia-a2ui/evals/routing-corpus.json

@@ -1,31 +1,38 @@
 {
-  "skill": "adia-a2ui",
-  "description": "Routing corpus — does a phrase route to adia-a2ui (the A2UI/gen-ui pipeline maintainer skill) or to a sibling/off-topic?",
-  "minimums_per_spec": {
-    "trigger_phrases": 10,
-    "adversarial_phrases": 5
-  },
-  "phrases": [
-    { "id": "t1", "phrase": "validate this A2UI document", "should_route_to_a2ui": true },
-    { "id": "t2", "phrase": "harvest a chunk from this HTML demo", "should_route_to_a2ui": true },
-    { "id": "t3", "phrase": "zettel coverage dropped after the last change", "should_route_to_a2ui": true },
-    { "id": "t4", "phrase": "should this repeated subtree become its own chunk", "should_route_to_a2ui": true },
-    { "id": "t5", "phrase": "tune the STRONG_MATCH threshold", "should_route_to_a2ui": true },
-    { "id": "t6", "phrase": "run check_anti_patterns on this rendered HTML", "should_route_to_a2ui": true },
-    { "id": "t7", "phrase": "refine composition with an OAuth row", "should_route_to_a2ui": true },
-    { "id": "t8", "phrase": "MRR dropped in the chunk retrieval eval", "should_route_to_a2ui": true },
-    { "id": "t9", "phrase": "add an MCP tool to the a2ui server", "should_route_to_a2ui": true },
-    { "id": "t10", "phrase": "audit the training data corpus for drift", "should_route_to_a2ui": true },
-    { "id": "t11", "phrase": "diagnose this eval gap and regression", "should_route_to_a2ui": true },
-    { "id": "t12", "phrase": "run the MCP pipeline: generate_ui then validate_schema", "should_route_to_a2ui": true },
-    { "id": "t13", "phrase": "lift a semantic fail under sixty", "should_route_to_a2ui": true },
-    { "id": "t14", "phrase": "why did the composer emit composition-match instead of composition-synthesized", "should_route_to_a2ui": true },
-    { "id": "a1", "phrase": "build a settings page from existing primitives", "should_route_to_a2ui": false, "expected_alternative": "adia-author" },
-    { "id": "a2", "phrase": "add a slot to button-ui and update its yaml contract", "should_route_to_a2ui": false, "expected_alternative": "adia-author" },
-    { "id": "a3", "phrase": "cut a release and bump the version tag", "should_route_to_a2ui": false, "expected_alternative": "adia-release" },
-    { "id": "a4", "phrase": "score the generated UI quality in apps/genui", "should_route_to_a2ui": false, "expected_alternative": "adia-gen-review" },
-    { "id": "a5", "phrase": "run a broad visual QA sweep across site and playgrounds", "should_route_to_a2ui": false, "expected_alternative": "adia-dogfood" },
-    { "id": "a6", "phrase": "fix the @adia-ai/llm SSE adapter", "should_route_to_a2ui": false, "expected_alternative": "adia-llm" },
-    { "id": "a7", "phrase": "explain how React state management works", "should_route_to_a2ui": false, "expected_alternative": "off-topic" }
-  ]
+  "positives": [
+    "validate this A2UI document",
+    "harvest a chunk from this HTML demo",
+    "zettel coverage dropped after the last change",
+    "should this repeated subtree become its own chunk",
+    "tune the STRONG_MATCH threshold",
+    "run check_anti_patterns on this rendered HTML",
+    "refine composition with an OAuth row",
+    "MRR dropped in the chunk retrieval eval",
+    "add an MCP tool to the a2ui server",
+    "audit the training data corpus for drift",
+    "diagnose this eval gap and regression",
+    "run the MCP pipeline: generate_ui then validate_schema",
+    "lift a semantic fail under sixty",
+    "why did the composer emit composition-match instead of composition-synthesized"
+  ],
+  "negatives": [
+    "build a settings page from existing primitives",
+    "add a slot to button-ui and update its yaml contract",
+    "cut a release and bump the version tag",
+    "score the generated UI quality in apps/genui",
+    "run a broad visual QA sweep across site and playgrounds",
+    "fix the @adia-ai/llm SSE adapter",
+    "explain how React state management works",
+    "compose a settings screen from catalog primitives",
+    "mount gen-root and wire data resolvers for end users at runtime",
+    "edit the getting-started docs page on the site"
+  ],
+  "_measured": {
+    "as_of": "2026-07-18",
+    "scorer": "routing_eval.py (nonoun-plugins/forge)",
+    "f1": 0.783,
+    "precision": 1.0,
+    "recall": 0.643,
+    "exit_code": 0
+  }
 }

package/skills/adia-a2ui/references/zettel-calibration.md

@@ -8,7 +8,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `STRONG_MATCH_THRESHOLD = 40`
 
-- **File**: `packages/a2ui/compose/strategies/zettel/generator-adapter.js:89`
+- **File**: `packages/a2ui/compose/strategies/zettel/generator-adapter.js` (`grep -n STRONG_MATCH_THRESHOLD`)
 - **Raised**: 22 → 40 post-incident.
 - **Reason**: at 22, login-form / signup-form played verbatim too often →
   repetitive output. At 40, only near-perfect retrievals (chart-dashboard=48,
@@ -29,7 +29,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `STRONG_RETRIEVAL_SCORE = 8`
 
-- **File**: `chunk-synthesizer.js:31`
+- **File**: `chunk-synthesizer.js` (`grep -n STRONG_RETRIEVAL_SCORE`)
 - **Scale**: corpus-size-**independent** absolute keyword score from
   `chunk-library.js#keywordScore()`: first name-word matches a token **+10**,
   full-query substring **+5**, whole-word token in name **+3**, substring /
@@ -46,7 +46,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `PRE_SEARCH_LIMIT = 30`
 
-- **Files**: `chunk-synthesizer.js:32`, `chunk-refiner.js:32`
+- **Files**: `chunk-synthesizer.js` + `chunk-refiner.js` (`grep -n PRE_SEARCH_LIMIT`)
 - **Reason**: token-budget mitigation — pre-filter the catalog before the LLM
   sees it; the full catalog per prompt would burn tens of thousands of tokens.
 - **Synthesizer**: kind-aware allocation —
@@ -61,7 +61,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `SCOPE_DRIFT_RATIO = 1.5` + `SCOPE_DRIFT_MIN_ACTUAL = 20`
 
-- **File**: `chunk-synthesizer.js:38-39` (exported)
+- **File**: `chunk-synthesizer.js` (exported; `grep -n SCOPE_DRIFT`)
 - Composed envelope's component count > 1.5× the sum of bound chunks' counts
   auto-fires a `scope-drift` issue — catches LLM creative expansion that
   hallucinates components beyond the bound chunks.
@@ -70,7 +70,7 @@ is calibrated against the held-out intent set or production telemetry.
 
 ## `DEFAULT_MAX_ATTEMPTS = 2`
 
-- **Files**: `chunk-refiner.js:31`, `chunk-synthesizer.js:33`
+- **Files**: `chunk-refiner.js` + `chunk-synthesizer.js` (`grep -n DEFAULT_MAX_ATTEMPTS`)
 - Validator-driven retry budget. After 2 failed validations the engine emits
   `synthesis-failed`.
 

package/skills/adia-author/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: adia-author
 description: >-
-  Author or modify code inside the adia-ui monorepo — primitives, shells,
-  demos, component yaml SoTs, the @adia-ai/llm bridge. Use when asked to add
-  or edit a primitive, prop, slot, shell, or component CSS, promote inline
-  UI to a module, or author a demo. NOT for composing app screens from
-  primitives (adia-compose) or pipeline internals (adia-a2ui).
+  Author or modify AdiaUI framework source inside the monorepo — primitives
+  (packages/web-components), shells/composites (packages/web-modules), yaml
+  SoTs, demos. Use when asked to add a new primitive component, add or fix a prop/slot/
+  attribute/CSS variant, update a component's yaml, build or fix a shell
+  (chat-shell, admin-shell, editor-shell — sidebar/pane/bespoke-tier
+  composition), promote or extract repeated inline content into a shared
+  module, audit a component's four-axis contract/token usage/lifecycle
+  (connected/disconnected symmetry) for drift, or author/write a demo or
+  examples.html for a component or composite. NOT for composing app screens
+  from primitives (adia-compose), A2UI pipeline internals (adia-a2ui),
+  @adia-ai/llm adapter/streaming/bridge internals (adia-llm-internals), or
+  site/pages docs pages (adia-site-docs).
 disable-model-invocation: false
 user-invocable: true
 ---
@@ -14,7 +21,9 @@ user-invocable: true
 
 Guard rails for code that lands INSIDE the adia-ui monorepo: primitives
 (`packages/web-components/`), shells and composites (`packages/web-modules/`),
-their `<name>.yaml` SoTs, the `@adia-ai/llm` bridge, and composite demos.
+their `<name>.yaml` SoTs, and composite demos. `@adia-ai/llm` internals
+(adapters, streaming, the bridge) are `adia-llm-internals`'s charter, not
+this skill's — route there.
 Light-DOM is load-bearing: `slot=` attributes are decorative metadata,
 positioning is CSS by tag + ancestor + DOM order — never `::slotted()`,
 `::part()`, or shadow DOM. `.claude/docs/specs/component-token-contract.md`
@@ -30,7 +39,6 @@ wins any tie with this skill. Monorepo source read while authoring (yaml, CSS,
 | Shell / bespoke cluster child (`<admin-*>` `<chat-*>` `<editor-*>` `<simple-*>`) | [shell-patterns.md](references/shell-patterns.md) |
 | Promote repeated inline UI → shared module | [module-promotion.md](references/module-promotion.md) |
 | Contract / token / lifecycle drift audit on an existing component | [token-contract.md](references/token-contract.md) + [anti-patterns.md](references/anti-patterns.md) |
-| Extend `@adia-ai/llm` (provider, streaming, proxy) | [llm-bridge.md](references/llm-bridge.md) |
 | Demo for a composite/module — any `packages/web-modules/**/*.{examples,contents}.html` | [composite-demo-protocol.md](references/composite-demo-protocol.md) — NOT the primitive or promotion paths; they lack the canonical-survey discipline |
 | Convention question ("is this idiomatic?") | [code-style.md](references/code-style.md) — cite the rule, don't expand it inline |
 
@@ -82,7 +90,6 @@ citation mechanically on every web-modules demo write; the
 | Shell | render `packages/web-modules/<cluster>/<name>/<name>.html`; `node scripts/dev/audit-native-primitive-leak.mjs --include=<surface>`; `node scripts/dev/audit-shell-composition.mjs --include=<surface>` for `<admin-shell>` composites |
 | Inline → module promotion | source page renders identically post-refactor (visual sweep + DOM diff) + native-primitive-leak audit on the touched surface |
 | Drift audit | the findings report itself; gates run once a fix is applied |
-| LLM-bridge extension | a real client round-trip parses + returns (`npm run check:lockstep` + `npm run smoke:engines`) |
 | Composite demo | `npm run audit:demo-pattern-source:strict` + `npm run qa:design-coherence:strict` + (8b) `npm run qa:rendered-dom:emit -- --slug=<slug>` |
 
 Full structural-gate sequence after any primitive / shell / promotion work: