@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/defense-in-depth/SKILL.md

@@ -0,0 +1,157 @@
+---
+model_tier: high
+name: defense-in-depth
+description: "Use when validation needs entry, business-logic, environment, and instrumentation guards so a bad value cannot reach the failure point — turns a local bug fix into a structural one."
+domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# defense-in-depth
+
+Validate at every layer the value passes through. Fixing the bug at one layer is locally sufficient and globally fragile — the next refactor, code path, mock, or platform edge case will rediscover it. Four-layer validation makes the bug *structurally* impossible.
+
+## When to use
+
+- Bug fix where invalid data caused failure several frames deep.
+- New entry point that funnels external input into existing internals.
+- Refactor that adds a second caller to a previously single-caller routine.
+- Test setup that shortcuts production guards (mocks bypassing entry validation).
+
+Do NOT use when:
+
+- Pure formatting / style change — no data flow, no layers to defend.
+- Boundary validation alone is correct (e.g. immutable value object with constructor invariant) — route to [`laravel-validation`](../laravel-validation/SKILL.md).
+- The fix belongs at a single architectural seam — adding three more guards is over-engineering. Use the gate function below to stop early.
+
+## Procedure: Apply the four-layer pattern
+
+### Step 0: Analyze the data flow before adding guards
+
+1. Identify where the bad value originates (test fixture, request body, env var, config).
+2. List every function that receives the value before the failure point.
+3. Mark which functions are reachable from production paths and which only from tests.
+
+### Step 1: Layer 1 — Entry-point validation
+
+Reject obviously invalid input at the API / route / command boundary. In Laravel this is FormRequest rules; in pure PHP services it is the public method on the service.
+
+```php
+public function createProject(string $name, string $workingDirectory): Project
+{
+    if (trim($workingDirectory) === '') {
+        throw new InvalidArgumentException('workingDirectory cannot be empty');
+    }
+    if (! is_dir($workingDirectory)) {
+        throw new InvalidArgumentException("workingDirectory does not exist: {$workingDirectory}");
+    }
+    if (! is_writable($workingDirectory)) {
+        throw new InvalidArgumentException("workingDirectory is not writable: {$workingDirectory}");
+    }
+    // ... proceed
+}
+```
+
+### Step 2: Layer 2 — Business-logic validation
+
+Verify the value still makes sense for the operation that consumes it. Different code paths can reach the same internal — re-check rather than trust the caller.
+
+```php
+public function initializeWorkspace(string $projectDir, string $sessionId): Workspace
+{
+    if ($projectDir === '') {
+        throw new RuntimeException('projectDir required for workspace initialization');
+    }
+    // ... proceed
+}
+```
+
+### Step 3: Layer 3 — Environment guards
+
+Refuse dangerous operations in the wrong context — most often: running a destructive command outside a test temp dir while the test suite is active.
+
+```php
+public function gitInit(string $directory): void
+{
+    if (app()->environment('testing')) {
+        $normalized = realpath($directory) ?: $directory;
+        $tmp = realpath(sys_get_temp_dir());
+
+        if ($tmp === false || ! str_starts_with($normalized, $tmp)) {
+            throw new RuntimeException("refusing git init outside tmp during tests: {$directory}");
+        }
+    }
+    // ... proceed
+}
+```
+
+### Step 4: Layer 4 — Debug instrumentation
+
+Capture context for forensics so the next failure surfaces *why*, not just *that*. Log only when the call is about to hit an irreversible side effect.
+
+```php
+public function gitInit(string $directory): void
+{
+    Log::debug('about to git init', [
+        'directory' => $directory,
+        'cwd' => getcwd(),
+        'trace' => (new Exception)->getTraceAsString(),
+    ]);
+    // ... proceed
+}
+```
+
+### Step 5: Verify each layer in isolation
+
+Try to bypass Layer 1 (call the internal directly) and confirm Layer 2 catches it. Mock the production guard and confirm Layer 3 still refuses. The pattern only earns its name when each layer is independently provable.
+
+## Gate function — when to stop adding layers
+
+```
+BEFORE adding the 5th guard:
+  STOP — re-check the data flow.
+
+  IF the value crosses ≤ 1 module boundary:
+    Use a single boundary check + a value-object invariant. Two layers max.
+
+  IF every layer would re-implement the same predicate:
+    Hoist the predicate into a value object / type and inject. One check is enough.
+
+  Layers are for distinct concerns: input shape vs operation invariant
+  vs environment risk vs forensic visibility. Same concern repeated is duplication, not depth.
+```
+
+## Output format
+
+1. The four guards (or a documented subset, with the gate-function justification).
+2. Tests that bypass each layer to prove the next layer catches the failure.
+3. One-line note on the data flow that motivated the layering.
+
+## Gotcha
+
+- Layers 1 and 2 must reject with **distinct** errors — same error string makes the second guard look like a duplicate.
+- Layer 3 environment checks should fail closed: unknown environment treated as production.
+- Layer 4 instrumentation must not change behavior — no early returns, no mutated state.
+- Test bypasses (in-process mocks) often skip Layer 1 — Layer 2 catches them; do not weaken Layer 2 to silence the test.
+
+## Do NOT
+
+- Do NOT replicate Layer 1 inside private methods that only Layer 1 can reach.
+- Do NOT log secrets in Layer 4 — sanitize before `Log::debug`.
+- Do NOT use Layer 3 to gate business logic — environments change, business rules do not.
+- Do NOT add a layer without a failing test that proves the layer was needed.
+
+## Auto-trigger keywords
+
+- defense in depth
+- multiple validation layers
+- bug deep in execution
+- structurally impossible
+
+## Provenance
+
+- Adopted from: an external reference (MIT, © 2025 an external reference).
+- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `defense-in-depth`).
+- Iron-Law floor: `non-destructive-by-default`, `verify-before-complete`, `skill-quality`.

