@event4u/agent-config 10.4.0 → 11.0.0

package/dist/agent-src/skills/corpus-grounding/scripts/decision_engine.ts

@@ -531,16 +531,76 @@ function _select_best_match(
 
 // ── grounding ────────────────────────────────────────────────────────────
 
+/**
+ * The three optional 1-10 design dials.
+ *
+ * Adapted from the upstream generator's tier table (MIT; see
+ * `design-intelligence/ATTRIBUTION.md` and `provenance/borrows.jsonl`). The
+ * TIER BOUNDARIES and the values they carry are the upstream's data; the
+ * plumbing below is this engine's own, because upstream threads them through a
+ * `generate()` this tree does not have and ours has `ground()` instead.
+ *
+ * Unset means unset: a dial the caller did not pass changes nothing, which is
+ * the upstream's own contract and the only thing that keeps the no-flag path
+ * byte-identical to the behaviour before this existed.
+ */
+export const DIAL_TIERS: Record<string, Array<[number, number, ResultDict]>> = {
+    variance: [
+        [1, 3, { label: 'Centered / Minimal', style_keywords: ['Minimalism', 'Exaggerated Minimalism', 'centered', 'symmetric', 'grid-based'] }],
+        [4, 7, { label: 'Balanced / Modern', style_keywords: ['modern', 'structured', 'balanced'] }],
+        [8, 10, { label: 'Bold / Asymmetric', style_keywords: ['Brutalism', 'Bento Grids', 'asymmetric', 'experimental'] }],
+    ],
+    motion: [
+        [1, 3, { label: 'Subtle', tier: 'Subtle' }],
+        [4, 7, { label: 'Standard', tier: 'Standard' }],
+        [8, 10, { label: 'Complex', tier: 'Complex' }],
+    ],
+    density: [
+        [1, 3, { label: 'Spacious', spacing: { xs: '4px', sm: '8px', md: '24px', lg: '32px', xl: '48px', '2xl': '64px', '3xl': '96px' } }],
+        [4, 7, { label: 'Standard', spacing: { xs: '4px', sm: '8px', md: '16px', lg: '24px', xl: '32px', '2xl': '48px', '3xl': '64px' } }],
+        [8, 10, { label: 'Dense / Dashboard', spacing: { xs: '2px', sm: '4px', md: '8px', lg: '12px', xl: '16px', '2xl': '24px', '3xl': '32px' } }],
+    ],
+};
+
+/** The dial values a caller may pass; `null`/absent means "do not engage". */
+export interface Dials {
+    variance?: number | null;
+    motion?: number | null;
+    density?: number | null;
+}
+
+/**
+ * Bucket a 1-10 dial value into its tier config, or `null` when unset.
+ *
+ * Out-of-range input is clamped rather than rejected: the dial is a coarse
+ * preference, and refusing an 11 would turn a typo into a failed run for no
+ * gain in meaning.
+ */
+export function resolve_dial(dial_name: string, value: number | null | undefined): ResultDict | null {
+    if (value === null || value === undefined || Number.isNaN(value)) return null;
+    const tiers = DIAL_TIERS[dial_name];
+    if (tiers === undefined) return null;
+    const v = Math.max(1, Math.min(10, Math.trunc(value)));
+    for (const [lo, hi, info] of tiers) {
+        if (v >= lo && v <= hi) return { ...info, value: v };
+    }
+    return null;
+}
+
 /**
  * Conditional grounding: category → rules → planned multi-domain search.
  *
  * Returns the interface-v1 grounded dict (see Python docstring). Async because
  * `_load_rules_callable` is async (dynamic import).
+ *
+ * `dials` is optional and additive: with none passed, the returned dict is
+ * exactly what it was before dials existed.
  */
 export async function ground(
     manifest: Manifest,
     query: string,
     context: Record<string, unknown> | null = null,
+    dials: Dials | null = null,
 ): Promise<ResultDict> {
     const reasoning = manifest.reasoning as Record<string, unknown> | null | undefined;
     if (!reasoning) {
@@ -607,6 +667,29 @@ export async function ground(
             .filter((s) => s.length > 0);
     }
 
+    // 4b — dials.
+    //
+    // Variance biases SELECTION, never RETRIEVAL, and never silently.
+    //
+    // An earlier version prepended the dial's keywords to `priority` outright.
+    // That looked like "biasing" and was not: `priority.slice(0, 2)` augments
+    // the query, so the rule's own corpus-grounded keywords were pushed out of
+    // the retrieval entirely, and five dial keywords then outscored two rule
+    // keywords in the match. The dial did not bias the evidence — it replaced
+    // it, and nothing said so.
+    //
+    // Split instead. `priority` stays the rule's, so what comes BACK from the
+    // corpus is unchanged by the dial. `selection_priority` carries the dial in
+    // front for choosing among those rows — which is what a preference dial is
+    // legitimately for. And when that choice differs from the one the rule's own
+    // keywords would have made, it is reported rather than left invisible.
+    const variance_info = resolve_dial('variance', dials?.variance);
+    const motion_info = resolve_dial('motion', dials?.motion);
+    const density_info = resolve_dial('density', dials?.density);
+    const selection_priority = variance_info
+        ? [...(variance_info.style_keywords as string[]), ...priority]
+        : priority;
+
     // 5 — planned multi-domain search.
     const selections: ResultDict = {};
     const domain_confidences: number[] = [];
@@ -621,12 +704,28 @@ export async function ground(
         }
         const result = search_domain(manifest, q, domain_name, _int(max_results));
         const results = (result.results as Row[] | null) || [];
-        const best =
-            domain_name === priority_domain
-                ? _select_best_match(results, priority, name_cols[domain_name])
-                : results.length > 0
-                  ? (results[0] as Row)
-                  : {};
+        let best: Row;
+        if (domain_name === priority_domain) {
+            best = _select_best_match(results, selection_priority, name_cols[domain_name]);
+            if (variance_info) {
+                // What the rule alone would have picked from the SAME rows.
+                // Reporting the divergence is the whole difference between a
+                // dial that biases and a dial that quietly overrules.
+                const ungated = _select_best_match(results, priority, name_cols[domain_name]);
+                if (ungated !== best) {
+                    const col = name_cols[domain_name];
+                    const nameOf = (r: Row): string =>
+                        col && r[col] !== undefined ? pyStr(r[col]) : '(unnamed)';
+                    gaps.push(
+                        `--variance ${String(variance_info.value)} changed the ${domain_name} pick to ` +
+                            `'${nameOf(best)}'; the rule's own keywords would have selected ` +
+                            `'${nameOf(ungated)}' — the dial biased the choice, it did not come from the corpus`,
+                    );
+                }
+            }
+        } else {
+            best = results.length > 0 ? (results[0] as Row) : {};
+        }
         selections[domain_name] = {
             best,
             // Python: [r for r in results if r is not best] — identity compare.
@@ -641,6 +740,53 @@ export async function ground(
         domain_confidences.push(score instanceof PyFloat ? score.value : (score as number | undefined) ?? 0.0);
     }
 
+    // 5b — the motion dial reads a corpus, which is why it needs `motion.csv`
+    // and the other two do not. Rows are filtered by the `Intensity Tier`
+    // column; a tier with no rows yields an evidence gap rather than a silent
+    // empty block, because "the dial did nothing" and "the corpus has nothing
+    // at this tier" are different facts to the reader.
+    let motion_selection: ResultDict | null = null;
+    if (motion_info) {
+        const tier = motion_info.tier as string;
+        const motion_domain = (manifest.domains as Record<string, ResultDict>)['gsap'];
+        if (motion_domain === undefined) {
+            gaps.push(
+                "the --motion dial needs a 'gsap' search domain (motion.csv); this manifest has none, so the dial had no effect",
+            );
+        } else {
+            // FILTER FIRST, then rank. Retrieving the global top-N and filtering
+            // afterwards drops rows at the requested tier that lost the global
+            // cut to rows of another tier — the dial then silently returns less
+            // than the corpus holds for it. `search_domain` already merges a
+            // filters dict (it is what the `--filter` flag uses), and the row
+            // count comes from the manifest like every other domain rather than
+            // from a literal here.
+            const motion_max = motion_domain['max_results'];
+            const motion_result = search_domain(
+                manifest,
+                query,
+                'gsap',
+                typeof motion_max === 'number' ? motion_max : null,
+                { 'Intensity Tier': tier },
+            );
+            const rows = (motion_result.results as Row[] | null) || [];
+            if (rows.length === 0) {
+                // No block at all, not an empty one: `motion: {best: {}}` reads
+                // as "the dial ran and found nothing worth showing", which is
+                // indistinguishable from a corpus that has nothing at this tier.
+                // The gap says which, and the absent key says the rest.
+                gaps.push(`no motion row at tier '${tier}' matched the query — the dial narrowed to nothing`);
+            } else {
+                motion_selection = {
+                    tier,
+                    best: rows[0] as Row,
+                    alternatives: rows.slice(1),
+                    confidence: motion_result.confidence,
+                };
+            }
+        }
+    }
+
     // 6 — aggregate confidence (weakest link wins).
     const numeric = domain_confidences.length > 0 ? pyRound(Math.min(...domain_confidences), 3) : 0.0;
     const label = numeric >= 0.4 ? 'high' : numeric >= 0.15 ? 'medium' : 'low';
@@ -653,7 +799,7 @@ export async function ground(
         }
     }
 
-    return {
+    const out: ResultDict = {
         domain: manifest.domain,
         query,
         category,
@@ -664,6 +810,24 @@ export async function ground(
         evidence_gap:
             gaps.length > 0 ? gaps : ['none — every planned domain returned a scored match'],
     };
+
+    // Dial output is ADDITIVE and omitted entirely when no dial was passed, so
+    // the no-flag result stays byte-identical to what it was before dials
+    // existed. `spacing_scale` is a top-level override because it replaces a
+    // scale rather than informing one.
+    if (variance_info || motion_info || density_info) {
+        out.dials = {
+            variance: variance_info ? variance_info.value : null,
+            variance_label: variance_info ? variance_info.label : null,
+            motion: motion_info ? motion_info.value : null,
+            motion_label: motion_info ? motion_info.label : null,
+            density: density_info ? density_info.value : null,
+            density_label: density_info ? density_info.label : null,
+        };
+        if (motion_selection) out.motion = motion_selection;
+        if (density_info) out.spacing_scale = density_info.spacing;
+    }
+    return out;
 }
 
 /** Python int(x) for a plan value (int or numeric string). */
@@ -745,6 +909,50 @@ export function _render_markdown(grounded: ResultDict, master = false): string {
         `- **Confidence:** ${pyStr(conf.label ?? '?')} ` + `(${_confScore(conf.score)})`,
         '',
     );
+
+    // Dials render HERE, not only under --json. This is the whole consumption
+    // path for two of the three output paths: the default text render and the
+    // persisted MASTER.md both come through this function, and `--density`'s
+    // only payload is `spacing_scale` — omitted here, that dial is inert
+    // everywhere a human actually reads the result.
+    const dials = (grounded.dials as ResultDict | null) || null;
+    if (dials) {
+        const dialLines: string[] = [];
+        for (const name of ['variance', 'motion', 'density']) {
+            const value = dials[name];
+            if (value === null || value === undefined) {
+                continue;
+            }
+            const label = dials[`${name}_label`];
+            dialLines.push(
+                `- **${name[0]?.toUpperCase()}${name.slice(1)}:** ${pyStr(value)}/10` +
+                    (label ? ` — ${pyStr(label)}` : ''),
+            );
+        }
+        if (dialLines.length > 0) {
+            lines.push('### Dials', '', ...dialLines, '');
+        }
+    }
+
+    const spacing = (grounded.spacing_scale as ResultDict | null) || null;
+    if (spacing && Object.keys(spacing).length > 0) {
+        lines.push('### Spacing scale (density override)', '');
+        for (const step of Object.keys(spacing)) {
+            lines.push(`- **${step}:** ${pyStr(spacing[step])}`);
+        }
+        lines.push('');
+    }
+
+    const motion = (grounded.motion as ResultDict | null) || null;
+    const motionBest = motion ? ((motion.best as Row | null) || {}) : {};
+    if (motion && Object.keys(motionBest).length > 0) {
+        lines.push(`### Motion (tier: ${pyStr(motion.tier ?? '')})`, '');
+        for (const key of Object.keys(motionBest)) {
+            lines.push(`- **${key}:** ${pyStr(motionBest[key])}`);
+        }
+        lines.push('');
+    }
+
     const selections = (grounded.selections as ResultDict | null) || {};
     for (const domain of Object.keys(selections)) {
         const sel = (selections[domain] as ResultDict | null) || {};

package/dist/agent-src/skills/corpus-grounding/scripts/ground.ts

@@ -125,6 +125,28 @@ interface Args {
     persist?: string | null;
     project_name?: string | null;
     page?: string | null;
+    /** Optional 1-10 design dials; `null` means "not passed", never a default. */
+    variance?: number | null;
+    motion?: number | null;
+    density?: number | null;
+}
+
+/**
+ * Parse a 1-10 dial value.
+ *
+ * A non-numeric value is rejected rather than clamped: `--motion high` is a
+ * mistake the caller can fix, and silently reading it as "no dial" would run
+ * the whole grounding pass and return a result that quietly ignored the flag.
+ * Out-of-RANGE numbers are a different case and are clamped downstream — 11 is
+ * a typo with an obvious intent, `high` is not a number at all.
+ */
+function _dial(flag: string, raw: string): number {
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+        process.stderr.write(`argument ${flag}: expected an integer 1-10, got '${raw}'\n`);
+        process.exit(2);
+    }
+    return Math.trunc(n);
 }
 
 /**
@@ -212,6 +234,18 @@ function _parseArgs(argv: string[]): Args {
             args.page = eat();
         } else if (a.startsWith('--page=')) {
             args.page = a.slice('--page='.length);
+        } else if (a === '--variance') {
+            args.variance = _dial('--variance', eat());
+        } else if (a.startsWith('--variance=')) {
+            args.variance = _dial('--variance', a.slice('--variance='.length));
+        } else if (a === '--motion') {
+            args.motion = _dial('--motion', eat());
+        } else if (a.startsWith('--motion=')) {
+            args.motion = _dial('--motion', a.slice('--motion='.length));
+        } else if (a === '--density') {
+            args.density = _dial('--density', eat());
+        } else if (a.startsWith('--density=')) {
+            args.density = _dial('--density', a.slice('--density='.length));
         } else {
             positionals.push(a);
         }
@@ -293,7 +327,11 @@ export async function main(argv: string[] | null = null): Promise<number> {
 
         // ground
         const context = args.context ? (JSON.parse(args.context) as Record<string, unknown>) : {};
-        const grounded = await run_ground(manifest, args.query as string, context);
+        const grounded = await run_ground(manifest, args.query as string, context, {
+            variance: args.variance ?? null,
+            motion: args.motion ?? null,
+            density: args.density ?? null,
+        });
         if (args.persist) {
             const info = persist_grounding(
                 grounded,

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

@@ -8,9 +8,26 @@ upstream repository below. Keep this file shipping with the skill; update the
 
 - Repository: `https://github.com/nextlevelbuilder/ui-ux-pro-max-skill`
 - Commit SHA: `b7e3af80f6e331f6fb456667b82b12cade7c9d35`
-- Last checked: 2026-06-07
+- Last checked: 2026-08-13
 - Upstream version: `skill.json` v2.5.x (npm `uipro-cli`)
 
+### Partial adoptions from a later upstream commit
+
+The base pin above still describes the corpus as a whole. Two assets were
+adopted **selectively** from `97eb2a20f...` on 2026-08-13, and the base pin is
+deliberately NOT bumped: at that commit nine files are absent from our `data/`
+and eleven more have drifted, so claiming the newer SHA wholesale would assert
+an adoption that did not happen (six of the absent files are desktop-UI stacks
+outside this pack's scope, and `google-fonts.csv` is declined by ADR-061 § 8).
+
+| Asset | From | Why |
+|---|---|---|
+| `data/motion.csv` (16 rows) | `97eb2a20` | Consumed by the `gsap` search domain and by the `--motion` design dial, which filters its `Intensity Tier` column. Without it the dial is inert. |
+| The three design dials (`variance` / `motion` / `density`) in `corpus-grounding/scripts/decision_engine.ts` + `ground.ts` | `97eb2a20`, `scripts/design_system.py` | Re-derived, not copied — see `provenance/borrows.jsonl`. |
+
+Licence re-verified at `97eb2a20` before adopting: MIT, same copyright holder,
+unchanged from the base pin.
+
 ## Licenses
 
 ### MIT — corpus + core engine (root `LICENSE`)
@@ -18,7 +35,7 @@ upstream repository below. Keep this file shipping with the skill; update the
 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`,
+`motion`, `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")

package/dist/agent-src/skills/design-intelligence/data/manifest.json

@@ -2,7 +2,7 @@
   "upstream": {
     "sha": "b7e3af80f6e331f6fb456667b82b12cade7c9d35",
     "repo": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill",
-    "last_checked": "2026-06-07",
+    "last_checked": "2026-08-13",
     "last_eval": {
       "date": "2026-06-16",
       "model": "claude-sonnet-4-5",
@@ -257,6 +257,29 @@
         "Severity"
       ],
       "max_results": 3
+    },
+    "gsap": {
+      "file": "motion.csv",
+      "search_cols": [
+        "Category",
+        "Intensity Tier",
+        "Keywords",
+        "Trigger"
+      ],
+      "output_cols": [
+        "Category",
+        "Intensity Tier",
+        "Keywords",
+        "Trigger",
+        "Duration",
+        "Easing",
+        "GSAP Snippet",
+        "Framework Notes",
+        "Do",
+        "Don't",
+        "Performance Notes"
+      ],
+      "max_results": 3
     }
   },
   "detect": {
@@ -454,6 +477,18 @@
       "form",
       "input type",
       "preconnect"
+    ],
+    "gsap": [
+      "motion",
+      "animation",
+      "animate",
+      "transition",
+      "easing",
+      "gsap",
+      "hover effect",
+      "scroll reveal",
+      "parallax",
+      "stagger"
     ]
   },
   "reasoning": {

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

@@ -0,0 +1,17 @@
+No,Category,Intensity Tier,Keywords,Trigger,Duration,Easing,GSAP Snippet,Framework Notes,Do,Don't,Performance Notes
+1,Hover Micro-interaction,Subtle,"hover, button, opacity, lift, press feedback",hover,150-200ms,power1.out,"gsap.to(el, { y: -1, opacity: 0.9, duration: 0.15, ease: 'power1.out' });",Bind on mouseenter/mouseleave; in React wrap in a ref + useEffect (or onMouseEnter/onMouseLeave props directly calling gsap.to),Keep displacement under 2px so it reads as feedback not motion,Don't animate layout-affecting props (width/height/margin) on hover,Runs on transform/opacity only so it stays on the compositor thread
+2,Hover Micro-interaction,Standard,"hover, card, scale, tilt, cursor feedback",hover,200-300ms,power2.out,"gsap.to(el, { y: -4, scale: 1.02, boxShadow: '0 12px 24px rgba(0,0,0,0.12)', duration: 0.25, ease: 'power2.out' });","Use gsap.quickTo(el, 'y') for cards with many hover targets to avoid re-creating tweens every event",Pair with a matching mouseleave tween that reverses the same properties,Don't leave the hover state stuck if the pointer leaves fast; always attach the reverse tween,quickTo() avoids GC churn on lists with 20+ hoverable cards
+3,Hover Micro-interaction,Complex,"hover, magnetic, cursor follow, 3d tilt",hover + mousemove,300-500ms,"elastic.out(1,0.4)","const xTo = gsap.quickTo(el, 'x', { duration: 0.4, ease: 'elastic.out(1,0.4)' }); const yTo = gsap.quickTo(el, 'y', { duration: 0.4, ease: 'elastic.out(1,0.4)' }); el.addEventListener('mousemove', (e) => { const r = el.getBoundingClientRect(); xTo((e.clientX - r.left - r.width/2) * 0.3); yTo((e.clientY - r.top - r.height/2) * 0.3); });",Debounce is not needed since quickTo interpolates; remove listeners on component unmount in React/Vue to avoid leaks,Clamp the pull strength (e.g. * 0.3) so the element never fully leaves its hit box,Don't apply magnetic effect to more than 1-2 focal elements per screen; it becomes noisy,Use will-change: transform on the target element for smoother compositing
+4,Scroll Reveal,Subtle,"scroll, fade in, reveal, on view",scroll (viewport enter),300-400ms,power1.out,"gsap.from(el, { opacity: 0, y: 12, duration: 0.35, ease: 'power1.out', scrollTrigger: { trigger: el, start: 'top 90%', toggleActions: 'play none none reverse' } });",Requires the ScrollTrigger plugin registered once via gsap.registerPlugin(ScrollTrigger),"Keep the y offset small (8-16px) so it reads as a fade, not a slide",Don't reveal below-the-fold content needed for SEO/crawlers as invisible-by-default without a no-JS fallback,toggleActions 'play none none reverse' avoids re-triggering on every scroll direction change
+5,Scroll Reveal,Standard,"scroll, slide up, staggered section, reveal",scroll (viewport enter),400-600ms,power2.out,"gsap.from(el.children, { opacity: 0, y: 24, duration: 0.5, stagger: 0.08, ease: 'power2.out', scrollTrigger: { trigger: el, start: 'top 85%' } });","In React use useGSAP(() => {...}, { scope: containerRef }) from @gsap/react to auto-cleanup on unmount",Scope the ScrollTrigger to the section container so it doesn't re-scan the whole page,Don't stagger more than ~8 children; beyond that the last items feel laggy,Set scroller/markers: false in production; markers is dev-only
+6,Scroll Reveal,Complex,"scroll, pin, scrub, storytelling, scrollytelling",scroll (continuous scrub),tied to scroll position,none (scrub-driven),"gsap.timeline({ scrollTrigger: { trigger: section, start: 'top top', end: '+=150%', scrub: 1, pin: true } }).from('.headline', { opacity: 0, y: 40 }).to('.bg-layer', { yPercent: -20 }, '<');",Pinning needs the section to have deterministic height; recalc ScrollTrigger.refresh() after images/fonts load,Use scrub: true or a small number (0.5-1.5) instead of instant jumps so it feels tied to the scrollbar,Don't pin more than 1-2 sections per page; excessive pinning fights native scroll feel and hurts mobile UX,"Pinning forces layout reflow; test on mid-tier mobile devices, not just desktop"
+7,Stagger List,Subtle,"list, stagger, cards, grid entrance",load or scroll,250-350ms,power1.out,"gsap.from('.list-item', { opacity: 0, y: 8, duration: 0.3, stagger: 0.03 });",Select items with a stable class/data-attribute (not array index) so re-renders in React don't break targeting,Keep per-item stagger delay small (0.02-0.04s) for lists longer than 10 items,Don't stagger by more than 0.1s per item on long lists; total reveal time becomes sluggish,"For virtualized lists, only animate items currently mounted in the DOM"
+8,Stagger List,Standard,"grid, bento, cards, staggered scale",load or scroll,300-450ms,back.out(1.4),"gsap.from('.grid-item', { opacity: 0, scale: 0.92, y: 16, duration: 0.4, stagger: { each: 0.06, from: 'start', grid: 'auto' }, ease: 'back.out(1.4)' });",grid: 'auto' lets GSAP infer rows/columns from a CSS grid layout for a natural wave stagger,Combine with from: 'center' for a bento-grid layout to draw the eye inward first,Don't use back.out on dense data tables; the overshoot reads as sloppy on informational UI,Group DOM writes; avoid interleaving layout reads (getBoundingClientRect) between staggered tweens
+9,Stagger List,Complex,"stagger, wave, text reveal, split text",load or scroll,400-700ms,expo.out,"const split = new SplitText(headline, { type: 'chars' }); gsap.from(split.chars, { opacity: 0, y: 20, rotateX: -40, duration: 0.6, stagger: 0.015, ease: 'expo.out' });",SplitText is a GSAP Club/paid plugin; confirm license before shipping and provide a plain fade fallback if unavailable,Revert SplitText on unmount/cleanup (split.revert()) to restore original text nodes for accessibility tools,Don't split-animate long paragraphs; reserve for short headlines (under ~8 words),Splitting text creates one element per character; keep it to headline-length copy only for DOM size
+10,Page Transition,Subtle,"route change, fade, page transition",route change,200-300ms,power1.inOut,"gsap.to(main, { opacity: 0, duration: 0.2, onComplete: () => { navigate(); gsap.fromTo(main, { opacity: 0 }, { opacity: 1, duration: 0.2 }); } });","Pair with the router's transition hooks (Next.js App Router transitions, React Router's useNavigate, Vue Router's beforeEach/afterEach)",Preload the destination route's critical assets before the exit tween finishes,Don't block navigation on animation; cap exit duration at ~250ms so the app never feels unresponsive,Exit animation should always resolve faster than entrance (asymmetric timing) so back/forward feels snappy
+11,Page Transition,Standard,"route change, slide, overlay wipe",route change,400-600ms,power2.inOut,"const tl = gsap.timeline(); tl.to('.transition-overlay', { yPercent: 0, duration: 0.4, ease: 'power2.inOut' }).call(navigate).to('.transition-overlay', { yPercent: -100, duration: 0.4, ease: 'power2.inOut', delay: 0.1 });",Keep the overlay element mounted at the layout root (outside the page component) so it survives the route swap,Show a lightweight loading indicator if the destination route's data fetch outlasts the overlay,Don't tie the overlay's reveal directly to data-fetch completion without a max-wait timeout; a slow API stalls the whole transition,Prefer CSS transform (yPercent) over top/left to keep the overlay animation on the compositor thread
+12,Page Transition,Complex,"shared element, morph, hero transition",route change,500-800ms,expo.inOut,"const state = Flip.getState('.hero-image'); navigate(); Flip.from(state, { duration: 0.6, ease: 'expo.inOut', absolute: true, zIndex: 100 });",Requires the GSAP Flip plugin; the 'from' and 'to' route must render the same element with a shared data-flip-id,Verify the shared element exists in both DOM states before calling Flip.from to avoid a silent no-op,Don't use shared-element transitions across more than one element pair per navigation; compounding Flips are hard to time correctly,Flip recalculates layout (FLIP technique) so test on low-end devices for jank
+13,Parallax Scroll,Subtle,"parallax, background, depth, scroll speed",scroll (continuous),tied to scroll position,linear (scrub),"gsap.to('.bg-layer', { yPercent: 10, ease: 'none', scrollTrigger: { trigger: section, scrub: true } });","Apply parallax to background/decorative layers only, never to text or interactive controls",Keep the yPercent delta small (5-15) so foreground and background never desync distractingly,Don't parallax body copy; it hurts reading comfort and can trigger motion sickness,will-change: transform on the parallax layer only; remove it after scroll settles to free GPU memory
+14,Parallax Scroll,Standard,"multi-layer parallax, depth, hero background",scroll (continuous),tied to scroll position,linear (scrub),"gsap.utils.toArray('.parallax-layer').forEach((layer, i) => { gsap.to(layer, { yPercent: (i + 1) * -8, ease: 'none', scrollTrigger: { trigger: layer.parentElement, scrub: 0.5 } }); });",Layer count beyond 3-4 has diminishing visual return and multiplies scroll-listener cost,"Vary speed per layer (background slowest, foreground fastest) to sell the depth illusion",Don't let parallax layers overflow their container; clip with overflow: hidden on the wrapper,Batch all layers under one ScrollTrigger container where possible instead of one per layer
+15,Loading / Skeleton,Subtle,"loading, skeleton, shimmer, pulse",on mount / async wait,1200-1600ms loop,sine.inOut,"gsap.to('.skeleton', { backgroundPosition: '200% 0', duration: 1.4, ease: 'sine.inOut', repeat: -1 });",Kill the loop tween (tween.kill()) as soon as real content mounts to avoid orphaned repeating animations,Use a CSS gradient background-position sweep rather than opacity pulsing; reads as 'loading' more clearly,Don't run more than one shimmer loop per skeleton group; sync them under one timeline so the wave reads as a single unit,repeat: -1 tweens are cheap but must be explicitly killed on unmount or they leak in SPA route changes
+16,Loading / Skeleton,Standard,"progress, spinner, morphing loader",on mount / async wait,800-1200ms loop,power1.inOut,"gsap.timeline({ repeat: -1 }).to('.loader-dot', { y: -8, duration: 0.4, stagger: { each: 0.15, yoyo: true, repeat: 1 } });",Wrap the whole loop timeline in useGSAP with { revertOnUpdate: false } in React so it isn't rebuilt every render,Cap total loop duration under ~1.5s so long waits don't feel like the UI froze on a single beat,Don't use elaborate loaders for sub-300ms waits; they flash and feel worse than no indicator,Pause the timeline (tl.pause()) when the loading tab/view is not visible to save CPU on background tabs

package/dist/agent-src/skills/git-workflow/SKILL.md

@@ -52,9 +52,15 @@ gh pr view <number> --json number,state,mergeStateStatus,mergedAt,baseRefName
 - **Before merging** → re-fetch and re-read `state` + `mergeStateStatus` in the
   **same turn**; never merge on a status seen earlier in the conversation.
 - **"Based on main" / "current"** → prove it with
-  `git rev-list --count HEAD..origin/main` (after `git fetch`); non-zero ⇒ the
-  branch is behind and is **not** current — merge `main` in before opening a PR
-  (see [`/create-pr`](../../commands/pr/create.md) § 1b).
+  `npx tsx node_modules/@event4u/agent-config/src/scripts/check_branch_freshness.ts`;
+  exit `1` ⇒ the branch is behind and is **not** current — merge the base in,
+  regenerate the derived files, then open the PR (see
+  [`/create-pr`](../../commands/pr/create.md) § 1b).
+  Prefer it over `git rev-list --count HEAD..origin/main`, which is wrong twice
+  over: it pins `main` as the base for a branch whose PR may target something
+  else, and it reads the local tracking ref — a fetch from earlier in the
+  session, which is memory rather than a check. The gate asks the remote and
+  resolves the base from the open PR.
 
 ## Conventions
 

package/dist/agent-src/skills/subagent-orchestration/SKILL.md

@@ -302,14 +302,17 @@ prefer the cheaper one (`do-and-judge` < `do-and-judge-two-stage` <
 `do-in-steps` < `do-in-parallel` < `do-competitively` <
 `judge-with-debate` < `do-in-worktrees`).
 
-**Mode 6 (`do-in-worktrees`) is gated by `worktrees.mode`** from
-`.agent-settings.yml` (default: `ask`). Resolve before picking:
+**Mode 6 (`do-in-worktrees`) is instruction-only** (ADR-229). There is no
+setting to resolve — `worktrees.mode` was deleted:
 
-| `worktrees.mode` | Mode 6 |
+| Situation | Mode 6 |
 |---|---|
-| `ask` | Eligible. `using-git-worktrees` will run the per-creation permission ask. |
-| `on` | Eligible. Per-creation ask suppressed. |
-| `off` | **Not eligible.** Fall back to mode 3 (`do-in-steps`) — same step-by-step chain, in-place on the current branch. Unless the user **explicitly asked this turn** for a worktree chain, in which case proceed with mode 6 and acknowledge the override per [`using-git-worktrees § Pre-flight`](../using-git-worktrees/SKILL.md). |
+| The user asked for a worktree chain in the chat ("do this in a worktree", "use mode 6") | Eligible. Proceed via [`using-git-worktrees`](../using-git-worktrees/SKILL.md); the request is the permission, so there is no further ask. |
+| Anything else | **Not eligible**, however well the chain shape fits. Fall back to mode 3 (`do-in-steps`) — the same step-by-step chain, in place on the current branch. Do not offer mode 6 as an option. |
+
+Because mode 6 is unreachable unprompted, it is effectively off the
+cheapness ladder above unless the user named it; read that ordering as
+covering modes 1–8 in the default case.
 
 ### 4. Dispatch
 

package/dist/agent-src/skills/using-git-worktrees/SKILL.md

@@ -48,30 +48,34 @@ work and makes it impossible to tell what you broke.
 
 ## Procedure
 
-### 0. Pre-flight — read `worktrees.mode`
+### 0. Pre-flight — instruction-only, no setting to read
 
-Before anything else, read `worktrees.mode` from `.agent-settings.yml`
-(default: `ask`). The setting is a **mechanical layer on top of**
-`scope-control`'s permission gate — it narrows, never widens.
+```
+NEVER CREATE A WORKTREE THE USER DID NOT ASK FOR.
+THERE IS NO SETTING. THE ONLY TRIGGER IS THE USER SAYING SO IN THE CHAT.
+```
+
+There is nothing to read: `worktrees.mode` was deleted (ADR-229). Creation
+is instruction-only and hardcoded, so the decision is never the agent's.
 
-| `worktrees.mode` | Behaviour |
+| Situation | Behaviour |
 |---|---|
-| `ask` | Status quo. Continue to step 1; `scope-control` permission gate applies for every worktree creation. |
-| `on` | Standing permission. Skip the per-creation permission ask; continue to step 1. Iron-Law gates (ignore-check, clean baseline) still apply. |
-| `off` | No autonomous worktree creation. **Refuse** unless the user explicitly asked **this turn** for a worktree ("do this in a worktree", "use mode 6", "spawn a worktree for X"). |
-
-**Off, no explicit request** → stop. Tell the user the setting is `off`,
-suggest the in-place alternative (`subagent-orchestration` mode 3
-`do-in-steps`, or just stay on the current branch). Do not re-ask on
-the same task.
-
-**Off, with explicit request this turn** → acknowledge once
-("`worktrees.mode` is `off`; running this on your explicit request
-for this task") and continue to step 1. The override is for this one
-task — it does not flip the setting.
-
-The setting only suppresses **unprompted** usage. The tool stays
-available when the user wants it.
+| The user asked for a worktree **in the chat** — "do this in a worktree", "use mode 6", "spawn a worktree for X", or the same in another language | Continue to step 1. No permission question: the request **is** the permission. |
+| Anything else, however well the shape would fit | **Do not create one.** Continue in place. |
+
+**No explicit request** → do not ask, do not offer, do not mention it. Use
+the in-place path (`subagent-orchestration` mode 3 `do-in-steps`, or just
+stay on the current branch) and say nothing about worktrees. Proposing one
+unprompted is the failure this rule exists to stop — it puts a decision the
+user did not raise in front of them, and the answer is nearly always no.
+
+This suppresses **unprompted** usage only. The tool stays fully available
+the moment the user wants it, with no confirmation loop in the way: an
+explicit request goes straight to step 1.
+
+The Iron-Law gates below are unchanged and still run on every
+explicitly-requested worktree — ignore-safety check (step 3) and clean
+baseline (step 5). Instruction-only removes the *choice*, never the checks.
 
 ### 1. Inspect current state
 

package/dist/agent-src/templates/agent-settings.md

@@ -575,7 +575,6 @@ the canonical narrative lives in
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
-| `worktrees.mode` | `off`, `on`, `ask` | `ask` | Controls autonomous `git worktree` usage. `off` = skill refuses unless the user explicitly asks for a worktree that turn (then it runs); `subagent-orchestration` mode 6 falls back to mode 3. `on` = standing permission (skill skips the per-creation ask; ignore-check and clean-baseline gates still apply). `ask` = status quo — `scope-control` permission gate runs every time. |
 | `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. Lives in the PROJECT settings (`agent-project-settings.example.yml` § roles), not in the personal template. See [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md). |
 | `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
 | `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast (not in the shipped personal template — add the block when needed). Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md). |

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "10.4.0"
+agent_config_version: "11.0.0"
 
 # --- Project identity ---
 project:

package/dist/cli-delegate/{chunk-BV3WR67D.js → chunk-55WZN5VF.js}

@@ -4055,7 +4055,6 @@ var accessStyle = external_exports.enum(["getters_setters", "get_attribute", "ma
 var chatFreq = external_exports.enum(["per_turn", "per_phase", "per_tool"]);
 var qualityCadence = external_exports.enum(["end_of_roadmap", "per_phase", "per_step"]);
 var regenCadence = external_exports.enum(["per_step", "every_5_steps", "phase_boundary"]);
-var worktreeMode = external_exports.enum(["off", "on", "ask"]);
 var fidelityMode = external_exports.enum(["strict", "structural", "hard-floor"]);
 var crossSourceMode = external_exports.enum(["on", "auto", "off"]);
 var richSkillsMode = external_exports.enum(["on", "ask", "off"]);
@@ -4375,11 +4374,9 @@ var settingsSchema = external_exports.object({
       "Opt-in adversarial-verification-council mode (subagent-orchestration Mode 9, ADR-122). off (default) = never runs; ask = offer it on an explicit high-risk change; on = auto-run on high-risk changes. Advisory only \u2014 a panel of distinct-model skeptics red-teams a real change for defect FINDING coverage and NEVER auto-gates it (Hard Floor). Stays default-off until the adversarial-council-finding-coverage claim is backed."
     )
   }),
-  worktrees: external_exports.object({
-    mode: worktreeMode.default("ask").describe(
-      "When the agent considers a parallel `git worktree` for risky / large work. ask (default) = surface a numbered option and wait. on = spawn worktrees autonomously. off = never use worktrees, edit in place."
-    )
-  }),
+  // `worktrees.mode` was DELETED (ADR-229). Worktree creation is
+  // instruction-only and hardcoded; there is nothing left to configure. A
+  // leftover key is ignored with one deprecation line via REMOVED_KEYS.
   ai_team: external_exports.object({
     model: external_exports.string().default("auto").describe(
       "Model handed to the codex CLI. 'auto' (default) = pass no --model flag so the CLI's own default applies \u2014 tracks the subscription's current strongest model instead of pinning a stale ID. Any other value passes through verbatim as `--model <value>`."

package/dist/cli-delegate/{chunk-X3VOARZD.js → chunk-L565YFXH.js}

@@ -2,10 +2,10 @@ import { createRequire as __acCreateRequire } from 'node:module'; const require
 import {
   ZodFirstPartyTypeKind,
   settingsSchema
-} from "./chunk-BV3WR67D.js";
+} from "./chunk-55WZN5VF.js";
 import {
   main
-} from "./chunk-6ENSXSBW.js";
+} from "./chunk-PPQO4NGR.js";
 import {
   RULE_SOURCE_REL
 } from "./chunk-BKO2AZ7Z.js";
@@ -48,7 +48,7 @@ import {
 import {
   find_project_root_with_anchor,
   load_agent_settings
-} from "./chunk-IR3IVRVC.js";
+} from "./chunk-NLP54U3J.js";
 import {
   event4u_root,
   legacy_xdg_root,