@event4u/agent-config 10.4.0 → 12.0.0

package/dist/agent-src/skills/ai-council/SKILL.md

@@ -328,9 +328,25 @@ not a default.
 2. **Bundle + redact.** Call `scripts/ai_council/bundler.ts` to produce
    a redacted artefact bundle. If `BundleTooLarge` fires, surface the
    size and ask the user to narrow scope — do NOT truncate silently.
-3. **Confirm spend.** Before any network call, surface members + cost
-   ceiling and require an explicit user `1` to proceed. Autonomy
-   settings do not override this gate.
+3. **Clear the spend bound.** The council is standing-authorized — there is
+   no per-invocation approval. What still binds is a *bound*, resolved in
+   this order:
+   - **No billable member** (every member is `mode: cli` under
+     subscription auth — `billable=False`) → nothing is spent. Render the
+     estimate table as information and fan out. No gate.
+   - **Billable members with a configured ceiling** (`cost_budget.max_total_usd`
+     non-zero, or `daily_limit_usd` non-zero) → the ceiling **is** the
+     authorization the user already gave. Render the estimate and fan out.
+     `on_overrun` still fires per member on breach (below) — that is where
+     the user regains the decision.
+   - **Billable members with no ceiling at all** (`max_total_usd: 0` AND
+     `daily_limit_usd: 0`) → unbounded paid spend, so surface the estimate
+     and require an explicit `1`. Nothing bounds the call, so the user must.
+
+   Autonomy settings do not *create* a bound and do not lift the last case.
+   Consumers who want the old per-run gate back set a small
+   `cost_budget.max_total_usd`: every call then breaches and `on_overrun`
+   asks, per member.
 4. **Fan out.** Dispatch the bundle to each enabled council member via
    `scripts/ai_council/orchestrator.ts`. Each member receives the
    neutrality preamble from `prompts.ts` plus the artefact — nothing
@@ -594,8 +610,9 @@ overrides the table regardless of how the lens resolved.
   identity — that primes the reviewer and collapses diversity.
 - Do NOT silently truncate a too-large bundle — surface the size and
   ask for narrower scope.
-- Do NOT auto-spend tokens under `personal.autonomy: on` — the cost
-  gate fires every time, no exceptions.
+- Do NOT spend against an unbounded budget without asking — a billable
+  member with neither `max_total_usd` nor `daily_limit_usd` set has no
+  ceiling, and autonomy is not a ceiling.
 - Do NOT reuse SDK clients across invocations — re-load keys via
   `load_*_key()` each call.
 
@@ -620,7 +637,8 @@ Real failure modes seen in the wild:
 | Paste the host-agent identity ("I am Augment / Claude Code…") | Identity primes the reviewer's model. | Neutrality preamble in `prompts.ts` already handles this. |
 | Silently truncate a too-large bundle. | Misleads the reviewer into thinking they saw the whole thing. | Bundler raises `BundleTooLarge`; surface and ask for narrower scope. |
 | Reuse the same SDK client across calls without re-loading the key. | Leaks the key in long-lived process state. | Each invocation builds fresh clients from `load_*_key()`. |
-| Auto-spend tokens under `personal.autonomy: on`. | Autonomy ≠ permission to spend money. | Always ask before consultation, even under autonomy. |
+| Spend against a billable member with no configured ceiling because "the council is standing-authorized". | Standing authorization is a *bound* the user set once, not a blank cheque. No ceiling = nothing was authorized. | Surface the estimate and ask, exactly in that one case (Procedure § 3). |
+| Re-ask per invocation once a ceiling exists. | The ceiling already carried the decision; re-asking is the approval burden this default removed. | Fan out; let `on_overrun` ask on breach. |
 | Forward council convergence to the user as numbered options without a host verdict. | Convergence ≠ correctness; the council never saw the codebase. | Apply the *Critical evaluation* lens; tag every finding `accept` / `accept-with-modification` / `reject` / `needs-input` with one-line reason. |
 | Reject a finding on preference, not evidence. | "I don't like this" is not a verdict. | Cite the file, line, ADR, or contract that justifies the rejection — or surface as `needs-input`. |
 | Paraphrase council output into the host's own analysis to defend a verdict. | Strips attribution, breaches `direct-answers` no-invented-facts. | Verdict cites host evidence (file:line); council output stays attributed in the per-member sections. |

package/dist/agent-src/skills/corpus-grounding/SKILL.md

