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

package/skills/adia-ui-a2ui/references/semantic-fail-lifting.md

@@ -1,120 +0,0 @@
-# Reference: Semantic fail lifting — sub-60 fail triage procedure
-
-**Source:** Absorbed from the former `zettel-internals` skill (§Semantic Fail Lifting) — Phase 3 rollup. **Used by:** mode 5 of `adia-ui-a2ui` (lift semantic fails). **Companion:** `strategy-engines.md`, `zettel-calibration.md`, `eval-diagnostics.md`.
-
----
-
-## Semantic Fail Lifting
-
-Use when `npm run eval:diff -- --engine zettel --semantic` reports any intent with `semanticScore < 60` or `< 70`. These are rows where the judge says the UI emitted for an intent doesn't actually match what was asked for.
-
-## What a sem fail looks like
-
-The judge scores on 3 axes:
-
-- **dominantPattern** (weight 0.5) — does the root/primary component match the intent type? (chat, form, calendar, data-display, nav…)
-- **requiredCapabilities** (weight 0.35) — are the specific controls the intent requires actually present?
-- **forbiddenNoise** (weight 0.15) — are off-topic components prominent?
-
-A sub-60 score almost always means dominantPattern scored < 40.
-
-## Triage procedure
-
-1. Read the latest eval run's `zettel.json` — find rows with `semanticScore < 70`, sorted ascending.
-2. For each row, read `row.semanticAxes.dominantPattern.{expected, observed}` and `row.semanticAxes.requiredCapabilities.missing`.
-3. Group failures into three buckets:
-   - **Thin composition** — retrieved comp exists but is too sparse (e.g., calendar-month-view had nav + weekday labels only, no grid).
-   - **Wrong composition winning** — retrieval collision; a different comp steals the intent via keyword overlap (e.g., empty-state won "error state with retry" because its keywords included both).
-   - **No matching composition exists** — need to author a new one (e.g., no accordion-settings composition existed; drawer-panel won instead).
-
-## Fix strategies (in order of preference)
-
-### Strategy A — Use a domain-specific primitive as the root
-
-The judge weights root component identity and component counts heavily. A Card wrapping 38 Badges
-
-- 43 Texts reads as "data-display" even if a 7-column Grid is inside. Swapping to a semantically-correct primitive fixes this instantly.
-
-Examples that worked:
-
-- calendar: `CalendarPicker` (not Grid of Text) → 32→65
-- chat: `Chat` > `Text[role=user|assistant]` (not Row+Text bubbles) → 52→70+
-- command palette: `Command` > `ActionItem` (not Command > Text) → 42→70+
-
-Check the registry (75+ components) before authoring children. **These do NOT exist**: `ChatMessage`, `CommandItem`, `TimelineItem`. Use:
-
-- Chat children → `Text` with `role="user"|"assistant"`
-- Command children → `ActionItem`
-- Timeline children → freeform (e.g., Row + Icon + Text + Badge)
-
-Inspect `packages/web-components/components/<name>/<name>.a2ui.json` for the component's props/slots/examples before writing the composition.
-
-### Strategy B — Resolve retrieval collisions by keyword surgery
-
-When an unrelated comp wins retrieval, don't just enrich the correct comp — also **strip overlapping keywords from the losing comp**.
-
-Worked example: `empty-state.json` had keywords `["empty", "empty state", "no results", "illustration", "error state", "retry", "nothing"]`. Added new `error-state-retry` composition BUT empty-state still won for "error state with retry" (sem=32) until its keywords dropped `"error state"` and `"retry"`. Then error-state-retry won at sem=91.
-
-### Strategy C — Author a new composition when none exists
-
-Indicators:
-
-- Multiple intents fail pointing at the same wrong candidate
-- Candidate's `dominantPattern.expected` ≠ any existing comp's purpose
-
-When authoring:
-
-- Use `card-header-with-description` fragment for the top (top-leverage fragment at 36+ uses)
-- Use `labeled-toggle` / `labeled-input` fragments for form controls — boosts reuse ratio
-- Put the pattern's signature affordance as the dominant child (Timeline[mode=steps] for a wizard, Textarea+Richtext for an editor, Accordion for settings, etc.)
-- Rich keyword set (15-20 terms) with exact intent phrases and domain synonyms ("import wizard", "csv import", "multi-step form")
-
-## Build + verify loop
-
-After each change:
-
-    node scripts/build/components.mjs           # rebuild
-    node scripts/build/components.mjs --verify  # confirm clean
-
-Then run the semantic eval (cached, so only changed intents re-judge):
-
-    node packages/a2ui/mcp/scripts/eval-diff.mjs --engine zettel --semantic
-
-Compare `avgSem` and the sub-60 list row by row. Cache is content-hashed on (rubricVersion, intent, a2ui-messages) — only changed generations re-judge.
-
-## Don't regress reuse ratio
-
-Adding new compositions without fragments lowers corpus reuse. Threshold is 29.9% (`fragment_refs / composition_nodes`). Watch the post-build line:
-
-    fragment refs: 197 across 664 composition nodes (reuse 29.7%)
-
-Fixes that lift reuse while keeping sem gains:
-
-- Use existing fragments (card-header-with-description, labeled-toggle, labeled-input, footer-cancel-save, icon-title-description) in every new composition
-- Extract an intra-composition fragment if a subtree repeats 10+ times (see `fragment-graph.md` — leverage rule exception #2)
-
-## Verification before done
-
-Full gate sweep:
-
-    node scripts/build/components.mjs --verify \
-      && npm run smoke:engines \
-      && npm run smoke:register-engine \
-      && npm run test:a2ui \
-      && node packages/a2ui/mcp/scripts/eval-diff.mjs --engine zettel --semantic
-
-Thresholds to hold:
-
-- coverage = 100
-- avgScore ≥ 88 (structural)
-- avgSem > baseline
-- reuse ratio ≥ 29.9%
-- test:a2ui green (+ 1 skipped OK)
-
-## Session outcomes cheat sheet
-
-A representative lift cycle — all lifts came from Strategy A + B + C combinations:
-
-calendar-month-view 32 → 65 (A: CalendarPicker root) event-calendar-details 32 → 72 (A: same comp rewrite) error-state-retry 32 → 91 (C: new comp + B: strip empty-state kwds) accordion-settings 32 → 92 (C: new comp, Accordion root) chat-interface 52 → 70+ (A: Chat > Text[role]) command-palette 42 → 70+ (A: Command > ActionItem + shortcuts) data-import-wizard 38 → 70+ (C: new, Timeline[mode=steps] + Upload) markdown-editor-preview 42 → 70+ (C: new, Textarea + Richtext split) notification-preferences 62 → 70+ (C: new, labeled-toggle fragments)
-
-avgSem 83 → 87. Reuse 26.4 → 33.5 (peak) → 29.7 (final).

package/skills/adia-ui-a2ui/references/strategy-engines.md

@@ -1,111 +0,0 @@
-# Reference: Strategy engines — file map + 5 strategy labels + parallel pipelines
-
-**Source:** Absorbed from the former `zettel-internals` skill (Phase 3 rollup). **Used by:** mode 5 of `adia-ui-a2ui` (debug zettel composition). **Companion:** `zettel-calibration.md`, `semantic-fail-lifting.md`, `fragment-graph.md`.
-
----
-
-## File map (~2,936 LOC across 12 files)
-
-```text
-packages/a2ui/compose/strategies/zettel/
-├── generator-adapter.js  202   ← entry point + 5-strategy dispatch
-├── generate.js            15   ← thin wrapper for direct invocation
-├── _smoke.js              37   ← in-tree smoke test
-│
-├── fragment-library.js   209   ← loader: corpus/{fragments,compositions}/*.json
-├── composer.js           146   ← resolves $fragment refs, prefixes IDs, applies bindings
-├── synthesizer.js        343   ← LLM-driven composition (fragment-graph)
-├── session-store.js      121   ← multi-turn artifact tracking (in-memory)
-│
-├── chunk-synthesizer.js  417   ← page-shell + slot-binding (chunk-corpus)
-├── chunk-composer.js     182   ← resolves chunk plan into A2UI messages
-├── chunk-refiner.js      514   ← multi-turn refinement (locator → modifier)
-├── state-cache.js        153   ← bounded LRU keyed by state_id
-└── issue-reporter.js     597   ← telemetry → .brain/audit-history/issues/
-```
-
-## Two parallel pipelines under one strategy
-
-```text
-                 ┌─ retrieval (always tried first)
-                 │   from corpus/fragments + corpus/compositions OR corpus/chunks
-                 │
-generator       │
--adapter.js    ─┼─ session iteration (turn > 1 + LLM)
-                │   reads session-store, hydrates priorTurns into prompt
-                │
-                └─ synthesis fallback (retrieval < threshold + LLM)
-                   ├─ synthesizer.js     (fragment-graph)
-                   └─ chunk-synthesizer  (chunk-corpus)
-```
-
-**These are NOT a hierarchy** — they're two parallel reasoning loops. `zettel` engine = fragment-graph; `chunk-zettel` engine = chunk-corpus. Both register independently in the engine registry.
-
-## The 5 strategy labels (emitted to eval harness)
-
-| Strategy | Trigger | Hot path? |
-| --- | --- | --- |
-| `composition-match` | Fresh retrieval, score ≥ `STRONG_MATCH_THRESHOLD` | Yes — no LLM call |
-| `composition-synthesized` | Fresh LLM composition (no prior turns) | No — LLM call |
-| `composition-iterated` | LLM modified prior turn's template | No — LLM call w/ history |
-| `fragment-candidates` | Retrieval weak + no LLM available → atoms only | Yes — no LLM call |
-| `synthesis-failed` | LLM tried + failed validation | Cold — failure path |
-
-For chunk-zettel, mirror set: `chunk-match`, `chunk-synthesized`, `chunk-iterated`, `chunk-failed`.
-
-## Issue reporter — three call paths
-
-| Path | Trigger | `ctx.reporter` | Suppression |
-| --- | --- | --- | --- |
-| LLM self-fire | `report_issue` MCP tool | `'llm'` | None |
-| Consumer-fire | Human requests bug ticket | `'user'` | None |
-| Engine auto-fire | Internal failure (e.g., scope-drift, synthesis-failed) | `'auto'` | When `ctx.evalMode = true` (avoid eval-run noise) |
-
-**Storage**: `.brain/audit-history/issues/<id>.json` (immutable). Traces > 200KB spill to sidecar `.trace.json`.
-
-**Type taxonomy**:
-
-- `bug` (code defect)
-- `training-gap` (corpus missing a pattern)
-- `protocol-gap` (MCP / engine contract issue)
-- `ux-feedback` (output quality complaint)
-
-**Severity ranks**: `nit` (0) < `drift` (1) < `blocker` (2)
-
-**Owner taxonomy**: `synthesis | retrieval | validator | chunk-corpus | mcp-protocol | unknown`
-
-**Distinct from `.tickets/`** — those are human-authored work items. Issues are runtime telemetry, promoted to tickets during weekly triage when patterns emerge (spec §11.5).
-
-## Session iteration — the priority flag
-
-```js
-if (hasHistory && llmAdapter) {
-  // ALWAYS goes to synthesis with history context.
-  // NEVER picks a fresh retrieved composition on follow-up turns.
-}
-```
-
-This is what makes "add a button" / "hydrate with real images" work — follow-ups modify the existing canvas instead of regenerating.
-
-## Pitfalls
-
-- **`STRONG_MATCH_THRESHOLD` was raised post-incident**. Lowering it back to 22 reverts to repetitive output. If you suspect retrieval is too cold, profile the score distribution first via `searchAll()` debugging, don't just lower the threshold.
-- **`PRE_SEARCH_LIMIT = 30` may be over-permissive at small corpus sizes.** It was calibrated for a much larger corpus. Worth re-tuning post-corpus-migration.
-- **`state-cache` is per-process** — multi-turn breaks across MCP restarts. Anything that needs durable state should write to `.brain/audit-history/` or `.tickets/`, not state-cache.
-- **`issueAccumulator` must be passed via `opts`** to refinement engines — if you wire a new engine, propagate it or auto-fire issues are lost.
-- **Strategy labels are public contract.** The eval harness, MCP tools, and dialog-recorder all pattern-match on the 5 strategy strings. Don't rename without a coordinated migration.
-
-## Verification
-
-```bash
-# Smoke tests (fast, no LLM)
-npm run zettel:smoke
-npm run smoke:engines
-
-# Full eval (slow, real LLM)
-npm run eval:diff -- --engine zettel
-npm run eval:diff -- --engine chunk-zettel
-
-# Issue store sanity (after auto-fire test)
-ls .brain/audit-history/issues/ | head
-```

package/skills/adia-ui-a2ui/references/teach-protocol.md

@@ -1,220 +0,0 @@
-# Reference: Teach Protocol — Absorbing new knowledge into the adia-ui-a2ui skill
-
-**Why authored:** As the A2UI pipeline absorbs new strategies, anti-patterns, calibration constants, MCP tools, and chunk-corpus shapes, each absorption was previously a one-off improvisation. This protocol gives every future "make sure `adia-ui-a2ui` knows about [pattern]" request a deterministic landing path.
-
-**Decision tree is mechanized.** The branch routing below is authoritative in `scripts/teach-route.mjs` (run `node scripts/teach-route.mjs "<payload>"`). The prose here is for human readers — worked examples, anti-patterns, rationale. The script is the routing.
-
-**Used by:** the `adia-ui-a2ui` skill, when an agent receives one of these triggers:
-
-- "make sure `adia-ui-a2ui` knows about [the new strategy / calibration / anti-pattern]"
-- "train `adia-ui-a2ui` on [the new MCP tool / fragment shape / eval finding]"
-- "the skill should know about [the new pattern]"
-- "absorb this lesson into adia-ui-a2ui"
-- "teach the skill about [the new chunk metadata field]"
-
-**Companion:** `eval-diagnostics.md` (run after any pipeline change), `strategy-engines.md` (when the new knowledge is engine-level), and `scripts/audit-a2ui-roster.mjs` (run after any §Teach landing).
-
-**Anti-companion:** `docs/journal/` (arc-specific stories belong in the journal, not the skill — see decision tree Branch H).
-
----
-
-## When to Use
-
-Trigger phrases (from the §Teach section in SKILL.md):
-
-- "make sure `adia-ui-a2ui` knows about X"
-- "train the skill on X"
-- "teach the skill about Y"
-- "the skill should be aware of Z"
-- "absorb [pattern/lesson/feedback] into adia-ui-a2ui"
-- "update the skill to reflect [the new strategy / the new threshold / the new tool]"
-
-The phrases are universal across all extensible skills; the **landing target** is what's specific to this skill.
-
-## Core Principles
-
-### 1. The skill is a CITATION layer, not a KNOWLEDGE layer
-
-Per-strategy facts live in `packages/a2ui/compose/strategies/*/`. Chunk authoring rules live in `packages/a2ui/corpus/CHUNK-AUTHORING.md`. MCP tool schemas live in `packages/a2ui/mcp/server.js`. The skill cites by path; it does NOT duplicate code or schema in prose.
-
-**Rule of thumb:** if you catch yourself writing "the zettel composer does X" in a SKILL.md file, stop. Is that fact in the strategy code already? If yes, cite the path + function name + line range. If no, the fact should land in the substrate first, THEN the skill cites it.
-
-### 2. Trigger surface is universal; landing targets are skill-specific
-
-The activation phrases — "train X on Y", "make sure X knows about Z", "absorb this into X" — are the same regardless of which skill X is. The **landing targets** vary per this skill's references/ topology.
-
-### 3. The negative case (Branch H) is load-bearing
-
-Arc-specific stories ("how I debugged this eval regression last month") belong in `docs/journal/`, not in the skill. The skill is procedural knowledge that will be true tomorrow; arc stories are history that's already finished.
-
-### 4. Eval is the source of truth
-
-When a §Teach landing introduces a calibration tweak or new strategy, the eval gate must agree. If the eval gate disagrees with the landing's intuition, the eval gate wins. Rebaseline if the eval threshold itself is wrong; document in CHANGELOG.
-
-### 5. The 5-step landing procedure generalizes
-
-Step 2 (author) is skill-specific. The other four steps are universal across all extensible skills.
-
-### 6. Anti-patterns are universal
-
-The seven anti-patterns generalize across every roll-up: append-only landing, substrate duplication, orphan triggers, capability menu lies, MINOR + PATCH bundling, hygiene-debt deferral, one-way thinking.
-
----
-
-## The Decision Tree — where does new knowledge land?
-
-Eight branches, each with a worked example. Branch A is the most common landing for substrate-author work; branch H is the negative case (do NOT land in the skill).
-
-### Branch A — New chunk metadata field
-
-**When**: someone adds a new field to chunk JSON (`provenance`, `last_harvested`, etc.) or extends `_index.json` shape.
-
-**Lands at**: `packages/a2ui/corpus/chunks/_index.json` schema documentation in `chunk-authoring.md`. NOT in the skill itself unless the field changes the authoring procedure.
-
-**Worked example**: a `derivation` field was added to chunks recording which HTML demo a chunk was harvested from. Landing: `chunk-authoring.md` got a new section under "Chunk schema" documenting `derivation`. The skill's SKILL.md didn't change.
-
-### Branch B — New MCP tool
-
-**When**: a new tool is exported from `packages/a2ui/mcp/server.js` (e.g., a new `inspect_chunk_keywords` tool joining `search_chunks` + `validate_schema` + `generate_ui`).
-
-**Lands at**: `packages/a2ui/mcp/server.js` (tool implementation) + `mcp-tool-reference.md` (schema doc) + `mcp-pipeline-ops.md` (workflow integration). SKILL.md gets a one-line mention in mode 1's trigger phrases if the tool is operator-facing.
-
-**Worked example**: the `report_issue` MCP tool was added for evolution-engine feedback. Landing was three-fold: server.js implementation + tool-reference schema + pipeline-workflows feedback-loop section.
-
-### Branch C — New strategy / engine
-
-**When**: a new composition strategy is added (e.g., a future `template-match` engine joining `zettel` + `free-form` + `monolithic` + `dogfood`).
-
-**Lands at**: `packages/a2ui/compose/strategies/<name>/` (engine code) + `packages/a2ui/compose/strategies/registry.js` (registration) + `strategy-engines.md` (engine map updated to include the new label). SKILL.md mode 5's trigger phrases may need to mention the new strategy by name.
-
-**Worked example**: the free-form engine was added in a major arc. Landing: new directory under strategies/ + registry.js update + strategy-engines.md got a new section + eval gate added a new threshold row (`cov≥90, avg≥83, F1≥55`).
-
-### Branch D — New anti-pattern rule
-
-**When**: a new anti-pattern is discovered (e.g., "popover-ui without trigger-element rule" joining the existing catalogue).
-
-**Lands at**: `anti-patterns.md` (catalogue entry) + possibly `packages/a2ui/validator/checks/<name>.js` (mechanized check). SKILL.md may need mode 8's trigger phrases extended.
-
-**Worked example**: a "chart-legend-without-tokens" anti-pattern was added during a cross-surface QA arc. Landing: anti-patterns.md got a new rule + validator gained a new check + the sibling `adia-ui-dogfood` skill cross-referenced it.
-
-### Branch E — New calibration constant / threshold
-
-**When**: someone tunes `STRONG_MATCH_THRESHOLD`, `STRONG_RETRIEVAL_SCORE`, the locator weights, or any of the constants in the calibration history.
-
-**Lands at**: `packages/a2ui/compose/strategies/zettel/composer.js` (constant value) + `zettel-calibration.md` (history table — append, never overwrite). SKILL.md doesn't change.
-
-**Worked example**: `STRONG_MATCH_THRESHOLD` was tuned across several arcs. Each tune left a row in `zettel-calibration.md`'s history table with rationale + eval delta. The history is the audit trail.
-
-### Branch F — Methodology / pipeline-design posture
-
-**When**: a new principle / posture emerges that shifts how the pipeline is approached (e.g., "always re-harvest chunks after @bp changes" became a posture during a responsive arc).
-
-**Lands at**: inline in SKILL.md (§Posture or §FirstPrinciples). This is the only branch that touches SKILL.md directly. MINOR version bump.
-
-**Worked example**: the "HTML-first chunk authoring" principle (don't hand-author JSON) was added to §Posture during a training-signal arc.
-
-### Branch G — New fragment-graph node type
-
-**When**: someone extends the fragment graph with a new node type (e.g., adding a `partial` node alongside `fragment` + `composition`).
-
-**Lands at**: `packages/a2ui/compose/strategies/zettel/composer.js` (`$fragment` ref resolution) + `fragment-graph.md` (extended node-type table) + `strategy-engines.md` (how the engine consumes the new type).
-
-**Worked example**: no new node types have been added since the initial fragment-graph design. When one is, the landing pattern follows the existing `$fragment` documentation in fragment-graph.md.
-
-### Branch H (NEGATIVE) — One-off eval debugging arc
-
-**When**: someone debugged a specific eval regression on a specific date. The story has a beginning
-
-- middle + end and won't repeat.
-
-**Lands at**: `docs/journal/` as a dated section. **NOT IN THE SKILL.**
-
-**Worked example**: a chunk-corpus expansion arc (28 → 64 annotated chunks) is documented in the journal. The skill's references mention the eval-floor result (`cov≥90`) but don't reproduce the debugging narrative.
-
-**Why this branch matters**: without it, every §Teach landing risks polluting the skill with arc history. The skill becomes unmaintainable as the journal sections pile up.
-
----
-
-## The Five-Step Landing Procedure
-
-Universal across all extensible skills:
-
-### 1. Audit before patching
-
-- Read the target reference file in full
-- Check working-tree state (`git status`)
-- Grep for existing coverage of the same topic
-- Re-confirm the landing-target choice via the decision tree above (or `scripts/teach-route.mjs`)
-
-### 2. Author the patch (skill-specific)
-
-Where does the new content go in this skill's references/? How is it formatted? What surrounding sections does it impact? Map each branch to its primary reference file (see Decision Tree above).
-
-### 3. Wire the activation surface
-
-- Trigger keywords in SKILL.md frontmatter `trigger:` block (if the new knowledge has new trigger phrases)
-- Capability menu entry (only for new modes — usually not needed for §Teach landings)
-- Binding-procedure line in §Posture or §FirstPrinciples (only for Branch F)
-
-### 4. Version + CHANGELOG
-
-- PATCH for citation strengthening / fact additions
-- MINOR for new procedural sections / new modes
-- MAJOR for renames / removed modes
-
-### 5. Verify with audit-a2ui-roster
-
-```bash
-node scripts/audit-a2ui-roster.mjs --strict
-# expect: all axes green
-```
-
-Plus the eval gate if the landing was strategy/calibration-related:
-
-```bash
-npm run eval:diff -- --engine zettel
-npm run eval:diff -- --engine free-form
-```
-
----
-
-## The 7 Anti-Patterns
-
-Universal across all extensible skills. Each one breaks the skill in a specific way:
-
-| # | Anti-pattern | What breaks |
-| --- | --- | --- |
-| 1 | **Append-only landing** | Content piles at end of section; semantic structure decays |
-| 2 | **Substrate duplication** | Strategy code or chunk schema copied into skill prose; drift on next strategy change |
-| 3 | **Orphan triggers** | Keywords added to frontmatter but no binding section in body |
-| 4 | **Capability menu lies** | Menu item points to non-existent section or stub |
-| 5 | **MINOR + PATCH bundling** | New procedural content cut alongside polish; muddied changelog |
-| 6 | **Hygiene-debt deferral** | Audit regression noticed during landing, deferred to "next cut" |
-| 7 | **One-way thinking** | Lands here without asking "should this be in a sibling skill?" (e.g., a chunk authoring rule might belong in `adia-ui-authoring`'s shell-patterns reference instead of here) |
-
----
-
-## Quick-Reference Card
-
-| Branch | Trigger | Lands at | SKILL.md change? |
-| --- | --- | --- | --- |
-| A | new chunk metadata field | chunk-authoring.md | no |
-| B | new MCP tool | mcp/server.js + mcp-tool-reference.md | minor (mode 1 triggers) |
-| C | new strategy / engine | strategies/ + strategy-engines.md | minor (mode 5 triggers + eval gate row) |
-| D | new anti-pattern rule | anti-patterns.md + validator/checks/ | minor (mode 8 triggers) |
-| E | calibration tune | composer.js + zettel-calibration.md | no |
-| F | methodology / posture | inline SKILL.md (§Posture / §FirstPrinciples) | MINOR bump |
-| G | new fragment-graph node type | composer.js + fragment-graph.md | no |
-| H | arc-specific story | docs/journal/ | **NEVER** |
-
-When in doubt, **prefer Branch H** (journal) over a skill landing. Arc stories that age out are easy to ignore; orphan rules that linger in the skill are hard to remove.
-
----
-
-## Cross-references
-
-- `${CLAUDE_PLUGIN_ROOT}/references/shared/pev-rationale.md` — the Plan-Execute-Verify rationale this §Teach inherits (every landing closes the PEV loop).
-- `scripts/teach-route.mjs` — the authoritative mechanized branch router.
-- `adia-ui-authoring` / `adia-ui-release` — sibling skills; route content there when Branch 7 (one-way thinking) applies.
-- `eval-diagnostics.md` — run after any Branch C / E landing.
-- `strategy-engines.md` + `zettel-calibration.md` — the engine-side substrate.

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

@@ -1,93 +0,0 @@
-# Reference: Zettel calibration — constants + history + locator/modifier two-pass
-
-**Source:** Absorbed from the former `zettel-internals` skill (§Calibration constants + §The locator → modifier two-pass pattern) — Phase 3 rollup. **Used by:** mode 5 of `adia-ui-a2ui` (tune calibration; lift fails). **Companion:** `strategy-engines.md`, `semantic-fail-lifting.md`.
-
-> **Calibration history is the substrate.** Each tweak leaves a row. Read history before retuning — the same value may have been tried and rejected before.
-
----
-
-## Calibration constants — values + history
-
-**Don't change these without running the eval-diff suite first.** Each is calibrated against the held-out 100-intent set or production telemetry.
-
-### `STRONG_MATCH_THRESHOLD = 40`
-
-- **File**: `generator-adapter.js`
-- **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, pricing-tiers=54) match; merely-good fall through to LLM for compositional variety.
-- **Scale**: **Absolute**, not relative. Score is a weighted sum of `semantic_role` (12) + `tags` (5 each) + `keywords` (3 each) matches between query tokens and fragment metadata. Adding/removing fragments from the corpus does not shift any specific (query, fragment) score — it's deterministic per pair. **Don't recalibrate as a function of corpus size** — that would be a misdiagnosis.
-- **Tradeoff**: More LLM calls (slower, costlier) ↔ compositional variety
-- **Re-eval before changing**: `npm run eval:diff -- --engine zettel`
-
-### `STRONG_RETRIEVAL_SCORE = 8`
-
-- **File**: `chunk-synthesizer.js`
-- **Scale**: corpus-size-**independent** absolute keyword score from `chunk-library.js#keywordScore()`. Adding 1k chunks doesn't shift any individual (chunk, query) score. Don't propose recalibration as a function of corpus size — that's a misdiagnosis.
-- **What 8 means**: at least one whole-word overlap between query and chunk name (10), OR full-query substring (5) + ≥1 whole-word token (3). Anything less is a "retrieval too weak — synthesize" signal.
-- **Async path**: `searchChunksAsync` blends `kw + cos*5`. Cosine ranges 0..1 so embeddings contribute 0..5 — pure-cosine matches max out at 5 and won't pass the 8 threshold. **Embeddings are a tie-breaker**, not the primary signal. This is intentional.
-- **Different scale** than fragment-graph `STRONG_MATCH_THRESHOLD=40` (which scores semantic_role + tags + keywords). Don't normalize the two scales — they measure different things.
-- **WONTFIX rationale** documented in the corpus audit reports under `docs/reports/`.
-
-### `PRE_SEARCH_LIMIT = 30`
-
-- **Files**: `chunk-synthesizer.js`, `chunk-refiner.js`
-- **Reason**: Token-budget mitigation — pre-filter catalog before LLM sees it. Sending the full catalog every prompt would burn tens of thousands of input tokens.
-- **Synthesizer** (`chunk-synthesizer.js`): kind-aware allocation — `limit: PRE_SEARCH_LIMIT - pageChunks.length - panelChunks.length`. All pages and panels included unconditionally; blocks fill the remaining budget. **Self-tuning by structure.**
-- **Refiner** (`chunk-refiner.js`): block-only allocation — `limit: PRE_SEARCH_LIMIT` for blocks alone, plus all pages/panels on top. Intentionally more generous because refinement is doing targeted edits and the LLM needs more options.
-- **Don't naively divide PRE_SEARCH_LIMIT by corpus size** to assess over-permissiveness. The kind-aware allocation makes the math non-linear. See the pre-search-limit audit under `docs/reports/` for the full analysis.
-
-### `SCOPE_DRIFT_RATIO = 1.5`
-
-- **File**: `chunk-synthesizer.js`
-- **Trigger**: Composed envelope's component count > 1.5× sum of bound chunks' component counts → auto-fires `scope-drift` issue
-- **Catches**: LLM creative expansion that hallucinates extra components beyond what's in the bound chunks
-
-### `SCOPE_DRIFT_MIN_ACTUAL = 20`
-
-- **File**: `chunk-synthesizer.js`
-- **Floor against false positives** on small UIs where slot-wrapper noise dominates. UIs with < 20 components don't trip the gate even if the ratio exceeds 1.5×.
-
-### `DEFAULT_MAX_ATTEMPTS = 2`
-
-- **Files**: `chunk-refiner.js`, `chunk-synthesizer.js`
-- **Validator-driven retry budget**. After 2 failed validations, emit `synthesis-failed` strategy.
-
-### `DEFAULT_MAX_SIZE = 64` (state-cache)
-
-- **File**: `state-cache.js`
-- **Override**: `A2UI_STATE_CACHE_SIZE` env var
-- **Per-process, in-memory.** Survives only as long as the MCP server. Multi-turn refinement breaks across server restarts.
-- **Eviction**: LRU on `set` when at capacity; `get` and overwriting `set` touch recency; `peek` reads without touching.
-
-### `TRACE_INLINE_THRESHOLD_BYTES = 200 * 1024` (issue-reporter)
-
-- **File**: `issue-reporter.js`
-- Above this, traces spill to sidecar `.trace.json` next to the issue JSON to keep the issue file readable.
-
-## The locator → modifier two-pass pattern (chunk-refiner.js)
-
-Multi-turn refinements use **two LLM passes**:
-
-### Pass 1 — Locator
-
-LLM is given:
-
-- The intent ("change the title", "remove the funnel", "add a country list")
-- A component map listing slots in the prior UI + their bound chunks
-
-LLM classifies the intent as:
-
-- **`targeted`** — specific slot/element named, OR verb implies localized change
-- **`untargeted`** — broad changes touching many slots ("more compact", "use teal")
-
-### Pass 2 — Modifier
-
-LLM emits ops from a fixed vocabulary:
-
-```text
-VALID_OP_TYPES = { rebindSlot, appendToSlot, removeFromSlot, replacePage }
-```
-
-Ops translate to A2UI `updateComponents` messages via `opsToA2UI()`.
-
-**Phase A simplification**: refinements operate on the chunk binding plan only. A later phase may introduce component-tree refinements; current code honors the wire format while keeping engine code chunk-focused.

package/skills/adia-ui-a2ui/scripts/audit-a2ui-roster.mjs

@@ -1,96 +0,0 @@
-#!/usr/bin/env node
-// audit-a2ui-roster.mjs — §SelfAudit enforcement for adia-ui-a2ui.
-// Universal axes via the shared audit-axes lib; plus a skill-specific axis:
-// absorbed-skill roster currency (the three absorbed standalones and their
-// predecessors must stay absorbed — not resurrected as live skill dirs).
-//
-// Shared lib resolution: ${CLAUDE_PLUGIN_ROOT}/bin/lib/audit-axes.mjs, with a
-// fallback relative to this script (per the plugin path convention).
-//
-// Usage (from the plugin/repo root):
-//   node skills/adia-ui-a2ui/scripts/audit-a2ui-roster.mjs
-//   node skills/adia-ui-a2ui/scripts/audit-a2ui-roster.mjs --json
-//   node skills/adia-ui-a2ui/scripts/audit-a2ui-roster.mjs --strict
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-// Plugin root: ${CLAUDE_PLUGIN_ROOT} if set, else 3 dirs up from this script
-// (skills/adia-ui-a2ui/scripts/ → plugin root).
-const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT
-  ? path.resolve(process.env.CLAUDE_PLUGIN_ROOT)
-  : path.resolve(__dirname, '..', '..', '..');
-
-const LIB_URL = pathToFileURL(path.join(PLUGIN_ROOT, 'bin', 'lib', 'audit-axes.mjs')).href;
-const { runUniversalAxes, formatResults } = await import(LIB_URL);
-
-// Skill layout: skills/<name>/ under the plugin root (matches run-skill-evals.mjs).
-const SKILL_DIR = path.join(PLUGIN_ROOT, 'skills', 'adia-ui-a2ui');
-const SKILL_MD = path.join(SKILL_DIR, 'SKILL.md');
-const SKILL_JSON = path.join(SKILL_DIR, 'skill.json');
-const SKILLS_ROOT = path.join(PLUGIN_ROOT, 'skills');
-
-// Absorbed skills + predecessors — must NOT exist as live skill directories.
-const ABSORBED = [
-  'a2ui-pipeline',
-  'adia-ui-training',
-  'zettel-internals',
-  'fragment-extraction',
-  'training-data-flow',
-  'eval-gap-diagnosis',
-  'semantic-fail-lifting',
-];
-
-function parseArgs(argv) {
-  return { json: argv.includes('--json'), strict: argv.includes('--strict') };
-}
-
-function axisAbsorbedRosterCurrency() {
-  const findings = [];
-  for (const name of ABSORBED) {
-    const dir = path.join(SKILLS_ROOT, name);
-    if (fs.existsSync(dir)) {
-      findings.push({
-        type: 'unexpected-directory',
-        message: `${name}/ exists but was absorbed into adia-ui-a2ui — should not be a live skill dir`,
-        name,
-      });
-    } else {
-      findings.push({ type: 'absorbed-clean', message: `${name}: absorbed, no live dir — correct`, name });
-    }
-  }
-  const driftCount = findings.filter(f => f.type !== 'absorbed-clean').length;
-  return {
-    axis: 'absorbedRosterCurrency',
-    axis_num: 9,
-    status: driftCount > 0 ? 'drift' : 'ok',
-    findings,
-    summary: driftCount > 0 ? `${driftCount} absorbed-skill issue(s)` : 'all absorbed-skill entries clean',
-  };
-}
-
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const ctx = { skillDir: SKILL_DIR, skillMd: SKILL_MD, skillJson: SKILL_JSON, repoRoot: PLUGIN_ROOT };
-  const { results: universal } = runUniversalAxes(ctx);
-  const axis9 = axisAbsorbedRosterCurrency();
-  const allResults = [...universal, axis9];
-  const driftCount = allResults.filter(r => r.status === 'drift').length;
-
-  if (args.json) {
-    console.log(JSON.stringify({ results: allResults, driftCount }, null, 2));
-    if (args.strict && driftCount > 0) process.exit(1);
-    return;
-  }
-
-  console.log(`[audit-a2ui-roster] adia-ui-a2ui §SelfAudit — ${driftCount} drifting axis/axes`);
-  console.log(formatResults(allResults));
-  if (driftCount === 0) console.log('\n✓ All clean.');
-  if (args.strict && driftCount > 0) process.exit(1);
-}
-
-main();