@event4u/agent-config 10.3.0 → 11.0.0

package/dist/agent-src/commands/pr/create.md

@@ -68,52 +68,77 @@ gate.
 
 Run, in order:
 
-1. `git fetch origin {target-base} --quiet` (default: `main`).
-2. `git rev-list --count HEAD..origin/{target-base}` — number of
-   commits HEAD is **behind** the base.
-3. `gh pr list --state open --base {target-base} --limit 20 --json number,headRefName,files`
-   — open PRs targeting the same base.
+1. **Ask the gate, never hand-roll the comparison:**
+
+   ```bash
+   ./scripts-run src/scripts/check_branch_freshness
+   ```
+
+   It resolves the base itself — explicit `--base`, else the base of the **open
+   PR for this branch** as the forge reports it, else the repo default from
+   `origin/HEAD`. Do **not** substitute `git rev-list --count HEAD..origin/main`:
+   that hardcodes a base this branch may not target, and it reads the local
+   tracking ref, which is a fetch from earlier in the session — a memory, not a
+   check (`direct-answers` Iron Law 2). Exit `0` = current, `1` = behind, and the
+   refusal names the base **and where that base came from**.
+
+2. `gh pr list --state open --base {resolved-base} --limit 20 --json number,headRefName,files`
+   — open PRs targeting the same base, for the overlap question below.
 
 **Decision matrix:**
 
-| Behind | Overlapping open PR touches same files? | Action |
+| Gate | Overlapping open PR touches same files? | Action |
 |---|---|---|
-| `0` | — | Proceed to Step 2 |
-| `1–N` | No | **Merge `origin/main` in** — `git merge origin/{target-base} --no-edit` — then proceed. No need to ask; state that you did it. Abort + surface only on conflict. |
-| `1–N` | **Yes** | STOP — surface the overlapping PR number, ask: stack on top of it / wait for it to land / proceed-anyway-and-accept-conflicts / cancel |
+| exit `0` | — | Proceed to Step 2 |
+| exit `1` | No | **Merge the base in** — `git fetch origin && git merge origin/{resolved-base} --no-edit` — then run the regeneration set below, then proceed. No need to ask; state that you did it. |
+| exit `1` | **Yes** | STOP — surface the overlapping PR number, ask: stack on top of it / wait for it to land / proceed-anyway-and-accept-conflicts / cancel |
+| warns `could not ask the forge` | — | The **default** base was checked and an open PR against a different base was **not** ruled out. Say so; do not report it as a clean freshness pass. |
 
-A branch behind its base is **not** current — bring `main` in **before** the PR
+A branch behind its base is **not** current — bring the base in **before** the PR
 exists, never after. Auto-merge when there is no file overlap (the common case);
 only ask when an overlapping open PR makes the base genuinely ambiguous. Never
 improvise the base or silently proceed when behind **and** overlapping. The
 10-second fetch beats hours of rebase reconciliation after the parent PR lands.
 
-**On merge conflict: regenerate, don't abort.** Most conflicts on this class of
-branch are in **generated files** — the roadmap dashboard
-(`agents/roadmaps-progress.md`), `docs/proof.md`, the `dist/agent-src/`
-projection, tool projections. Those are resolved **by regenerating from the merged sources**,
-never by hand-picking hunks:
-
-1. `./agent-config roadmap:progress` → resolves the dashboard.
-2. `./scripts-run src/scripts/build_proof` → resolves `docs/proof.md`.
-3. `bash src/scripts/condense.sh --sync`, then `--check` → resolves any
-   conflict inside `dist/agent-src/` by re-projecting from the merged source.
+**After EVERY merge — not only on conflict — regenerate the derived files.**
+This is the half that gets skipped, because a merge that lands cleanly *looks*
+finished. It is not: these files are **generated**, so a clean auto-merge of
+them produces a file that describes neither side's sources. The dashboard is the
+usual casualty — it merges without a conflict marker and then reports a roadmap
+set that no longer exists.
+
+1. `./agent-config roadmap:progress` → the roadmap dashboard.
+2. `./scripts-run src/scripts/build_proof` → `docs/proof.md`.
+3. `bash src/scripts/condense.sh --sync`, then `--check` → re-projects
+   `dist/agent-src/` from the merged source.
 4. Stage the regenerated files, complete the merge, and re-run the touched
    verification before pushing.
 
-Only a conflict in **hand-authored** content (source code, prose you or the
-other PR wrote) is surfaced to the user; a generated-file conflict never is.
+On a **conflict**, the same four steps are the resolution — regenerate from the
+merged sources, never hand-pick hunks. Only a conflict in **hand-authored**
+content (source code, prose you or the other PR wrote) is surfaced to the user;
+a generated-file conflict never is.
 
 ### 1b-ii. Update freshness — MANDATORY on EVERY later push to an open PR
 
 The gate above is not creation-only. **Every subsequent push** to a branch with
 an open PR (a CI fix, a review response, a follow-up commit) re-runs the same
