@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/agents/routing-corpus.json

@@ -1,67 +1,295 @@
 {
   "$schema": "https://anthropic.com/schemas/agent-routing-evals.v1.json",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Routing-accuracy corpus for the adia-ui-forge in-repo agent roster (6 cards + README). For each user phrase, declares the expected agent that should activate (or null for phrases that route nowhere / off-topic). Scored by `scripts/skills/run-agent-evals.mjs --agents-dir packages/plugins/adia-ui-forge/agents`. Boris falsification test T1 (agent routing). First eval pass 2026-06-08.",
   "scope": "Forge agents: tech-lead, author, a2ui-engineer, release-engineer, repo-steward, spec-architect, verifier.",
   "scoring_notes": "Same TF-IDF scorer as scripts/skills/run-skill-evals.mjs. Treat misroutes as signal to tighten the card's description field. MIN_SCORE_THRESHOLD 2.0 + MIN_MATCH_COUNT 2 required to activate.",
-
   "phrases": [
-    { "id": "tech-lead-01", "phrase": "decompose this feature into layer-slices and assign them",            "expected": "tech-lead", "rationale": "Feature decomposition + assignment — tech-lead's orchestration role." },
-    { "id": "tech-lead-02", "phrase": "gate the release on a green verify pass",                             "expected": "tech-lead", "rationale": "Verify-gate sequencing — tech-lead's integration closure." },
-    { "id": "tech-lead-03", "phrase": "sequence the cross-layer handoff for this release window",            "expected": "tech-lead", "rationale": "Multi-agent handoff sequencing is tech-lead's primary role." },
-    { "id": "tech-lead-04", "phrase": "orchestrate the v0.8.0 release window across all layers",             "expected": "tech-lead", "rationale": "Orchestrate release window — tech-lead." },
-    { "id": "tech-lead-05", "phrase": "I have 6 items for this sprint, who should own what?",                "expected": "tech-lead", "rationale": "Work decomposition + claim assignment — tech-lead." },
-
-    { "id": "author-01",    "phrase": "add a new web-component primitive for timeline-ui",                   "expected": "author", "rationale": "In-tree primitive authoring — author's four-layer scope." },
-    { "id": "author-02",    "phrase": "modify the card-ui yaml to add a compact attribute",                  "expected": "author", "rationale": "In-tree yaml edit — author." },
-    { "id": "author-03",    "phrase": "fix the four-axis contract violation on this component",               "expected": "author", "rationale": "Four-axis contract — author's authoring discipline." },
-    { "id": "author-04",    "phrase": "add a new token to the styles/ foundation bundle",                    "expected": "author", "rationale": "Foundation token authoring — author." },
-    { "id": "author-05",    "phrase": "wire up a .contents.js behavior for the chat surface",                "expected": "author", "rationale": "Functional wiring (.contents.js) is author's scope." },
-    { "id": "author-06",    "phrase": "update the docs site sitemap for the new component page",             "expected": "author", "rationale": "Docs site authoring — author's fourth layer." },
-    { "id": "author-07",    "phrase": "promote inline CSS to a proper @layer module file",                   "expected": "author", "rationale": "Styles refactor — author." },
-
-    { "id": "a2ui-01",      "phrase": "diagnose why zettel composition coverage dropped",                     "expected": "a2ui-engineer", "rationale": "Zettel engine + eval gap diagnosis — a2ui-engineer." },
-    { "id": "a2ui-02",      "phrase": "harvest a new training chunk for the corpus",                          "expected": "a2ui-engineer", "rationale": "Corpus authoring — a2ui-engineer." },
-    { "id": "a2ui-03",      "phrase": "tune the STRONG_MATCH threshold for free-form composition",            "expected": "a2ui-engineer", "rationale": "Strategy calibration — a2ui-engineer." },
-    { "id": "a2ui-04",      "phrase": "add a new MCP tool to the a2ui-mcp server",                           "expected": "a2ui-engineer", "rationale": "MCP server authoring — a2ui-engineer." },
-    { "id": "a2ui-05",      "phrase": "the eval regression shows MRR dropped — investigate",                 "expected": "a2ui-engineer", "rationale": "Eval regression diagnosis — a2ui-engineer." },
-    { "id": "a2ui-06",      "phrase": "extract a fragment from this monolithic HTML pattern for the corpus",  "expected": "a2ui-engineer", "rationale": "Fragment extraction into corpus — a2ui-engineer." },
-
-    { "id": "release-01",   "phrase": "cut a v0.7.17 lockstep release of all 9 packages",                    "expected": "release-engineer", "rationale": "9-package lockstep cut — release-engineer's primary task." },
-    { "id": "release-02",   "phrase": "publish the npm packages after the tag",                               "expected": "release-engineer", "rationale": "npm publish — release-engineer." },
-    { "id": "release-03",   "phrase": "batch push the accumulated v0.7.x releases",                          "expected": "release-engineer", "rationale": "Batch push — release-engineer." },
-    { "id": "release-04",   "phrase": "we shipped a version skip, need to recover",                           "expected": "release-engineer", "rationale": "Version-skip recovery — release-engineer." },
-    { "id": "release-05",   "phrase": "write the GitHub release notes for v0.7.16",                           "expected": "release-engineer", "rationale": "Release notes authoring — release-engineer." },
-    { "id": "release-06",   "phrase": "ship the adia-ui-factory plugin as a standalone version cut",          "expected": "release-engineer", "rationale": "Independent-version plugin ship — also release-engineer." },
-
-    { "id": "steward-01",   "phrase": "audit the .brain folder for stale content",                            "expected": "repo-steward", "rationale": "Repo-brain / memory-layer audit — repo-steward." },
-    { "id": "steward-02",   "phrase": "update the PLAN for the v0.8 milestone",                               "expected": "repo-steward", "rationale": "PLAN/ROADMAP currency — repo-steward." },
-    { "id": "steward-03",   "phrase": "write the migration guide for the v0.7 → v0.8 breaking changes",       "expected": "repo-steward", "rationale": "Migration guide authoring — repo-steward (folds in migration-agent)." },
-    { "id": "steward-04",   "phrase": "harvest a memory entry from today's session",                          "expected": "repo-steward", "rationale": "Memory-layer curation — repo-steward." },
-    { "id": "steward-05",   "phrase": "curate the AGENTS.md stewardship section after the rename",            "expected": "repo-steward", "rationale": "AGENTS.md / skill stewardship — repo-steward." },
-    { "id": "steward-06",   "phrase": "write a postmortem for the 2026-06-02 agent collision incident",       "expected": "repo-steward", "rationale": "Postmortems — repo-steward." },
-
-    { "id": "architect-01", "phrase": "turn this PRD into a locked spec before authoring starts",             "expected": "spec-architect", "rationale": "PRD → spec — spec-architect's primary task." },
-    { "id": "architect-02", "phrase": "author an ADR for the light-DOM substrate decision",                   "expected": "spec-architect", "rationale": "ADR authoring — spec-architect." },
-    { "id": "architect-03", "phrase": "write a design note with guardrails before we build this feature",     "expected": "spec-architect", "rationale": "Design note + guardrails — spec-architect." },
-    { "id": "architect-04", "phrase": "validate this premise before any code is written",                     "expected": "spec-architect", "rationale": "Premise validation (plan-before-execute) — spec-architect." },
-    { "id": "architect-05", "phrase": "I need a spec for the new canvas feature",                             "expected": "spec-architect", "rationale": "Spec authoring — spec-architect." },
-
-    { "id": "verifier-01",  "phrase": "run the visual regression probes on the dogfood app",                  "expected": "verifier", "rationale": "Visual + structural review — verifier." },
-    { "id": "verifier-02",  "phrase": "run a11y probes on the new admin-shell surface",                       "expected": "verifier", "rationale": "A11y probing — verifier." },
-    { "id": "verifier-03",  "phrase": "set up a new gate script to enforce the card-ui body contract",        "expected": "verifier", "rationale": "Test substrate / gate scripts — verifier." },
-    { "id": "verifier-04",  "phrase": "the gen-UI review flagged visual drift — investigate",                  "expected": "verifier", "rationale": "Gen-UI review + visual coherence — verifier." },
-    { "id": "verifier-05",  "phrase": "run the full pre-merge verification pass",                              "expected": "verifier", "rationale": "Pre-merge verify pass — verifier's core role." },
-
-    { "id": "null-01", "phrase": "what's the weather in Helsinki today?",                                      "expected": null, "note": "Off-topic." },
-    { "id": "null-02", "phrase": "explain how React useEffect hooks work",                                     "expected": null, "note": "Generic programming — no forge agent applies." },
-    { "id": "null-03", "phrase": "compose a settings page for a consumer app",                                 "expected": null, "note": "Consumer composition — factory/screen-composer, not a forge card." },
-    { "id": "null-04", "phrase": "scaffold a new SPA host for the consumer's app",                             "expected": null, "note": "Consumer scaffolding — factory, not forge." },
-
-    { "id": "ambig-01", "phrase": "verify the release before cutting",                                        "expected": "verifier", "ambiguous_between": ["verifier", "release-engineer"], "note": "Both cards mention 'verify'. Verifier owns the independent structural pass; release-engineer runs pre-flight gates. Corpus labels verifier for the structural-proof framing; release-engineer for 'pre-flight' framing. This phrasing skews verifier." },
-    { "id": "ambig-02", "phrase": "write up what happened in the last cycle",                                  "expected": "release-engineer", "ambiguous_between": ["release-engineer", "repo-steward"], "note": "Post-cycle writeup defaults to release ledger (release-engineer). If framed as an incident → repo-steward postmortem. Context determines the split." }
+    {
+      "id": "tech-lead-01",
+      "phrase": "decompose this feature into layer-slices and assign them",
+      "expected": null,
+      "rationale": "Feature decomposition + assignment — tech-lead's orchestration role."
+    },
+    {
+      "id": "tech-lead-02",
+      "phrase": "gate the release on a green verify pass",
+      "expected": null,
+      "rationale": "Verify-gate sequencing — tech-lead's integration closure."
+    },
+    {
+      "id": "tech-lead-03",
+      "phrase": "sequence the cross-layer handoff for this release window",
+      "expected": null,
+      "rationale": "Multi-agent handoff sequencing is tech-lead's primary role."
+    },
+    {
+      "id": "tech-lead-04",
+      "phrase": "orchestrate the v0.8.0 release window across all layers",
+      "expected": null,
+      "rationale": "Orchestrate release window — tech-lead."
+    },
+    {
+      "id": "tech-lead-05",
+      "phrase": "I have 6 items for this sprint, who should own what?",
+      "expected": null,
+      "rationale": "Work decomposition + claim assignment — tech-lead."
+    },
+    {
+      "id": "author-01",
+      "phrase": "add a new web-component primitive for timeline-ui",
+      "expected": "component-author",
+      "rationale": "In-tree primitive authoring — author's four-layer scope."
+    },
+    {
+      "id": "author-02",
+      "phrase": "modify the card-ui yaml to add a compact attribute",
+      "expected": "component-author",
+      "rationale": "In-tree yaml edit — author."
+    },
+    {
+      "id": "author-03",
+      "phrase": "fix the four-axis contract violation on this component",
+      "expected": "component-author",
+      "rationale": "Four-axis contract — author's authoring discipline."
+    },
+    {
+      "id": "author-04",
+      "phrase": "add a new token to the styles/ foundation bundle",
+      "expected": "component-author",
+      "rationale": "Foundation token authoring — author."
+    },
+    {
+      "id": "author-05",
+      "phrase": "wire up a .contents.js behavior for the chat surface",
+      "expected": "component-author",
+      "rationale": "Functional wiring (.contents.js) is author's scope."
+    },
+    {
+      "id": "author-06",
+      "phrase": "update the docs site sitemap for the new component page",
+      "expected": "component-author",
+      "rationale": "Docs site authoring — author's fourth layer."
+    },
+    {
+      "id": "author-07",
+      "phrase": "promote inline CSS to a proper @layer module file",
+      "expected": "component-author",
+      "rationale": "Styles refactor — author."
+    },
+    {
+      "id": "a2ui-01",
+      "phrase": "diagnose why zettel composition coverage dropped",
+      "expected": "a2ui-engineer",
+      "rationale": "Zettel engine + eval gap diagnosis — a2ui-engineer."
+    },
+    {
+      "id": "a2ui-02",
+      "phrase": "harvest a new training chunk for the corpus",
+      "expected": "a2ui-engineer",
+      "rationale": "Corpus authoring — a2ui-engineer."
+    },
+    {
+      "id": "a2ui-03",
+      "phrase": "tune the STRONG_MATCH threshold for free-form composition",
+      "expected": "a2ui-engineer",
+      "rationale": "Strategy calibration — a2ui-engineer."
+    },
+    {
+      "id": "a2ui-04",
+      "phrase": "add a new MCP tool to the a2ui-mcp server",
+      "expected": "a2ui-engineer",
+      "rationale": "MCP server authoring — a2ui-engineer."
+    },
+    {
+      "id": "a2ui-05",
+      "phrase": "the eval regression shows MRR dropped — investigate",
+      "expected": "a2ui-engineer",
+      "rationale": "Eval regression diagnosis — a2ui-engineer."
+    },
+    {
+      "id": "a2ui-06",
+      "phrase": "extract a fragment from this monolithic HTML pattern for the corpus",
+      "expected": "a2ui-engineer",
+      "rationale": "Fragment extraction into corpus — a2ui-engineer."
+    },
+    {
+      "id": "release-01",
+      "phrase": "cut a v0.7.17 lockstep release of all 9 packages",
+      "expected": "release-engineer",
+      "rationale": "9-package lockstep cut — release-engineer's primary task."
+    },
+    {
+      "id": "release-02",
+      "phrase": "publish the npm packages after the tag",
+      "expected": "release-engineer",
+      "rationale": "npm publish — release-engineer."
+    },
+    {
+      "id": "release-03",
+      "phrase": "batch push the accumulated v0.7.x releases",
+      "expected": "release-engineer",
+      "rationale": "Batch push — release-engineer."
+    },
+    {
+      "id": "release-04",
+      "phrase": "we shipped a version skip, need to recover",
+      "expected": "release-engineer",
+      "rationale": "Version-skip recovery — release-engineer."
+    },
+    {
+      "id": "release-05",
+      "phrase": "write the GitHub release notes for v0.7.16",
+      "expected": "release-engineer",
+      "rationale": "Release notes authoring — release-engineer."
+    },
+    {
+      "id": "release-06",
+      "phrase": "ship the adia-ui-factory plugin as a standalone version cut",
+      "expected": "release-engineer",
+      "rationale": "Independent-version plugin ship — also release-engineer."
+    },
+    {
+      "id": "steward-01",
+      "phrase": "audit the .brain folder for stale content",
+      "expected": null,
+      "rationale": "Repo-brain / memory-layer audit — repo-steward."
+    },
+    {
+      "id": "steward-02",
+      "phrase": "update the PLAN for the v0.8 milestone",
+      "expected": null,
+      "rationale": "PLAN/ROADMAP currency — repo-steward."
+    },
+    {
+      "id": "steward-03",
+      "phrase": "write the migration guide for the v0.7 → v0.8 breaking changes",
+      "expected": null,
+      "rationale": "Migration guide authoring — repo-steward (folds in migration-agent)."
+    },
+    {
+      "id": "steward-04",
+      "phrase": "harvest a memory entry from today's session",
+      "expected": null,
+      "rationale": "Memory-layer curation — repo-steward."
+    },
+    {
+      "id": "steward-05",
+      "phrase": "curate the AGENTS.md stewardship section after the rename",
+      "expected": null,
+      "rationale": "AGENTS.md / skill stewardship — repo-steward."
+    },
+    {
+      "id": "steward-06",
+      "phrase": "write a postmortem for the 2026-06-02 agent collision incident",
+      "expected": null,
+      "rationale": "Postmortems — repo-steward."
+    },
+    {
+      "id": "architect-01",
+      "phrase": "turn this PRD into a locked spec before authoring starts",
+      "expected": null,
+      "rationale": "PRD → spec — spec-architect's primary task."
+    },
+    {
+      "id": "architect-02",
+      "phrase": "author an ADR for the light-DOM substrate decision",
+      "expected": null,
+      "rationale": "ADR authoring — spec-architect."
+    },
+    {
+      "id": "architect-03",
+      "phrase": "write a design note with guardrails before we build this feature",
+      "expected": null,
+      "rationale": "Design note + guardrails — spec-architect."
+    },
+    {
+      "id": "architect-04",
+      "phrase": "validate this premise before any code is written",
+      "expected": null,
+      "rationale": "Premise validation (plan-before-execute) — spec-architect."
+    },
+    {
+      "id": "architect-05",
+      "phrase": "I need a spec for the new canvas feature",
+      "expected": null,
+      "rationale": "Spec authoring — spec-architect."
+    },
+    {
+      "id": "verifier-01",
+      "phrase": "run the visual regression probes on the dogfood app",
+      "expected": "framework-verifier",
+      "rationale": "Visual + structural review — verifier."
+    },
+    {
+      "id": "verifier-02",
+      "phrase": "run a11y probes on the new admin-shell surface",
+      "expected": "framework-verifier",
+      "rationale": "A11y probing — verifier."
+    },
+    {
+      "id": "verifier-03",
+      "phrase": "set up a new gate script to enforce the card-ui body contract",
+      "expected": "framework-verifier",
+      "rationale": "Test substrate / gate scripts — verifier."
+    },
+    {
+      "id": "verifier-04",
+      "phrase": "the gen-UI review flagged visual drift — investigate",
+      "expected": "framework-verifier",
+      "rationale": "Gen-UI review + visual coherence — verifier."
+    },
+    {
+      "id": "verifier-05",
+      "phrase": "run the full pre-merge verification pass",
+      "expected": "framework-verifier",
+      "rationale": "Pre-merge verify pass — verifier's core role."
+    },
+    {
+      "id": "null-01",
+      "phrase": "what's the weather in Helsinki today?",
+      "expected": null,
+      "note": "Off-topic."
+    },
+    {
+      "id": "null-02",
+      "phrase": "explain how React useEffect hooks work",
+      "expected": null,
+      "note": "Generic programming — no forge agent applies."
+    },
+    {
+      "id": "null-03",
+      "phrase": "compose a settings page for a consumer app",
+      "expected": null,
+      "note": "Consumer composition — factory/screen-composer, not a forge card."
+    },
+    {
+      "id": "null-04",
+      "phrase": "scaffold a new SPA host for the consumer's app",
+      "expected": null,
+      "note": "Consumer scaffolding — factory, not forge."
+    },
+    {
+      "id": "ambig-01",
+      "phrase": "verify the release before cutting",
+      "expected": "framework-verifier",
+      "ambiguous_between": [
+        "verifier",
+        "release-engineer"
+      ],
+      "note": "Both cards mention 'verify'. Verifier owns the independent structural pass; release-engineer runs pre-flight gates. Corpus labels verifier for the structural-proof framing; release-engineer for 'pre-flight' framing. This phrasing skews verifier."
+    },
+    {
+      "id": "ambig-02",
+      "phrase": "write up what happened in the last cycle",
+      "expected": "release-engineer",
+      "ambiguous_between": [
+        "release-engineer",
+        "repo-steward"
+      ],
+      "note": "Post-cycle writeup defaults to release ledger (release-engineer). If framed as an incident → repo-steward postmortem. Context determines the split."
+    }
   ],
-
   "expected_baseline": {
     "as_of": "2026-06-08",
     "scorer_version": "0.1.0",
@@ -69,21 +297,22 @@
     "scorer_min_match_count": 2,
     "accuracy": 0.935,
     "per_agent_f1": {
-      "a2ui-engineer": 1.00,
+      "a2ui-engineer": 1.0,
       "author": 0.93,
       "release-engineer": 0.92,
-      "repo-steward": 1.00,
-      "spec-architect": 1.00,
-      "tech-lead": 0.80,
+      "repo-steward": 1.0,
+      "spec-architect": 1.0,
+      "tech-lead": 0.8,
       "verifier": 0.91,
       "__null__": 0.89
     },
     "notes": "First measured baseline 2026-06-08 (post-triggers vocabulary pass). Two iterations: (1) 56.5% pre-triggers; (2) 93.5% after adding triggers: fields to all 7 cards. Remaining 3 misroutes are INHERENT-SCORER-LIMITS documented below. null-03/null-04 consumer phrases correctly fire null (forge cards don't match consumer-domain vocabulary).",
-    "strict_floor_accuracy": 0.90,
+    "strict_floor_accuracy": 0.9,
     "named_weakpoints": [
       "tech-lead-04 'orchestrate the v0.8.0 release window across all layers' → author (7.159) over tech-lead (6.753) — margin 0.4 points. Author's description contains @layer which contributes 'layer' token; tech-lead's trigger block has 'release window' + 'orchestrate' but fewer matching tokens in this phrase. Near-tie inherent-scorer-limit; monitor in next pass.",
       "ambig-01 'verify the release before cutting' → tech-lead (3.962) ties verifier (3.962) exactly; alphabetic tiebreak selects tech-lead ('t' > 'v' alphabetically... wait — alphabetic ascending: tech-lead < verifier). Labeled verifier; inherent alphabetic-tie ambiguity.",
       "ambig-02 'write up what happened in the last cycle' → null (max score 1.981 < 2.0 threshold). Only content tokens are 'write' + 'happened'; 'happened' doesn't appear in any card's vocabulary. Inherent: vague retrospective phrasing. A real orchestrator would ask 'release ledger or incident postmortem?'."
     ]
-  }
-}
+  },
+  "notes": "Re-keyed to the v2 4-agent roster 2026-07-11 (tech-lead/spec-architect/repo-steward retired — their phrases now expect null: the host loop owns orchestration/specs/hygiene)."
+}

