@event4u/agent-config 9.34.0 → 9.36.0

package/dist/agent-src/rules/design-review-after-ui-write.md

@@ -6,6 +6,14 @@ description: "UI written or changed — review it against the design contract be
 triggers:
   - path_prefix: "resources/views/"
   - path_prefix: "resources/js/"
+  - path_prefix: "components/"
+  - path_prefix: "src/components/"
+  - path_prefix: "pages/"
+  - file_pattern: "*.vue"
+  - file_pattern: "*.svelte"
+  - file_pattern: "*.tsx"
+  - file_pattern: "*.jsx"
+  - file_pattern: "*.blade.php"
   - keyword: "component"
   - keyword: "design token"
 routes_to:
@@ -20,6 +28,14 @@ collision_ok:
   "design token": "same surface, opposite side: ui-audit-gate inventories tokens before the write, this reviews what the write emitted"
   "resources/views/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "resources/js/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "components/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "src/components/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "pages/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "*.vue": "one component file, two obligations: inventory before the write, review after it"
+  "*.svelte": "one component file, two obligations: inventory before the write, review after it"
+  "*.tsx": "one component file, two obligations: inventory before the write, review after it"
+  "*.jsx": "one component file, two obligations: inventory before the write, review after it"
+  "*.blade.php": "one template file, two obligations: inventory before the write, review after it"
 # obligation: line 39
 obligation_frequency: "per-edit"
 ---
@@ -87,18 +103,49 @@ enforcement. So this rule ships `enforced_by: none`, the same honesty boundary
 for their own obligations, rather than pretending a satisfiable-by-assertion
 condition is a gate.
 
+**A runtime carrier now exists, and it does not change that.** The
+`ui-route-nudge` PreToolUse concern emits one warning on a UI write with no
+design consultation latched this session.
+
+It runs **parallel** to this rule rather than consuming it. Nothing in the tree
+reads this frontmatter at session time; the concern decides what counts as a UI
+surface from `src/scripts/_lib/ui_surface.ts`, and the `keyword:` triggers here
+still have no runtime consumer. A test — not a code path — keeps the two from
+drifting: `ui_rule_triggers.test.ts` asserts every `file_pattern` declared here
+is accepted by that predicate.
+
+Warn-only, capped at two nudges per session, default-OFF, bound only on hosts
+carrying a `pre_tool_use` slot. A nudge that can be ignored is not enforcement,
+so `enforced_by:` stays `none` — it moves the day a mechanism can refuse, not
+the day a reminder appears. `agent-config hooks:status` answers whether the
+concern is bound on the host you are actually on.
+
 What that leaves, and it is the useful part: the write side now has a named
 obligation and a route to the skill that discharges it, where before it had
 neither. Full enforcement needs the work-engine `review`/`polish` gates (which
 already act on `a11y_violation` and `token_violation` findings) or pack-scoped
 rule projection — a maintainer decision, never an automated one.
 
-One asymmetry worth stating: `design-review` lives in `engineering-base` while
-this rule is scoped to `frontend-design`. The route still resolves — a rule may
-name a skill from another pack — but a consumer with `frontend-design` and
-without `engineering-base` gets the obligation without the skill. That is why
-`accessibility-auditor` is a second route: it is the part of the review that
-must not depend on the pairing.
+One asymmetry worth stating, in the direction it actually runs: `design-review`
+lives in `engineering-base` while this rule is scoped to `frontend-design`. The
+route still resolves — a rule may name a skill from another pack.
+
+The case this paragraph used to describe — `frontend-design` installed without
+`engineering-base`, so the obligation arrives without the skill — **cannot
+occur**: `frontend-design` declares `requires: [engineering-base]`, and the
+resolver expands that graph transitively. The real gap is the reverse and was
+undocumented: an **`engineering-base`-only** install (a plain `laravel` or
+`react` consumer, since both only *suggest* `frontend-design`) carries
+`existing-ui-audit`, `design-review` and `fe-design` while carrying **no rule
+that routes to them**. It bites only where pack-scoped rule projection is
+active — `rules.packs` ships inactive, so a default install still receives both
+rules — which makes it a latent defect rather than a live one, and exactly the
+kind that surfaces the day the projection axis is switched on.
+
+`lint_rule_skill_pack_reach` is the invariant that keeps this honest: no rule
+may route to a skill a pack-legal install of that rule's packs cannot receive.
+`accessibility-auditor` remains a second route for the independent reason that
+the a11y half of the review should not depend on the pairing at all.
 
 ## Failure modes
 

