@adia-ai/adia-ui-factory 0.2.4 → 0.8.1

package/skills/adia-ui-kit/references/state.md

@@ -1,229 +0,0 @@
----
-name: state
-load-when: Authoring state management — signals, controllers, BaseController extension, optimistic updates, undo/redo. Covers the state-as-attribute contract + the controller delegation pattern
-load-size-tokens: ~2,000
-required-for:
-  - composition with interactive state
-  - controller authoring
-  - data-stream binding
----
-
-# §State — Signals, controllers, undo/redo
-
-AdiaUI components reactively re-render when their JS properties change.
-The signal-backed property system is the substrate everything else builds on.
-
-### Three layers
-
-| Layer | Use for | API |
-|---|---|---|
-| **Signals** | Local reactive state — counters, form values, toggles | `signal()`, `computed()`, `effect()` |
-| **Controllers** | Domain state — tasks list, document tree, selection | `extends BaseController` |
-| **Component props** | Auto-bound to signals via `static properties` | `el.foo = value` (re-renders) |
-
-### Signals (local state)
-
-Three primitives from `@adia-ai/web-components/core/signals`:
-
-```js
-import { signal, computed, effect, batch } from '@adia-ai/web-components/core/signals';
-
-// Mutable signal
-const count = signal(0);
-count.value = 5;           // re-fires subscribers
-count.peek();              // read without subscribing
-
-// Derived signal (re-computes when deps change)
-const doubled = computed(() => count.value * 2);
-
-// Side effect (auto-tracks deps)
-const dispose = effect(() => {
-  console.log('count:', count.value);
-});
-dispose();                 // cleanup
-
-// Batch multiple writes into one notification
-batch(() => {
-  count.value = 10;
-  count.value = 20;        // only one re-render
-});
-```
-
-**Wiring to components:**
-
-```js
-const slider = document.querySelector('slider-ui');
-const speed = signal(50);
-
-// One-way: signal → component
-effect(() => { slider.value = speed.value; });
-
-// Two-way: component → signal
-slider.addEventListener('change', e => { speed.value = e.detail.value; });
-```
-
-> ⚠️ **Update components in place — never re-render by replacing `innerHTML`.**
-> The wiring above mutates a JS property (`slider.value = …`) on an element
-> that already exists. Do **not** instead rebuild the subtree on every signal
-> change with `container.innerHTML = …` — that destroys and recreates every
-> `*-ui` element, and each fresh `connectedCallback` starts with no prior
-> state, so CSS transitions have nothing to animate from: `segmented-ui`'s
-> indicator pill never slides, `chart-ui` loses its data-change animation,
-> `button-ui` its press / hover transitions.
->
-> **Rule:** create components once; update them via property mutation
-> (`el.value = x`, `el.data = arr`, `el.text = s`). `innerHTML` is for the
-> initial scaffold and for static / empty / error overlays only — never for
-> a reactive re-render of transitioning primitives.
->
-> **Never set `.innerHTML` on a UIElement component host itself** — not just
-> on a plain container. `drawer.innerHTML = …` / `card.innerHTML = …` wipes
-> the element's own stamped internal parts (`drawer-ui`'s `<dialog>`, card
-> chrome, …). The component re-stamps on its next render, but a reference it
-> captured in `connected()` is left pointing at detached DOM — `drawer-ui`
-> silently stops opening, with no console error. For a dynamic drawer: keep
-> `<header>`/`<section>`/`<footer>` as persistent children and mutate the
-> content of a plain inner element, never the `<drawer-ui>` host.
-
-### Controllers (domain state with optimistic + undo)
-
-For non-trivial apps, extend `BaseController` from
-`@adia-ai/web-components/core/controller`:
-
-```js
-import { BaseController } from '@adia-ai/web-components/core/controller';
-import { signal, batch } from '@adia-ai/web-components/core/signals';
-
-const tasksSignal = signal([]);
-
-export class TaskController extends BaseController {
-  static schema = {
-    name: 'task',
-    state: { tasks: 'array', undoStack: 'array', redoStack: 'array' },
-    commands: ['create', 'update', 'delete', 'undo', 'redo'],
-    attributes: ['data-task-count'],
-  };
-
-  #undoStack = [];
-  #redoStack = [];
-
-  // Required: snapshot for sync re-renders
-  getState() {
-    return {
-      tasks: tasksSignal.value,
-      undoStack: this.#undoStack.map(e => ({ id: e.id, label: e.label })),
-      redoStack: this.#redoStack.map(e => ({ id: e.id, label: e.label })),
-    };
-  }
-
-  // Reflect summary attributes back to host (for CSS targeting)
-  reflect() {
-    if (!this.host) return;
-    this.host.setAttribute('data-task-count', String(tasksSignal.value.length));
-  }
-
-  // Commands (invoked from UI)
-  create(task) {
-    const prev = tasksSignal.value;
-    tasksSignal.value = [...prev, task];
-    this.#undoStack.push({ id: task.id, label: 'create task', undo: () => {
-      tasksSignal.value = prev;
-    }});
-    this.#redoStack = [];
-    this.notify();
-  }
-
-  undo() {
-    const entry = this.#undoStack.pop();
-    if (!entry) return;
-    entry.undo();
-    this.#redoStack.push(entry);
-    this.notify();
-  }
-}
-```
-
-**Hooking into a component:**
-
-```js
-// In your shell setup
-const controller = new TaskController();
-const taskList = document.querySelector('#task-list');
-controller.connect(taskList);
-
-// Re-render when state changes
-controller.subscribe(() => {
-  const { tasks } = controller.getState();
-  taskList.data = tasks;
-});
-
-// Commands invoked from UI
-document.querySelector('#new-task-btn').addEventListener('press', () => {
-  controller.create({ id: crypto.randomUUID(), title: 'New task' });
-});
-```
-
-### Optimistic updates pattern
-
-The controller writes the optimistic state first, then awaits the server
-and rolls back on failure:
-
-```js
-async create(task) {
-  const prev = tasksSignal.value;
-  // 1. Optimistic write — UI updates immediately
-  tasksSignal.value = [...prev, { ...task, pending: true }];
-  this.notify();
-  try {
-    // 2. Server confirms
-    const saved = await this.#service.create(task);
-    tasksSignal.value = tasksSignal.value.map(t =>
-      t.id === task.id ? { ...saved, pending: false } : t
-    );
-  } catch (err) {
-    // 3. Rollback on failure
-    tasksSignal.value = prev;
-    throw new ServiceError('create-failed', { task, cause: err });
-  } finally {
-    this.notify();
-  }
-}
-```
-
-### Form submission
-
-Two patterns depending on whether you need a JS controller:
-
-**Pattern A — native form submit (no JS):**
-
-```html
-<form action="/api/users" method="POST">
-  <col-ui gap="3">
-    <field-ui label="Name"><input-ui name="name" required></input-ui></field-ui>
-    <field-ui label="Email"><input-ui name="email" type="email" required></input-ui></field-ui>
-    <button-ui text="Submit" variant="primary" type="submit"></button-ui>
-  </col-ui>
-</form>
-```
-
-AdiaUI form participants (`input-ui`, `select-ui`, `textarea-ui`, `check-ui`,
-etc.) use `ElementInternals` form participation — they submit like native
-HTML inputs. The `name` attribute is what shows up in the form data.
-
-**Pattern B — JS handler with validation:**
-
-```js
-const form = document.querySelector('form');
-form.addEventListener('submit', async (e) => {
-  e.preventDefault();
-  const data = Object.fromEntries(new FormData(form));
-  try {
-    await controller.submit(data);
-    toastUI.show({ variant: 'success', text: 'Saved' });
-  } catch (err) {
-    toastUI.show({ variant: 'danger', text: err.message });
-  }
-});
-```
-
----

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