package/bin/demo-postwrite-pattern-gate

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""demo-postwrite-pattern-gate — PostToolUse check: composite demos cite a pattern source.
+
+Composite demos authored without surveying a canonical page produced the
+2026-05 broken-demo cohort; the repo's no-merge CI gate
+(`npm run audit:demo-pattern-source:strict`) enforces a `Pattern source:`
+citation. This hook moves that feedback from CI-time to write-time: when a
+`packages/web-modules/**/*.{examples,contents}.html` file is written without
+the citation, it feeds the repair back immediately.
+
+It checks only the deterministic residue (citation present). Whether the
+cited pattern is APPROPRIATE stays judgment — the adia-author skill's
+composite-demo reference owns that.
+
+Usage:
+  demo-postwrite-pattern-gate --hook       # PostToolUse mode: event JSON on stdin
+  demo-postwrite-pattern-gate selftest     # prove matcher + content check on fixtures
+"""
+import json
+import os
+import sys
+
+MARKER = "Pattern source:"
+
+
+def in_scope(path):
+    return "packages/web-modules/" in path and (
+        path.endswith(".examples.html") or path.endswith(".contents.html")
+    )
+
+
+def check_content(text):
+    return MARKER in text
+
+
+def hook_mode():
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        return 0
+    tool_input = event.get("tool_input") or {}
+    path = tool_input.get("file_path") or ""
+    if not in_scope(path):
+        return 0
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            text = f.read()
+    except OSError:
+        return 0
+    if check_content(text):
+        return 0
+    reason = (
+        f"demo-postwrite-pattern-gate · {path} has no `Pattern source:` citation. "
+        "Composite demos must cite the canonical page they pattern from — survey "
+        "apps/<area>/app/**.contents.html + catalog/ui-patterns/ first, then add "
+        "`<!-- Pattern source: <path> -->` near the top (see adia-author's "
+        "composite-demo reference). CI enforces this via "
+        "`npm run audit:demo-pattern-source:strict`. If a citation is genuinely "
+        "impossible, document the carve-out in the file header instead."
+    )
+    print(json.dumps({"decision": "block", "reason": reason}))
+    return 0
+
+
+def selftest():
+    scope_cases = [
+        ("packages/web-modules/shell/admin/admin.examples.html", True),
+        ("packages/web-modules/chat/input/input.contents.html", True),
+        ("packages/web-components/components/badge/badge.html", False),
+        ("apps/tasks/app/index.contents.html", False),
+    ]
+    for path, expected in scope_cases:
+        if in_scope(path) != expected:
+            print(f"selftest: FAIL scope {path}")
+            return 1
+    content_cases = [
+        ("<!-- Pattern source: apps/saas/app/admin/admin.contents.html -->\n<div>", True),
+        ("<div>no citation here</div>", False),
+    ]
+    for text, expected in content_cases:
+        if check_content(text) != expected:
+            print(f"selftest: FAIL content {text[:30]!r}")
+            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/bin/forge-lint

@@ -179,8 +179,19 @@ def _hook():
             return 0
     findings = lint_text(text, path)
     if findings:
-        print(_render(path, findings))
-        print("  (advisory — adia-ui framework authoring smells; the skills own the judgment)")
+        # 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
 
 
@@ -228,11 +239,15 @@ def _selftest():
                                 "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
 

package/bin/sidecar-prewrite-guard

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""sidecar-prewrite-guard — PreToolUse deny on hand-edits to GENERATED artifacts.
+
+The framework's generated files (a2ui sidecars, the trait catalog, the
+component reference) are build outputs of the yaml/source SoT. Hand-editing
+them creates drift the verify gates then hard-fail on. This guard converts
+the former AGENTS.md prose rule ("never hand-edit generated registries")
+into enforcement: it denies Write/Edit on the generated paths with a repair
+message naming the real source + rebuild command.
+
+Deliberately narrow: only the three generated classes below. Bash-driven
+regeneration (npm run components / build:traits) is unaffected — this guard
+watches the Write/Edit tools only.
+
+Usage:
+  sidecar-prewrite-guard --hook       # PreToolUse mode: event JSON on stdin
+  sidecar-prewrite-guard selftest     # prove the matcher on embedded fixtures
+"""
+import json
+import sys
+
+GENERATED = (
+    # (predicate description, matcher fn, source-of-truth + rebuild command)
+    (
+        "trait catalog",
+        lambda p: p.endswith("traits/_catalog.json"),
+        "edit the trait source files and run `npm run build:traits`",
+    ),
+    (
+        "a2ui sidecar",
+        lambda p: p.endswith(".a2ui.json"),
+        "edit the component's `<name>.yaml` SoT and run `npm run components`",
+    ),
+    (
+        "generated component reference",
+        lambda p: "/.claude/docs/reference/components/" in p
+        or p.startswith(".claude/docs/reference/components/"),
+        "edit the component yaml/source and run `npm run docs:reference`",
+    ),
+)
+
+
+def classify(path):
+    for label, match, fix in GENERATED:
+        if match(path):
+            return label, fix
+    return None, None
+
+
+def hook_mode():
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        return 0  # malformed event: stay quiet
+    tool_input = event.get("tool_input") or {}
+    path = tool_input.get("file_path") or ""
+    label, fix = classify(path)
+    if not label:
+        return 0
+    reason = (
+        f"sidecar-prewrite-guard · {path} is a GENERATED {label} — "
+        f"hand-edits are overwritten and fail the drift gates. Instead: {fix}. "
+        "If this block is wrong for this file, report it against "
+        ".claude/docs/specs/plugin-estate-v2.md — do not hand-edit the artifact."
+    )
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason,
+                }
+            }
+        )
+    )
+    return 0
+
+
+def selftest():
+    cases = [
+        ("packages/web-components/traits/_catalog.json", True),
+        ("packages/web-components/components/badge/badge.a2ui.json", True),
+        (".claude/docs/reference/components/table.md", True),
+        ("packages/web-components/components/badge/badge.yaml", False),
+        ("packages/web-components/components/badge/badge.css", False),
+        ("apps/tasks/app/index.html", False),
+    ]
+    for path, should_block in cases:
+        blocked = classify(path)[0] is not None
+        if blocked != should_block:
+            print(f"selftest: FAIL {path} blocked={blocked} expected={should_block}")
+            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/deploy.md

@@ -0,0 +1,9 @@
+---
+description: Deploy a service or dist to the exe.dev VMs (ui-kit.exe.xyz and siblings), or diagnose a running exe service.
+argument-hint: "[host or service]"
+---
+
+Deploy or diagnose an exe.dev surface. **$ARGUMENTS**
+
+Invoke **`adia-deploy`** and follow its playbook for the named host; verify
+against the live endpoint before reporting done.