package/dist/agent-src/skills/design-intelligence/ATTRIBUTION.md

@@ -0,0 +1,54 @@
+# Attribution — vendored design-knowledge corpus + grounding engine
+
+This skill's `data/` corpus and the ported engine code derive from the
+upstream repository below. Keep this file shipping with the skill; update the
+`last-checked` date on every refresh.
+
+## Upstream source
+
+- Repository: `https://github.com/nextlevelbuilder/ui-ux-pro-max-skill`
+- Commit SHA: `b7e3af80f6e331f6fb456667b82b12cade7c9d35`
+- Last checked: 2026-06-07
+- Upstream version: `skill.json` v2.5.x (npm `uipro-cli`)
+
+## Licenses
+
+### MIT — corpus + core engine (root `LICENSE`)
+
+Copyright (c) 2024 **Next Level Builder**. The tabular corpus
+(`ui-reasoning`, `products`, `colors`, `styles`, `typography`, `charts`,
+`landing`, `icons`, `ux-guidelines`, `react-performance`, `app-interface`,
+`stacks/*`) and the Python engine sources (`core.py`, `search.py`,
+`design_system.py`) are MIT-licensed. Obligation: **retain this notice**.
+
+### Apache-2.0 — `ui-styling`-derived material ("claudekit")
+
+The upstream `ui-styling` sub-skill ships a dedicated `LICENSE.txt`
+(Apache License 2.0, vendored "claudekit"). The dedicated license file is
+treated as authoritative over the sub-skill's MIT frontmatter claim.
+Obligations for any asset derived from it (`shadcn_add.py`,
+`tailwind_config_gen.py`, a11y reference material):
+
+- retain the notice and attribute "claudekit";
+- **mark modified files** (Apache-2.0 §4b) — every ported/edited file carries
+  a header line `Modified from upstream (Apache-2.0, claudekit) — see ATTRIBUTION.md`;
+- ship the Apache-2.0 license text alongside the derived assets
+  (`LICENSE.apache-2.0.txt` in this directory when the first derived asset
+  lands).
+
+## Modifications (running log)
+
+- 2026-06-07 — Engine ported into `src/skills/_lib/corpus-grounding/`
+  (BM25 + decision-rule evaluator + schema validator), de-duplicated
+  (`core.py` / `slide_search_core.py` were byte-identical), slide-only paths
+  stripped, structured `filters` pre-filtering added, manifest-driven
+  multi-domain support added. Corpus CSVs adopted unmodified except:
+  `draft.csv` skipped (dead byte-identical backup), `google-fonts.csv`
+  skipped (public-API-redundant — see ADR-061 §8), `design.csv` prose
+  translated to English.
+
+## Provenance discipline
+
+Per ADR-061 §6, every adopted asset carries an inline upstream-source line
+(repo + SHA + last-checked). Refresh cadence and the named maintenance owner
+live in the corpus manifest headers.

