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

package/bin/release-pretag-docs-gate

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""release-pretag-docs-gate — PreToolUse gate on irreversible release verbs.
+
+Fires before Bash runs a command that makes a release irreversible — tag
+creation (tag-lockstep without --delete), release-tag pushes, publish
+dispatch, or release-pack's handoff mode — and requires the release docs
+to already be in shape: every lockstep CHANGELOG carries the version's
+section (no leftover [Unreleased] content), entry READMEs exist, and the
+team release notes are generated at docs/releases/v<X>.md. The actual
+checks live in the repo (scripts/release/check-release-docs.mjs) so the
+git pre-push hook shares them; this wrapper only classifies the command,
+derives the version, and converts the gate's findings into a deny with
+the repair commands attached.
+
+Born from the v0.8.4 near-miss (2026-07-17): the promotion step was
+skipped, F-N1 fired only after tagging, and the publish shipped tarballs
+with [Unreleased] CHANGELOG headers. This gate runs the same checks at
+the last reversible moment instead.
+
+Deliberately quiet: non-Bash events, non-release commands, --delete /
+--dry runs, and repos without the gate script (consumer installs of this
+plugin) all exit 0 with no output.
+
+Usage:
+  release-pretag-docs-gate --hook       # PreToolUse mode: event JSON on stdin
+  release-pretag-docs-gate selftest     # prove the classifier on fixtures
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+GATE_REL = "scripts/release/check-release-docs.mjs"
+
+# Irreversible release verbs -> how to find the version in the command.
+VERSION_FLAG = re.compile(r"--version[= ]['\"]?(\d+\.\d+\.\d+)")
+# A pushed TAG is a bare token like `v0.8.4`, `web-components-v0.8.4`, or
+# the full-form `refs/tags/v0.8.4`; branch refs (`release/v0.8.4`,
+# `refs/heads/…`) stay reversible and deliberately don't match, as do tag
+# DELETIONS (`:refs/tags/v0.8.4` — leading colon).
+TAG_TOKEN = re.compile(r"^(?:[a-z0-9-]+-)?v(\d+\.\d+\.\d+)$")
+
+# Sentinel: the command is release-irreversible but no single version can
+# be derived (e.g. `git push --tags`) — deny with the doctrine message
+# rather than fail open.
+AMBIGUOUS = "AMBIGUOUS"
+
+
+def classify(command):
+    """Return the target version string when `command` is an irreversible
+    release verb, AMBIGUOUS when it is irreversible but version-less
+    (fail closed), else None."""
+    if not command:
+        return None
+    if "tag-lockstep.mjs" in command or "dispatch-publish.mjs" in command \
+            or ("release-pack.mjs" in command and "--mode handoff" in command):
+        # Reversal / preview / selftest invocations only suppress for these
+        # script verbs (selftest earned its row on first live fire: a
+        # compound running `tag-lockstep.mjs selftest` next to an unrelated
+        # --version flag denied — 2026-07-17).
+        if "--delete" in command or "--dry" in command or "selftest" in command:
+            return None
+        m = VERSION_FLAG.search(command)
+        return m.group(1) if m else None
+    push_m = re.search(r"\bgit\b[^|;&\n]*\bpush\b", command)
+    if push_m:
+        # Scan ONLY the push command's own segment — a compound command's
+        # unrelated text (a PR body mentioning "v0.8.4", a commit message)
+        # must not classify a branch push as a tag push (live false
+        # positive 2026-07-17: `git push <branch> … && gh pr create
+        # --body "…v0.8.4…"` denied).
+        segment = re.split(r"[|;&\n]", command[push_m.start():])[0]
+        # `git push --dry-run` / `-n` never moves refs.
+        if "--dry-run" in segment or re.search(r"\s-n\b", segment):
+            return None
+        # Blanket tag pushes can carry release tags AND break the
+        # one-tag-per-push publish doctrine — fail closed.
+        if "--tags" in segment or "--follow-tags" in segment:
+            return AMBIGUOUS
+        for token in segment.split():
+            token = token.strip("\"'")
+            if token.startswith("refs/tags/"):
+                token = token[len("refs/tags/"):]
+            m = TAG_TOKEN.match(token)
+            if m:
+                return m.group(1)
+        return None
+    return None
+
+
+def find_repo_gate(start):
+    """Walk up from `start` to the git root looking for the gate script —
+    a release command launched from a subdirectory must not bypass the
+    gate just because cwd isn't the repo root."""
+    d = os.path.abspath(start or os.getcwd())
+    for _ in range(12):
+        gate = os.path.join(d, GATE_REL)
+        if os.path.isfile(gate):
+            return d, gate
+        if os.path.isdir(os.path.join(d, ".git")):
+            return None, None  # repo root reached, no gate — consumer repo
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None, None
+        d = parent
+    return None, None
+
+
+def deny(reason):
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }))
+    sys.exit(0)
+
+
+def hook_mode():
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+    if event.get("tool_name") != "Bash":
+        sys.exit(0)
+    version = classify((event.get("tool_input") or {}).get("command", ""))
+    if not version:
+        sys.exit(0)
+    root, gate = find_repo_gate(event.get("cwd"))
+    if not gate:
+        sys.exit(0)  # consumer repo — nothing to enforce here
+    if version == AMBIGUOUS:
+        deny(
+            "release-pretag-docs-gate · blanket tag push in the release monorepo\n"
+            "`git push --tags`/`--follow-tags` can carry release tags unchecked AND\n"
+            "batched tag pushes drop the publish-on-tag triggers (invariant 4).\n"
+            "Push release tags ONE per `git push origin <tag>` instead."
+        )
+    try:
+        proc = subprocess.run(
+            ["node", gate, "--version", version],
+            capture_output=True, text=True, cwd=root, timeout=60,
+        )
+    except (subprocess.TimeoutExpired, OSError) as e:
+        # Fail CLOSED on the release path — an erroring gate is not a pass.
+        deny(
+            "release-pretag-docs-gate · the docs gate itself errored (" + type(e).__name__ + ")\n"
+            "Run it directly to diagnose: node " + GATE_REL + " --version " + version
+        )
+    if proc.returncode == 0:
+        sys.exit(0)
+    findings = (proc.stderr or proc.stdout).strip()
+    deny(
+        "release-pretag-docs-gate · release docs not ready for v" + version + "\n"
+        + findings + "\n"
+        "This command is irreversible (tags/publish) — land the doc fixes via PR first\n"
+        "(invariant 3), then re-run. If a finding seems wrong, report it against\n"
+        "scripts/release/check-release-docs.mjs; do not bypass the gate."
+    )
+
+
+def selftest():
+    cases = [
+        ("node .claude/skills/adia-release/scripts/tag-lockstep.mjs --version 0.8.4", "0.8.4"),
+        ("node .claude/skills/adia-release/scripts/tag-lockstep.mjs --version 0.8.4 --delete", None),
+        ("node scripts/x/dispatch-publish.mjs --version 1.2.3 --verify-triggered", "1.2.3"),
+        ("node release-pack.mjs --mode handoff --version 0.9.0 --yes", "0.9.0"),
+        ("node release-pack.mjs --mode cut --version 0.9.0", None),
+        ("node release-pack.mjs --mode handoff --version 0.9.0 --dry", None),
+        ("git push origin web-components-v0.8.4", "0.8.4"),
+        ("git push origin v0.8.4", "0.8.4"),
+        ('git -C "$REPO" push origin v0.8.4', "0.8.4"),
+        ("git push origin refs/tags/v0.8.4", "0.8.4"),
+        ("git push origin :refs/tags/v0.8.4", None),      # tag DELETION is a reversal
+        ("git push origin v0.8.4 --dry-run", None),
+        ("git push --tags origin", AMBIGUOUS),
+        ("git push --follow-tags origin main", AMBIGUOUS),
+        ("node tag-lockstep.mjs --version '0.8.4'", "0.8.4"),
+        ("git push origin main", None),
+        ("git push -u origin release/v0.8.4", None),  # branch push is reversible
+        # Compound: branch push + unrelated version text in a later command
+        # (PR bodies) must NOT classify as a tag push.
+        ('git push -u origin feat/x 2>&1 | tail -1\ngh pr create --body "the four v0.8.4 defects"', None),
+        ('git push origin v0.8.4 && echo done', "0.8.4"),
+        ("npm run build", None),
+        ("", None),
+    ]
+    for cmd, want in cases:
+        got = classify(cmd)
+        if got != want:
+            print(f"selftest FAIL: classify({cmd!r}) = {got!r}, want {want!r}", file=sys.stderr)
+            sys.exit(1)
+
+    # find_repo_gate walks up from a subdirectory (tempdir fixture — the
+    # v1 bug checked cwd only, so any subdir cwd bypassed the gate).
+    import tempfile
+    with tempfile.TemporaryDirectory() as td:
+        os.makedirs(os.path.join(td, ".git"))
+        os.makedirs(os.path.join(td, "scripts", "release"))
+        open(os.path.join(td, GATE_REL), "w").write("// fixture\n")
+        sub = os.path.join(td, "packages", "deep", "nested")
+        os.makedirs(sub)
+        root, gate = find_repo_gate(sub)
+        if root != td or not gate:
+            print(f"selftest FAIL: find_repo_gate walk-up ({root!r})", file=sys.stderr)
+            sys.exit(1)
+    with tempfile.TemporaryDirectory() as td:
+        os.makedirs(os.path.join(td, ".git"))
+        sub = os.path.join(td, "src")
+        os.makedirs(sub)
+        root, gate = find_repo_gate(sub)
+        if gate is not None:
+            print("selftest FAIL: consumer repo must yield no gate", file=sys.stderr)
+            sys.exit(1)
+    print("selftest OK")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "selftest":
+        selftest()
+    elif len(sys.argv) > 1 and sys.argv[1] == "--hook":
+        hook_mode()
+    else:
+        print(__doc__)

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

