@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/skills/existing-ui-audit/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: existing-ui-audit
+description: "Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set."
+source: package
+---
+
+# existing-ui-audit
+
+## When to use
+
+Use this skill when:
+- The dispatcher has routed work to `directive_set="ui"` (intent `ui-build` or `ui-improve`)
+- A `mixed` flow is about to enter its UI phase
+- The user asks "what UI do we already have for X?"
+
+Do NOT use when:
+- `directive_set="ui-trivial"` — the trivial path bypasses audit by precondition (≤1 file, ≤5 lines, no new component, no new state, no new dep)
+- `directive_set="backend"` — no UI surface to inventory
+- The audit findings already exist in `state.ui_audit` for this state-file (cached) — re-run only if `package.json` or `composer.json` mtime changed
+
+## Procedure: Audit the existing UI surface
+
+### 0. Inspect stack and input
+
+1. Read `state.stack.frontend` — set by `scripts/work_engine/stack/detect.py` (one of `blade-livewire-flux`, `react-shadcn`, `vue`, `plain`).
+2. Read `state.input` — the request being processed. The audit must answer: "what already exists that is similar to this request?"
+
+### 1. Enumerate components and templates
+
+| Stack | Where to look |
+|---|---|
+| `blade-livewire-flux` | `resources/views/components/`, `resources/views/livewire/`, `resources/views/partials/`, `resources/views/layouts/`, `app/View/Components/`, `app/Livewire/` |
+| `react-shadcn` | `components/`, `app/components/`, `src/components/`, `src/app/(routes)/`, plus any `app/**/page.tsx` for Next.js |
+| `vue` | `resources/js/components/`, `src/components/`, `pages/` |
+| `plain` | `resources/views/`, plus any `*.html` under `public/` |
+
+Capture each component/template as: `{path, name, kind: page|partial|component|layout, exports?: [props]}`.
+
+### 2. Identify the design system
+
+Detect markers, in order. **Stop at the first match** — projects rarely run more than one design system.
+
+| Marker | Signal | Where |
+|---|---|---|
+| Flux | `livewire/flux` in `composer.json`, `<flux:*>` tags in views | `composer.json`, grep `resources/views` |
+| shadcn/ui | `components.json` exists at repo root | `components.json` |
+| Headless UI | `@headlessui/react` or `@headlessui/vue` in `package.json` | `package.json` |
+| Radix | `@radix-ui/*` in `package.json` (without shadcn marker) | `package.json` |
+| Material/Chakra/Mantine/Ant | their package names in `package.json` | `package.json` |
+| Custom / none | none of the above match | — |
+
+### 3. Detect design tokens
+
+Write into `state.ui_audit.design_tokens` (object, never null — empty object is fine):
+
+| Source | What to extract |
+|---|---|
+| `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |
+| `:root { --... }` blocks in `resources/css/`, `app/globals.css`, `src/app/globals.css` | every `--token-name: value` pair |
+| `theme.json` / `tokens.json` (any depth) | flat or nested token tree |
+| `app/css/variables.css`, `assets/scss/_tokens.scss` | SCSS `$var: value` and CSS custom properties |
+
+Group output by category: `colors`, `spacing`, `radius`, `font`, `shadow`, `breakpoint`, `other`.
+
+### 4. Detect shadcn inventory (only when `state.stack.frontend == "react-shadcn"`)
+
+Read `components.json` for the registered style + base color, then read `package.json` for `@radix-ui/*` and any locally vendored `components/ui/*.tsx` files. Write into `state.ui_audit.shadcn_inventory`:
+
+```
+{
+  version: <from package.json shadcn registry CLI version, or null>,
+  style: "default" | "new-york" | <other>,
+  base_color: "slate" | "zinc" | ...,
+  primitives: ["Button", "Dialog", "Form", "Table", ...],   // names of files in components/ui/
+  installed_radix: ["@radix-ui/react-dialog", ...]          // raw radix list
+}
+```
+
+### 5. List reusable patterns
+
+Categorize what already exists. Empty arrays are valid, never omit the keys.
+
+```
+state.ui_audit.patterns = {
+  forms: [<component path:str>, ...],     // any component with <form>, useForm, <flux:input>, <Input> + <Button type=submit>
+  tables: [...],                          // <table>, <flux:table>, DataTable, headless table primitives
+  modals: [...],                          // <flux:modal>, <Dialog>, AlertDialog, Sheet
+  empty_states: [...],                    // components matching grep "no results"|"empty"|"keine"|"nothing yet"
+  navigation: [...],                      // sidebar, breadcrumb, tabs
+  data_display: [...]                     // cards, lists, stat tiles
+}
+```
+
+### 6. Match candidates for the current input
+
+For each item in `state.ui_audit.components`, score similarity to `state.input.data` (fuzzy on filename + props/slots + co-occurring terms). Keep top 5 with `score >= 0.3`. Write into `state.ui_audit.candidates`:
+
+```
+[{path, name, score, reason: "matches 'settings' + 'toggle' in props"}, ...]
+```
+
+If `candidates` is empty, the user is building net-new. That is normal — record the empty list, do not halt.
+
+### 7. Greenfield branch
+
+If **all** are true:
+- `state.ui_audit.components` is empty
+- `state.ui_audit.design_system == "custom-or-none"`
+- `state.ui_audit.design_tokens` is empty (no Tailwind config customizations, no `:root`)
+
+then set `state.ui_audit.greenfield = true` and emit a halt:
+
+```
+> No existing UI surface detected — this looks like greenfield.
+>
+> 1. Scaffold a minimal token set + a base component primitive folder
+>    before building (recommended for projects with >1 planned screen)
+> 2. Proceed bare with Tailwind defaults (recommended for one-off prototypes)
+> 3. Point me at an external design-system reference (URL or file)
+
+**Recommendation: 1 — Scaffold tokens + primitives** — even one extra screen
+benefits from a shared base; the scaffold cost is ~10 min and saves
+re-doing every primitive on screen 2. Caveat: flip to 2 if this is a
+demo or single-page prototype that will not grow.
+```
+
+Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay).
+
+### 8. (Optional) Capture an a11y baseline
+
+The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`
+when present; the review gate then filters incoming
+`state.ui_review.a11y.violations` against it so pre-existing
+violations stay informational and only NEW or CHANGED entries block
+the polish loop. Without a baseline the gate sees every violation as
+actionable — fine for greenfield, noisy for legacy surfaces.
+
+Capture the baseline when:
+
+- The audit covers components with known a11y debt the project does
+  not intend to fix in this run (legacy templates, third-party
+  embeds, vendor widgets).
+- The user says "don't block on existing a11y issues" or similar.
+
+Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`
+unset) when:
+
+- The surface is greenfield — the review gate should treat every
+  violation as new.
+- The project's a11y posture is "zero known violations" and any
+  finding is by definition actionable.
+
+Shape (each entry must carry at least `rule` + `selector`; severity
+is optional but recommended so the review gate's severity-floor
+filter behaves the same on replay):
+
+```
+state.ui_audit.a11y_baseline = [
+  {rule: "color-contrast", selector: ".legacy-tab", severity: "moderate"},
+  {rule: "label",          selector: "form#search input[type=search]"},
+  ...
+]
+```
+
+Producer parity: the review skill that writes
+`state.ui_review.a11y.violations` MUST use the same `(rule, selector)`
+shape, otherwise the engine's de-dup will miss matches and pre-existing
+violations will surface as new findings on every run.
+
+### 9. Validate and write findings
+
+1. Verify every key in the **Output format** below is present in `state.ui_audit` (empty arrays/objects allowed; `null` only for `shadcn_inventory` outside the react-shadcn stack).
+2. Verify `state.ui_audit.greenfield == true` implies `state.ui_audit.greenfield_decision` is set.
+3. Write the full object back into the state-file. Audit completes with outcome `done` — the dispatcher's audit gate now passes.
+
+## Output format
+
+1. **`state.ui_audit.components`** — array of component/template descriptors (path, name, kind, exports)
+2. **`state.ui_audit.design_system`** — single string identifying the dominant system or `custom-or-none`
+3. **`state.ui_audit.design_tokens`** — object grouped by category (colors, spacing, radius, font, shadow, breakpoint, other)
+4. **`state.ui_audit.shadcn_inventory`** — object with version, style, base_color, primitives (only when stack is `react-shadcn`; `null` otherwise)
+5. **`state.ui_audit.patterns`** — object with forms, tables, modals, empty_states, navigation, data_display arrays
+6. **`state.ui_audit.candidates`** — top-5 similarity matches for the current input (may be empty)
+7. **`state.ui_audit.greenfield`** — boolean; when true, `greenfield_decision` MUST also be set before the dispatcher advances
+8. **`state.ui_audit.a11y_baseline`** *(optional)* — array of `{rule, selector, severity?}` entries documenting pre-existing a11y violations the review gate should treat as informational. Omit the key entirely when no baseline applies; do not write `[]` for "I checked and there are none" — that disables the gate's filter for every future run.
+
+## Gotcha
+
+- The model tends to skip the audit and start designing straight from the request — the dispatcher gate at `directives/ui/audit.py` enforces "no design without audit findings". Never treat this skill as optional for non-trivial UI.
+- The model tends to misidentify a single Tailwind utility as a "design token" — tokens come from the config or `:root`, not from class strings in templates.
+- Don't assume a Radix-only `package.json` means shadcn — shadcn requires `components.json` at repo root.
+- `state.ui_audit.shadcn_inventory.version` is often missing; the shadcn CLI does not always pin itself in `package.json`. Record `null` rather than guessing.
+- Greenfield is detected, not assumed — a project with one Blade layout and no components is still greenfield only if tokens AND design system markers AND components are all empty.
+- Re-running the skill on a stale state-file: cache by `(composer.json mtime, package.json mtime)`; if either changed, re-audit and overwrite.
+
+## Do NOT
+
+- Do NOT advance to `directives/ui/design.py` or `apply.py` if `state.ui_audit` is empty.
+- Do NOT advance to design or apply if `state.ui_audit.greenfield == true` and `state.ui_audit.greenfield_decision` is unset.
+- Do NOT silently skip the greenfield halt because "Tailwind has defaults" — the user picks the path explicitly.
+- Do NOT write paths outside the project root into the inventory.
+- Do NOT rewrite `state.ui_audit` once it is populated unless re-detection is triggered by mtime change — design and apply read from it.

package/.agent-src/skills/fe-design/SKILL.md

@@ -1,73 +1,82 @@
 ---
 name: fe-design
-description: "Use when designing frontend interfaces — component architecture, layout patterns, form design, table patterns, responsive strategies, and UX principles for Blade/Livewire/Flux/Tailwind."
+description: "Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py."
 source: package
 ---
 
-# Frontend Design Skill
+# Frontend Design Skill (Reference)
+
+## Positioning — reference, not executor
+
+`fe-design` is a **universal reference skill**, not an executor. It carries
+stack-agnostic heuristics that the UI directive set cites; it does **not**
+own the flow.
+
+| Concern | Owner |
+|---|---|
+| Layout / states / microcopy lock | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Stack-dispatched implementation | [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) → `blade-ui` / `livewire` / `flux` / `react-shadcn-ui` |
+| Existing-component inventory + tokens | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) (mandatory pre-step) |
+| Design-review polish loop | [`directives/ui/review.py`](../../templates/scripts/work_engine/directives/ui/review.py) + [`directives/ui/polish.py`](../../templates/scripts/work_engine/directives/ui/polish.py) |
 
 ## When to use
 
-Use this skill when:
+Cite this skill when:
+
 - Planning a new page or feature UI before implementing
 - Choosing between component patterns (modal vs. inline, table vs. cards)
 - Designing forms with complex validation or multi-step flows
 - Making responsive design decisions
 - Reviewing UI for accessibility and usability
-- Deciding how to structure Livewire components
-
-## Procedure: Design a frontend interface
 
-1. **Understand requirements** — What data is shown? What actions are available? Who is the user?
-2. **Choose technology** — Pick from the project stack (see table below).
-3. **Design layout** — Mobile-first, component-based, consistent spacing.
-4. **Implement** — Build with Blade components, Livewire for interactivity, Flux for UI primitives.
-5. **Verify** — Check accessibility (labels, focus, contrast), responsive behavior, loading states.
+Do NOT use this skill to:
 
-This project uses a server-rendered stack:
+- Implement components — that is the apply-step's stack-dispatched skill
+- Audit an existing UI — that is `existing-ui-audit`
+- Drive the full UI flow — that is the `directives/ui/` orchestrator
 
-| Layer | Technology | Skill |
-|---|---|---|
-| Templates | Laravel Blade | `blade-ui` |
-| Interactivity | Livewire 3 | `livewire` |
-| Component library | Flux (by Laravel) | `flux` |
-| Styling | Tailwind CSS | `tailwind` |
-| Icons | Heroicons / custom | — |
+## How the directive set cites this skill
 
-**Key principle:** Server-first. Use Livewire for interactivity. Avoid JavaScript unless Livewire can't handle it (e.g., drag-and-drop, complex animations).
+`directives/ui/design.py` produces the design brief (layout, components,
+states, microcopy, a11y). The brief picks heuristics from this reference
+when the audit doesn't already pin a project pattern. Stack-specific
+choices come from the dispatched implementation skill, not from here.
 
 ## Component Architecture
 
-### Page structure
+### Page structure (universal shape)
 
 ```
-Page (Blade layout)
-├── Header (Blade partial)
-├── Navigation (Livewire — active state)
+Page layout
+├── Header (static)
+├── Navigation (interactive — active state)
 ├── Content area
-│   ├── Page heading + actions (Blade)
-│   ├── Filters (Livewire — reactive)
-│   ├── Data display (Livewire — table/cards)
-│   └── Pagination (Livewire)
-└── Footer (Blade partial)
+│   ├── Page heading + actions (static)
+│   ├── Filters (interactive — reactive)
+│   ├── Data display (interactive — table / cards)
+│   └── Pagination (interactive)
+└── Footer (static)
 ```
 
-### When to use what
+The stack-specific mapping (Blade partial vs. Livewire component vs.
+React island vs. Vue SFC) is the apply-step's concern, not this skill's.
+
+### When to use what (kind, not framework)
 
-| Pattern | When | Example |
+| Kind | When | Example |
 |---|---|---|
-| **Blade partial** | Static content, no interactivity | Header, footer, static info |
-| **Blade component** | Reusable UI element, props only | Button, badge, card shell |
-| **Livewire component** | Needs server interaction or state | Forms, tables, filters |
-| **Flux component** | Standard UI element from library | Modal, dropdown, input, toast |
-| **Alpine.js** | Client-only micro-interaction | Toggle, accordion, clipboard |
+| **Static partial** | No interactivity, server-rendered only | Header, footer, static info |
+| **Reusable UI component** | Props-only, no state | Button, badge, card shell |
+| **Stateful component** | Needs server interaction or local state | Forms, tables, filters |
+| **Library primitive** | Standard UI from a design system | Modal, dropdown, input, toast |
+| **Client-only micro-interaction** | No server roundtrip needed | Toggle, accordion, clipboard |
 
 ### Component granularity
 
-- **One Livewire component per concern** — don't build mega-components
-- **Compose with Blade components** inside Livewire for reusable UI pieces
-- **Use Flux for standard elements** — don't rebuild what Flux provides
-- **Extract when used 3+ times** — DRY applies to UI too
+- **One stateful component per concern** — don't build mega-components.
+- **Compose with reusable UI components** for shared shells, headers, fields.
+- **Use the project's library primitives first** — never rebuild what the design system already provides (audit findings tell you which).
+- **Extract when used 3+ times** — DRY applies to UI too.
 
 ## Form Design
 
@@ -127,11 +136,11 @@ Step indicator (1 — 2 — 3)
 - Default: 25 rows per page
 - Show total count: "Showing 1–25 of 142"
 - Allow page size change (10, 25, 50, 100)
-- Use Livewire pagination (server-side)
+- Prefer server-side pagination — avoid loading the full set client-side
 
 ## Responsive Strategy
 
-### Breakpoints (Tailwind)
+### Breakpoints (Tailwind reference scale)
 
 | Prefix | Min width | Target |
 |---|---|---|
@@ -187,25 +196,40 @@ Step indicator (1 — 2 — 3)
 5. **Loading states** — Skeleton screens or spinners, never blank screens
 6. **Error recovery** — Clear error messages with suggested actions
 
-## Related
+## Procedure
 
-- **Skill:** `blade-ui` — Blade template implementation
-- **Skill:** `livewire` — Livewire component implementation
-- **Skill:** `flux` — Flux component library usage
-- **Skill:** `tailwind` — Tailwind CSS utility patterns
-- **Skill:** `dashboard-design` — Monitoring dashboard design (different domain)
+When `directives/ui/design.py` (or any caller) cites this skill:
 
+1. **Confirm the audit ran first** — `state.ui_audit` from [`existing-ui-audit`](../existing-ui-audit/SKILL.md) is mandatory. Stop and request the audit if missing.
+2. **Pick the smallest matching section** — Component Architecture, Form Design, Table Design, Responsive Strategy, Accessibility, or UX Principles. Cite by H2/H3 heading, never paste the whole skill.
+3. **Defer to audit findings** — when the audit pins a project pattern (token, primitive, layout convention), use it. The heuristics here are fallbacks for gaps, not overrides.
+4. **Defer to the stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from the dispatched implementation skill, never from this reference.
+5. **Surface conflicts** — if a heuristic here contradicts an audit finding or stack convention, name both and let the caller decide; do not silently pick.
 
 ## Output format
 
-1. Component structure with layout, data flow, and interaction patterns
-2. Responsive behavior for mobile/tablet/desktop breakpoints
-3. Accessibility annotations (ARIA, keyboard navigation)
+When this skill's content is folded into a design brief or review:
+
+1. Quote the cited heuristic verbatim, with the H2/H3 heading and a one-line "why this applies" tie-back to the request.
+2. Map each heuristic to a concrete artifact in the brief (component, form section, table column, breakpoint rule, a11y check, UX state).
+3. Keep stack-agnostic — never name Blade/Livewire/Flux/React primitives in the cited prose; the apply step adds those.
+4. Mark anything overridden by audit findings as `[audit override]` and link to the audit entry.
+
+## Related
+
+- **Orchestrator:** [`directives/ui/`](../../templates/scripts/work_engine/directives/ui/) — owns the UI flow
+- **Pre-step (mandatory):** [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — inventory before design
+- **Stack apply skills (dispatched, not standalone):**
+  - [`blade-ui`](../blade-ui/SKILL.md) — Blade template implementation
+  - [`livewire`](../livewire/SKILL.md) — Livewire component implementation
+  - [`flux`](../flux/SKILL.md) — Flux component library usage
+  - [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — React + shadcn primitives
+- **Adjacent reference:** [`dashboard-design`](../dashboard-design/SKILL.md) — monitoring dashboard design (different domain)
 
 ## Gotcha
 
-- Don't design components without checking existing Flux/Livewire components first — avoid reinventing.
-- The model tends to use raw HTML instead of project component library — always prefer existing components.
+- Don't design components without running `existing-ui-audit` first — the audit's component/token inventory is the canonical source for "what already exists in this project". Reinventing is the #1 failure mode.
+- Heuristics in this reference apply across stacks; do not promote them to project rules without checking the audit.
 - Mobile-first is not optional — every layout must work on 320px width.
 
 ## Do NOT
@@ -213,11 +237,4 @@ Step indicator (1 — 2 — 3)
 - Do NOT skip mobile viewport testing.
 - Do NOT use fixed pixel widths for responsive layouts.
 - Do NOT ignore accessibility requirements.
-
-## Auto-trigger keywords
-
-- frontend design
-- component architecture
-- layout
-- form design
-- responsive
+- Do NOT use this skill as an executor — it is a reference cited by `directives/ui/design.py`.

package/.agent-src/skills/file-editor/SKILL.md

@@ -8,6 +8,8 @@ execution:
   allowed_tools: []
 ---
 
+<!-- cloud_safe: noop -->
+
 # file-editor
 
 ## When to use
@@ -127,3 +129,10 @@ code app/Models/User.php
 - Do NOT prompt the user about IDE settings during normal work — suggest `/onboard` (for first-run) or editing `.agent-settings.yml` directly.
 - Do NOT open files that were only read, not edited.
 - Do NOT open more than 10 files at once — summarize instead.
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this skill is **fully inert** —
+there is no local IDE to open files in, no `.agent-settings.yml` to read, and
+no shell handler available. The cloud agent simply finishes its edits and
+reports back; file-opening is a local-agent concern.

package/.agent-src/skills/finishing-a-development-branch/SKILL.md

@@ -31,6 +31,10 @@ become a PR. Never destroy work without explicit confirmation.
 NO MERGE, NO PR, NO DISCARD WITHOUT VERIFIED TESTS + EXPLICIT CHOICE.
 ```
 
+Skipping verification because "it worked a minute ago" is how broken
+`main` happens. Discarding because "I assumed the user meant it" is
+how work gets lost.
+
 ## Procedure
 
 ### 1. Inspect branch state

package/.agent-src/skills/flux/SKILL.md

@@ -1,18 +1,36 @@
 ---
 name: flux
-description: "Use when writing Laravel Flux UI components — the official Livewire component library by the Laravel team. Covers components, slots, and variants."
+description: "Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives."
 source: package
 ---
 
 # flux
 
+## Positioning — dispatched, not standalone
+
+`flux` is the **primitive-library executor** for projects on the Livewire + Flux stack. Invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) once the design brief is locked, and revisited by `review.py` / `polish.py` during the design-review loop. Does **not** own the flow, drive the audit, or lock the design.
+
+| Concern | Owner |
+|---|---|
+| Audit + token inventory (mandatory pre-step) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) |
+| Design brief (layout / states / microcopy) | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Universal design heuristics | [`fe-design`](../fe-design/SKILL.md) |
+| Component logic / state / actions | [`livewire`](../livewire/SKILL.md) |
+| Static Blade partials | [`blade-ui`](../blade-ui/SKILL.md) |
+
 ## When to use
 
-Use when building UI with Flux components in a project that uses `livewire/flux`.
+Cite this skill when:
+
+- Project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
+- Building forms, modals, dropdowns, toasts, or other standard UI elements Flux already provides
 
 Do NOT use when:
+
 - Raw Blade templates without Flux (use `blade-ui` skill)
-- Livewire component logic (use `livewire` skill)
+- Livewire component logic / state (use `livewire` skill)
+- React + shadcn (use `react-shadcn-ui` skill)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
 
 ## Procedure: Create a Flux view
 
@@ -44,9 +62,18 @@ Do NOT use when:
 1. Blade view using Flux components with correct props and slots
 2. Livewire component class if interactive behavior is needed
 
+### Review pass — a11y findings + preview envelope
+
+When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
+
+Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+
 ## Gotcha
 
-- The model tends to use old Flux API syntax — always check latest docs.
+- Model tends to use old Flux API syntax — always check latest docs.
 - Flux has built-in validation display — don't add manual error rendering alongside it.
 - Don't mix Flux with raw HTML form elements in the same form.
 

package/.agent-src/skills/guideline-writing/SKILL.md

@@ -4,6 +4,8 @@ description: "Use when creating or editing a guideline in .agent-src.uncompresse
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+
 # guideline-writing
 
 ## When to use
@@ -109,8 +111,8 @@ Above the split signal, break by sub-topic into sibling files in the same folder
   → 0 FAIL (guidelines have relaxed linting but must still parse).
 * Run `bash scripts/compress.sh --sync` → regenerates `.agent-src/guidelines/`.
 * Run `python3 scripts/check_references.py` → no broken links.
-* Run the full CI pipeline locally — each script directly — must exit 0
-  except for tolerated warnings.
+* Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
+  the script list) — must exit 0 except for tolerated warnings.
 
 ## Output format
 
@@ -135,6 +137,26 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 * Do NOT create an orphan guideline with no inbound links
 * Do NOT edit `.agent-src/guidelines/` or `.augment/guidelines/` — generated
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/check_references.py`, `scripts/skill_linter.py`, and `task`
+runner are not reachable. The skill still applies — with prose-only
+validation:
+
+* Emit the full guideline file as a copyable Markdown block. Do not
+  attempt to write to disk.
+* Self-check the frontmatter: `description` only, no `type`, no
+  `alwaysApply`.
+* Self-check the body: reference material, no numbered procedures,
+  named in a topic folder.
+* Tell the user to save under
+  `.agent-src.uncompressed/guidelines/{topic}/{name}.md` and run
+  `task sync && task lint-skills && task check-refs` locally before
+  committing.
+* Do not call the linter, ref-checker, or compressor — they only
+  run on the user's machine.
+
 ## Examples
 
 Good guideline name + description:

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -68,7 +68,7 @@ Before proceeding, the learning MUST pass all gates:
 | Repetition | Occurred 2+ times OR clearly generalizable? |
 | Impact | Improves correctness, reliability, or consistency? |
 | Failure pattern | Prevents a real, observed failure? |
-| Non-duplication | No existing rule/skill/guideline covers this? |
+| Non-duplication | No existing rule/skill/guideline/command covers this? **Verify via § 4 search protocol — a negative grep alone is not proof.** |
 | Scope fit | Fits rule, skill, or guideline? |
 | Minimal | Update existing preferred over creation? |
 
@@ -115,11 +115,53 @@ Choose one:
 * Update existing guideline
 * **Nothing** (baseline knowledge, standard tool usage, one-off)
 
-### 4. Check for overlap
+### 4. Check for overlap — search protocol (mandatory)
 
-* Does a similar rule already exist?
-* Does a similar skill already exist?
-* Would a small update be better than a new file?
+A grep that returns zero hits is **not** proof of no overlap. Knowledge in
+this package is distributed across **four surfaces** — `skills/`, `rules/`,
+`guidelines/`, `commands/`. Skip any of them and recall drops to ~25 %.
+Run all four steps before declaring "no overlap":
+
+**Step 1 — list all four surfaces.** Directory taxonomy is free evidence:
+
+```bash
+ls .agent-src.uncompressed/skills/ \
+   .agent-src.uncompressed/rules/ \
+   .agent-src.uncompressed/guidelines/ \
+   .agent-src.uncompressed/commands/
+```
+
+Sub-directories matter — `guidelines/php/patterns/`, `guidelines/agent-infra/`,
+etc. carry topic taxonomies a flat file scan misses. Always descend one level.
+
+**Step 2 — grep with both vocabularies.** Search for **solution-words** *and*
+**problem-words**. Solution-only grep is confirmation bias — the existing
+artifact may name the *symptom*, not the cure.
+
+| Vocabulary | Example for "agents miss Strategy pattern, write switch chains" |
+|---|---|
+| Solution-words | `strategy`, `registry`, `polymorph`, `interface` |
+| Problem-words | `discriminator`, `enum.*match`, `switch.*on`, `if.*else.*chain` |
+
+```bash
+grep -rl -E "<solution-words>|<problem-words>" .agent-src.uncompressed/
+```
+
+**Step 3 — taxonomy scan.** For any topic with a likely sub-folder
+(`patterns/`, `php/`, `laravel/`, `agent-infra/`), `ls` that folder
+*before* reading any file. Filename alone often answers the overlap question.
+
+**Step 4 — sample, do not just list.** On *any* keyword overlap from
+steps 2–3, **open and skim the 3 nearest matches** — read § headings, the
+"When to use" / "Overview" block, and the examples list. Listing filenames
+is not enough; semantic overlap hides behind unrelated keywords.
+
+Only after all four steps return clean → declare "no overlap" and proceed.
+Citation in the proposal: *"Reviewed before drafting: <files skimmed>"* —
+this is the audit trail § 0's Non-duplication gate verifies against.
+
+→ When the parent task is "create a new artifact", `artifact-drafting-protocol`
+Phase B (Research) requires this same protocol — single source of truth.
 
 ### 5. Draft the content
 
@@ -169,9 +211,9 @@ Mandatory fields the draft MUST fill:
 * `Success signal` (§7) — one metric, one baseline, one target, one
   evaluation date
 
-Run `python3 scripts/check_proposal.py agents/proposals/<id>.md` before
-handing to `upstream-contribute`. The
-script is a hard gate: non-zero exit = the proposal does not move
+Run `./agent-config proposal:check agents/proposals/<id>.md`
+before handing to `upstream-contribute`. The
+gate is hard: non-zero exit = the proposal does not move
 to stage `gated`.
 
 ## Output format
@@ -183,7 +225,7 @@ For the **decision step** (what this skill prints to the user):
 3. Rationale in one to three lines
 4. If decision ≠ "no action": path of the written proposal
    (`agents/proposals/<proposal_id>.md`) and gate status
-   (`check_proposal.py` exit 0 = ready for review)
+   (`./agent-config proposal:check` exit 0 = ready for review)
 
 The **proposal file itself** follows
 `proposal.example.md` verbatim — all ten sections, YAML frontmatter