@@ -71,7 +71,8 @@ Scripts resolve all paths **skill-relative** (per
 
 ./scripts-run <skills-root>/corpus-grounding/scripts/ground ground \
   --manifest <skills-root>/<domain-skill>/data/manifest.json \
-  "luxury e-commerce" [--context '{"data_heavy": true}'] [--persist DIR]
+  "luxury e-commerce" [--context '{"data_heavy": true}'] [--persist DIR] \
+  [--variance 1-10] [--motion 1-10] [--density 1-10]
 
 ./scripts-run <skills-root>/corpus-grounding/scripts/ground validate --manifest …
 ```
@@ -79,6 +80,16 @@ Scripts resolve all paths **skill-relative** (per
 `<skills-root>` is wherever skills are deployed (`~/.claude/skills/` for
 Claude Code installs; `src/skills/` inside this repo).
 
+**The three `ground` dials are optional 1-10 preferences, and unset means
+unset** — a dial you do not pass changes nothing, so the no-flag result is
+byte-identical to what it was before they existed. `--variance` biases which
+style is **selected** from the rows the corpus returned (never which rows come
+back), and when it changes the pick away from the grounding rule's own choice
+the run says so in its evidence gaps. `--motion` needs a `gsap` domain in the
+manifest and reports when a tier matches nothing. `--density` overrides the
+spacing scale. All three render in the text output and in a persisted
+`MASTER.md`, not only under `--json`.
+
 ## Output format
 
 **Interface contract v1 — stability promise.** Per ADR-061 §2 ("Opus

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/docx-authoring/SKILL.md

@@ -6,6 +6,7 @@ status: active
 tier: senior
 domain: process
 compatibility: "Requires a consumer-installed OOXML library (python-docx for create/fill; a zip+xml toolchain for the unpack→edit→pack path). No LibreOffice/soffice dependency — that surface is gated (see pptx, road-to-ecosystem-harvest-document-skills Phase 2). Ships zero runtime in this package."
+harness_compat: consumer-installed-deps
 workspaces:
   - agent-config-maintainer
 packs:

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

@@ -52,9 +52,23 @@ 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). Exit `0` means only that
+  the gate did **not refuse**: read the line. `branch is current` is the pass;
+  `NOT VERIFIED` means the base could not be reached and freshness is
+  **unknown** — the gate exits `0` there on purpose so an offline push is not
+  blocked, which makes reporting it as "current" the one misread it cannot
+  catch. Exit `0` also covers the paths with nothing to check — a no-op in CI, a
+  detached HEAD, standing on the base itself — and under `--quiet` a genuine
+  pass prints nothing, so run it without the flag when you need a verdict to
+  read.
+  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/pdf-tools/SKILL.md

@@ -6,6 +6,7 @@ status: active
 tier: senior
 domain: process
 compatibility: "Requires consumer-installed PDF libraries: pypdf (merge/split/rotate/encrypt/extract), reportlab (create), a form library for AcroForm fill; an OCR engine (e.g. tesseract) only for the OCR task. No LibreOffice dependency. Ships zero runtime in this package."
+harness_compat: consumer-installed-deps
 workspaces:
   - agent-config-maintainer
 packs:

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

@@ -672,6 +672,41 @@ This duplicates the rules on purpose, and the duplication is the point: the
 rules are the enforcement, the section is what survives the artifact leaving
 their reach.
 
+## Action-reference split (required pattern, `safety_mode: strict` skills)
+
+`execution.safety_mode: strict` says the skill's execution path may mutate
+something. That is a claim made in the frontmatter, and until the body backs it
+the claim costs nothing: a reader who follows the procedure top to bottom finds
+the mutating step sitting inline with every other step, indistinguishable from a
+read.
+
+A strict skill therefore takes one of exactly two shapes, and says which:
+
+- **Gate it inline.** The mutating step carries its precondition in the same
+  breath — propose the exact command first, `--dry-run` before the live run, the
+  user confirms, verify the effect landed afterwards. The precondition is part of
+  the step, never a general reassurance three sections away.
+- **Defer it.** The SKILL.md states plainly that it **does not define the
+  mutating workflow**, and points the write-path steps at a file under the
+  skill's own `references/`. The pointer is the precondition's home: the
+  reference opens with what must be true before its first step runs.
+
+Deferring is the better shape once the write path has more than a couple of
+steps, and for the reason the split exists at all — the main body stays readable
+as the thing an agent loads to decide *whether* to act, while the steps that
+change something live behind one deliberate extra read. What it must never
+become is a second copy: the reference holds the write path, the SKILL.md holds
+the pointer, and neither restates the other.
+
+`skill_linter` nudges (`strict_mode_missing_write_gate`, warning) when a strict
+skill's body carries neither shape. It is a warning and it matches on prose, so
+treat it as a prompt to check the body rather than a verdict on it — a skill that
+gates its write path some third way is doing the right thing and should say so
+plainly enough that the next reader sees the gate without running the linter.
+
+Read with § Security-constraints above: that section states what the script may
+touch, this one states what must be true before it touches it.
+
 ## Mechanism-teaching section (optional pattern, skills whose subject has one)
 
 A procedure tells the agent what to do in the cases you thought of. A