@@ -1,421 +0,0 @@
-# Reference: Teach Protocol — Absorbing new knowledge into the adia-ui-kit skill
-
-**Authored:** 2026-05-22 (§409 follow-up to the §404 SoT-yaml sweep + §408 catalog-renderer bug).
-**Why authored:** The skill has §SkillHygiene (audit) and a CHANGELOG cadence (cut/ship), but no explicit *teach* procedure. Operator + sibling-agent requests of the shape "make sure adia-ui-kit is aware of [x, y, z]" / "train the skill on [a, b, c]" need a deterministic landing path so the next person who needs to add knowledge knows where it goes — not just where they *think* it should go.
-
-**Ecosystem context:** This reference is the canonical instance of a generalizable **extensibility** pattern documented at `.agents/skills/VISION-extensibility.md`. The vision separates universal components (the trigger cluster, the 7 anti-patterns, the 5-step landing procedure, the citation-vs-knowledge principle, the negative case G) from skill-specific components (the decision tree's branches A-G, the worked examples). When editing this file, preserve the universal sections verbatim where possible — they're shared infrastructure. When porting §Teach to sibling roll-ups (`adia-ui-release`, `adia-ui-authoring`), this file is the template; copy the universal parts, replace the decision tree + worked examples with the sibling's topology.
-
-**Used by:** `adia-ui-kit` skill, when an agent receives one of these triggers (the SKILL.md §Teach section, when added, names the trigger phrases and routes here for the procedural detail):
-
-- "make sure `adia-ui-kit` skill is aware of [x]"
-- "train/update `adia-ui-kit` on [y, z]"
-- "the skill should know about [the new pattern from §397]"
-- "[FEEDBACK-NN was resolved with this fix] — make sure the skill reflects it"
-- "absorb this lesson into adia-ui-kit"
-- "teach the skill about [the new component / pattern / discipline]"
-
-**Companion:** `feedback-authoring.md` (when the new knowledge originated from a FEEDBACK ticket loop) and the §SkillHygiene section of `SKILL.md` (run hygiene audit after any §Teach landing).
-
-**Anti-companion:** `.claude/docs/journal/YYYY/MM/<date>.md` (arc-specific stories belong in the journal, not the skill — see decision tree below).
-
----
-
-## When to Use
-
-Trigger phrases (from the §Teach section in SKILL.md):
-
-- "make sure `adia-ui-kit` 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-kit"
-- "update the skill to reflect [the new ADR / the resolved FEEDBACK-NN / the new primitive]"
-
-This protocol applies when **another agent in the codebase** (substrate author, kanban worker, peer skill author) hands you new knowledge to integrate. It does NOT apply when:
-
-- You're authoring fresh content from scratch (use §Mission's Author posture instead)
-- You're fixing a wrong claim in the skill (use §CorrectionLoop instead)
-- You're running cleanup / archive sweeps (use §SkillHygiene's hygiene-cut shape)
-
-The procedure below is **the binding** for skill-teach requests. Follow it in order. Each step has a stop-condition; do not skip ahead.
-
----
-
-## Core Principles
-
-1. **The skill is a citation layer, not a knowledge layer.** Per-component facts (slots, props, decision rules, keywords, synonyms) live in **yaml SoT** at `packages/web-components/components/*.yaml`. The skill cites tags + recipe patterns, never duplicates yaml prose.
-2. **Reference files are the cold-start budget's safety valve.** New content > ~50 LOC of procedural detail belongs in `references/<topic>.md` and is cited from SKILL.md, not inlined. This protects the eight hygiene axes (especially axis 1 token economy + axis 8 cold-start path weight).
-3. **Triggers without binding sections are waste.** Adding keywords to `trigger:` without a corresponding §-section in SKILL.md (or a referenced file) consumes activation budget for no payoff. Always pair the two.
-4. **Capability menu items must reach an actual section.** A menu item that points nowhere is worse than no menu item — the cold-start surface is the agent's mental model; lies cost more than gaps.
-5. **Version bumps are PATCH for citations, MINOR for new procedural sections, MAJOR for renames/removals.** Most §Teach landings are MINOR (a new section + reference file). Never bundle MINOR adds with PATCH polish in one cut.
-6. **Hygiene audit is the receipt.** A §Teach landing isn't done until `node scripts/skills/audit-skill-hygiene.mjs adia-ui-kit` runs clean (or you've explicitly noted the new thresholds you accept).
-
----
-
-## The Decision Tree — where does new knowledge land?
-
-Run this **before** any patch. The wrong landing target wastes effort and creates drift.
-
-**v3.1.0+ mechanized**: the decision tree is now `scripts/teach-route.mjs`. Given a knowledge-payload description, the script returns a deterministic landing target (file path or "journal-only"). Run it before authoring any teach-landing patch:
-
-```bash
-node scripts/teach-route.mjs --payload="new slot on button-ui for trailing icons"
-# → landing: packages/web-components/components/button/button.yaml
-# → branch: A (per-component-contract)
-# → confidence: high
-
-# Pipe from stdin:
-echo "add a recipe for composing an editor-shell inside an admin-page-body" \
-  | node scripts/teach-route.mjs
-# → landing: references/patterns-shells.md
-# → branch: B (recipe)
-```
-
-If the script's confidence is **low**, re-read the prose tree below and classify by hand — the keyword vocabulary missed the payload's shape and you should consider adding the payload to `../evals/teach-routing-cases.json` so future runs catch it. If the script's confidence is **high** or **medium**, trust the landing.
-
-Behavioral eval suite: `node scripts/teach-route.mjs --eval=evals/teach-routing-cases.json` runs all canonical cases and reports pass/fail. v3.1.0 baseline: 9/9 (100%).
-
-### The 7 branches (mechanized in `teach-route.mjs`)
-
-```
-Is the new fact a PER-COMPONENT contract (slot, prop, decision rule,
-keyword, synonym, a2ui.rule)?
-  → YES (branch A): belongs in YAML SoT, not in the skill.
-         Open the component's `.yaml` file at
-         `packages/web-components/components/<name>/<name>.yaml`
-         (or `packages/web-modules/.../<name>.yaml`).
-         Add to the appropriate field; run `npm run build:components`
-         to regenerate sidecars + catalog. Skill cites by tag — it
-         doesn't need to change.
-         STOP HERE. Do not edit the skill.
-         (See Worked Example A below.)
-  → NO: continue.
-
-Is it a RECIPE — a cross-component composition pattern with code?
-  → YES (branch B): lands in `references/patterns-<domain>.md`.
-         Choose domain by the recipe's center of gravity:
-           - shell composition / nesting → `patterns-shells.md`
-           - form layouts / input bindings → `patterns-forms.md`
-           - data tables / charts / wiring → `patterns-data.md`
-           - layout primitives (row/col/stack) → `patterns-layout.md`
-           - agent-UI surfaces (chat/feedback/trace) → `patterns-agent.md`
-           - event wiring / controllers / signals → `patterns-wiring.md`
-           - traits and behavioral primitives → `patterns-traits.md`
-         If the recipe spans 3+ domains, prefer `patterns-recipes.md`
-         (the cross-cutting bundle).
-         Add cross-link from SKILL.md §Patterns table.
-         (See Worked Example B below.)
-
-Is it a FLOW — an end-to-end multi-page user journey?
-  → YES (branch C): lands in `references/flows-<domain>.md`. Existing flows:
-           - flows-auth.md, flows-content.md, flows-data.md,
-             flows-interaction.md, flows-shells.md
-         Create a new `flows-<X>.md` if no existing file fits.
-         Cross-link from SKILL.md §Flows table.
-         (See Worked Example C below.)
-
-Is it a DISCIPLINE / POSTURE / METHODOLOGY shift?
-  → YES (branch D): lands INLINE in SKILL.md. These ARE the procedural spine:
-         §Mission, §ReasoningMethodologies, §CorrectionLoop, §LoadingProtocol,
-         §SkillHygiene, §FeedbackDiscipline.
-         They're allowed to grow because they shape every other section.
-         Run §SkillHygiene audit + `check:skills:seed-size` after to confirm
-         cold-start budget held.
-         (See Worked Example D below.)
-
-Is it a TOOLING addition — a new script / CLI / verification command?
-  → YES (branch E): lands in `scripts/` (under SKILL.md's `scripts/` directory or
-         the repo's `scripts/audit/` etc.). Cross-link from the
-         §SkillHygiene "harness manifest" table in SKILL.md.
-         (See Worked Example E below.)
-
-Is it a FEEDBACK RESOLUTION (upstream ticket landed, skill should reflect)?
-  → YES (branch F): TWO landings usually needed.
-         1. The fix itself (yaml / code) — that's in the substrate, not
-            the skill.
-         2. The CORRECTION (what the skill said before that turned out
-            to be wrong) — this is §CorrectionLoop territory. Patch the
-            skill text where the bug-shape was misdiagnosed; add the
-            new pattern to the bug-shape taxonomy.
-         (See Worked Example F below.)
-
-Is it a one-off ARC STORY, LESSON LEARNED, OR HISTORICAL CONTEXT?
-  → NO landing in the skill (branch G — the NEGATIVE case).
-    It belongs in `.claude/docs/journal/YYYY/MM/<date>.md` where future
-    archeology will find it (per AGENTS.md's journal discipline).
-    Skipping the skill here is a feature, not a gap.
-    (See Worked Example G — the negative case.)
-```
-
-When the script and the prose disagree, the script wins for tractability — but ALSO update the prose tree above + the corpus to bring them back in sync (the script is the SoT for routing; prose is for human review).
-
----
-
-## The Five-Step Landing Procedure
-
-After the decision tree picks a target, follow these steps in order:
-
-### Step 1 — Audit before patching
-
-Before writing anything:
-
-1. **Read the target file in full.** Don't skim. The skill's reference files have established voice + section ordering; patches must match.
-2. **`git status` + `git log -5`** on the working tree. Confirm no peer activity in `.agents/skills/` (peer agents may be authoring sibling skills like `adia-ui-release/`). If peer is dirty here, halt + coordinate.
-3. **Grep for existing coverage.** Run `grep -rn "<keyword>" .agents/skills/adia-ui-kit/` to confirm the new knowledge isn't already partly covered. If it IS, the landing is a *patch + augment*, not a *new section* — different shape (Step 2 changes).
-4. **Confirm the landing-target choice.** Re-read the Decision Tree above against your specific case. Two minutes of "is this really a recipe or is it actually a flow?" prevents two hours of misplaced content.
-
-### Step 2 — Author the patch
-
-Two shapes depending on Step 1's grep:
-
-**Shape A — NEW section / file (no existing coverage)**
-
-If the target is a new reference file:
-- Create `references/<topic>.md` with the canonical header block (provenance, why-authored, used-by, companion, anti-companion, separator, "## When to Use" with trigger phrases, "## Core Principles", then content).
-- Reference the new file from the SKILL.md `### The reference manifest` table with a one-line "when to load" + "v<current-version>" tag.
-
-If the target is a new section inside SKILL.md:
-- Place it adjacent to its closest siblings (e.g. a new methodology section goes near §ReasoningMethodologies, a new posture goes near §Mission).
-- Use the H2 form `## §Name — Short description`. Add corresponding entry to the capability menu (§"What this skill can do") and the binding table.
-
-**Shape B — AUGMENT existing section (grep found partial coverage)**
-
-- Read the entire existing section first, including any cross-references to other files.
-- Author the augment as a sub-section (H3) or inline paragraph at the *semantically correct place*, not the end.
-- If the augment changes the meaning of nearby paragraphs, edit those too — don't leave stale claims standing.
-
-### Step 3 — Wire the activation surface
-
-For ANY §Teach landing that should be discoverable:
-
-1. **Add trigger keywords to `trigger:` in the frontmatter.** Pick 3-7 phrases an agent or user would naturally say. Be specific (not "design") but not over-specific (not the exact tag name unless that's the user vocabulary).
-2. **Add a capability menu entry** in §"What this skill can do (capability surface)" — under the appropriate H3 grouping ("Author", "Consultant", "Correction", etc.).
-3. **Add a binding-procedure line** in §"LLM procedure (binding — follow this on every request)" if the new section needs explicit step-listing. Most don't (default LLM behavior is "scan capability menu → match → jump"). Bind only when the section must run in a specific phase (e.g. before §0 reasoning gate).
-
-If the landing is a reference file, the SKILL.md edits are minimal — just the manifest table row + a capability menu entry if it warrants one.
-
-### Step 4 — Version + CHANGELOG
-
-Cut the new content as a release:
-
-- **PATCH (vN.M.x+1)** — citation strengthening, typo fixes, augmenting an existing section with one paragraph.
-- **MINOR (vN.M+1.0)** — new reference file, new H2 section in SKILL.md, new capability-menu item with binding.
-- **MAJOR (vN+1.0.0)** — renames, removals, restructuring (don't bundle with adds).
-
-Update `skill.json` version + `CHANGELOG.md` entry. The entry must name:
-- What was added (one-line summary)
-- Where it lives (file path + section anchor)
-- What triggers it (1-3 phrases from the trigger keywords)
-- What it replaces / supersedes (if anything; usually nothing for adds)
-
-### Step 5 — Verify with `audit:skill-hygiene`
-
-Run the hygiene audit:
-
-```bash
-node scripts/skills/audit-skill-hygiene.mjs adia-ui-kit
-```
-
-Check the eight axes. The §Teach landing should NOT regress:
-- **Axis 1 (token economy)** — if SKILL.md grew, did the reference-file extraction protect the cold-start? If not, you inlined too much.
-- **Axis 7 (capability menu drift)** — if you added a section, did you add the menu entry? Drift > 5 means lies in the menu.
-- **Axis 8 (cold-start path weight)** — if the new section is in the first 5 H2s, did you push the cold-start over the 30K threshold?
-
-If any axis regresses, **fix it in the same cut**, not the next one. Hygiene-debt compounds.
-
----
-
-## Worked Examples
-
-### Example A — New primitive's a2ui.rule (yaml SoT, NOT skill)
-
-**Request:** "make sure adia-ui-kit knows about the new `<calendar-picker-ui>` form-associated date input — it shouldn't be used for date ranges."
-
-**Decision tree:** Per-component contract (decision rule vs sibling primitive). → **YAML SoT, not skill.**
-
-**Action:**
-```bash
-# Open the yaml
-$EDITOR packages/web-components/components/calendar-picker/calendar-picker.yaml
-
-# Add to a2ui.rules:
-# - rule: "Use for single-date input. For date ranges compose two pickers or use a dedicated range component."
-#   reason: "Single-value scope."
-
-# Regenerate sidecars + catalog
-npm run build:components
-
-# Verify
-npm run check:yaml-rules-coverage  # ≥1 rule per component
-npm run check:corpus-rules-format  # no malformed bullets
-```
-
-**No skill edits required.** The skill cites `<calendar-picker-ui>` by tag in its capability surface; the new rule flows into LLM context via the catalog automatically.
-
-**Pitfall to avoid:** "While I'm in the skill, let me also add a paragraph about calendar-picker in §Forms." NO. That paragraph would duplicate the yaml SoT and drift on the next yaml change. Skill cites the tag; doesn't describe its contract.
-
-### Example B — New recipe (cross-component composition pattern)
-
-**Request:** "train adia-ui-kit on the editor inspector pane pattern — a right-pane inside `<editor-shell>` that hosts `<tabs-ui>` + `<inspector-ui>` for live A2UI doc state inspection."
-
-**Decision tree:** Recipe — cross-component composition pattern. → **`patterns-recipes.md`** (or `patterns-shells.md` if editor-cluster-specific).
-
-**Action:**
-1. Open `patterns-recipes.md`.
-2. Add a new H2 section "## Editor inspector pane" with: triggers, when to use, composition (HTML + A2UI JSON), token contract, anti-patterns.
-3. Cross-link from SKILL.md §Patterns table (one row: pattern name, file, when-to-load).
-4. Bump version PATCH (vN.M.x+1) since reference-file augment, not new section.
-
-**Real-session reference:** §404 (2026-05-22) — the editor inspector pane + editor sub-views recipes were added to `patterns-recipes.md` in adia-ui-kit v2.20.9 as part of the SoT-yaml sweep cleanup.
-
-### Example C — New flow (end-to-end user journey)
-
-**Request:** "teach the skill about the new agent onboarding wizard flow — 3 pages (welcome → persona pick → tool consent) using `<simple-shell>` + `<stepper-ui>`."
-
-**Decision tree:** Flow — multi-page user journey. → **`flows-auth.md`** or new `flows-onboarding.md`.
-
-**Action:**
-1. Decide: does this fit existing `flows-auth.md` (which covers registration wizards)? If yes, augment. If the onboarding wizard has distinct lifecycle hooks (telemetry, persona persistence) that don't fit auth, create `flows-onboarding.md`.
-2. Author the flow as a Markdown article: brief, page-by-page composition, A2UI JSON wiring, telemetry hooks, anti-patterns.
-3. Cross-link from SKILL.md §Flows table.
-4. MINOR bump if new file (vN.M+1.0); PATCH if augmenting existing flows-auth.md.
-
-### Example D — New methodology / posture (inline in SKILL.md)
-
-**Request:** "absorb the §405 lesson into adia-ui-kit — never audit YAML with regex, always use a real parser."
-
-**Decision tree:** Discipline / methodology shift. → **inline in SKILL.md**, near §ReasoningMethodologies.
-
-**Action:**
-1. Open `.agents/skills/adia-ui-kit/SKILL.md`.
-2. Add to §ReasoningMethodologies as a new numbered rung: "### 7. Parse, don't regex — YAML / JSON / code requires its own parser. Sniff tests on YAML source text via regex produce ghost counts (§404 lesson: 32 false-positive empty descriptions; real parser found 0)."
-3. Cross-link from §CorrectionLoop (Phase 3 bug-shape taxonomy: "regex-based audit miscount").
-4. MINOR bump for the rung add. Run `audit:skill-hygiene` — confirm cold-start budget held (axis 8).
-
-**Why inline, not reference file:** Methodology / posture sections shape every other section. They're the procedural spine; they're allowed to grow. Reference-extracting them would mean agents miss them on cold-start.
-
-### Example E — New tooling script
-
-**Request:** "make sure the skill knows about the new `audit-yaml-rules-coverage` gate."
-
-**Decision tree:** Tooling addition. → **Cross-link from SKILL.md's harness manifest table** + brief mention in §SkillHygiene.
-
-**Action:**
-1. Confirm the script exists (`scripts/audit/audit-yaml-rules-coverage.mjs` was added in §409).
-2. Open SKILL.md, find the harness-manifest table in §SkillHygiene or §LoadingProtocol.
-3. Add a row: script path + when-to-run + what-it-catches.
-4. PATCH bump.
-
-**Pitfall to avoid:** Inlining the script's full documentation in SKILL.md. The script's own `--help` flag + the docstring at the top of the `.mjs` file are the SoT. The skill cites; it doesn't duplicate.
-
-### Example F — Feedback resolution + skill correction
-
-**Request:** "FEEDBACK-37 was retracted (the slot-contract diagnostic for admin-topbar was misdiagnosed) — make sure the skill reflects this."
-
-**Decision tree:** Feedback resolution. → **TWO landings:**
-
-1. **The substrate fix** (yaml change retiring the false slot-contract claim) — already shipped, not skill territory.
-2. **The skill correction** — patch whatever section was citing the misdiagnosed pattern. This is §CorrectionLoop territory.
-
-**Action:**
-1. `grep -rn "FEEDBACK-37" .agents/skills/adia-ui-kit/` — find every citation.
-2. Read the original misdiagnosis (in the FEEDBACK-37 ticket file under `.agents/team/tickets/archive/`).
-3. Patch the skill section that adopted the false pattern. Add a bug-shape entry to §CorrectionLoop's Phase 3 taxonomy ("light-DOM slot misdiagnosis — FB-37 lesson: slot= on AdiaUI primitives is DECORATIVE metadata, not projection directives").
-4. Bump PATCH for the correction (it's a fix, not a new feature).
-
-**Real-session reference:** §399 (2026-05-21) — the FB-37 retraction lesson landed in adia-ui-kit v2.19.x as a bug-shape taxonomy entry. Future cold-starts of the skill warn agents not to repeat the misdiagnosis.
-
-### Example G — One-off arc story (the NEGATIVE case)
-
-**Request:** "the skill should remember how we shipped Arc D today — the catalog-renderer bug, the dict-stringification, the 12-day silence."
-
-**Decision tree:** One-off arc story / historical context. → **`.claude/docs/journal/YYYY/MM/<date>.md`, NOT the skill.**
-
-**Action:**
-1. The journal entry already exists (§408 in `.claude/docs/journal/2026/05/2026-05-22.md`).
-2. **Do nothing in the skill.** The skill is procedural ("what to do"), not historical ("what happened"). Future archeology grep'ing for "catalog-renderer" or "[object Object]" finds the journal entry; that's where it belongs.
-3. The structural lesson (axis 1 of the audit-corpus-rules-format gate) is already captured procedurally by Example E above.
-
-**Pitfall to avoid:** "But the skill should know about every important arc!" NO. The skill teaches the agent **what to do**; the journal records **what happened**. Conflating them bloats the skill and rots the journal.
-
----
-
-## Anti-patterns (the §Teach landing failure modes)
-
-These are the shapes of bad §Teach landings observed during this skill's evolution. Each one was a real near-miss or fix.
-
-### Anti-pattern 1 — "Append-only" landing
-
-Adding new content to the end of an existing section without integrating it. Symptom: section grows monotonically; new paragraphs don't connect to the surrounding voice; cross-references go stale.
-
-**Fix:** When augmenting a section, find the *semantically correct insertion point*, not the end. If the new content doesn't fit any insertion point, you may be in the wrong section.
-
-### Anti-pattern 2 — Duplicating yaml SoT
-
-Adding a per-component contract (slot, prop, decision rule) to the skill instead of (or in addition to) the yaml. Symptom: the skill paragraph and the yaml `description` say the same thing in different words.
-
-**Fix:** When you catch yourself writing "the `<X-ui>` component does Y", check — is this really in the yaml already? If yes, delete what you were writing and cite the yaml. The skill cites tags; doesn't describe them.
-
-### Anti-pattern 3 — Trigger keywords without binding
-
-Adding phrases to `trigger:` for a section that doesn't exist yet, or that exists but has no procedural binding. Symptom: agent activates the skill on the keyword, then has no procedure to follow.
-
-**Fix:** Pair the keyword add with the section authoring in the SAME cut. Never bump the version with orphan triggers.
-
-### Anti-pattern 4 — Capability menu lies
-
-Adding a menu item that points to a section that doesn't exist, or to a stub. Symptom: agent reads the menu, picks the item, jumps to the section, finds nothing actionable, falls back to general knowledge.
-
-**Fix:** Capability-menu entries are the cold-start surface — they're load-bearing. Treat each new entry as a contract that the underlying section MUST deliver. If you're not ready to write the section, don't add the menu item yet.
-
-### Anti-pattern 5 — Bundling MINOR + PATCH in one cut
-
-Shipping a new section (MINOR) alongside three citation-strengthening edits (PATCH) in a single `vN.M+1.0` cut. Symptom: the CHANGELOG entry is unclear; consumers can't tell what the new behavior is.
-
-**Fix:** Cut the MINOR first (with just the new section). Cut the PATCH after (with the polish). Each cut has a clean intent.
-
-### Anti-pattern 6 — Hygiene-debt deferral
-
-Landing a new section, observing that `audit:skill-hygiene` shows a threshold regression, and deferring the fix to "next cut." Symptom: the next cut has a different focus; the hygiene-debt is forgotten; six cuts later the skill is 30% over the token-economy threshold.
-
-**Fix:** Fix axis regressions IN THE SAME CUT as the §Teach landing. Hygiene-debt compounds — it never gets easier to address later.
-
-### Anti-pattern 7 — Treating §Teach as one-way
-
-Receiving a §Teach request and landing the content without asking "should this be in adia-ui-kit, or in adia-ui-migration / adia-ui-training / a new sibling skill?" Symptom: adia-ui-kit absorbs content that semantically belongs in a sibling skill, blowing past the cold-start budget while leaving the sibling thin.
-
-**Fix:** The §LoadingProtocol's peer-skill manifest table is the routing layer. Before landing in adia-ui-kit, ask: is there a sibling skill for this domain? If yes, route there. If no, defend the inclusion in the CHANGELOG entry.
-
----
-
-## Cross-references
-
-- **§Mission** (SKILL.md) — defines the three postures (Author / Consultant / Correction). §Teach is a fourth posture, narrower than Author (which is forward-generation from scratch).
-- **§SkillHygiene** (SKILL.md) — the audit gate that catches §Teach landing regressions. Always run after.
-- **§LoadingProtocol** (SKILL.md) — defines the reference-file extraction discipline. §Teach respects it by routing content > ~50 LOC to `references/`.
-- **`feedback-authoring.md`** — companion when §Teach is triggered by a FEEDBACK resolution (Example F).
-- **AGENTS.md** (repo root) — defines the journal discipline that §Teach defers to for arc stories (Example G).
-- **`scripts/skills/audit-skill-hygiene.mjs`** — the eight-axis audit; run after any §Teach landing.
-- **`scripts/audit/audit-yaml-rules-coverage.mjs`** + siblings (§409) — the regression gates that catch yaml-SoT drift when §Teach lands in yaml instead of the skill (Example A).
-
----
-
-## Worked Decision Examples — Quick-Reference Card
-
-When in doubt, the table below routes by request shape.
-
-| Request shape | Landing target | Version bump | Audit gate |
-|---|---|---|---|
-| "new primitive does X" | yaml SoT only (no skill change) | yaml change only | `check:yaml-rules-coverage` |
-| "new keyword for `<tag>`" | yaml SoT only | yaml change only | `check:yaml-rules-coverage` |
-| "new composition recipe" | `references/patterns-<domain>.md` | PATCH | `audit:skill-hygiene` |
-| "new end-to-end flow" | `references/flows-<domain>.md` | MINOR if new file else PATCH | `audit:skill-hygiene` |
-| "new methodology / posture" | inline in SKILL.md (near §Mission / §ReasoningMethodologies) | MINOR | `audit:skill-hygiene` |
-| "new audit / verification script" | cross-link from SKILL.md harness manifest | PATCH | `audit:skill-hygiene` |
-| "FEEDBACK-NN resolved + skill reflected" | patch the misdiagnosed section + bug-shape taxonomy entry | PATCH | manual review |
-| "arc story / lesson learned" | `.claude/docs/journal/YYYY/MM/<date>.md` (NOT skill) | n/a | journal-date sanity hook |
-| "absorb sibling-skill knowledge" | route to peer skill OR defend inclusion in CHANGELOG | varies | `audit:skill-hygiene` + peer review |
-
----
-
-**Version of this reference file:** v1.0 — initial authoring (2026-05-22, journal §409 follow-up). Future revisions: when new landing-target patterns emerge (e.g. a §Teach landing for the `adia-ui-training` sibling skill that doesn't fit any of the seven existing decision-tree branches), augment this file's decision tree + worked examples in the same arc as the landing.