@event4u/agent-config 9.10.0 → 9.12.0

package/src/agent-src/templates/scripts/work_engine/stack/detect.ts

@@ -17,17 +17,35 @@
  *
  * 1. `composer.json` lists `livewire/livewire` AND `livewire/flux` →
  *    `blade-livewire-flux`
- * 2. `package.json` lists `react` AND any of `@radix-ui/*`,
+ * 2. `composer.json` lists `filament/filament` → `filament` (before bare
+ *    Livewire: Filament pulls Livewire in transitively)
+ * 3. `composer.json` lists `livewire/livewire` → `blade-livewire`
+ * 4. `package.json` lists `react` AND any of `@radix-ui/*`,
  *    `shadcn-ui` or has a `components.json` (the shadcn marker file)
  *    → `react-shadcn`
- * 3. `package.json` lists `vue` (any major) → `vue`
- * 4. Otherwise → `plain`
+ * 5. `package.json` lists `react` → `react`
+ * 6. `package.json` lists `vue` (any major) → `vue`
+ * 7. Either manifest names a recognised-but-unmodelled framework
+ *    (Svelte, Angular, Nuxt, Astro, Solid, Qwik, Inertia) → `unknown`
+ * 8. Otherwise → `plain`
+ *
+ * Rules 3, 5 and 7 exist because the earlier table sent three common
+ * shapes into `plain`: Laravel+Livewire without Flux failed rule 1's `&&`,
+ * React without Radix failed rule 4, and every unmodelled framework was
+ * indistinguishable from a genuinely plain project. `plain` now means "no
+ * frontend markers"; `unknown` means "a framework we do not model", and
+ * dispatch refuses on it rather than handing over generic tooling silently.
  *
  * Detection is filesystem-cheap: at most three small JSON reads per
  * project root. Errors (missing file, malformed JSON, missing `require`
  * section) downgrade to `plain` rather than raising — a wrong stack
  * label is recoverable (audit catches it, user can override), but a
  * crash mid-dispatch is not.
+ *
+ * Root manifests only, by design: a monorepo caller passes the workspace
+ * root that carries the manifest it cares about. Note the consequence —
+ * a caller that always passes the repository root gets `plain` for a
+ * monorepo, so the caller owns scope selection, not the detector.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -43,18 +61,59 @@ import * as path from 'node:path';
  */
 export const KNOWN_STACKS: ReadonlySet<string> = new Set([
     'blade-livewire-flux',
+    'blade-livewire',
+    'filament',
     'react-shadcn',
+    'react',
     'vue',
     'plain',
+    'unknown',
 ]);
 
-/** Fallback when no manifest signal matches. */
+/**
+ * Label for a project with no frontend markers at all.
+ *
+ * `plain` used to carry two meanings — "genuinely a plain HTML/Tailwind
+ * project" and "detection failed, here is generic tooling anyway" — which made
+ * a loud failure impossible without punishing real plain projects. The second
+ * meaning is now {@link UNSUPPORTED_STACK}.
+ */
 export const DEFAULT_STACK = 'plain';
 
+/**
+ * Label for a project whose frontend IS recognisable but is not modelled.
+ *
+ * Dispatch refuses on this label instead of degrading to generic tooling: a
+ * Filament or Svelte project silently routed to a Tailwind-only bundle is
+ * user-hostile precisely because the output looks like it worked.
+ */
+export const UNSUPPORTED_STACK = 'unknown';
+
 const _SHADCN_RADIX_PREFIX = '@radix-ui/';
 const _SHADCN_PACKAGE_NAMES: ReadonlySet<string> = new Set(['shadcn-ui', 'shadcn']);
 const _FLUX_PACKAGE = 'livewire/flux';
 const _LIVEWIRE_PACKAGE = 'livewire/livewire';
