@event4u/agent-config 10.3.0 → 11.0.0

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/design-system-capture/SKILL.md

@@ -202,6 +202,15 @@ auto-installer (out of scope). Full schema is lazy-loaded from
 [`references/design-system-json.md`](references/design-system-json.md) — read it
 only when an import is requested.
 
+**The supply path is real, and it is one command.** Where an extractor's output
+is not already in this shape, run it through the three-lane adapter first —
+`/design-system:import <file>`, which accepts a native artifact, a DTCG token
+file, or an extraction tool's raw JSON and emits the contract. Lanes and
+documented producers:
+[`references/design-system-json.md`](references/design-system-json.md)
+§ Extractor compatibility. The adapter is offline and pure — it does not change
+what this skill owns.
+
 **Import procedure:**
 
 1. Read `design-system.json`; reject it if `source` (kind + ref + captured_at)

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

@@ -71,3 +71,73 @@ brand wins). Precedence on import: registered brand tokens > confirmed
 
 The package **owns this contract**; it does **not** ship the crawler, the
 Playwright runtime, or a font-bundler.
+
+## Extractor compatibility — which crawler, and how its output gets here
+
+The contract above says what this skill reads. This section says how a real
+tool's output becomes that shape, so the answer to *"which crawler?"* lives in
+the contract rather than in somebody's memory.
+
+`src/scripts/design_system_import.ts` is a **pure, offline file transform** with
+three input lanes. It reads a file and writes the contract shape to stdout — no
+network, no browser, no crawl. That is the lock restated as code: a transform
+that fetched would quietly become the crawler this package does not ship.
+
+| Lane | Input | What it does |
+|---|---|---|
+| `native` | an existing `design-system.json` | Validates `source`, carries every other key verbatim. Past provenance the validation is **report-only** — a key whose shape contradicts the contract is flagged and kept, never dropped, because the import is a proposal a human reads. |
+| `dtcg` | a W3C DTCG token file (`{$value, $type}` leaves) | Buckets by `$type`, so it works on any authoring tool's layering — **with two stated path exceptions**: `dimension` / `number` is genuinely ambiguous in DTCG (spacing, radius and font size share it), so the path breaks that tie, and a path segment named `dark` files a colour under the dark theme. Both are inferences and both are reported in the notes. Resolves `{alias.references}` to their values. Tokens with no contract bucket land in `_meta.unmapped` — which is why `component.button.paddingX` lands there rather than under spacing. |
+| `dembrandt` | an extraction tool's raw JSON | Matches the documented top-level key names and accepts a small set of shapes per bucket. Motion durations/easings become the `motion` block; per-context profiles, hover deltas, WCAG results and breakpoints are **observation** and land in `_meta`. |
+
+```bash
+# The command is the supported entry point:
+/design-system:import <file>
+
+# Or call the transform directly, from an installed package:
+npx tsx node_modules/@event4u/agent-config/src/scripts/design_system_import.ts <file> \
+    [--lane native|dtcg|dembrandt] \
+    [--source-kind url|repo|dir --source-ref <ref>] [--captured-at <ISO>] \
+    [--format json|summary]
+```
+
+**Documented producers.** Two extraction tools are known to emit input this
+adapter consumes, and both are **user-installed and user-connected** — the
+package ships the adapter, the instructions, and the validation, never the tool:
+
+- **dembrandt** (MIT, npm) — the richest single source: computed-DOM tokens,
+  automatic motion extraction (duration scale, easing curves), component
+  observations, WCAG pairs, and a stdio MCP server. Feeds the `dembrandt` lane
+  directly, or the `dtcg` lane via its `--dtcg` export.
+- **designlang** (MIT) — DTCG in primitive/semantic/composite layers plus
+  interaction states. Feeds the `dtcg` lane. Its own repo-writing feature is not
+  invoked; this package owns its projection.
+
+A third, **extract-design-system**, emits plain W3C `tokens.json` and feeds the
+same `dtcg` lane. Any other tool that can export DTCG works without a new lane.
+
+**Provenance is mandatory on every lane, and its origin is recorded.** DTCG
+carries no `source` block by construction, so the caller supplies one; the
+result then carries `source._meta.provenance_origin: "caller"` rather than
+`"input"`, so a reader can always tell an extracted provenance from an asserted
+one. Neither one present is a rejection, not a default — you cannot confirm what
+you cannot trace.
+
+**A lane is never forced.** Where a real sample cannot be mapped without
+inventing values, the adapter emits it as `_meta` observation and says so in a
+note. An import that lands mostly under `_meta` is the designed degradation, not
+a failure — it means the tool's shape moved, and the values are still in front
+of the human instead of silently coerced into tokens.
+
+**Parked, not adopted — runtime drift detection.** One documented producer also
+ships a drift gate: `--compare <baseline>` against a captured baseline, with
+distinct exit codes (0 clean · 1 drift · 2 usage · 67 threshold) and a
+machine-readable `drift` key carrying per-token `changes[]`. That is a
+*design-quality CI* capability, not an import one, and nothing in this package
+asks for it today — recorded here as a candidate so the next reader finds it
+already assessed, and taken up only if a design-quality roadmap asks for runtime
+drift detection.
+
+The compatibility matrix is committed as tests, not prose:
+`tests/scripts/fixtures/design-system-import/` holds one input/expected pair per
+lane, and that directory's README states which sample is a real capture and
+which is derived from a tool's published output surface.

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.3.0"
+agent_config_version: "11.0.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/scripts/work_engine/directives/ui/design.ts