@@ -9,6 +9,16 @@
             "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/bin/sidecar-prewrite-guard\" --hook"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/bin/release-pretag-docs-gate\" --hook",
+            "timeout": 90
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "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/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
@@ -81,10 +86,18 @@ npm run test:a2ui                            # 22/22 (+1 skipped OK)
 npm run eval:diff -- --engine zettel         # floors: cov≥87, avg≥85, MRR≥0.94
 npm run check:zettel-eval-regression -- --latest --strict   # mechanical floor gate
 npm run check:free-form-eval-regression -- --latest         # free-form twin
-npm run eval:diff -- --engine free-form      # floors: cov≥90, avg≥83, F1≥55
+npm run eval:diff -- --engine free-form      # floors: cov≥88, avg≥85, F1≥52
 ```
 
-Monolithic floor: cov=100, avg≥95. Dogfood set: 20/20, avg≥95. A failing gate
+The two `check:*-eval-regression` scripts (`scripts/release/check-zettel-eval-regression.mjs`,
+`scripts/release/check-free-form-eval-regression.mjs`) own the floor numbers — read
+their `ALERT_FLOOR` constants before quoting a number here; this file only mirrors
+them and can drift (it once silently regressed to `cov≥40` before the mechanical
+gate existed).
+
+Monolithic floor: cov=100, avg≥95. Dogfood set: 20/20, avg≥95. No mechanical
+regression gate exists for monolithic yet — this floor is convention-only, same
+failure mode the zettel/free-form gates were built to close. A failing gate
 is the artifact — fix at the source (chunk HTML, engine code, tool schema),
 re-run the narrowest gate, then the full sequence. A threshold tweak that
 papers over a failing gate is a regression, not a fix.
@@ -101,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/pipeline-overview.md

@@ -14,7 +14,7 @@ lifecycle), `.claude/docs/specs/package-architecture.md` (package relations).
 | File | Role |
 | --- | --- |
 | `packages/a2ui/compose/core/generator.js` | `generate_ui` orchestrator — instant / pro / thinking / stream modes; multi-turn via `executionId` |
-| `packages/a2ui/compose/strategies/registry.js` | Engine registry — `registerEngine(name, factory)`. Reserved names: `monolithic`, `zettel`, `mcp`, `monolithic-*` |
+| `packages/a2ui/compose/strategies/registry.js` | Engine registry — `registerEngine(name, factory)`. Reserved names: `monolithic`, `monolithic-instant`, `monolithic-pro`, `monolithic-thinking`, `zettel`, `chunk-zettel`, `free-form` |
 | `packages/a2ui/compose/strategies/zettel/` | Zettel + chunk-zettel engines — see [strategy-engines](strategy-engines.md) for the per-file map |
 | `packages/a2ui/compose/strategies/free-form-composer/` | Free-form engine (`index.js`, `system-prompt.js`, `transpile.js`) |
 | `packages/a2ui/compose/strategies/_shared/chunk-loader.js` | Shared chunk loading for engines |

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:
@@ -93,6 +100,7 @@ npm run verify:traits                        # 100% coverage
 npm run smoke:engines                        # green
 node scripts/dev/audit-native-primitive-leak.mjs   # 0 critical leaks
 node scripts/dev/audit-shell-composition.mjs       # 0 critical defects
+node scripts/dev/audit-template-child-conflict.mjs # 0 critical (gh#284 shape — non-null template + slots.default)
 ```
 
 A failed gate is the artifact: fix at the source, re-run the narrowest gate,