@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/references/css-policy.md

@@ -0,0 +1,343 @@
+---
+name: css-policy
+load-when: Before §Setup — when an agent needs the explicit-import CSS policy (why side-effect CSS imports are forbidden, the CDN-bundle table, the /with-css opt-in, reserved layout attribute names, the v0.6.32 CDN bundle correctness milestone)
+load-size-tokens: ~4,400
+required-for:
+  - CDN consumers (mode 7)
+  - bundler consumers (mode 6)
+  - admin-shell layout work
+  - icon-loader troubleshooting
+---
+
+# §CSSPolicy — Explicit-import CSS policy (read before §Setup confuses you)
+
+**Normative policy decision** for `@adia-ai/*` packages: **no component
+JS module self-imports its CSS.** This applies uniformly across
+`@adia-ai/web-components` primitives AND `@adia-ai/web-modules` shells.
+Consumers are responsible for explicitly importing every CSS file they
+need.
+
+Confirmed and re-affirmed 2026-05-20 in response to claims-ui F-006
+(`admin-shell.js` produces an unstyled stacked-divs layout when its CSS
+isn't imported). The policy is the design — F-006 is a documentation gap,
+not a code bug. The cold-start cost is intentional.
+
+### Why explicit-import (the reasoning)
+
+1. **Light-DOM cascade control.** Components render into the light DOM
+   (no shadow root). Consumer styles + AdiaUI styles share one cascade.
+   If component CSS auto-loaded, it would arrive in whatever order JS
+   resolves modules — sometimes after the consumer's overrides, sometimes
+   before. Explicit imports let the consumer place AdiaUI CSS at a
+   deterministic point in their entry file (typically *before* their
+   own brand overrides).
+
+2. **Tree-shake honesty.** A self-importing component pulls its CSS
+   even when the consumer never instantiates it. The barrel import
+   `@adia-ai/web-components` registers ~95 custom elements; if each
+   shipped a side-effect CSS import, every consumer would pay the
+   full-catalog CSS cost regardless of which primitives they actually
+   render. Today: `@adia-ai/web-components/css` is the explicit
+   single-line opt-in for the full catalog — predictable, removable.
+
+3. **Density / theme layering.** Consumers commonly want
+   `<base-tokens> → <brand-overrides> → <component-CSS> → <density-overrides>`.
+   Explicit imports make this trivial. Side-effect imports embedded in
+   JS make it hard.
+
+4. **Light-DOM means CSS is data, not implementation.** Treating CSS
+   as an artifact the consumer schedules (not the framework's side
+   effect) keeps the consumer in control of layout, color, and
+   density decisions.
+
+### What this policy means for consumers (the cold-start contract)
+
+Every AdiaUI surface needs THREE explicit CSS imports at minimum:
+
+```ts
+// 1. Design tokens — must arrive first
+import '@adia-ai/web-components/css';
+
+// 2. Brand overrides — your tokens replacing theirs (optional)
+import './my-brand-tokens.css';
+
+// 3. Shell CSS — REQUIRED for every shell tag you use
+import '@adia-ai/web-modules/shell/admin-shell.css';
+// import '@adia-ai/web-modules/chat/chat-shell.css';
+// import '@adia-ai/web-modules/editor/editor-shell.css';
+// import '@adia-ai/web-modules/simple/simple-shell.css';
+```
+
+**The first time a consumer renders a shell without (3), they get an
+unstyled stacked-divs layout. That's the policy operating as intended.**
+
+### What this policy does NOT mean
+
+- ❌ It does NOT mean per-primitive CSS imports are required.
+  `@adia-ai/web-components/css` is the catalog barrel — one import
+  covers all 100+ primitives. Per-primitive imports
+  (`@adia-ai/web-components/components/button.css`) exist for
+  tree-shaking, not as the default expectation.
+- ❌ It does NOT forbid future opt-in side-effect bundles. A
+  `/with-css` subpath variant (e.g.
+  `@adia-ai/web-modules/shell/admin-shell/with-css`) that re-exports the
+  JS + side-effect-imports the CSS would be acceptable. Such variants
+  are **opt-in**; the default subpath (without `/with-css`) must
+  preserve the explicit-import contract.
+- ❌ It does NOT mean every primitive needs its own CSS file. CSS
+  organization within `@adia-ai/web-components` is a maintainer
+  concern; the policy governs the consumer-facing API.
+
+### Opt-in `/with-css` variants (since v0.6.10)
+
+The policy ships an explicit carve-out: a `/with-css` companion subpath
+that opts INTO side-effect CSS imports. The default subpath remains
+explicit-import (policy intact); the `/with-css` companion is the
+single canonical exception. Available for the 4 shells:
+
+```js
+// Default subpath — explicit-import contract (works in every Vite version,
+// gives you tree-shake + cascade control + theme-layering)
+import '@adia-ai/web-modules/shell/admin-shell';
+import '@adia-ai/web-modules/shell/admin-shell.css';  // explicit
+
+// Opt-in /with-css — single import, side-effect CSS included
+import '@adia-ai/web-modules/shell/admin-shell/with-css';
+//                                              ^^^^^^^^ subpath companion
+```
+
+The same pair exists for `chat-shell`, `editor-shell`, `simple-shell`.
+
+**When to use the opt-in form:**
+
+- Cold-start onboarding (one fewer line to remember; one fewer way to
+  forget the CSS)
+- Quick prototypes / demos where tree-shake doesn't matter
+- Documentation / tutorial examples where the goal is "render
+  something fast"
+
+**When to STAY on the default form:**
+
+- Production builds where bundle size matters
+- Applications with custom theme layering (the explicit form lets you
+  insert your theme CSS between the tokens import and the shell CSS)
+- Applications composing multiple shells (the explicit form lets you
+  cherry-pick which shells' CSS load when)
+
+**Why this is policy-safe:**
+
+The carve-out is **explicit by name**: a consumer who writes
+`/with-css` has knowingly opted into side-effect CSS imports for THAT
+import statement. The default subpath (`@adia-ai/web-modules/shell/admin-shell`)
+preserves the original explicit-import contract for everyone else. No
+silent behavior change; no breakage for existing consumers; no policy
+fork.
+
+**Future scope (v0.7.0+):**
+
+Primitive-level `/with-css` variants (e.g. `@adia-ai/web-components/components/button-ui/with-css`)
+are NOT shipping in v0.6.x. The 56 primitives × build cost don't fit
+the patch slice. If consumer demand materializes, evaluate for v0.7.0.
+Until then, primitives stay on the explicit-import contract uniformly.
+
+### CDN-bundle path (since v0.6.29 for CSS, v0.6.30 for JS)
+
+A third consumption tier alongside explicit-import (default) and
+`/with-css` (opt-in npm form): the **CDN-bundle path** ships
+pre-flattened + minified CSS + JS via jsdelivr/unpkg. Consumers link
+directly from HTML — no bundler, no npm install, no build step.
+
+**The contract** — three tags get you a working page:
+
+```html
+<link rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.7/dist/web-components.min.css">
+<link rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.css">
+<script type="module"
+        src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/everything.min.js"></script>
+```
+
+**The 4-tier policy taxonomy now**:
+
+| Tier | Path shape | Tree-shake? | Theme layering? | When to use |
+|------|-----------|-------------|-----------------|-------------|
+| **Explicit-import** (default) | `import '@adia-ai/web-components/css'` + per-shell `*.css` | ✓ (with bundler) | ✓ (insert overrides between imports) | Production apps; brand-overrides; cherry-picked shells |
+| **`/with-css`** (opt-in npm) | `import '@adia-ai/web-modules/shell/admin-shell/with-css'` | ✗ (kitchen sink) | ✗ (CSS is side-effect) | Cold-start; prototypes; tutorial code |
+| **CDN-bundle** (HTML-first) | `<link rel="stylesheet" href="cdn.jsdelivr.net/.../dist/*.min.css">` + `<script type="module" src=".../dist/everything.min.js">` | ✗ (kitchen sink, ~1 MB raw / ~330 KB Brotli) | ✗ (one bundle, no insertion points) | HTML-only; CodePen; marketing; agent-in-fresh-repo |
+| **`<theme-provider>`** (adopt-from-anywhere · v0.7.12 · experimental) | `import '@adia-ai/web-components/components/theme-provider'` then `<theme-provider theme="ocean" scale="prose">…</theme-provider>` | ✗ (adopts the whole foundation once into `document.adoptedStyleSheets`) | ✓ (`theme=` preset + `scale=` register, adopted on demand) | SPA roots / embedded apps / dynamic mounts with **no `<head>` access**; coexists with the `<link>` path |
+
+> **`<theme-provider>` — adopt the foundation from anywhere (v0.7.12, experimental).**
+> A `display: contents` wrapper (own no box) that, at module-eval, adopts the
+> constructable-stylesheet twin of `web-components.min.css` (the `./css/sheet`
+> export — `import '@adia-ai/web-components/css/sheet'` for the raw sheet) into
+> `document.adoptedStyleSheets` once, deduped. So a SPA root / embedded app / dynamic
+> mount renders fully-styled **without a hand-wired `<link>` in `<head>`**. Opt-in
+> `theme="ocean|forest|sunset|lavender|rose|slate|midnight"` and `scale="verse|prose"`
+> adopt their layer twin on demand. **Deliberately NOT in the all-primitives barrel**
+> (it carries the whole foundation) — import the `components/theme-provider` subpath
+> explicitly. Use the `<link>`/CDN path for multi-page top-level surfaces (cacheable,
+> no flash); the provider for no-`<head>` contexts.
+
+**Why this is still policy-safe**: the CDN bundles are pre-built
+artifacts in `dist/` — they don't violate the **no JS module
+self-imports CSS** rule because they're explicit `<link>` tags in the
+HTML head (no JS module imports), AND they don't violate the **carve-out
+is explicit by name** rule because the consumer is explicitly choosing
+the CDN URL rather than an npm import path.
+
+**Pick ONE JS bundle path within CDN mode.** Mixing
+`@adia-ai/web-modules/.../everything.min.js` with
+`@adia-ai/web-components/.../web-components.min.js` causes
+`customElements.define` to throw "name already defined". Choices:
+
+| Bundle | Use case |
+|--------|----------|
+| `web-modules/.../everything.min.js` | CodePen / kitchen-sink / "just make it work" (registers all 100+ primitives + a2ui-runtime + 17 module-tier shells/parts via `defineIfFree`; v0.6.32 bundle ships with `icons-manifest.js` baked in) |
+| `web-components/.../web-components.min.js` + per-shell `*.min.js` | Primitives + one specific shell |
+| `web-components/.../web-components.min.js` alone | Primitives only, no shells |
+
+> ⚠️ **`everything.min.js` ≤ v0.6.31 was shells-only (751 KB) — broken
+> in published tarballs at v0.6.29/0.6.30/0.6.31.** The bundle did NOT
+> register primitives (`search-ui`, `select-ui`, `field-ui`,
+> `stat-ui`, `row-ui`, etc.) — consumers following the CDN-first
+> guidance hit a hard `TypeError: Cannot read properties of undefined
+> (reading 'toLowerCase')` on any code that touched a primitive
+> element's `.value`. Root cause: `bundle-js.mjs` used
+> `packages/web-modules/index.js` as the entry, which only re-exports
+> shell clusters — no primitives registration.
+>
+> **Fix landed in v0.6.32+**: new `packages/web-modules/everything.js`
+> entry file imports `@adia-ai/web-components` (registering all
+> primitives) BEFORE re-exporting `./index.js` (shells).
+> `everything.min.js` is now ~1 MB raw / ~330 KB Brotli wire, with
+> 100+ primitives + 17 shells registered.
+>
+> **If pinned to ≤0.6.31**, EITHER (a) upgrade to ≥0.6.32, OR (b) load
+> `web-components.min.js` BEFORE `everything.min.js` (defineIfFree on
+> primitive registrations + direct define on shells; verify no
+> "already defined" throws for the overlapping elements: tab-ui,
+> stat-ui, a2ui-root, canvas-ui).
+
+> ⚠️ **`web-components.min.js` icon support depends on
+> `icons-manifest.js` co-distribution (v0.6.32+).** The primitives
+> bundle does `import("./icons-manifest.js")` at runtime to load icon
+> SVG data. In versions ≤0.6.31 the manifest was NOT shipped in the
+> tarball — CDN consumers got a silent 404 and all `icon=` attributes
+> failed to render SVGs (non-fatal but visually broken).
+>
+> **Fix landed in v0.6.32+**: `packages/web-components/dist/icons-manifest.js`
+> is now a tracked dist artifact (256 KB, 9,072 icon names) generated
+> by `scripts/build/bundle-js.mjs`. The manifest includes a `cdn` key
+> pointing to `@phosphor-icons/core@2.1.1/assets/` so SVGs fetch from
+> jsdelivr (not `/node_modules/...`). CDN icons now work end-to-end
+> without consumer-side setup.
+>
+> **If pinned to ≤0.6.31** and using `web-components.min.js`: any
+> `icon=` attribute silently fails. Upgrade to ≥0.6.32 OR use
+> `everything.min.js` (which inlines icon data directly — but see the
+> previous callout: `everything.min.js` ≤0.6.31 also has the
+> shells-only bug, so the only working pre-0.6.32 path is the
+> dual-bundle workaround).
+
+**Authoritative reference**: `references/setup.md` Step 0.5 (peer authored
+in the v0.6.30 cycle); full CDN docs at
+[`ui-kit.exe.xyz/site/getting-started/cdn-usage`](https://ui-kit.exe.xyz/site/getting-started/cdn-usage);
+working CodePen template at
+[`examples/codepen.html`](https://github.com/adiahealth/gen-ui-kit/blob/main/examples/codepen.html).
+
+### Reserved layout-helper attribute names (admin-shell scoping)
+
+`admin-shell.helpers.css` ships 5 layout-utility attribute selectors
+intended for use INSIDE `<admin-shell>`:
+
+```css
+admin-shell [data-col]    { display: flex; flex-direction: column; … }
+admin-shell [data-row]    { display: flex; align-items: center; … }
+admin-shell [data-grid]   { display: grid; grid-template-columns: 1fr 1fr; … }
+admin-shell [data-actions]{ display: flex; align-items: center; … }
+admin-shell [data-spacer] { flex: 1; }
+```
+
+> ⚠️ **`[data-col]`, `[data-row]`, `[data-grid]`, `[data-actions]`,
+> `[data-spacer]` are reserved layout-helper attribute names.**
+> Loading `admin-shell.min.css` on a page that uses any of these
+> attribute names on non-admin-shell elements (or on `<admin-shell>`
+> descendants where the application of `display: flex/grid` is
+> unintended) WILL apply layout to those elements. **In Safari/WebKit
+> this silently breaks `<table>` layout** when `<th data-col="N">` or
+> similar matches the bare `[data-col]` selector — the table renders
+> with `<thead>` as a vertical left column and `<tbody>` shifted right.
+>
+> **Mitigation already shipped (v0.6.31 source, v0.6.32+ dist)**: all 5
+> selectors prefixed with `admin-shell` ancestor. Versions ≤ v0.6.30
+> shipped bare global selectors and remain broken for CDN consumers
+> pinned to those versions.
+>
+> **Defense for new authoring**: do NOT use `data-col` / `data-row` /
+> `data-grid` / `data-actions` / `data-spacer` for arbitrary table
+> headers, sortable columns, or any non-admin-shell layout marker.
+> Namespaced names (`data-page-col`, `data-my-actions`, `data-sort-col`)
+> sidestep the collision entirely. Even after the v0.6.32 scoping fix,
+> the names remain reserved within admin-shell descendants — using
+> `data-col` on a `<th>` that happens to live inside an
+> `<admin-page-body>` table will still apply `display: flex`.
+
+**Why `admin-shell` ancestor and not `@scope`**: the admin-shell build
+pipeline emits 0 `@scope` blocks in its dist CSS (LightningCSS strips
+them or the source never authored them). The parent-tag selector is
+the only reliable CDN-safe scoping mechanism for these helpers.
+
+### Operational rules — CDN-bundle path lead-with
+- When the user's intent is "quick prototype" / "static HTML" / "CodePen demo" /
+  "no bundler" — **lead with CDN, not bundler**. The setup discussion is
+  one paragraph instead of an 8-step procedure.
+- When the user's intent is "production app" / "we use Vite" / "tree-shake matters" —
+  **stay on the explicit-import tier**. The CDN bundle's kitchen-sink
+  payload is over-fetched compared to a tree-shaken Vite build.
+- When the user lands in a repo with NO `package.json` (per §Recon
+  Gap class 0 detection) — **mention both paths**: (1) `npm init` +
+  bundler + explicit-import, OR (2) zero-install CDN. Let the operator
+  choose. Historically the gate was "ship deps with `npm install`"; CDN
+  removes that as the only option.
+
+### Operational rules (for skill, docs, and tooling)
+
+- **Skill examples** (this skill, README files in `@adia-ai/*` packages,
+  USAGE.md): every shell-using code example MUST show the matching CSS
+  import. Pattern callouts MUST flag missing CSS imports as the most
+  common cold-start failure mode (see §Patterns → Admin shell anatomy).
+- **CI gate** (recommended; not yet implemented): a release-time audit
+  that grep-greps every `*-shell.js` and `*-ui.js` for `import .*\\.css`
+  and fails if any are found. This catches accidental policy drift.
+- **Migration path**: if the policy ever changes (e.g. a new ADR adopts
+  side-effect CSS), it MUST be a coordinated MAJOR-version cut across
+  all 9 `@adia-ai/*` packages, accompanied by a MIGRATION GUIDE entry.
+
+### Consumer-side migration helpers
+
+For consumers who hit the unstyled-stacked-divs failure mode:
+
+1. **Run a Playwright probe** that takes a screenshot of the rendered
+   shell. If it visually matches "unstyled stacked divs", the diagnosis
+   is "missing shell CSS import".
+2. **Check your entry file** for `import '@adia-ai/web-modules/shell/<name>.css'`.
+   If missing, add it.
+3. **Verify the path shape**: `./shell/<name>.css` (the export-map
+   wildcard resolves this to `./shell/<name>/<name>.css` on disk).
+   Pre-v0.6.7 docs incorrectly showed the disk shape; v2.4.1 of this
+   skill corrected it.
+
+### Cross-references
+
+- `claims-ui/.agent/team/tickets/README.md` §F-006 (the cold-start
+  failure that surfaced the policy ambiguity).
+- `.brain/notes/2026-05-20-claims-ui-feedback-followup.md` §F-006
+  (peer-agent synthesis + the user-direction quote that pinned the
+  policy).
+- `§Patterns → Admin shell anatomy` (the pitfall callout that warns
+  consumers about the missing-CSS failure mode).
+- `§Setup` step 3 (the actual import lines, now with all 4 shell variants).
+
+
+---

package/skills/adia-ui-kit/references/decision-model.md

@@ -0,0 +1,158 @@
+# DecisionModel — Orphan-Component Audit Contract (advisory in v3.1.0)
+
+**Status.**
+- v3.1.0: **ADVISORY** — `scripts/audit-decision-trace.mjs` runs in `--advisory` mode by default (reports findings; never fails CI). Goal: collect ≥3 weeks of real-world traces to calibrate the orphan-component definition.
+- v3.2.0+ (planned): **HARD-FAIL** — same script with `--strict`. Promotion gate: zero false-positive findings observed across ≥3 weeks of advisory-mode traces, AND the orphan definition stable for ≥2 minor releases.
+
+Per REFACTOR-SPEC P5(b). Counter-proposal accepted by user 2026-05-22 (Phase 4 advisory rollout — split P5 into P5(a) session-log + P5(b) DecisionModel; ship both in v3.1.0; advisory-only for P5(b) until 2026-08-22 BORIS §B3 checkpoint at the earliest).
+
+---
+
+## The Contract
+
+A **decision** is a named choice between two or more **possible actions**, resolved by a **required signal**. Every component the agent names in a composition output (modes 1-4) should trace to ≥1 decision's `possible_actions` array.
+
+The shape:
+
+```json
+{
+  "decision": "string — what was being decided (≤ 120 chars, in English)",
+  "required_signal": "string — what input the decision depended on",
+  "possible_actions": ["action-a", "action-b", "action-c"],
+  "chosen_action": "string — must be one of possible_actions",
+  "rationale": "string — why this signal mapped to this action"
+}
+```
+
+Each entry in `possible_actions` is either:
+- a **component tag** (e.g. `button-ui`, `simple-shell`, `editor-canvas`), or
+- a **higher-level intent label** that itself decomposes into named components later (e.g. `none (raw)`, `marketing-hero-recipe`, `chat-shell-anatomy`).
+
+The audit traces forward: every component tag named in the agent's output must appear in some decision's `possible_actions` or `chosen_action`.
+
+---
+
+## What it catches (the jagged-edge problem)
+
+**Jagged-edge composition** = the agent names a component that wasn't connected to any tracked decision. Either:
+- (a) the component is genuinely a good idea but the agent skipped surfacing the decision (loss of audit trail, hard to retro why later), OR
+- (b) the component is hallucinated / wrong-fit (the agent named it without a decision because there wasn't a real reason).
+
+Both are bugs in different ways. (a) is a discipline gap — the decision happened in the agent's head but didn't get logged. (b) is a correctness bug — the component appeared from nowhere.
+
+The audit doesn't distinguish (a) from (b); it surfaces both as "orphan-component" findings and lets the operator decide.
+
+---
+
+## Worked Example — login page composition
+
+### DecisionModel (3 decisions)
+
+```json
+[
+  {
+    "decision": "which shell wraps the login page",
+    "required_signal": "page chrome needs",
+    "possible_actions": ["admin-shell", "simple-shell", "editor-shell", "none (raw)"],
+    "chosen_action": "simple-shell",
+    "rationale": "login pages are standalone marketing-style pages without admin chrome"
+  },
+  {
+    "decision": "input control for the email field",
+    "required_signal": "is the value type email + does the form need validation",
+    "possible_actions": ["input-ui type=email", "form-field with input-ui", "email-input-ui"],
+    "chosen_action": "form-field with input-ui",
+    "rationale": "form-field wraps label + validation + error display; we need all three"
+  },
+  {
+    "decision": "submit affordance for the form",
+    "required_signal": "is this a primary form action with potential loading state",
+    "possible_actions": ["button-ui variant=primary", "submit-button-ui", "form-actions slot"],
+    "chosen_action": "button-ui variant=primary [type=submit] [loading]",
+    "rationale": "single primary action; button-ui supports the loading state for in-flight submit"
+  }
+]
+```
+
+### Generated composition
+
+```html
+<simple-shell>
+  <simple-hero>
+    <h1>Sign in</h1>
+  </simple-hero>
+  <form>
+    <field-ui label="Email">
+      <input-ui type="email" required></input-ui>
+    </field-ui>
+    <field-ui label="Password">
+      <input-ui type="password" required></input-ui>
+    </field-ui>
+    <button-ui variant="primary" type="submit">Sign in</button-ui>
+  </form>
+</simple-shell>
+```
+
+### Audit walk
+
+| Tag | Decision matched | Status |
+|---|---|---|
+| `simple-shell` | Decision 1 (`chosen_action`) | ✓ traced |
+| `simple-hero` | — | ✗ **ORPHAN** (no decision named it) |
+| `form-field` | Decision 2 (`chosen_action`) | ✓ traced |
+| `input-ui` | Decision 2 (inside chosen_action) | ✓ traced (partial — second use for password is implicit) |
+| `button-ui` | Decision 3 (`chosen_action`) | ✓ traced |
+
+→ 1 orphan finding: `simple-hero` was named without a decision. The agent should either (a) retroactively add Decision 4 ("which heading affordance — `simple-hero` vs raw `h1` vs `page-header-ui`?"), or (b) accept it as an obvious idiom and add it to the project-specific allowlist.
+
+---
+
+## Allowlist mechanism (escape hatch)
+
+Some idioms are universal enough that surfacing a decision is overkill (e.g. `<h1>` inside `<simple-hero>`, `<p>` inside any text container). Per-project allowlist at `.agents/skills/adia-ui-kit/.decision-trace-allowlist.json`:
+
+```json
+{
+  "version": "1",
+  "allowed_orphans": [
+    {
+      "tag": "h1",
+      "rationale": "raw heading — universal idiom, no decision needed"
+    },
+    {
+      "tag": "h2",
+      "rationale": "raw heading — universal idiom"
+    },
+    {
+      "tag": "p",
+      "rationale": "raw paragraph — universal idiom"
+    }
+  ]
+}
+```
+
+The audit subtracts allowlist entries from findings. Allowlist additions should themselves be justified (the `rationale` field is required).
+
+---
+
+## What v3.1.0 ships
+
+- `scripts/audit-decision-trace.mjs` — runs in advisory mode by default. Reads a JSONL session log (per `session-log-schema.md`), extracts `decision_made` and `component_named` events, walks the trace, reports orphan-component findings.
+- `references/decision-model.md` — this document.
+- **No SKILL.md hard requirement** that agents emit DecisionModel events in v3.1.0 — emission is opt-in / advisory.
+
+## What v3.2.0+ may add
+
+- Hard-fail mode in `audit-decision-trace.mjs --strict` wired into `check:skills:strict`.
+- Agents in modes 1-4 emit `decision_made` events before every component_named (per BORIS §Plan-Execute-Verify discipline).
+- Promotion gate: ≥3 weeks of advisory-mode traces with manual review confirming 0 false-positive orphans, OR a stable definition of orphan-vs-allowed.
+
+---
+
+## Cross-references
+
+- `scripts/audit-decision-trace.mjs` — the runtime audit
+- `references/session-log-schema.md` — the JSONL event format that this audit consumes
+- `references/teach-protocol.md` — branch-D decisions about NEW methodologies land here
+- REFACTOR-SPEC P5(b) — origin of this contract
+- AGENTS.md Plan-Execute-Verify rule (§14) — the discipline that DecisionModel mechanizes

package/skills/adia-ui-kit/references/diagnostic-output.md

@@ -0,0 +1,57 @@
+---
+name: diagnostic-output
+load-when: When authoring a §DiagnosticOutput repo-health report — the 7-section template that pairs with §Recon + §GapDetection
+load-size-tokens: ~700
+required-for:
+  - mode 5 (consultant) audit-output authoring
+---
+
+# 7. Overall posture assessment
+
+One-paragraph bottom-line summary the report-reader can carry into a
+hallway conversation. The shape:
+
+> `<Repo>` is in **<strong | moderate | weak> adoption state** — ~N%
+> canonical, with M consumer-side gaps (X spec-drift, Y hygiene, Z
+> upstream-deferred). The biggest leverage finding is `<Gap N>`. Roughly
+> `<the best | a representative | a struggling>` consumer the substrate
+> currently has. **Recommended next action:** `<Sweep K>` (`<effort>`).
+> Defer the rest until `<trigger condition>`.
+
+This section is mandatory; skipping it leaves the report consumer with
+a ranked gap list but no narrative. Sections 1–6 are exhaustive; §7 is
+the tl;dr.
+````
+
+### Discipline rules for the diagnostic report
+
+1. **Evidence is mandatory.** Every gap must cite at least one
+   `<file:line>` or grep output. Findings without evidence get rejected.
+2. **Mechanism before remediation.** State *why* the gap exists before
+   *how* to fix it. A remediation without a mechanism is a workaround.
+3. **Leverage ranking is explicit.** Gaps with no leverage estimate
+   don't appear in the report — they go in §5 (out-of-scope) with the
+   deliberate-exclusion rationale.
+4. **PATCH-scoped sweeps only.** Each remediation must fit a single
+   PATCH cut (additive, non-breaking). Bigger sweeps decompose into N
+   PATCH cuts ranked by leverage.
+5. **Hand off; do not author.** The report ends. The user reads it and
+   either confirms, scopes, or rejects each sweep. Authoring proceeds
+   from a *confirmed* plan — never from an inferred one.
+
+### Anti-patterns
+
+- **Dumping recon output as "the report."** Recon is raw inventory;
+  the report is a *synthesis* of inventory + gaps + plan. A grep dump
+  is not a report.
+- **Ranking gaps by personal interest instead of leverage.** "I want
+  to refactor the shells" is not leverage; "8 shells × 12 LOC each
+  replaceable with 4 LOC each = -64 LOC net" is.
+- **Proposing remediation without verification.** Every sweep needs a
+  gate that confirms it landed. If no gate exists, propose one as
+  part of the sweep.
+- **Skipping out-of-scope.** §5 is load-bearing — it shows the user
+  what you *considered and rejected*, which builds trust faster than
+  any other section.
+
+---