@event4u/agent-config 9.10.0 → 9.12.0

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

@@ -146,7 +146,17 @@ function _missing_required_keys(design: Record<string, Any>): string[] {
             missing.push(key);
             continue;
         }
-        if (key === 'states' && _isDict(value)) {
+        if (key === 'states') {
+            // A non-object `states` (a string, a list) used to skip the
+            // per-state loop entirely, so `states: "n/a"` satisfied the gate
+            // without covering a single state. Report every required key
+            // instead — the author gets the same actionable list either way.
+            if (!_isDict(value)) {
+                for (const state_key of REQUIRED_STATE_KEYS) {
+                    missing.push(`states.${state_key}`);
+                }
+                continue;
+            }
             for (const state_key of REQUIRED_STATE_KEYS) {
                 if (!_pyTruthy(value[state_key])) {
                     missing.push(`states.${state_key}`);
@@ -157,37 +167,74 @@ function _missing_required_keys(design: Record<string, Any>): string[] {
     return missing;
 }
 
-/** Return microcopy paths whose values match a placeholder pattern. */
+/**
+ * Return brief paths whose values match a placeholder pattern.
+ *
+ * Covers `microcopy` **and** `states`. The five required states were checked
+ * for truthiness only, so `states.error: "TBD"` satisfied the gate — the brief
+ * looked complete while covering nothing. Both slots carry strings the user
+ * signs off on, so both are held to the same bar.
+ *
+ * An explicit `"n/a"` stays legitimate: a static landing page genuinely has no
+ * error or disabled state, and *declaring* that is the opposite of inventing
+ * filler. That is why the gate demands all five keys rather than branching on
+ * page type — the author states the answer instead of the engine guessing which
+ * states a surface ought to have.
+ */
 function _placeholder_violations(design: Record<string, Any>): string[] {
-    const microcopy = design['microcopy'];
-    if (!_isDict(microcopy)) return [];
+    return [
+        ...placeholder_paths(design['microcopy'], 'microcopy'),
+        ...placeholder_paths(design['states'], 'states'),
+    ];
+}
+
+/**
+ * Return every path under `node` whose leaf string carries a placeholder.
+ *
+ * Traverses objects **and arrays**. The array arm is load-bearing, not
+ * defensive: a list is the natural shape for the most common microcopy
+ * (`nav_items`, `menu`, `steps`) and for a rendered file split into lines,
+ * and a walker that recursed into objects only let
+ * `{ nav_items: ["Home", "TODO: Link"] }` through both the brief lock and
+ * the rendered-output gate.
+ *
+ * Array elements are addressed `key[i]` so the halt names the exact element
+ * the author has to fix, not just the list.
+ *
+ * Shared by `design` (producer side, on `microcopy`) and `apply` (consumer
+ * side, on the rendered envelope). One implementation on purpose: the two
+ * call sites previously carried byte-identical copies of the same bug, so
+ * duplicating them bought no independence — see
+ * `docs/contracts/ui-track-flow.md` § implement → apply.
+ */
+export function placeholder_paths(node: Any, prefix = ''): string[] {
     const violations: string[] = [];
-    _walk_microcopy(microcopy, '', violations);
+    _walk_placeholders(node, prefix, violations);
     return violations;
 }
 
-function _walk_microcopy(
-    node: Record<string, Any>,
-    prefix: string,
-    violations: string[],
-): void {
-    for (const key of Object.keys(node)) {
-        const value = node[key];
-        const path = prefix ? `${prefix}.${key}` : String(key);
-        if (_isDict(value)) {
-            _walk_microcopy(value, path, violations);
-            continue;
-        }
-        if (typeof value !== 'string') {
-            continue;
-        }
-        const lowered = value.toLowerCase();
+function _walk_placeholders(node: Any, prefix: string, violations: string[]): void {
+    if (typeof node === 'string') {
+        const lowered = node.toLowerCase();
         for (const pattern of PLACEHOLDER_PATTERNS) {
             if (lowered.includes(pattern)) {
-                violations.push(path);
-                break;
+                violations.push(prefix);
+                return;
             }
         }
+        return;
+    }
+    if (Array.isArray(node)) {
+        node.forEach((value, index) => {
+            _walk_placeholders(value, `${prefix}[${index}]`, violations);
+        });
+        return;
+    }
+    if (_isDict(node)) {
+        for (const key of Object.keys(node)) {
+            const path = prefix ? `${prefix}.${key}` : String(key);
+            _walk_placeholders(node[key], path, violations);
+        }
     }
 }
 
@@ -311,15 +358,23 @@ function _halt_unconfirmed(state: DeliveryState, design: Record<string, Any>): S
     });
 }
 
-/** Count leaf string entries in `microcopy` (recursive). */
-function _count_microcopy(microcopy: Record<string, Any>): number {
-    let total = 0;
-    for (const value of Object.values(microcopy)) {
-        if (_isDict(value)) {
-            total += _count_microcopy(value);
-        } else if (typeof value === 'string') {
-            total += 1;
-        }
+/**
+ * Count leaf string entries in `microcopy` (recursive, arrays included).
+ *
+ * The count is shown in the sign-off the user confirms, so it has to agree
+ * with what the placeholder walker inspects — an object-only count reported
+ * fewer locked strings than were actually locked.
+ */
+function _count_microcopy(microcopy: Any): number {
+    if (typeof microcopy === 'string') return 1;
+    if (Array.isArray(microcopy)) {
+        return microcopy.reduce((total: number, value) => total + _count_microcopy(value), 0);
+    }
+    if (_isDict(microcopy)) {
+        return Object.values(microcopy).reduce(
+            (total: number, value) => total + _count_microcopy(value),
+            0,
+        );
     }
-    return total;
+    return 0;
 }

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

@@ -15,6 +15,11 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    is_ambiguous_stack,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
 /** Maximum number of polish rounds per `/work` run. */
 export const POLISH_CEILING = 2;
@@ -31,9 +36,15 @@ export const TOKEN_REPEAT_THRESHOLD = 2;
 /** Map `state.stack.frontend` → agent-directive skill name. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-polish-blade-livewire-flux',
+    'blade-livewire': 'ui-polish-blade-livewire',
+    filament: 'ui-polish-filament',
     'react-shadcn': 'ui-polish-react-shadcn',
+    react: 'ui-polish-react',
     vue: 'ui-polish-vue',
     plain: 'ui-polish-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-polish-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -184,6 +195,17 @@ function _delegate_to_polish_skill(
     ceiling: number,
 ): StepResult {
     const directive = _resolve_directive(state);
+    if (is_ambiguous_stack(state.stack)) {
+        const conflicts = ((state.stack as Record<string, Any>)['ambiguity'] ??
+            []) as ReadonlyArray<string>;
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('polish', conflicts),
+            message:
+                `UI polish halted: detection is ambiguous (${conflicts.join('; ')}) — ` +
+                'the open question is which project to build for.',
+        });
+    }
     const stack_label = _stack_label(state);
     const next_round = rounds + 1;
     let findings_line =
@@ -203,6 +225,7 @@ function _delegate_to_polish_skill(
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Polish round ${next_round} of ${ceiling}.`,
+            bundle_line(state.stack, 'build', stack_label),
             findings_line,
             '> Fix chart-type / contrast findings against the adopted ' +
                 "corpus rows (design-intelligence § 'Grounding the " +

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

@@ -16,13 +16,24 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    is_ambiguous_stack,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
-/** Map `state.stack.frontend` → agent-directive skill name. */
+/** Map `state.stack.frontend` → agent-directive verb. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-design-review-blade-livewire-flux',
+    'blade-livewire': 'ui-design-review-blade-livewire',
+    filament: 'ui-design-review-filament',
     'react-shadcn': 'ui-design-review-react-shadcn',
+    react: 'ui-design-review-react',
     vue: 'ui-design-review-vue',
     plain: 'ui-design-review-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-design-review-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -181,12 +192,24 @@ function _stack_label(state: DeliveryState): string {
 function _delegate_to_review_skill(state: DeliveryState): StepResult {
     const directive = _resolve_directive(state);
     const stack_label = _stack_label(state);
+    if (is_ambiguous_stack(state.stack)) {
+        const conflicts = ((state.stack as Record<string, Any>)['ambiguity'] ??
+            []) as ReadonlyArray<string>;
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('review', conflicts),
+            message:
+                `UI review halted: detection is ambiguous (${conflicts.join('; ')}) — ` +
+                'the open question is which project to build for.',
+        });
+    }
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Reviewing rendered components ` +
                 'against the locked design brief.',
+            bundle_line(state.stack, 'review', stack_label),
             '> The review pass compares `state.ticket.ui_apply.rendered` ' +
                 'against `state.ui_design` (microcopy, states, a11y, layout) ' +
                 'and produces a structured `findings` list.',

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

@@ -0,0 +1,332 @@
+/**
+ * Verb → skill-bundle map for the stack-dispatched UI steps.
+ *
+ * The UI steps halt with `@agent-directive: ui-apply-<stack>` (and the
+ * `ui-design-review-` / `ui-polish-` equivalents). Those names are **directive
+ * verbs, not skill paths** — the same shape as `run-tests`, `create-plan`, and
+ * `apply-plan`, which likewise resolve to no skill file. Only 2 of the engine's
+ * 11 literal verbs name a real skill, so a verb is something the agent
+ * interprets, and the mapping from verb to the skills that implement it is a
+ * separate fact that has to be written down somewhere.
+ *
+ * Before this module that mapping lived only in a prose table in
+ * `docs/contracts/ui-track-flow.md`. Nothing verified it, and two of its four
+ * rows were wrong: `vue` pointed at the directive verb itself (naming no skill
+ * at all) and `plain` — which is also the fallback for every unrecognised
+ * project — pointed at `blade-ui`, a skill whose frontmatter is
+ * `packs: [laravel]` and which a non-Laravel consumer therefore does not have
+ * installed.
+ *
+ * Keeping the map here makes it checkable: `lint_ui_stack_bundles` asserts every
+ * member resolves to a real skill, and that no lane reachable without the
+ * `laravel` pack names a `laravel`-only skill. A CI check in this repo cannot
+ * see a consumer's installed pack combination, so the second assertion is the
+ * part that actually prevents the `plain → blade-ui` class of defect.
+ */
+
+/** Skills that implement a lane, in the order the agent should load them. */
+export interface StackBundle {
+    /** Skills that build / fix UI for this lane (`apply`, `polish`). */
+    readonly build: ReadonlyArray<string>;
+    /** Skills that review UI for this lane (`review`). */
+    readonly review: ReadonlyArray<string>;
+    /**
+     * True when every skill above ships outside the framework packs, i.e. the
+     * lane is safe as a fallback for a consumer whose packs we cannot predict.
+     * Only lanes marked `pack_agnostic` may be used as `DEFAULT_*`.
+     */
+    readonly pack_agnostic: boolean;
+}
+
+/**
+ * The stack-neutral build bundle. All three live in `engineering-base`, so they
+ * are present in every install.
+ *
+ * `ui-apply-generic` leads: it carries the implementation contract that used to
+ * exist only inside the framework executors, and it pulls framework idiom from
+ * the 16-stack corpus rather than from prose. That is what turns this lane from
+ * an honest refusal into actual coverage for Svelte, Astro, Angular and
+ * anything future — without minting a skill per framework.
+ *
+ * The other two are the companions it composes with: `ui-component-architect`
+ * ("the same lens applies to Blade, Livewire, React, or Vue trees") and
+ * `tailwind-engineer` ("the **how** for any Tailwind-stack screen").
+ */
+const GENERIC_BUILD: ReadonlyArray<string> = [
+    'ui-apply-generic',
+    'ui-component-architect',
+    'tailwind-engineer',
+];
+
+/** `design-review` is stack-neutral and ships in `engineering-base`. */
+const GENERIC_REVIEW: ReadonlyArray<string> = ['design-review'];
+
+/**
+ * Lane → bundle. Keys mirror `KNOWN_STACKS`; the dispatch tables in
+ * `apply` / `review` / `polish` keep their own verb strings (a tested public
+ * contract) and consume this map only to name the skills in the halt body.
+ */
+export const STACK_BUNDLES: Readonly<Record<string, StackBundle>> = {
+    // An unmodelled framework routes to the generic lane rather than refusing:
+    // `ui-apply-generic` queries the stack corpus, which covers svelte, astro,
+    // angular, nuxt and eleven more. Refusing while holding that corpus is the
+    // "an honest refusal is not coverage" defect. A genuine ambiguity still
+    // refuses — see `is_ambiguous_stack`.
+    unknown: {
+        build: GENERIC_BUILD,
+        review: GENERIC_REVIEW,
+        pack_agnostic: true,
+    },
+    'blade-livewire-flux': {
+        build: ['flux', 'livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // Livewire without Flux — the common Laravel frontend. Previously fell
+    // into `plain` because detection required Livewire AND Flux.
+    'blade-livewire': {
+        build: ['livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // Filament is Livewire + Blade + Tailwind under the hood; the same
+    // executors apply. A Filament-specific skill is gated on evidence that
+    // these produce unusable output for it, not assumed.
+    filament: {
+        build: ['livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    'react-shadcn': {
+        build: ['react-shadcn-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // React without Radix/shadcn. `react-shadcn-ui` still carries the React
+    // component idiom; the shadcn-specific parts simply do not apply.
+    react: {
+        build: ['react-shadcn-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // No Vue executor exists. The previous prose row pointed at the directive
+    // verb itself, which named nothing; the generic pair is a smaller lie and a
+    // stated one — the halt body says the lane has no Vue-specific skill.
+    vue: {
+        build: GENERIC_BUILD,
+        review: GENERIC_REVIEW,
+        pack_agnostic: true,
+    },
+    plain: {
+        build: GENERIC_BUILD,
+        review: GENERIC_REVIEW,
+        pack_agnostic: true,
+    },
+};
+
+/**
+ * Lanes served by the stack-neutral pair rather than a framework executor.
+ *
+ * `plain` and `vue` share the bundle but not the meaning, and the halt body has
+ * to say which it is. For `plain` the pair IS the right answer — there is no
+ * framework to be idiomatic about. For `vue` it is a gap: a Vue project has a
+ * definite idiom and the package has no executor for it, so the result must not
+ * read as Vue support.
+ */
+export const GENERIC_LANES: ReadonlySet<string> = new Set(['vue', 'plain', 'unknown']);
+
+/** Lanes where the stack-neutral pair is the correct answer, not a shortfall. */
+const NATIVELY_GENERIC_LANES: ReadonlySet<string> = new Set(['plain']);
+
+/**
+ * The label detection returns for a framework it recognises but does not
+ * model. Mirrors `stack/detect.ts::UNSUPPORTED_STACK`; duplicated as a literal
+ * because this module is import-free by design (the detector is a leaf module
+ * the directives must not depend on).
+ */
+export const UNSUPPORTED_LANE = 'unknown';
+
+/**
+ * Return the bundle for a stack state.
+ *
+ * Composition wins when the state carries axes; the hand-written map is the
+ * fallback for a legacy `state.stack` persisted before Detection v2. Keeping
+ * both is not indecision — a state file written by an older run must still
+ * dispatch, and the map is exactly what it expects.
+ */
+export function bundle_for(stack_state: unknown): StackBundle {
+    if (typeof stack_state === 'object' && stack_state !== null) {
+        const raw = (stack_state as Record<string, unknown>)['axes'];
+        if (typeof raw === 'object' && raw !== null) {
+            return compose_bundle(raw as Record<string, string>);
+        }
+        const label = (stack_state as Record<string, unknown>)['frontend'];
+        if (typeof label === 'string' && label in STACK_BUNDLES) {
+            return STACK_BUNDLES[label] as StackBundle;
+        }
+    }
+    if (typeof stack_state === 'string' && stack_state in STACK_BUNDLES) {
+        return STACK_BUNDLES[stack_state] as StackBundle;
+    }
+    return STACK_BUNDLES['plain'] as StackBundle;
+}
+
+/**
+ * True when the `unknown` label came from a question, not from a coverage gap.
+ *
+ * `unknown` carries two different situations and they need opposite handling:
+ *
+ * - **An unmodelled framework** (svelte, astro, angular …). Since
+ *   `ui-apply-generic` exists and queries the stack corpus, refusing here would
+ *   be the "an honest refusal is not coverage" defect — the corpus almost
+ *   certainly HAS the stack. Route to the generic lane, naming the framework.
+ * - **A genuine ambiguity** — two SPA frameworks in one manifest, or several
+ *   workspace roots. No executor can fix that: the open question is *which
+ *   project is this*, and only the caller can answer. Refuse.
+ *
+ * `StackResult.ambiguity` is what distinguishes them, so the check is on the
+ * ambiguity list rather than on the label.
+ */
+export function is_ambiguous_stack(stack_state: unknown): boolean {
+    if (typeof stack_state !== 'object' || stack_state === null) return false;
+    const raw = (stack_state as Record<string, unknown>)['ambiguity'];
+    return Array.isArray(raw) && raw.length > 0;
+}
+
+/**
+ * Questions for the refusal halt when detection cannot say what the project is.
+ *
+ * Not a directive — there is nothing honest to dispatch to, because the missing
+ * input is a decision rather than a skill. `conflicts` are echoed verbatim from
+ * `StackResult.ambiguity` so the user sees the actual collision.
+ */
+export function unsupported_stack_questions(
+    step: string,
+    conflicts: ReadonlyArray<string> = [],
+): string[] {
+    const lines = [
+        '> Detection found conflicting signals, so it will not pick a stack for ' +
+            `you at \`${step}\`. Guessing here is the failure this halt exists ` +
+            'to prevent.',
+    ];
+    for (const c of conflicts) {
+        lines.push(`> - \`${c}\``);
+    }
+    lines.push(
+        '> 1. Name the project to build for — the workspace path, or which ' +
+            'framework owns this surface. Detection re-runs against that scope.',
+        '> 2. Continue on the stack-neutral floor anyway — `ui-apply-generic` ' +
+            'plus its companions. Output will not be idiomatic for either ' +
+            'framework; say so in the result.',
+        '> 3. Abort — drop this UI request.',
+    );
+    return lines;
+}
+
+/**
+ * Render the "load these skills" line for a dispatch halt.
+ *
+ * The engine cannot load a skill itself; naming the bundle is what stops the
+ * agent from resolving an unresolvable verb by guessing. A lane with no
+ * framework-specific executor says that outright rather than presenting the
+ * generic pair as if it were stack support.
+ */
+export function bundle_line(
+    stack_state: unknown,
+    role: 'build' | 'review',
+    stack_label?: string,
+): string {
+    const bundle = bundle_for(stack_state);
+    const stack =
+        stack_label ??
+        (typeof stack_state === 'string'
+            ? stack_state
+            : String(
+                  (stack_state as Record<string, unknown> | null)?.['frontend'] ?? 'plain',
+              ));
+    const skills = role === 'review' ? bundle.review : bundle.build;
+    const rendered = skills.map((name) => `\`${name}\``).join(' + ');
+    if (NATIVELY_GENERIC_LANES.has(stack)) {
+        return `> Skills: ${rendered} — stack-neutral, which is what \`${stack}\` means.`;
+    }
+    if (GENERIC_LANES.has(stack)) {
+        return (
+            `> Skills: ${rendered} — there is no \`${stack}\`-specific executor, ` +
+            'so this is the stack-neutral floor, not idiomatic ' +
+            `\`${stack}\`. Say so in the result.`
+        );
+    }
+    return `> Skills: ${rendered}.`;
+}
+
+// ── Axis-driven composition ─────────────────────────────────────────────────
+
+/**
+ * Overlay table: one axis value → the skills that add its idiom.
+ *
+ * This is what replaces lane enumeration. A lane is no longer a hand-written
+ * bundle but the base plus whatever the axes turn on, so a stack the package has
+ * never named still composes: `reactivity: livewire` pulls Livewire **with or
+ * without** Flux, and `component_lib: flux` layers Flux on top. The two
+ * full-match lanes fall out as a special case — that identity is the regression
+ * witness, asserted in `ui_lane_matrix.test.ts`.
+ *
+ * Only axis values with a real overlay skill appear. Everything else is served
+ * by the base plus its corpus query, which is the point: coverage without a
+ * skill per framework.
+ */
+const _AXIS_OVERLAYS: Readonly<Record<string, ReadonlyArray<string>>> = {
+    'reactivity:livewire': ['livewire'],
+    'reactivity:react': ['react-shadcn-ui'],
+    'component_lib:flux': ['flux'],
+    'component_lib:shadcn': ['react-shadcn-ui'],
+    'component_lib:radix': ['react-shadcn-ui'],
+    'view:blade': ['blade-ui'],
+    'meta:filament': ['livewire', 'blade-ui'],
+};
+
+/** Axes consulted for overlays, most-specific first. */
+const _OVERLAY_AXES: ReadonlyArray<string> = [
+    'component_lib',
+    'meta',
+    'reactivity',
+    'view',
+];
+
+/** Skill → the pack it ships in, for the pack-agnostic determination. */
+const _FRAMEWORK_PACK_SKILLS: ReadonlySet<string> = new Set([
+    'livewire',
+    'flux',
+    'blade-ui',
+    'react-shadcn-ui',
+]);
+
+/**
+ * Derive a bundle from detected axes.
+ *
+ * Order is deliberate and matches the hand-written lanes: overlays first
+ * (most-specific axis first), base last. An overlay carries framework idiom the
+ * base cannot, so it must be read before the generic contract's fallbacks.
+ *
+ * `pack_agnostic` is computed, not declared: a composition that pulled in any
+ * framework-pack skill is not safe as a fallback, and computing it removes the
+ * chance of a hand-written `true` outliving the bundle it described.
+ */
+export function compose_bundle(axes: Readonly<Record<string, string>>): StackBundle {
+    const build: string[] = [];
+    for (const axis of _OVERLAY_AXES) {
+        const value = axes[axis];
+        if (value === undefined || value === 'none' || value === 'unknown') continue;
+        for (const skill of _AXIS_OVERLAYS[`${axis}:${value}`] ?? []) {
+            if (!build.includes(skill)) build.push(skill);
+        }
+    }
+    for (const skill of GENERIC_BUILD) {
+        if (!build.includes(skill)) build.push(skill);
+    }
+    return {
+        build,
+        review: GENERIC_REVIEW,
+        pack_agnostic: !build.some((s) => _FRAMEWORK_PACK_SKILLS.has(s)),
+    };
+}