-sequence first: `git fetch origin {target-base}` → behind-check → merge
-`origin/{target-base}` in (regenerating on conflict as above) → verify → push.
+sequence first: `check_branch_freshness` → on exit `1`, merge
+`origin/{resolved-base}` in → regenerate the derived files → verify → push.
 A PR that sits open while its base advances goes stale silently; keeping the
 base merged **at every touch** means it stays `mergeStateStatus: CLEAN` instead
-of accumulating conflicts for the moment the user wants to merge. If the
-behind-check shows `0`, the step costs one fetch and nothing else.
+of accumulating conflicts for the moment the user wants to merge. If the gate
+exits `0`, the step costs one `ls-remote` and nothing else.
+
+Once the PR exists, this is also when the resolution gets *more* precise rather
+than less: the gate can now read the PR's real `baseRefName` from the forge, so
+a stacked or release-line PR is measured against the branch it will actually
+merge into instead of against the repo default.
+
+Where the project wires this gate into its pre-push chain, a push that goes out
+through the hook is covered without a separate step. Run it by hand when you push
+with the hook bypassed, or when you are about to open the PR some time after the
+last push — that gap is exactly where a base moves unseen.
 
 ### 1c. PR-gate — archive completed roadmaps (MANDATORY)
 

package/dist/agent-src/commands/worktree/create.md

@@ -26,7 +26,7 @@ Thin orchestration — mechanics live in the skills; do not restate them.
 ### 1. Gate + create
 
 Run [`using-git-worktrees`](../../../skills/using-git-worktrees/SKILL.md)
-in full: `worktrees.mode` pre-flight, existing-worktree inspection,
+in full: instruction-only pre-flight, existing-worktree inspection,
 directory convention, ignore-safety check, worktree creation, the
 [§ 4b seeding allow/deny list](../../../skills/using-git-worktrees/SKILL.md#4b-seed-the-worktree--allow--deny-list),
 dependency install + clean baseline. Its Iron Law (no worktree without
@@ -61,5 +61,7 @@ name it as the suggested next action — suggest, never auto-run.
 ### Rules
 
 - **Do NOT commit or push.**
-- Worktree creation stays permission-gated per `scope-control` unless
-  `worktrees.mode: on` grants standing permission (skill § 0).
+- Worktree creation is instruction-only (ADR-229). Invoking this command
+  **is** the explicit request, so the skill's § 0 pre-flight passes and no
+  further permission question is raised. Nothing here creates a worktree
+  the user did not ask for.

package/dist/agent-src/rules/settings-ask-protocol.md

@@ -77,12 +77,16 @@ conservative default (`""`, `false`, `false`), so absent is indistinguishable
 from *no* and never from *yes*.
 
 **Class C carrying an `ask` value in its own enum** — a runtime question whose
-answer dies with the run: `worktrees.mode` (**ships** as `ask`), plus
-`tokens.rich_skills`, `subagents.adversarial_council`, `decision_engine.on_block`
-(which can be set to `ask` by a human but do not ship that way). Always-on
-orchestration (road-to-always-on-orchestration Phase 1) deleted
-`subagents.auto` and `subagents.budget_routing` — the layer no longer carries a
-setting for this protocol to route.
+answer dies with the run: `tokens.rich_skills`,
+`subagents.adversarial_council`, `decision_engine.on_block`. **None of them
+ships as `ask`** — a human sets it, so the whole class is opt-in and no shipped
+default routes a question through this protocol at all.
+
+Two deletions got the list here. Always-on orchestration
+(road-to-always-on-orchestration Phase 1) removed `subagents.auto` and
+`subagents.budget_routing`. ADR-229 removed `worktrees.mode`, which was the last
+key that *shipped* as `ask` — worktree creation is instruction-only now, so
+there is no setting and nothing to ask about.
 
 ## The budget
 
@@ -153,9 +157,10 @@ by `settings:set` and only *displayed* by the GUI.
 - Class A — resolves to its default, never asked.
 - Class C **not** set to `ask` — no question; a change is a human edit.
 - Already decided on any resolution layer, or the run completes without it.
-- **The `ask` routes to a permission gate.** `worktrees.mode: ask` means
-  `scope-control`'s per-creation gate applies — a permission ask about an
-  *action*, which that rule owns; a storage line there would store nothing.
+- **The `ask` routes to a permission gate** — a permission ask about an
+  *action*, which `scope-control` owns; a storage line there would store
+  nothing. `worktrees.mode: ask` was the worked example until ADR-229 deleted
+  the key; the carve-out is kept because the shape recurs, not the key.
 - **The `ask` is code, not agent-carried.** `decision_engine.on_block: ask` is a
   TTY prompt in `work_engine/hooks/builtin/decision_gate.ts`.
 

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")