+const _FILAMENT_PACKAGE = 'filament/filament';
+
+/**
+ * Frontend markers this package recognises but does not model.
+ *
+ * One of these present means detection **succeeded** at recognising a
+ * framework and the package simply has no lane for it — the `unknown` case,
+ * not the `plain` case. Keep the list short and factual; a marker leaves it
+ * only when a real lane exists.
+ */
+const _UNMODELLED_MARKERS: ReadonlyArray<string> = [
+    'svelte',
+    '@angular/core',
+    'nuxt',
+    'astro',
+    'solid-js',
+    '@builder.io/qwik',
+    '@inertiajs/vue3',
+    '@inertiajs/react',
+    'inertiajs/inertia-laravel',
+];
 
 /**
  * A heterogeneous JSON object, mirroring a Python `dict[str, object]`.
@@ -63,6 +122,49 @@ const _LIVEWIRE_PACKAGE = 'livewire/livewire';
  */
 type Manifest = { [key: string]: unknown };
 
+/**
+ * The independent axes a frontend stack actually varies along.
+ *
+ * A flat label forces all-or-nothing matches: `livewire ∧ flux` was never the
+ * bug, it was the symptom of collapsing three axes into one enum value. The
+ * measured proof is Nuxt — `nuxt` is on the unmodelled-marker list, but the
+ * project is labelled `vue` because Vue is a Nuxt dependency and matched first.
+ * No ordering of one list can express "Nuxt implies Vue but is not Vue".
+ *
+ * Axes are **additive**: the flat `frontend` label keeps its existing
+ * computation untouched, so the eight shipped labels are byte-stable by
+ * construction rather than by test. Dispatch composition reads the axes.
+ *
+ * `'none'` means "this axis is genuinely absent" (a Blade app has no JS
+ * component library); `'unknown'` means "not recognised", which is a different
+ * fact and must not be conflated with absence.
+ */
+export interface StackAxes {
+    /** Template / view layer — what markup is authored in. */
+    readonly view: string;
+    /** Reactivity layer — what drives updates. */
+    readonly reactivity: string;
+    /** Component library on top of the reactivity layer. */
+    readonly component_lib: string;
+    /** Styling system. */
+    readonly css: string;
+    /**
+     * Meta-framework wrapping the reactivity layer (Nuxt over Vue, Next over
+     * React, Astro over anything). Its own axis precisely because it does not
+     * replace the layer underneath — which is what the flat label got wrong.
+     */
+    readonly meta: string;
+}
+
+/** Every axis unresolved — the shape for a project with no signals at all. */
+const _EMPTY_AXES: StackAxes = {
+    view: 'none',
+    reactivity: 'none',
+    component_lib: 'none',
+    css: 'none',
+    meta: 'none',
+};
+
 /**
  * Outcome of one detection pass.
  *
@@ -79,10 +181,28 @@ type Manifest = { [key: string]: unknown };
 export class StackResult {
     readonly frontend: string;
     readonly mtime: number;
+    /** Multi-axis view of the same detection. See {@link StackAxes}. */
+    readonly axes: StackAxes;
+    /**
+     * Conflicting signals on one axis, e.g. `['reactivity: react + vue']`.
+     *
+     * Non-empty means the project is genuinely two things and the detector
+     * refuses to pick. Guessing a priority order is the worse property for a
+     * global package: asking costs one turn, a wrong silent pick costs the
+     * whole run.
+     */
+    readonly ambiguity: ReadonlyArray<string>;
 
-    constructor(args: { frontend: string; mtime: number }) {
+    constructor(args: {
+        frontend: string;
+        mtime: number;
+        axes?: StackAxes;
+        ambiguity?: ReadonlyArray<string>;
+    }) {
         this.frontend = args.frontend;
         this.mtime = args.mtime;
+        this.axes = args.axes ?? _EMPTY_AXES;
+        this.ambiguity = args.ambiguity ?? [];
     }
 }
 