package/dist/agent-src/rules/improve-before-implement.md

@@ -44,7 +44,7 @@ Before implementing:
 
 ## Demand gate — should this exist? (build / defer)
 
-On a "build me an app / add this feature" ask, ONE reflexive pre-check before the three checks: **who asked · what breaks if unbuilt · what's the evidence?** Recommend **build** only at a real retention/activation blocker (evidence, not anxiety); else **defer/validate**, naming the missing evidence. Advisory — "just build it" proceeds immediately; no network lookup. Hierarchy + build/defer table: guideline § 8-pre.
+On a "build me an app / add this feature" ask, ONE reflexive pre-check before the three checks: **who asked · what breaks if unbuilt · what's the evidence?** **Read the addressee first** — `project.audience` (`agent-config settings:get project.audience`, absent → `public`): the demand hierarchy measures **market** demand and is meaningless where no market is intended, so at `self` the check is inert and the work is classified `L-self` → **build**. With a market: recommend **build** at a real retention/activation blocker (evidence, not anxiety); else **defer/validate**, naming the missing evidence. Never gate a roadmap on a user population the project is not meant to have. Advisory — "just build it" proceeds immediately; no network lookup. Hierarchy + build/defer table: guideline § 8-pre.
 
 ## The solution-size ladder — stop at the first rung that works
 

package/dist/agent-src/rules/ui-audit-gate.md

@@ -6,6 +6,14 @@ description: "Writing/editing UI — components, screens, layouts, design tokens
 triggers:
   - path_prefix: "resources/views/"
   - path_prefix: "resources/js/"
+  - path_prefix: "components/"
+  - path_prefix: "src/components/"
+  - path_prefix: "pages/"
+  - file_pattern: "*.vue"
+  - file_pattern: "*.svelte"
+  - file_pattern: "*.tsx"
+  - file_pattern: "*.jsx"
+  - file_pattern: "*.blade.php"
   - keyword: "component"
   - keyword: "design token"
 routes_to:
@@ -21,6 +29,14 @@ collision_ok:
   "design token": "same surface, opposite side: this inventories tokens before the write, design-review-after-ui-write reviews what the write emitted"
   "resources/views/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "resources/js/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "components/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "src/components/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "pages/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
+  "*.vue": "one component file, two obligations: inventory before the write, review after it"
+  "*.svelte": "one component file, two obligations: inventory before the write, review after it"
+  "*.tsx": "one component file, two obligations: inventory before the write, review after it"
+  "*.jsx": "one component file, two obligations: inventory before the write, review after it"
+  "*.blade.php": "one template file, two obligations: inventory before the write, review after it"
 # obligation: line 39
 obligation_frequency: "per-edit"
 ---
@@ -91,6 +107,25 @@ Full enforcement requires the dispatcher (or the `frontend-design` pack once
 pack-scoped rule projection is enabled; that flip is a maintainer decision,
 never an automated one).
 