package/dist/agent-src/skills/design-intelligence/LICENSE.apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/agent-src/skills/design-intelligence/SKILL.md

@@ -0,0 +1,177 @@
+---
+model_tier: inherit
+name: design-intelligence
+description: "Grounded design brief from the adopted corpus — style, WCAG-checked color tokens, typography, layout pattern, anti-patterns. Use on ui-design-brief or any which-style/palette/font/chart decision."
+domain: engineering
+personas:
+  - frontend-engineer
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+trust:
+  level: professional
+install:
+  removable: true
+execution:
+  type: manual
+---
+
+# design-intelligence
+
+> The grounded source for frontend design decisions (ADR-061; first
+> consumer of [`corpus-grounding`](../corpus-grounding/SKILL.md)). When the
+> UI directive set's `design` step emits `@agent-directive: ui-design-brief`,
+> consult this corpus FIRST and pre-fill the brief candidates — then the
+> human confirms (`design_confirmed`). Corpus output is a **constraint
+> set**, never final microcopy; the placeholder lock in
+> `directives/ui/design.py` is unaffected.
+>
+> **Boundary (council-locked):** `design.py` stays a pure orchestration
+> gate and never imports the engine — the corpus call lives HERE, in the
+> skill layer, keeping the engine an optional dependency.
+
+Corpus: 11 tabular CSVs under [`data/`](data/) (161-row `ui-reasoning`
+decision map, WCAG-adjusted color token sets, 84 styles, 73 font
+pairings, 25 chart rules, UX/react/mobile guidelines) + 16 prose
+design-language specs ([`references/design-languages.md`](references/design-languages.md))
++ the 10-category pre-delivery checklist
+([`references/design-rules-checklist.md`](references/design-rules-checklist.md)).
+Provenance + licenses: [`ATTRIBUTION.md`](ATTRIBUTION.md); manifest:
+[`data/manifest.json`](data/manifest.json).
+
+## When to use
+
+- The UI directive set emits `@agent-directive: ui-design-brief` (the
+  design step found `state.ui_design` empty).
+- Any pre-build selection question: which style / palette / font pairing /
+  layout pattern / chart type / icon system fits this product.
+- Stack-idiom lookup before writing UI code (`--stack` axis).
+
+## Procedure: Produce a grounded design brief (`ui-design-brief` rebound)
+
+1. **Ground** (one call — engine runs the manifest's plan
+   product → style → color → landing → typography with decision rules):
+
+   ```bash
+   python3 <skills-root>/corpus-grounding/scripts/ground.py ground \
+     --manifest <skills-root>/design-intelligence/data/manifest.json \
+     "<product type + mood + platform>" --json
+   ```
+
+2. **Translate selections into the brief** for `state.ui_design`:
+   - `layout` ← landing/pattern selection (`Section Order`, CTA placement)
+     + the reasoning rule's `Recommended_Pattern`;
+   - `components` ← audit reuse first (`existing-ui-audit` inventory wins
+     over corpus suggestions — never propose a new component the audit
+     already has);
+   - `states` ← required five (`empty/loading/error/success/disabled`),
+     styled per the selected design language;
+   - `microcopy` ← **agent-written, final strings** — the corpus never
+     supplies microcopy;
+   - `a11y` ← color selection's contrast-adjusted token set + the
+     checklist's CRITICAL rows + `accessibility-auditor` method;
+   - style/typography/effects/anti-patterns ← the grounded selections
+     verbatim, with alternatives listed.
+3. **Always surface** the grounded output's `confidence` + `evidence_gap`
+   lines in the brief summary — the user signs off on what the corpus
+   could NOT support, not only on what it could.
+4. On `design_confirmed: true` the directive engine advances; revisions
+   loop back here.
+
+### Font fallback (no google-fonts index — by design)
+
+The 745 KB Google-Fonts index was rejected (ADR-061 §8): it duplicates a
+public API. When a requested font is outside `typography.csv`'s 73
+pairings: query `https://fonts.google.com/specimen/<Family>` (or the
+`webfonts` API) for metadata, OR propose the nearest curated pairing and
+say why. Never invent pairing metadata.
+
+## `MASTER.md` + page overrides ↔ `state.ui_design` (mapping)
+
+The upstream cross-session memory pattern maps onto our delivery state:
+
+| Upstream artifact | Our state | Notes |
+|---|---|---|
+| `design-system/<project>/MASTER.md` | `state.ui_design` (project-level brief: style, tokens, typography, anti-patterns) | The state is the source of truth during a run. |
+| `design-system/<project>/pages/<page>.md` | per-page override entries inside `state.ui_design` (e.g. `pages.<page>` dict) | Page rules override project rules for that page only. |
+
+File persistence stays **opt-in** (`ground … --persist <dir>`) and writes
+under the consumer's project as a durable artifact for multi-session
+consistency; on a fresh session, re-hydrate `state.ui_design` from
+`MASTER.md` + the page file before re-running `design`.
+
+## Grounding the review/polish a11y gate (charts + contrast)
+
+The `review`/`polish` steps gate on `state.ui_review.a11y`. Ground two
+finding classes instead of ad-hoc judgment:
+
+- **Chart-type findings** — `…/ground.py search --manifest … --domain
+  chart "<data shape>"` → `Accessibility Grade`, `A11y Fallback`,
+  `Color Guidance` columns justify "wrong chart type / missing colorblind
+  fallback" findings with a citable row.
+- **Contrast findings** — `--domain color "<product>"` returns the
+  WCAG-adjusted token set; a finding that a hex pair deviates from the
+  adopted set cites the row instead of eyeballing ratios. Auditing
+  *method* stays with [`accessibility-auditor`](../accessibility-auditor/SKILL.md).
+
+## Stack guidance (`--stack` axis)
+
+Per-framework Do/Don't corpora (16 stacks) ride the same manifest:
+
+```bash
+python3 <skills-root>/corpus-grounding/scripts/ground.py search \
+  --manifest <skills-root>/design-intelligence/data/manifest.json \
+  --stack react "list rerender memo" [--filter "Severity=HIGH"]
+```
+
+Stack executors ([`blade-ui`](../blade-ui/SKILL.md),
+[`livewire`](../livewire/SKILL.md), [`flux`](../flux/SKILL.md),
+[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md),
+[`tailwind-engineer`](../tailwind-engineer/SKILL.md)) pull idiomatic
+guidance + docs URLs from here instead of memory.
+
+## Output format
+
+1. Grounded brief candidates per `state.ui_design` slot (layout,
+   components, states, microcopy placeholder-free, a11y) — selections
+   cited per corpus row.
+2. The grounded output's `confidence` label + every `evidence_gap` line,
+   verbatim, in the brief summary.
+3. Alternatives list per domain so the human can swap before
+   `design_confirmed`.
+
+## Do NOT
+
+- Do NOT let the corpus write microcopy — it supplies constraint sets;
+  final strings are agent-written (placeholder lock stays in force).
+- Do NOT import the engine into `directives/ui/design.py` — council
+  boundary; the corpus call lives in this skill layer.
+- Do NOT propose a new component the `existing-ui-audit` inventory
+  already covers — audit findings outrank corpus suggestions.
+- Do NOT hide low confidence — the user signs off on the gaps too.
+
+## Interplay (who owns what)
+
+| Concern | Owner |
+|---|---|
+| What already exists (components, tokens) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — mandatory pre-step; audit findings outrank corpus suggestions |
+| What to build (grounded selection) | **this skill** |
+| Stack-agnostic heuristics + flow | [`fe-design`](../fe-design/SKILL.md) — invokes this skill for grounding |
+| Orchestration gates + locks | `directives/ui/{design,review,polish}.py` — never import the engine |
+| WCAG audit method | [`accessibility-auditor`](../accessibility-auditor/SKILL.md) |
+| Token authoring | [`design-tokens`](../design-tokens/SKILL.md) |
+
+## Gotchas
+
+- Corpus grounds **pre-action selection** — do not use it as mid-task
+  reference (open `references/` instead) or as a validator (rules own that).
+- Empty result ≠ error: surface the evidence gap and proceed on priors.
+- Keep queries product-shaped ("fintech dashboard", "luxury e-commerce
+  mobile") — the detect map routes generic words to `style`.
+
+## Policies
+
+- Upstream MIT + Apache-2.0 obligations: [`ATTRIBUTION.md`](ATTRIBUTION.md).
+- Refresh: quarterly per the manifest; bump `upstream.last_checked` on
+  every refresh (ADR-061 §6).

package/dist/agent-src/skills/design-intelligence/data/app-interface.csv

@@ -0,0 +1,31 @@
+No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity
+1,Accessibility,Icon Button Labels,icon button accessibilityLabel,iOS/Android/React Native,Icon-only buttons must expose an accessible label,Set accessibilityLabel or label prop on icon buttons,Icon buttons without accessible names,"<Pressable accessibilityLabel=""Close""><XIcon /></Pressable>","<Pressable><XIcon /></Pressable>",Critical
+2,Accessibility,Form Control Labels,form input label accessibilityLabel,iOS/Android/React Native,All inputs must have a visible label and an accessibility label,Pair Text label with input and set accessibilityLabel,Inputs with placeholder only,"<View><Text>Email</Text><TextInput accessibilityLabel=""Email address"" /></View>","<TextInput placeholder=""Email"" /></View>",Critical
+3,Accessibility,Role & Traits,accessibilityRole accessibilityTraits,iOS/Android/React Native,Interactive elements must expose correct roles/traits,Use accessibilityRole/button/link/checkbox etc.,Rely on generic views with no roles,"<Pressable accessibilityRole=""button"">Submit</Pressable>","<View onTouchStart={submit}>Submit</View>",High
+4,Accessibility,Dynamic Updates,accessibilityLiveRegion announce,iOS/Android/React Native,Async status updates should be announced to screen readers,Use accessibilityLiveRegion or announceForAccessibility,Update text silently with no announcement,"<Text accessibilityLiveRegion=""polite"">{status}</Text>","<Text>{status}</Text>",Medium
+5,Accessibility,Decorative Icons,accessible={false} importantForAccessibility,iOS/Android/React Native,Decorative icons should be hidden from screen readers,Mark decorative icons as not accessible,Have screen reader read every icon,"<Icon accessible={false} importantForAccessibility=""no"" />","<Icon />",Medium
+6,Touch,Touch Target Size,touch 44x44 hitSlop,iOS/Android/React Native,Primary touch targets must be at least 44x44pt,Increase hitSlop or padding to meet minimum,Small icons with tiny touch area,"<Pressable hitSlop={10}><Icon /></Pressable>","<Pressable><Icon style={{ width: 16, height: 16 }} /></Pressable>",Critical
+7,Touch,Touch Spacing,touch spacing gap 8px,iOS/Android/React Native,Adjacent touch targets need enough spacing,Keep at least 8dp spacing between touchables,Cluster many buttons with no gap,"<View style={{ gap: 8 }}><Button ... /><Button ... /></View>","<View><Button ... /><Button ... /></View>",Medium
+8,Touch,Gesture Conflicts,scroll swipe back gesture,iOS/Android/React Native,Custom gestures must not break system scroll/back,Reserve horizontal swipes for carousels,Full-screen custom swipe conflicting with back,"HorizontalPager inside vertical ScrollView","PanResponder on full screen blocking back",High
+9,Navigation,Back Behavior,back handler navigation stack,iOS/Android/React Native,Back navigation should be predictable and preserve state,Use navigation.goBack and keep screen state,Reset stack or exit app unexpectedly,onPress={() => navigation.goBack()},"BackHandler.exitApp() on first press",Critical
+10,Navigation,Bottom Tabs,tab bar max items,iOS/Android/React Native,Bottom tab bar should have at most 5 primary items,Use 3–5 tabs and move extras to More/Settings,Overloaded tab bar with many icons,Home/Explore/Profile/Settings,"Home/Explore/Shop/Cart/Profile/Settings/More",Medium
+11,Navigation,Modal Escape,modal dismiss close affordance,iOS/Android/React Native,Modals/sheets must have clear close actions,Provide close button and swipe-down where platform expects,Trapping users in modal with no obvious exit,"<Modal><Button title=""Close"" onPress={onClose} /></Modal>","<Modal><View>{children}</View></Modal>",High
+12,State,Preserve Screen State,navigation preserve state,iOS/Android/React Native,Returning to a screen should restore its scroll and form state,Keep components mounted or persist state,Reset list scroll and form inputs on every visit,"<Tab.Navigator screenOptions={{ unmountOnBlur: false }}>","<Tab.Screen options={{ unmountOnBlur: true }} />",Medium
+13,Feedback,Loading Indicators,activity indicator skeleton,iOS/Android/React Native,Show visible feedback during network operations,Use ActivityIndicator or skeleton for >300ms operations,Leave button and screen frozen,"{loading ? <ActivityIndicator /> : <Button title=""Save"" />}", "<Button title=""Save"" onPress={submit} /> // no loading",High
+14,Feedback,Success Feedback,toast checkmark banner,iOS/Android/React Native,Confirm successful actions with brief feedback,Show toast/checkmark or banner,Complete actions silently with no confirmation,"showToast('Saved successfully')","// silently update state only",Medium
+15,Feedback,Error Feedback,inline error banner,iOS/Android/React Native,Show clear error messages near the problem,input-level error + summary banner,Only change border color with no explanation,"<TextInput ... /><Text style={{color:'red'}}>{error}</Text>","<TextInput style={{borderColor:'red'}} />",High
+16,Forms,Inline Validation,onBlur validation,iOS/Android/React Native,Validate inputs on blur or submit with clear messaging,Validate onBlur and onSubmit,Validate on every keystroke causing jank,"onBlur={() => validateEmail(value)}","onChangeText={v => validateEmail(v)} // every char",Medium
+17,Forms,Keyboard Type,keyboardType returnKeyType,iOS/Android/React Native,Use appropriate keyboardType and returnKeyType,Match email/tel/number/search types,Use default keyboard for all inputs,"<TextInput keyboardType=""email-address"" />","<TextInput keyboardType=""default"" />",Medium
+18,Forms,Auto Focus & Next,autoFocus blurOnSubmit onSubmitEditing,iOS/Android/React Native,Guide users through form fields with Next/Done flows,Use onSubmitEditing to focus next input,Force users to tap each field manually,"onSubmitEditing={() => nextRef.current?.focus()}","// no onSubmitEditing, manual tap only",Low
+19,Forms,Password Visibility,secureTextEntry toggle,iOS/Android/React Native,Allow toggling password visibility securely,Provide Show/Hide icon toggling secureTextEntry,Force users to type blind with no option,"<TextInput secureTextEntry={secure} /><Icon onPress={toggle} />","<TextInput secureTextEntry /> // no toggle",Medium
+20,Performance,Virtualize Long Lists,FlatList SectionList virtualization,iOS/Android/React Native,Use FlatList/SectionList for lists over ~50 items,Use keyExtractor and initialNumToRender appropriately,Render hundreds of items with ScrollView,"<FlatList data={items} renderItem={...} />","<ScrollView>{items.map(renderItem)}</ScrollView>",High
+21,Performance,Image Size & Cache,Image resize cache,iOS/Android/React Native,Use correctly sized and cached images,Use Image component with proper resizeMode and caching,Load full-resolution images everywhere,"<Image source={{uri}} resizeMode=""cover"" />","<Image source={require('4k.png')} /> // small avatar",Medium
+22,Performance,Debounce High-Freq Events,debounce scroll search,iOS/Android/React Native,Debounce scroll/search callbacks to avoid jank,Wrap handlers with debounce/throttle,Run heavy logic on every event,"onScroll={debouncedHandleScroll}","onScroll={handleScrollHeavy}",Medium
+23,Animation,Duration & Easing,animation duration easing,iOS/Android/React Native,Micro-interactions should be 150–300ms with native-like easing,Use ease-out for enter/ease-in for exit,Use long or linear animations for core UI,"Animated.timing(..., { duration: 200, easing: Easing.out(Easing.quad) })","Animated.timing(..., { duration: 800, easing: Easing.linear })",Medium
+24,Animation,Respect Reduced Motion,reduced motion accessibility,iOS/Android/React Native,Respect OS reduced-motion accessibility setting,Check reduceMotionEnabled and simplify animations,Ignore user motion preferences,"if (reduceMotionEnabled) skipAnimation()","Always run complex parallax animations",Critical
+25,Animation,Limited Continuous Motion,loop animation loader,iOS/Android/React Native,Reserve infinite animations for loaders and live data,Use looping only where necessary,Keep decorative elements looping forever,"Animated.loop(loaderAnim) for ActivityIndicator","Animated.loop(bounceAnim) on background icons",Medium
+26,Typography,Base Font Size,fontScale dynamic type,iOS/Android/React Native,Body text must be readable and support Dynamic Type,Use platform fontScale and at least 14–16pt base,Render critical text below 12pt,"<Text style={{ fontSize: 16 }}>Body</Text>","<Text style={{ fontSize: 10 }}>Body</Text>",High
+27,Typography,Dynamic Type Support,allowFontScaling adjustsFontSizeToFit,iOS/Android/React Native,Support system text scaling without breaking layout,Set allowFontScaling and test large text,Disable scaling on all text globally,"<Text allowFontScaling>{label}</Text>","<Text allowFontScaling={false}>{label}</Text>",High
+28,Safe Areas,Safe Area Insets,safe area insets notch gesture,iOS/Android/React Native,Content must not overlap notches/gesture bars,Wrap screens in SafeAreaView or apply insets,Place tappable content under system bars,"<SafeAreaView style={{ flex: 1 }}><Screen /></SafeAreaView>","<View style={{ flex: 1 }}><Screen /></View>",High
+29,Theming,Light/Dark Contrast,dark mode contrast tokens,iOS/Android/React Native,Ensure sufficient contrast in both light and dark themes,Use semantic tokens and test both themes,Reuse light-theme grays directly in dark mode,"colors.textPrimaryDark = '#F9FAFB'","colors.textPrimaryDark = '#9CA3AF' on '#111827'",High
+30,Anti-Pattern,No Gesture-Only Actions,gesture only hidden controls,iOS/Android/React Native,Don't rely solely on hidden gestures for core actions,Provide visible buttons in addition to gestures,Rely on swipe/shake only with no UI affordance,"Swipe to delete + visible Delete button","Only shake device to undo with no UI",Critical