@@ -345,7 +345,10 @@ function _halt_provided_without_contract(
         '> 1. Proceed — port it with those five losses on the record; `apply` ' +
             'still has to report what it honoured, translated, and flagged',
         '> 2. Supply a `design-system.json` — its token values are then ' +
-            'honoured verbatim instead of re-derived',
+            'honoured verbatim instead of re-derived. Already have an ' +
+            "extractor's output in another shape? `/design-system:import " +
+            '<file>` maps a DTCG token file or an extraction tool\'s raw JSON ' +
+            'into this contract offline.',
         '> 3. Abort — drop this UI request',
         '',
         '**Recommendation: 2 — Supply the contract** — it is the only option ' +

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,

package/dist/cli-delegate/{chunk-JMQZ7MM5.js → chunk-MNWRDMR5.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-MMJL4TIX.js";
 import {
   load_agent_settings
-} from "./chunk-IR3IVRVC.js";
+} from "./chunk-NLP54U3J.js";
 
 // src/scripts/chat_history.ts
 import { createHash } from "node:crypto";

package/dist/cli-delegate/{chunk-IR3IVRVC.js → chunk-NLP54U3J.js}

@@ -517,7 +517,8 @@ var REMOVED_KEYS = /* @__PURE__ */ new Map([
   ["chat_history.max_size_kb", "the rotate command takes --max-kb from argv; session-count pruning bounds the file"],
   ["chat_history.on_overflow", "the overflow mode comes from the rotate command --mode argv"],
   ["quality.wait_for_remote_ci", "whether to poll follows from the push plus a detectable remote pipeline"],
-  ["legal_review_prep.consented_at", "the provenance sidecar settings:set writes and consentVerdict reads"]
+  ["legal_review_prep.consented_at", "the provenance sidecar settings:set writes and consentVerdict reads"],
+  ["worktrees.mode", "the user asking for a worktree in the chat; creation is instruction-only and hardcoded"]
 ]);
 var _warnedRemovedKeys = /* @__PURE__ */ new Set();
 function _readDottedSettingsPath(root, dotted) {

package/dist/cli-delegate/{chunk-FV34EGEX.js → chunk-NN4KW4HZ.js}

@@ -53,7 +53,7 @@ import {
   load_agent_settings,
   project_settings_path,
   resolve_project_root
-} from "./chunk-IR3IVRVC.js";
+} from "./chunk-NLP54U3J.js";
 import {
   event4u_root,
   resolve_with_fallback,

package/dist/cli-delegate/{chunk-6ENSXSBW.js → chunk-PPQO4NGR.js}

@@ -1,7 +1,7 @@
 import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
 import {
   resolve_project_root
-} from "./chunk-IR3IVRVC.js";
+} from "./chunk-NLP54U3J.js";
 import {
   resolvePackageRoot
 } from "./chunk-MCJYCQPF.js";

package/dist/cli-delegate/chunk-RLN73PR5.js

@@ -0,0 +1,157 @@
+import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+import {
+  git_common_dir
+} from "./chunk-PZWRPRWP.js";
+
+// src/scripts/_lib/envelope_grounding.ts
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// src/scripts/_lib/git_env.ts
+var GIT_DISCOVERY_VARS = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_COMMON_DIR",
+  "GIT_NAMESPACE",
+  "GIT_PREFIX"
+];
+function gitEnv(base = process.env) {
+  const env = { ...base };
+  for (const key of GIT_DISCOVERY_VARS) {
+    delete env[key];
+  }
+  return env;
+}
+
+// src/scripts/_lib/envelope_grounding.ts
+var MAX_FIELD_CHARS = 200;
+var MAX_PATHS = 40;
+function git(root, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: root,
+      env: gitEnv(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function canonicalizeRepoIdentity(raw) {
+  let s = raw.trim();
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+  s = s.replace(/^[^/@]+@/, "");
+  s = s.replace(/^([^/:]+):(?!\/)/, "$1/");
+  s = s.replace(/\/+$/, "");
+  s = s.replace(/\.git$/i, "");
+  const slash = s.indexOf("/");
+  if (slash > 0) {
+    s = s.slice(0, slash).toLowerCase() + s.slice(slash);
+  } else {
+    s = s.toLowerCase();
+  }
+  return s;
+}
+function collectRepoAnchor(root) {
+  const remote = git(root, ["config", "--get", "remote.origin.url"]);
+  let identity = null;
+  if (remote) {
+    identity = canonicalizeRepoIdentity(remote);
+  } else {
+    const common = git_common_dir(root);
+    if (common !== null) {
+      try {
+        identity = fs.realpathSync(common);
+      } catch {
+        identity = common;
+      }
+    }
+  }
+  return {
+    repo_identity: identity ? identity.slice(0, MAX_FIELD_CHARS) : null,
+    branch: git(root, ["rev-parse", "--abbrev-ref", "HEAD"]),
+    head: git(root, ["rev-parse", "HEAD"])
+  };
+}
+var VERIFY_STATE_REL = path.join("agents", "runtime", "state", "verify-before-complete.json");
+function readLastVerify(root) {
+  try {
+    const raw = fs.readFileSync(path.join(root, VERIFY_STATE_REL), "utf-8");
+    const state = JSON.parse(raw);
+    const lv = state["last_verification"];
+    if (typeof lv !== "object" || lv === null || Array.isArray(lv)) return null;
+    const rec = lv;
+    const command = typeof rec["command"] === "string" ? rec["command"] : null;
+    if (!command) return null;
+    const at = typeof rec["at"] === "string" ? rec["at"] : "unknown time";
+    return `${command} @ ${at} (no exit status is recorded anywhere)`.slice(0, MAX_FIELD_CHARS);
+  } catch {
+    return null;
+  }
+}
+function collectGrounding(root) {
+  const anchor = collectRepoAnchor(root);
+  const porcelain = git(root, ["status", "--porcelain"]);
+  if (porcelain === null) {
+    return { ...anchor, uncommitted_paths: [], status_summary: null, last_verify: readLastVerify(root) };
+  }
+  const lines = porcelain.split("\n").filter((l) => l.trim().length > 0);
+  const paths = lines.map((l) => l.slice(3).trim()).filter((p) => p.length > 0 && p.length <= MAX_FIELD_CHARS).slice(0, MAX_PATHS);
+  return {
+    ...anchor,
+    uncommitted_paths: paths,
+    status_summary: lines.length === 0 ? "clean working tree" : `${lines.length} uncommitted path(s)${lines.length > MAX_PATHS ? `, first ${MAX_PATHS} listed` : ""}`,
+    last_verify: readLastVerify(root)
+  };
+}
+function describeDrift(envelope, actual) {
+  if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) return [];
+  const e = envelope;
+  const drift = [];
+  const recordedIdentity = typeof e["repo_identity"] === "string" ? e["repo_identity"] : null;
+  if (recordedIdentity && actual.repo_identity && recordedIdentity !== actual.repo_identity) {
+    drift.push(
+      `IDENTITY DRIFT: this envelope was written in "${recordedIdentity}", you are in "${actual.repo_identity}". Re-verify every path before acting \u2014 same branch name does not mean same working tree.`
+    );
+  }
+  const recordedBranch = typeof e["branch"] === "string" ? e["branch"] : null;
+  if (recordedBranch && actual.branch && recordedBranch !== actual.branch) {
+    drift.push(
+      `BRANCH DRIFT: envelope written on "${recordedBranch}", checkout is on "${actual.branch}".`
+    );
+  }
+  const recordedHead = typeof e["head"] === "string" ? e["head"] : null;
+  if (recordedHead && actual.head && recordedHead !== actual.head) {
+    drift.push(
+      `COMMIT DRIFT: envelope written at ${recordedHead.slice(0, 12)}, HEAD is now ${actual.head.slice(0, 12)} \u2014 re-read anything the envelope quotes.`
+    );
+  }
+  return drift;
+}
+
+// src/scripts/_lib/recycle_envelope_paths.ts
+import * as path2 from "node:path";
+var RECYCLE_ENVELOPE_REL = path2.join("agents", "runtime", "state", "recycle-envelope.json");
+var RECYCLE_CONSUMED_REL = path2.join(
+  "agents",
+  "runtime",
+  "state",
+  "recycle-envelope.consumed.json"
+);
+var RECYCLE_MAX_AGE_HOURS = 48;
+var RECYCLE_ENVELOPE_MAX_BYTES = 6144;
+
+export {
+  collectRepoAnchor,
+  collectGrounding,
+  describeDrift,
+  RECYCLE_ENVELOPE_REL,
+  RECYCLE_CONSUMED_REL,
+  RECYCLE_MAX_AGE_HOURS,
+  RECYCLE_ENVELOPE_MAX_BYTES
+};

package/dist/cli-delegate/{chunk-6LOPHJLD.js → chunk-RYNADUFG.js}

@@ -2,7 +2,7 @@ import { createRequire as __acCreateRequire } from 'node:module'; const require
 import {
   DEFAULT_PROJECT_FILE,
   logger
-} from "./chunk-IR3IVRVC.js";
+} from "./chunk-NLP54U3J.js";
 
 // src/scripts/config/profiles.ts
 import * as fs2 from "node:fs";