+**A runtime carrier now exists, and it does not change the verdict.** The
+`ui-route-nudge` PreToolUse concern warns once on a UI write with no design
+consultation latched this session.
+
+It is a **parallel** mechanism, not a consumer of the triggers above — the
+distinction matters and the earlier wording here got it wrong. The concern
+decides "is this a UI surface" from `src/scripts/_lib/ui_surface.ts`; nothing
+in the tree parses this frontmatter at session time, so the `keyword:` triggers
+still have no runtime consumer at all, and the two sets can drift. What holds
+them together is a test, not a dependency: `ui_rule_triggers.test.ts` asserts
+every `file_pattern` declared here is accepted by that predicate. The predicate
+is deliberately wider (it also covers `.css`, `.scss`, `.astro`), because a
+measurement denominator and a routing trigger are not the same population.
+
+Warn-only, capped at two per session, default-OFF, bound only where a
+`pre_tool_use` slot exists. A reminder that can be ignored is not a gate, so
+`enforced_by:` stays `none`. Run `agent-config hooks:status` for the host you
+are on rather than trusting this sentence.
+
 ## Failure modes
 
 - Writing the component first and "thinking about reuse later".

package/dist/agent-src/scripts/roadmap_gates.ts

@@ -46,6 +46,13 @@
  *   ./agent-config gates --all      # every open blocker, grouped by owner
  *   ./agent-config gates --json     # machine-readable
  *   ./agent-config gates --reply    # reply-close form; empty when none
+ *   ./agent-config gates --pending  # staged actions awaiting confirmation
+ *
+ * `--pending` reads a different source — the staged-confirmation store, not the
+ * roadmap tree — and stays out of `--reply` on purpose. ADR-222 fixes the
+ * reply-close form at exactly ONE decision rendered in full; folding a second
+ * source into it would silently change which decision "the one" is, and that
+ * contract is not this step's to move.
  */
 
 import * as path from 'node:path';
@@ -58,6 +65,8 @@ import {
     blocker_needs_user as needsUser,
     type Blocker,
 } from './update_roadmap_progress.js';
+import { listPending } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation_store.js';
+import type { StagedAction } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -327,6 +336,89 @@ function renderJson(entries: readonly Entry[], all: boolean): string {
     );
 }
 