@@ -105,19 +225,97 @@ export function detect_stack(project_root: string): StackResult {
     const components_json = _is_file(path.join(project_root, 'components.json'));
     const mtime = latest_manifest_mtime(project_root);
 
+    // Axes are computed once and attached to every result below. The label
+    // chain that follows is UNCHANGED — that is deliberate, so the eight
+    // shipped labels stay byte-stable by construction rather than by test.
+    // Composition reads `axes`; only the ambiguity guard alters a label.
+    const axes = _detect_axes(composer, pkg, components_json, project_root);
+    const ambiguity = _detect_ambiguity(composer, pkg);
+    const _r = (frontend: string): StackResult =>
+        new StackResult({ frontend, mtime, axes, ambiguity });
+
+    // Conflicting signals on one axis: refuse rather than let the priority
+    // chain below silently pick a winner. Measured baseline: react + vue in
+    // one manifest resolved to `react` with no warning at all.
+    if (ambiguity.length > 0) {
+        return _r(UNSUPPORTED_STACK);
+    }
+
     if (_is_blade_livewire_flux(composer)) {
-        return new StackResult({ frontend: 'blade-livewire-flux', mtime });
+        return _r('blade-livewire-flux');
+    }
+
+    // Filament before bare Livewire: it pulls Livewire in transitively, so a
+    // Filament project would otherwise be labelled by its dependency rather
+    // than by the framework the developer actually works in.
+    if (_has_package(composer, ['require', 'require-dev'], _FILAMENT_PACKAGE)) {
+        return _r('filament');
+    }
+
+    // Livewire WITHOUT Flux is the common Laravel frontend, not an unknown
+    // one. It used to fail the `&&` above and land in `plain`.
+    if (_has_package(composer, ['require', 'require-dev'], _LIVEWIRE_PACKAGE)) {
+        return _r('blade-livewire');
     }
 
     if (_is_react_shadcn(pkg, components_json)) {
-        return new StackResult({ frontend: 'react-shadcn', mtime });
+        return _r('react-shadcn');
+    }
+
+    // React without Radix/shadcn is a served stack, not an unknown one.
+    if (_has_package(pkg, _PKG_DEP_KEYS, 'react')) {
+        return _r('react');
     }
 
     if (_has_vue(pkg)) {
-        return new StackResult({ frontend: 'vue', mtime });
+        return _r('vue');
     }
 
-    return new StackResult({ frontend: DEFAULT_STACK, mtime });
+    // A recognised-but-unmodelled framework is NOT `plain`. Refusing here is
+    // the point: `plain` means "no frontend markers", and conflating the two
+    // is what let a Svelte or Inertia project receive Tailwind-only tooling
+    // and no warning.
+    if (_has_unmodelled_marker(composer, pkg)) {
+        return _r(UNSUPPORTED_STACK);
+    }
+
+    // Monorepo: no manifest at the root, but one sits in a workspace directory.
+    // That is a wrong-scope call, not a plain project — the caller owns scope
+    // selection, so say so instead of labelling the whole repo `plain` and
+    // dispatching generic tooling at it.
+    //
+    // A repo with no manifest ANYWHERE stays `plain`: that is greenfield, and
+    // the scaffold path depends on it.
+    if (mtime === 0.0) {
+        const roots = _nested_frontend_roots(project_root);
+        if (roots.length === 1) {
+            // Unambiguous scope: descend once and keep the workspace's own
+            // axes. Refusing here would punish the common monorepo shape for a
+            // scope decision the layout already makes.
+            const inner = detect_stack(roots[0] as string);
+            return new StackResult({
+                frontend: inner.frontend,
+                mtime: inner.mtime,
+                axes: inner.axes,
+                ambiguity: inner.ambiguity,
+            });
+        }
+        if (roots.length > 1) {
+            // Several frontend roots: the caller owns scope selection, so name
+            // them and let the step ask. Picking the first would be the silent
+            // guess this detector exists to avoid.
+            return new StackResult({
+                frontend: UNSUPPORTED_STACK,
+                mtime,
+                axes,
+                ambiguity: [
+                    `workspace roots: ${roots.map((r) => path.basename(r)).join(' + ')}`,
+                ],
+            });
+        }
+    }
+
+    return _r(DEFAULT_STACK);
 }
 
 /**
@@ -130,9 +328,8 @@ export function detect_stack(project_root: string): StackResult {
  * sentinel rather than a missing-file error.
  */
 export function latest_manifest_mtime(project_root: string): number {
-    const candidates = ['composer.json', 'package.json'];
     const mtimes: number[] = [];
-    for (const name of candidates) {
+    for (const name of _CACHE_KEY_FILES) {
         const p = path.join(project_root, name);
         if (_is_file(p)) {
             mtimes.push(_stat_mtime(p));
@@ -141,6 +338,26 @@ export function latest_manifest_mtime(project_root: string): number {
     return mtimes.length > 0 ? Math.max(...mtimes) : 0.0;
 }
 
+/**
+ * Files whose mtime invalidates a cached detection.
+ *
+ * The two manifests are not sufficient: the signal table also reads marker
+ * files, so adding `components.json` or a `nuxt.config.ts` changes the detected
+ * axes while leaving both manifests untouched — and the cache would have served
+ * the pre-marker answer indefinitely.
+ *
+ * `components.json` is listed first so a shadcn adoption, the most common of
+ * these, is picked up.
+ */
+const _CACHE_KEY_FILES: ReadonlyArray<string> = [
+    'composer.json',
+    'package.json',
+    'components.json',
+    'nuxt.config.ts',
+    'nuxt.config.js',
+    'astro.config.mjs',
+];
+
 /**
  * Read a JSON manifest, returning `{}` on any error.
  *
@@ -185,6 +402,227 @@ function _all_dependencies(manifest: Manifest, ...keys: string[]): Manifest {
     return merged;
 }
 
+/** Dependency sections a `package.json` can carry. */
+const _PKG_DEP_KEYS: ReadonlyArray<string> = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+];
+
+/** True when `name` appears in any of `manifest`'s named dependency sections. */
+function _has_package(
+    manifest: Manifest,
+    sections: ReadonlyArray<string>,
+    name: string,
+): boolean {
+    return name in _all_dependencies(manifest, ...sections);
+}
+
+/**
+ * Signal table, one entry per axis value.
+ *
+ * `first match wins` applies **per axis only** — collapsing that across axes is
+ * the original defect. A Nuxt project matches `meta: nuxt` AND
+ * `reactivity: vue`; both are true, and the flat label could hold only one.
+ *
+ * Order within an axis is specificity-descending: a marker file beats a bare
+ * dependency, and a wrapper is listed before what it wraps.
+ */
+const _AXIS_SIGNALS: ReadonlyArray<{
+    readonly axis: keyof StackAxes;
+    readonly value: string;
+    readonly npm?: ReadonlyArray<string>;
+    readonly npm_prefix?: ReadonlyArray<string>;
+    readonly composer?: ReadonlyArray<string>;
+    readonly files?: ReadonlyArray<string>;
+}> = [
+    // meta — wrappers, checked before the layer they wrap
+    { axis: 'meta', value: 'nextjs', npm: ['next'] },
+    { axis: 'meta', value: 'nuxt', npm: ['nuxt'], files: ['nuxt.config.ts', 'nuxt.config.js'] },
+    { axis: 'meta', value: 'astro', npm: ['astro'], files: ['astro.config.mjs'] },
+    { axis: 'meta', value: 'remix', npm: ['@remix-run/react'] },
+    { axis: 'meta', value: 'sveltekit', npm: ['@sveltejs/kit'] },
+    { axis: 'meta', value: 'filament', composer: ['filament/filament'] },
+
+    // reactivity
+    { axis: 'reactivity', value: 'react', npm: ['react'] },
+    { axis: 'reactivity', value: 'vue', npm: ['vue'] },
+    { axis: 'reactivity', value: 'svelte', npm: ['svelte'] },
+    { axis: 'reactivity', value: 'angular', npm: ['@angular/core'] },
+    { axis: 'reactivity', value: 'solid', npm: ['solid-js'] },
+    { axis: 'reactivity', value: 'qwik', npm: ['@builder.io/qwik'] },
+    { axis: 'reactivity', value: 'livewire', composer: ['livewire/livewire'] },
+    { axis: 'reactivity', value: 'alpine', npm: ['alpinejs'] },
+    { axis: 'reactivity', value: 'htmx', npm: ['htmx.org'] },
+
+    // view
+    { axis: 'view', value: 'svelte-sfc', npm: ['svelte'] },
+    { axis: 'view', value: 'vue-sfc', npm: ['vue'] },
+    // Angular templates are HTML with its own directive syntax, not JSX.
+    // Listing it under `jsx` was wrong and would have handed a React idiom to
+    // an Angular project through the Phase-3 composition.
+    { axis: 'view', value: 'angular-html', npm: ['@angular/core'] },
+    { axis: 'view', value: 'astro', npm: ['astro'] },
+    { axis: 'view', value: 'jsx', npm: ['react'] },
+    { axis: 'view', value: 'blade', composer: ['laravel/framework'] },
+
+    // component_lib — marker file beats dependency
+    { axis: 'component_lib', value: 'shadcn', npm: ['shadcn-ui', 'shadcn'], files: ['components.json'] },
+    { axis: 'component_lib', value: 'radix', npm_prefix: ['@radix-ui/'] },
+    { axis: 'component_lib', value: 'flux', composer: ['livewire/flux'] },
+    { axis: 'component_lib', value: 'nuxt-ui', npm: ['@nuxt/ui'] },
+    { axis: 'component_lib', value: 'vuetify', npm: ['vuetify'] },
+    { axis: 'component_lib', value: 'mui', npm: ['@mui/material'] },
+
+    // css
+    { axis: 'css', value: 'tailwind', npm: ['tailwindcss'] },
+    { axis: 'css', value: 'bootstrap', npm: ['bootstrap'] },
+];
+
+/** Axes where two signals are a genuine conflict rather than a stack. */
+const _AMBIGUOUS_AXES: ReadonlyArray<keyof StackAxes> = ['reactivity'];
+
+/**
+ * Client-side SPA frameworks — two of these in one manifest is a real conflict.
+ *
+ * Everything else on the reactivity axis co-exists legitimately: Alpine and htmx
+ * are progressive-enhancement layers, and Livewire is server-driven, so
+ * Laravel+Livewire with a React widget is an ordinary stack, not an ambiguity.
+ * Treating any two reactivity signals as a conflict refused those projects —
+ * caught by the existing blade-wins-over-react precedence test.
+ */
+const _EXCLUSIVE_REACTIVITY: ReadonlySet<string> = new Set([
+    'react',
+    'vue',
+    'svelte',
+    'angular',
+    'solid',
+    'qwik',
+]);
+
+/** Resolve every axis independently from the manifests plus marker files. */
+function _detect_axes(
+    composer: Manifest,
+    pkg: Manifest,
+    components_json: boolean,
+    project_root: string,
+): StackAxes {
+    const npm = _all_dependencies(pkg, ..._PKG_DEP_KEYS);
+    const php = _all_dependencies(composer, 'require', 'require-dev');
+    const npm_names = Object.keys(npm);
+    const out: Record<string, string> = { ..._EMPTY_AXES };
+    const decided = new Set<string>();
+
+    for (const sig of _AXIS_SIGNALS) {
+        if (decided.has(sig.axis)) continue;
+        const hit =
+            (sig.npm ?? []).some((n) => n in npm) ||
+            (sig.npm_prefix ?? []).some((p) => npm_names.some((n) => n.startsWith(p))) ||
+            (sig.composer ?? []).some((n) => n in php) ||
+            (sig.files ?? []).some(
+                (f) =>
+                    (f === 'components.json' && components_json) ||
+                    _is_file(path.join(project_root, f)),
+            );
+        if (hit) {
+            out[sig.axis] = sig.value;
+            decided.add(sig.axis);
+        }
+    }
+
+    // An unresolved axis on a project that HAS manifests is "not recognised" —
+    // a different fact from "absent", and conflating them is what made a
+    // refusal indistinguishable from a genuinely plain project.
+    const has_manifest = npm_names.length > 0 || Object.keys(php).length > 0;
+    if (has_manifest) {
+        for (const axis of ['view', 'reactivity'] as const) {
+            if (!decided.has(axis)) out[axis] = 'unknown';
+        }
+    }
+    return out as unknown as StackAxes;
+}
+
+/** Report axes carrying two mutually exclusive signals. */
+function _detect_ambiguity(composer: Manifest, pkg: Manifest): string[] {
+    const npm = _all_dependencies(pkg, ..._PKG_DEP_KEYS);
+    const php = _all_dependencies(composer, 'require', 'require-dev');
+    const found: string[] = [];
+    for (const axis of _AMBIGUOUS_AXES) {
+        const hits = _AXIS_SIGNALS.filter(
+            (sig) =>
+                sig.axis === axis &&
+                ((sig.npm ?? []).some((n) => n in npm) ||
+                    (sig.composer ?? []).some((n) => n in php)),
+        )
+            .map((sig) => sig.value)
+            .filter((v) => _EXCLUSIVE_REACTIVITY.has(v));
+        if (hits.length > 1) {
+            found.push(`${axis}: ${hits.join(' + ')}`);
+        }
+    }
+    return found;
+}
+
+/** Workspace directories a monorepo conventionally puts its packages in. */
+const _WORKSPACE_DIRS: ReadonlyArray<string> = ['packages', 'apps', 'services', 'libs'];
+
+/**
+ * Return the workspace roots that carry a manifest, sorted.
+ *
+ * Reads the declarative `workspaces` field when present and falls back to the
+ * conventional directories. Deliberately shallow — one `readdir` per candidate
+ * directory, one `stat` per child.
+ *
+ * Empty means "not a monorepo". Exactly one means the scope is unambiguous and
+ * detection can descend into it. More than one is a question for the caller,
+ * not a guess for the detector.
+ */
+function _nested_frontend_roots(project_root: string): string[] {
+    const roots: string[] = [];
+    const seen = new Set<string>();
+    // `workspaces` is the declarative answer when present; the conventional
+    // directories are the fallback for repos that do not declare them.
+    const root_pkg = _read_json(path.join(project_root, 'package.json'));
+    const declared = root_pkg['workspaces'];
+    const globs: string[] = Array.isArray(declared)
+        ? (declared as unknown[]).filter((g): g is string => typeof g === 'string')
+        : [];
+    const dirs = new Set<string>(_WORKSPACE_DIRS);
+    for (const g of globs) {
+        const head = g.split('/')[0];
+        if (head !== undefined && head !== '' && !head.includes('*')) dirs.add(head);
+    }
+    for (const dir of dirs) {
+        const base = path.join(project_root, dir);
+        let entries: string[];
+        try {
+            entries = fs.readdirSync(base);
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const child = path.join(base, entry);
+            if (seen.has(child)) continue;
+            if (
+                _is_file(path.join(child, 'package.json')) ||
+                _is_file(path.join(child, 'composer.json'))
+            ) {
+                seen.add(child);
+                roots.push(child);
+            }
+        }
+    }
+    return roots.sort();
+}
+
+/** True when either manifest names a framework we recognise but do not model. */
+function _has_unmodelled_marker(composer: Manifest, pkg: Manifest): boolean {
+    const composer_deps = _all_dependencies(composer, 'require', 'require-dev');
+    const pkg_deps = _all_dependencies(pkg, ..._PKG_DEP_KEYS);
+    return _UNMODELLED_MARKERS.some((marker) => marker in composer_deps || marker in pkg_deps);
+}
+
 function _is_blade_livewire_flux(composer: Manifest): boolean {
     const deps = _all_dependencies(composer, 'require', 'require-dev');
     return _LIVEWIRE_PACKAGE in deps && _FLUX_PACKAGE in deps;

package/src/agent-src/templates/scripts/work_engine/state.ts

@@ -629,10 +629,12 @@ function _validate_app_spec(app_spec: JsonValue): void {
  * agent-directive that populates it. An empty dict is the in-progress
  * shape after the skill returns but before the brief lands; the gate
  * treats it the same as `null`. Once populated, `design_confirmed`
- * (when present) must be a bool. Other keys (`layout`, `components`,
- * `states`, `microcopy`, `a11y`, `reused_from_audit`) are
- * validated by the design handler against the skill contract — the
- * schema only enforces shape, not content.
+ * (when present) must be a bool, and `states` (when present and not
+ * `null`) must be an object — the design gate's per-state loop is
+ * object-guarded, so a string or list would bypass all five checks.
+ * The remaining keys (`layout`, `components`, `microcopy`, `a11y`,
+ * `reused_from_audit`) are validated by the design handler against the
+ * skill contract — the schema only enforces shape, not content.
  */
 function _validate_ui_design(ui_design: JsonValue): void {
     if (ui_design === null) {
@@ -652,6 +654,21 @@ function _validate_ui_design(ui_design: JsonValue): void {
             'state.ui_design.design_confirmed must be a boolean when present',
         );
     }
+    // `states` is shape-checked here, not left to the handler. The design
+    // gate's per-state loop was guarded on "is this an object", so a string or
+    // list silently skipped all five required-state checks — the gate passed
+    // while covering no state at all. Rejecting the wrong shape at the schema
+    // boundary means the loop can no longer be bypassed by type.
+    if (
+        'states' in ui_design &&
+        ui_design['states'] !== null &&
+        !_isDict(ui_design['states'])
+    ) {
+        throw new SchemaError(
+            'state.ui_design.states must be a JSON object (one key per ' +
+                `required state) or null; got ${pyTypeName(ui_design['states'])}`,
+        );
+    }
 }
 
 /**

package/src/config/discovery/packs.yml

@@ -62,6 +62,11 @@
   description: Laravel framework patterns; depends on PHP at the artefact level.
   workspaces: [engineering]
   requires: [php, engineering-base]
+  # The design layer is a companion, not a dependency: this pack ships UI
+  # executors (blade-ui, flux, livewire) whose grounded selection lives in
+  # frontend-design, but a Laravel API-only project needs none of it. Advisory
+  # so the wizard offers it; `requires` would force the weight on every install.
+  suggests: [frontend-design]
   cluster: php
   trust_level_default: professional
   domain: engineering
@@ -98,6 +103,8 @@
   description: React framework patterns.
   workspaces: [engineering]
   requires: [javascript, engineering-base]
+  # Companion, not dependency — see the note on `laravel`.
+  suggests: [frontend-design]
   cluster: typescript
   trust_level_default: professional
   domain: engineering

package/src/config/evaluator-budgets.json

@@ -8,7 +8,7 @@
         "unpacked_size_mb": {
             "max": 28,
             "last_measured": 26.05,
-            "method": "npm pack --json → dist.unpackedSize / 1e6 — includes the Phase-1 precompiled bundles (dist/hooks/dispatch.js + dist/mcp/server.mjs, ~2.1 MB) that bought the 23x hook-latency win and the tsx removal"
+            "method": "npm pack --json → dist.unpackedSize / 1e6 — includes the Phase-1 precompiled bundles (dist/hooks/dispatch.js + dist/mcp/server.mjs, ~2.1 MB) that bought the 23x hook-latency win and the tsx removal, plus dist/cli-delegate/ (~1.40 MB, ADR-204) which finished that removal for the consumer command surface. This gate is the ONLY size trip-wire on those bundles by design: a dedicated per-bundle budget key would need its own measurement wired into evaluator_umbrella.sh, and an unwired key fails check_evaluator_budgets with 'no measurement supplied' instead of guarding anything. ADR-204 projected 27.45 against max 28 without packing — the next real measurement here is the confirming one, and headroom is thin"
         },
         "node_modules_mb": {
             "max": 140,

package/src/config/pack-size-budget.json

@@ -0,0 +1,27 @@
+{
+    "_comment": "Payload budget for the published npm tarball (road-to-zero-ceremony-install Phase 4). MEASURED, NEVER INVENTED — the numbers below come from `npm pack --dry-run --json --ignore-scripts` on the tracked tree at 9.9.0 (2026-07-31). Two metrics, both genuinely ungated before this file: COMPRESSED tarball size, and PER-SKILL share of the skills subtree. The UNPACKED size is deliberately absent — it is already owned by src/config/evaluator-budgets.json (unpacked_size_mb), and a second number for one lever is how three conflicting figures start circulating.",
+    "schema_version": 1,
+    "owner": "maintainer",
+    "review_by": "2027-07-31",
+    "regression_pct": 10,
+    "measurement_conditions": "npm pack --dry-run --json --ignore-scripts, run at the repo root on a clean checkout. `--ignore-scripts` means NO build runs, so dist/cli, dist/ui, dist/mcp and dist/hooks are absent and the figure covers only the TRACKED payload (src/scripts/, dist/agent-src/, dist/install/, docs/guidelines/, templates). That is deliberate: this gate is always-on for every PR, and the tracked content tree is exactly the surface that grows by accretion. The built artifact is ~5.4 MB larger and is gated separately, at release time, by evaluator-budgets.unpacked_size_mb.",
+    "budgets": {
+        "packed_size_mb": {
+            "max": 6.4,
+            "last_measured": 5.903,
+            "method": "npm pack --dry-run --json --ignore-scripts → dist.size / 1e6 (the compressed tarball a consumer actually downloads)"
+        }
+    },
+    "per_skill_share": {
+        "max_pct": 5.0,
+        "basis": "a single skill's share of the total bytes under dist/agent-src/skills/ in the tarball",
+        "rationale": "Measured 2026-07-31: the largest non-excepted skill is corpus-grounding at 2.33%, so a 5% cap is green with better than 2x headroom and red for any skill that doubles. It is a falsifiable gate, not a ritual one.",
+        "exceptions": {
+            "design-intelligence": {
+                "max_pct": 23.0,
+                "measured_pct": 22.63,
+                "reason": "771 KB of BM25 corpus (27 CSVs + 16 design-language prose specs + manifest.json) consumed at runtime by corpus-grounding's retriever, and referenced by 6 further skills. Moving it behind a lazy fetch would add a network dependency to a skill that works offline today — the same trade-off ADR-061 §8 already REJECTED for a 745 KB font index. The exception is visible debt, not an endorsement: raising max_pct requires a reason in the same commit."
+            }
+        }
+    }
+}

package/src/install/emit_host_rules_cli.ts

@@ -21,7 +21,8 @@
  *     the Phase-1b rule filter, so scoped installs get scoped host files
  *     for free;
  *   - re-using the exported emitters keeps consumer output byte-identical
- *     to the maintainer projection (Pipeline B never drifts from A).
+ *     to the maintainer projection (the consumer install never drifts from
+ *     Pipeline A, the source projection into `dist/agent-src/`).
  * The trade-off (node required at install time) matches the rule-scope
  * resolver: no node → install.sh keeps its legacy fallback surfaces.
  *