+/**
+ * `--pending`: staged actions awaiting a human confirmation.
+ *
+ * A second source under the same verb, and the reason it belongs here rather
+ * than in a new command is the verb's own definition — "open decisions that
+ * need you, as actions". A staged irreversible action IS one, and the most
+ * literal kind: the roadmap blockers above are decisions a human owes a plan,
+ * this is a decision a human owes an action that is already loaded and waiting.
+ *
+ * Expired stages are counted, never listed as actionable. An expired stage
+ * cannot execute (`stageStatus` derives that from the clock, not from a sweep
+ * having run), so rendering it beside a live one would put two rows in front of
+ * the reader where only one is a decision.
+ */
+function renderPending(root: string, now: number): string {
+    const rows = listPending(root, now);
+    const live = rows.filter((r) => r.status === 'pending');
+    const expired = rows.filter((r) => r.status === 'expired');
+    const lines: string[] = [];
+
+    if (live.length === 0) {
+        lines.push(
+            expired.length === 0
+                ? 'No staged actions awaiting confirmation.'
+                : `Nothing awaits your confirmation. ${expired.length} stage` +
+                      `${expired.length !== 1 ? 's' : ''} expired unconfirmed — the action never fired.`,
+        );
+        return lines.join('\n') + '\n';
+    }
+
+    lines.push(
+        `${live.length} staged action${live.length !== 1 ? 's' : ''} await` +
+            `${live.length === 1 ? 's' : ''} your confirmation` +
+            (expired.length > 0 ? ` · ${expired.length} expired unconfirmed` : ''),
+    );
+    let n = 0;
+    for (const { stage } of live) {
+        n += 1;
+        lines.push(...renderStage(stage, n));
+    }
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+
+function renderStage(stage: StagedAction, index: number): string[] {
+    const head = `${index} · ${stage.action}`;
+    const tail = `token: ${stage.token}`;
+    const dashes = Math.max(3, WIDTH - head.length - tail.length - 6);
+    return [
+        '',
+        `── ${head} ${'─'.repeat(dashes)} ${tail}`.trimEnd(),
+        // The object is the first field on purpose: an approval that does not
+        // name the exact object is the thing non-destructive-by-default forbids,
+        // so it is what the reader must see before anything else.
+        ...field('Object:', stage.object),
+        ...field('Staged by:', stage.source),
+        ...field('Expires:', stage.expires_at),
+    ];
+}
+
+function renderPendingJson(root: string, now: number): string {
+    const rows = listPending(root, now);
+    return (
+        JSON.stringify(
+            {
+                awaitingYou: rows.filter((r) => r.status === 'pending').length,
+                expired: rows.filter((r) => r.status === 'expired').length,
+                staged: rows.map(({ stage, status }) => ({
+                    token: stage.token,
+                    action: stage.action,
+                    object: stage.object,
+                    source: stage.source,
+                    stagedAt: stage.staged_at,
+                    expiresAt: stage.expires_at,
+                    status,
+                })),
+            },
+            null,
+            2,
+        ) + '\n'
+    );
+}
+
 function _isDir(p: string): boolean {
     try {
         return fs.statSync(p).isDirectory();
@@ -340,8 +432,8 @@ function _isDir(p: string): boolean {
  * `agents/roadmaps`, otherwise fall back to the git toplevel (monorepo
  * sub-project support).
  */
-function _resolveRepoRoot(start: string): string {
-    if (_isDir(path.join(start, 'agents', 'roadmaps'))) {
+function _resolveRepoRoot(start: string, marker = path.join('agents', 'roadmaps')): string {
+    if (_isDir(path.join(start, marker))) {
         return start;
     }
     try {
@@ -351,7 +443,7 @@ function _resolveRepoRoot(start: string): string {
             timeout: 10_000,
         });
         const top = (r.stdout || '').trim();
-        if (r.status === 0 && top !== '' && _isDir(path.join(top, 'agents', 'roadmaps'))) {
+        if (r.status === 0 && top !== '' && _isDir(path.join(top, marker))) {
             return top;
         }
     } catch {
@@ -365,6 +457,18 @@ function main(argv?: readonly string[]): number {
     const all = args.includes('--all');
     const json = args.includes('--json');
     const reply = args.includes('--reply');
+    const pending = args.includes('--pending');
+
+    // `--pending` resolves against `agents/runtime/`, not `agents/roadmaps/`,
+    // and is answered BEFORE the roadmaps-directory exit below: a staged action
+    // is independent of whether this project plans in roadmaps at all, so
+    // "no roadmaps here" is not an answer to "what awaits my confirmation".
+    if (pending) {
+        const root = _resolveRepoRoot(process.cwd(), path.join('agents', 'runtime'));
+        const now = Date.now();
+        process.stdout.write(json ? renderPendingJson(root, now) : renderPending(root, now));
+        return 0;
+    }
 
     const repoRoot = _resolveRepoRoot(process.cwd());
     const roadmapRoot = path.join(repoRoot, 'agents', 'roadmaps');
@@ -412,5 +516,16 @@ if (_isCliEntry()) {
     process.exitCode = main();
 }
 
-export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson, renderReply };
+export {
+    main,
+    needsUser,
+    regroupTodo,
+    wrap,
+    collectEntries,
+    render,
+    renderJson,
+    renderReply,
+    renderPending,
+    renderPendingJson,
+};
 export type { Entry };

package/dist/agent-src/skills/design-system-capture/SKILL.md

@@ -199,7 +199,7 @@ external static-extraction tool and hand the result to this skill as a
 `design-system.json` artifact. We own the **import contract**, not the crawler:
 the package never ships the Playwright runtime, a font-bundler, or a `.skill`
 auto-installer (out of scope). Full schema is lazy-loaded from
-[`reference/design-system-json.md`](reference/design-system-json.md) — read it
+[`references/design-system-json.md`](references/design-system-json.md) — read it
 only when an import is requested.
 
 **Import procedure:**
@@ -281,7 +281,7 @@ most common handoff ambiguity.
 When the goal is to extract this repo's design system as a **reusable package
 artifact** (not just DESIGN.md prose), the extraction meets this floor — the
 handoff shape emitted alongside `design-system.json`
-([import contract](reference/design-system-json.md)).
+([import contract](references/design-system-json.md)).
 
 - **Contract contents.** A complete extraction carries: a root guide / manifest;
   token CSS (or the stack's equivalent); the typography / colour / spacing /

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

@@ -256,7 +256,7 @@ Load on demand once the audit needs the pitfall catalog:
 **Design-system export (current-repo source):** when the goal is to seed
 `DESIGN.md` from *this* repo, emit the inventory as a `design-system.json`
 artifact (the import contract in
-[`design-system-capture`](../design-system-capture/reference/design-system-json.md))
+[`design-system-capture`](../design-system-capture/references/design-system-json.md))
 and hand it to `design-system-capture` — the same shape an external extraction
 tool produces, so the import path is uniform.
 

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

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: fe-design
-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.ts."
+description: "Frontend design heuristics — and, outside the ticket engine, the loop that applies them: audit, brief, build, review. Use when building or changing any UI, not only when planning one."
 personas:
   - frontend-engineer
 domain: engineering
@@ -11,15 +11,82 @@ packs:
   - engineering-base
 ---
 
-# 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 |
+# Frontend Design Skill
+
+## Ad-hoc mode — outside the engine, YOU run this loop now
+
+One question decides which mode you are in: **is a `/implement-ticket` run
+dispatching this?**
+
+| Situation | Who owns the UI write | This skill is |
+|---|---|---|
+| A ticketed run — the UI directive set is dispatching | `directives/ui/*` | a reference it cites |
+| Anything else — "build me the page", "improve this form", "implement the approved design" | **you, in this turn** | the executor |
+
+Outside the engine, nothing else owns the design quality of a UI write. Reading
+this skill and then writing the UI from priors is the failure it exists to
+prevent — the loop below is not optional context, it is the work.
+
+**Skip only when the change is `ui-trivial`, decidable off the diff:** ≤ 1 file,
+≤ 5 changed lines, no new component, no new state, no new dependency. Anything
+else runs the loop.
+
+### The loop
+
+1. **Audit first** — run [`existing-ui-audit`](../existing-ui-audit/SKILL.md).
+   What already exists (components, tokens, layout conventions) outranks every
+   heuristic below. Reinventing an existing component is the #1 failure mode.
+2. **Brief** — cover the same five keys the engine requires before any code:
+   `layout`, `components`, `states`, `microcopy`, `a11y`. `states` means all
+   five of `empty`, `loading`, `error`, `success`, `disabled` — a brief missing
+   one is unfinished, not concise.
+3. **Build** — against the audit's primitives, in the project's stack.
+4. **Review** — run [`design-review`](../design-review/SKILL.md) before calling
+   it done, and scope the verdict honestly: render-scoped when you can render
+   it, otherwise explicitly static-scoped, naming which checks actually ran.
+   "Looks good" with neither scope named is a verdict without evidence.
+
+### The heuristics — here, not one hop away
+
+The load-bearing subset, inline so that "loaded" means the content is in
+context. Depth stays in [`references/design-patterns.md`](references/design-patterns.md).
+
+1. **Audit outranks heuristic.** A token, primitive or convention the audit
+   found wins over anything on this list; say `[audit override]` when it does.
+2. **Reuse tokens, never raw values.** A hex, font or px literal where the
+   audit found a token is off-brand by construction.
+3. **All five states are designed.** `empty` is a helpful message, not a blank
+   region; `loading` prefers a skeleton over a spinner (it shows structure, so
+   it reads as faster); `error` says what to do next.
+4. **Labels are always visible.** No placeholder-only inputs.
+5. **Validate on blur and on submit**, never on every keystroke; the message
+   goes below the field and is specific.
+6. **Mobile-first, and 320 px actually works.** Default styles are the small
+   viewport; complexity is added at larger breakpoints, never removed at
+   smaller ones.
+7. **A11y minimums are non-negotiable:** 4.5:1 contrast for text (3:1 large),
+   every interactive element reachable by Tab, a visible focus ring, semantic
+   elements over `div`, and an `aria-label` wherever there is no visible text.
+8. **Every action gets feedback.** Users read silence as failure.
+9. **Prefer undo over a confirmation dialog** — confirmations get clicked
+   through; an undo affordance actually protects the user.
+10. **Tables:** numbers right-aligned, text left-aligned, a designed empty
+    state, and a sticky header on anything long enough to scroll.
+11. **No placeholder microcopy ships.** Lorem ipsum, `TODO`, and
+    `[Your text here]` are unfinished output, not drafts.
+
+Before proposing a direction, run the anti-slop scan named under
+[Anti-slop discipline](#anti-slop-discipline) below.
+
+## Positioning — reference inside the engine, executor outside it
+
+Inside a `/implement-ticket` run, `fe-design` is a **universal reference
+skill**: it carries stack-agnostic heuristics the UI directive set cites, and
+it does not own the flow. The ownership table below applies **to that mode**.
+Outside the engine the table has no dispatcher behind it — the ad-hoc loop
+above is the owner instead.
+
+| Concern | Owner (engine-mediated runs) |
 |---|---|
 | Layout / states / microcopy lock | [`directives/ui/design.ts`](../../templates/scripts/work_engine/directives/ui/design.ts) |
 | Stack-dispatched implementation | [`directives/ui/apply.ts`](../../templates/scripts/work_engine/directives/ui/apply.ts) → `blade-ui` / `livewire` / `flux` / `react-shadcn-ui` |
@@ -37,12 +104,17 @@ Cite this skill when:
 - Making responsive design decisions
 - Reviewing UI for accessibility and usability
 
-Do NOT use this skill to:
+**Inside a ticketed run**, do NOT use this skill to:
 
 - 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
 
+Outside a ticketed run, the first and third lines invert: no dispatcher is
+running, so implementation quality and the flow are yours. The second holds in
+both modes — the audit is always `existing-ui-audit`; you invoke it, you do not
+replace it.
+
 > **Resource-first, before taste.** Any request to recreate / redesign / mock /
 > prototype / improve an existing UI runs the
 > [resource-first context gate](../existing-ui-audit/SKILL.md#resource-first-context-gate-design-fidelity)
@@ -129,4 +201,4 @@ approach or explicitly invoke the override condition in the design brief.
 - Do NOT skip mobile viewport testing.
 - Do NOT use fixed pixel widths for responsive layouts.
 - Do NOT ignore accessibility requirements.
-- Do NOT use this skill as an executor — it is a reference cited by `directives/ui/design.ts`.
+- Do NOT use this skill as an executor INSIDE a ticketed run — there the executor is `directives/ui/design.ts` and this is the reference it cites. Outside one, the ad-hoc loop at the top of this file IS the executor; do NOT read the reference and then write the UI from priors.

package/dist/agent-src/skills/fe-design/evals/triggers.json

@@ -1,7 +1,7 @@
 {
     "skill": "fe-design",
-    "last_eval": "2026-07-10",
-    "description": "5 should-trigger + 5 should-not-trigger queries for the variation & canvas planning layer (road-to-design-artifact-fidelity Phase 4). Should-trigger covers exploration / variation planning and UI-design decisions where fe-design plans BEFORE generating (give me directions, explore, plan the flow, pattern choice). Should-not-trigger covers near-misses that must NOT invoke design planning: pure implementation of an already-selected design (apply-step), inventorying existing UI (existing-ui-audit), a surgical one-line edit, and non-UI/backend work.",
+    "last_eval": "2026-08-12",
+    "description": "Should-trigger covers BOTH halves of this skill's two modes: planning/exploration (give me directions, explore, plan the flow, pattern choice) AND — new — ad-hoc implementation, because outside a ticketed run no other artefact owns the design quality of a UI write. The implementation query used to be labelled should-not-trigger on the reasoning that it belongs to the apply step; that step only exists as a dispatch target inside the engine, so the label routed ad-hoc implementation prompts to nobody. Should-not-trigger keeps the genuine near-misses: inventorying existing UI (existing-ui-audit owns it in both modes), a ui-trivial one-line edit, and non-UI work.",
     "queries": [
         {
             "q": "give me three directions for the pricing page",
@@ -25,7 +25,15 @@
         },
         {
             "q": "implement the selected checkout design in React exactly as approved",
-            "trigger": false
+            "trigger": true
+        },
+        {
+            "q": "build the settings page",
+            "trigger": true
+        },
+        {
+            "q": "improve this form, it feels clunky",
+            "trigger": true
         },
         {
             "q": "what form components do we already have in the codebase?",

package/dist/agent-src/skills/prediction-pool-optimizer/SKILL.md

@@ -94,7 +94,7 @@ biggest publicly-viewable books**, not a single portal:
    each special/award market a bonus question needs) from several books.
    Odds-comparison aggregators (Oddschecker, Oddsportal / Betexplorer) show
    many books at once; supplement with named books. Concrete book list and
-   the weighting recipe live in [`reference/odds-and-bonus.md`](reference/odds-and-bonus.md).
+   the weighting recipe live in [`references/odds-and-bonus.md`](references/odds-and-bonus.md).
 2. **De-vig each book** independently (remove its margin) → per-book implied
    probabilities. Raw odds sum to >100%; never treat them as probabilities.
 3. **Aggregate with a healthy weighting**, not a blind average: weight
@@ -203,7 +203,7 @@ Respect all strategy limits from step 1 (max identical tips, etc.).
 
 Walk the **step-1 checklist** and answer **each** entry. Pick the method by
 question type — full taxonomy + per-type method in
-[`reference/odds-and-bonus.md`](reference/odds-and-bonus.md):
+[`references/odds-and-bonus.md`](references/odds-and-bonus.md):
 
 - **Tournament structure** (group winners, KO rounds, finalists, champion):
   use real **outright market odds** ("to win group", "to reach final",
@@ -253,7 +253,7 @@ deadline is the only hard constraint.
 
 3. **Group standings and the full bracket** where the event has them.
 4. **Self-check note** — (a) confirm the tips reconcile with
-   [`reference/ev-fixtures.md`](reference/ev-fixtures.md) (known pool rules +
+   [`references/ev-fixtures.md`](references/ev-fixtures.md) (known pool rules +
    market odds → a known-good EV tip); (b) confirm the bonus table has the
    **same number of rows as the step-1 checklist** — a shorter table means a
    question was dropped. If your method disagrees with a fixture, your method
@@ -310,10 +310,10 @@ gate — the skill never enters or submits anything.
 
 - [`/prediction-pool`](../../commands/prediction-pool.md) — the orchestrator (event,
   persistence, Playwright entry, gates).
-- [`reference/odds-and-bonus.md`](reference/odds-and-bonus.md) — the major-book
+- [`references/odds-and-bonus.md`](references/odds-and-bonus.md) — the major-book
   list + sharpness-weighted consensus recipe, and the bonus / award / special
   question taxonomy with a per-type method.
-- [`reference/ev-fixtures.md`](reference/ev-fixtures.md) — known-good
+- [`references/ev-fixtures.md`](references/ev-fixtures.md) — known-good
   rules+odds → EV examples.
 - `node_modules/@event4u/agent-config/src/scripts/prediction-pool/score_ev.ts` —
   the executed exact-score EV optimiser (step 4a; λ + rule → EV-max scoreline).

package/dist/agent-src/skills/react-shadcn-ui/SKILL.md

@@ -132,7 +132,7 @@ The default path is the bundled `scripts/shadcn_add.ts` CLI wrapper + reading
 `components.json` — it works on most shadcn projects and stays the default.
 The modern registry model is an **opt-in enhancement**; do not add round-trips
 to every component op. Full JSON-schema + namespace detail is lazy-loaded from
-[`reference/registry.md`](reference/registry.md) — read it only on this path,
+[`references/registry.md`](references/registry.md) — read it only on this path,
 not on the vanilla `add`.
 
 **`shadcn info --json` handshake** — run it as the grounding step **when** the

package/dist/agent-src/skills/skill-writing/SKILL.md

@@ -106,6 +106,30 @@ Do NOT create a skill or rule for:
 * If two skills overlap heavily → merge
 * If a skill becomes "read the guideline" → it lost its purpose, restore the workflow
 
+### Progressive disclosure — the directory is `references/`, plural
+
+When a skill needs depth the workflow does not, the depth goes in a
+**`references/`** subdirectory beside `SKILL.md` — that exact name, plural. It
+was two spellings across nine skills until 2026-08-12 because nothing here
+named one; the split cost a rename, not a decision.
+
+* **Body:** the trigger, the workflow, the ownership statement, and every
+  heuristic that changes a write decision. A skill whose body is a map to its
+  own content is loaded and not applied.
+* **`references/`:** corpora, lookup tables, long schemas, worked examples —
+  read on the path that needs them, never on every activation.
+
+Splitting is not a size escape hatch. The measured estate (n=289, 2026-08-12):
+median 1,077 words, p90 1,867, **only 6 skills above 2,500 and 4 above 3,000**.
+So a skill at 1,500 words is ordinary, and moving prose out of the body to hit
+a number makes it worse. Split when the material is genuinely
+consulted-on-demand; keep the load-bearing part in the body even when that
+leaves the file long.
+
+A `references/` split does not change the gates that already apply: a
+`token_budget_class: rich` skill still meets its 3,500-token ceiling on the
+body alone.
+
 ## Procedure
 
 ### 0. Inspect, then run the Drafting Protocol

package/dist/agent-src/skills/subagent-orchestration/prompts/README.md

@@ -23,6 +23,35 @@ Every prompt cites the status taxonomy in
 ends with the **return-envelope** instruction so the subagent's reply
 validates against that schema.
 
+### UI-shaped slices carry the design context, or name its absence
+
+A delegated worker's context is whatever the dispatch prompt carries. For a
+slice that writes UI, that has a specific consequence: the audit findings and
+the design brief live in the orchestrator's context, and nothing moves them
+across the dispatch boundary on its own. A worker that receives "build the
+settings page" and nothing else will build it from priors — the same failure
+the design skills exist to prevent, one layer down.
+
+So a UI-shaped dispatch prompt carries, in its `CONTEXT FILES:` section:
+
+- the **audit findings** from `existing-ui-audit` (components, tokens, layout
+  conventions the project already has), and
+- the **design brief** — `layout`, `components`, `states`, `microcopy`, `a11y`,
+  with all five states covered.
+
+When either is genuinely absent, **say so in the prompt** rather than omitting
+it silently: `no audit findings available — run existing-ui-audit first`. A
+worker told the context is missing can ask for it; a worker told nothing
+assumes there was nothing to know.
+
+**This is model-carried, and the reason is worth stating.** An orchestration
+record carries `ts`, `spawn_count`, `token_delta`, `tier_chosen` and
+`task_class` — it has no field able to hold a prompt, deliberately, for the same
+privacy-by-construction reason the telemetry event has none. So no lint can join
+a dispatch prompt against its record to check this clause: the data a check
+would need does not exist and should not be made to exist. The obligation is
+stated here and carried by the orchestrator, not enforced.
+
 ## Prompt-cache discipline
 
 When dispatching sibling subagents (e.g. `do-in-parallel` with N independent