@event4u/agent-config 9.9.0 → 9.11.0

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

@@ -17,14 +17,25 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
-import { PLACEHOLDER_PATTERNS } from './design.js';
+import { placeholder_paths } from './design.js';
+import {
+    UNSUPPORTED_LANE,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
 /** Map `state.stack.frontend` → agent-directive skill name. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-apply-blade-livewire-flux',
+    'blade-livewire': 'ui-apply-blade-livewire',
+    filament: 'ui-apply-filament',
     'react-shadcn': 'ui-apply-react-shadcn',
+    react: 'ui-apply-react',
     vue: 'ui-apply-vue',
     plain: 'ui-apply-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-apply-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -104,47 +115,36 @@ function _resolve_directive(state: DeliveryState): string {
     return DEFAULT_DIRECTIVE;
 }
 
-/** Return paths into `envelope['rendered']` whose text matches a pattern. */
+/**
+ * Return paths into `envelope['rendered']` whose text matches a pattern.
+ *
+ * Delegates to the walker shared with `design`, so the producer-side and
+ * consumer-side gates cannot drift apart. They previously held
+ * byte-identical copies of the same array-blind recursion, which meant the
+ * contract's "defense-in-depth" framing described two layers that failed on
+ * exactly the same inputs.
+ */
 function _placeholder_violations_in_output(envelope: Record<string, Any>): string[] {
-    const rendered = envelope['rendered'];
-    if (!_isDict(rendered)) {
-        return [];
-    }
-    const violations: string[] = [];
-    _walk_rendered(rendered, '', violations);
-    return violations;
-}
-
-function _walk_rendered(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_rendered(value, path, violations);
-            continue;
-        }
-        if (typeof value !== 'string') {
-            continue;
-        }
-        const lowered = value.toLowerCase();
-        for (const pattern of PLACEHOLDER_PATTERNS) {
-            if (lowered.includes(pattern)) {
-                violations.push(path);
-                break;
-            }
-        }
-    }
+    return placeholder_paths(envelope['rendered']);
 }
 
 /** First-pass halt — emit the stack-specific apply directive. */
 function _delegate_to_stack_skill(state: DeliveryState): StepResult {
     const directive = _resolve_directive(state);
     const stack_label = _stack_label(state);
+    if (stack_label === UNSUPPORTED_LANE) {
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('apply'),
+            message: 'UI apply refused: frontend framework not modelled by any lane.',
+        });
+    }
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
+            bundle_line(stack_label, 'build'),
             '> Microcopy is locked — every button label, empty-state ' +
                 'message, and validation message must come verbatim from ' +
                 '`state.ui_design.microcopy`.',

package/dist/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/dist/agent-src/templates/scripts/work_engine/directives/ui/polish.ts

@@ -15,6 +15,11 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    UNSUPPORTED_LANE,
+    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,14 @@ function _delegate_to_polish_skill(
     ceiling: number,
 ): StepResult {
     const directive = _resolve_directive(state);
+    const unsupported_label = _stack_label(state);
+    if (unsupported_label === UNSUPPORTED_LANE) {
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('polish'),
+            message: 'UI polish refused: frontend framework not modelled by any lane.',
+        });
+    }
     const stack_label = _stack_label(state);
     const next_round = rounds + 1;
     let findings_line =
@@ -203,6 +222,7 @@ function _delegate_to_polish_skill(
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Polish round ${next_round} of ${ceiling}.`,
+            bundle_line(stack_label, 'build'),
             findings_line,
             '> Fix chart-type / contrast findings against the adopted ' +
                 "corpus rows (design-intelligence § 'Grounding the " +
@@ -336,7 +356,7 @@ function _classify_token_violations(
     tokens: Record<string, Any>,
 ): [Record<string, Any>[], Record<string, Any>[]] {
     const matched: Record<string, Any>[] = [];
-    // Insertion-ordered map keyed by `${category}${value}` to mirror the
+    // Insertion-ordered map keyed by `${category}\0${value}` to mirror the
     // Python `dict[tuple[str, str], int]` insertion order.
     const unmatched_counts = new Map<string, { category: string; value: string; count: number }>();
     for (const finding of findings) {
@@ -356,7 +376,7 @@ function _classify_token_violations(
             matched.push(finding);
             continue;
         }
-        const key = `${category}${value}`;
+        const key = `${category}\0${value}`;
         const existing = unmatched_counts.get(key);
         if (existing) {
             existing.count += 1;

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

@@ -16,13 +16,24 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    UNSUPPORTED_LANE,
+    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,20 @@ 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 (stack_label === UNSUPPORTED_LANE) {
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('review'),
+            message: 'UI review refused: frontend framework not modelled by any lane.',
+        });
+    }
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Reviewing rendered components ` +
                 'against the locked design brief.',
+            bundle_line(stack_label, 'review'),
             '> The review pass compares `state.ticket.ui_apply.rendered` ' +
                 'against `state.ui_design` (microcopy, states, a11y, layout) ' +
                 'and produces a structured `findings` list.',
@@ -294,7 +313,7 @@ function _filter_known(violations: Any[], known: Any[]): Any[] {
  * scalars, mirroring Python tuple-equality in a JS `Set`.
  */
 function _keyOf(rule: Any, selector: Any): string {
-    return `${_tag(rule)}${_tag(selector)}`;
+    return `${_tag(rule)}\0${_tag(selector)}`;
 }
 
 function _tag(v: Any): string {

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

@@ -0,0 +1,179 @@
+/**
+ * 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 pack-agnostic pair. Both live in `engineering-base`, so they are present
+ * in every install; both self-describe as stack-neutral
+ * (`ui-component-architect`: "the same lens applies to Blade, Livewire, React,
+ * or Vue trees"; `tailwind-engineer`: "the **how** for any Tailwind-stack
+ * screen"). This is the honest floor for a lane with no framework-specific
+ * executor — not a claim that the lane is fully served.
+ */
+const GENERIC_BUILD: ReadonlyArray<string> = ['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>> = {
+    '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']);
+
+/** 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 `stack`, or the `plain` bundle when unmapped. */
+export function bundle_for(stack: string): StackBundle {
+    return STACK_BUNDLES[stack] ?? (STACK_BUNDLES['plain'] as StackBundle);
+}
+
+/**
+ * Questions for the refusal halt on an unmodelled framework.
+ *
+ * Not a directive — there is nothing honest to dispatch to. The agent names
+ * the actual markers from the manifest (it has filesystem access; the engine
+ * deliberately does not carry them on `StackResult`), and the user chooses
+ * between the stack-neutral floor and stopping.
+ */
+export function unsupported_stack_questions(step: string): string[] {
+    return [
+        '> Detection found a frontend framework this package does not model, ' +
+            `so there is no \`${step}\` lane for it.`,
+        '> Name the markers you see in `composer.json` / `package.json` so the ' +
+            'choice below is made on the real stack, not on a guess.',
+        '> 1. Continue on the stack-neutral floor — `ui-component-architect` + ' +
+            '`tailwind-engineer`. Output will not be idiomatic for this ' +
+            'framework; say so in the result.',
+        '> 2. Abort — drop this UI request and add a lane first ' +
+            '(`docs/contracts/ui-stack-extension.md`).',
+    ];
+}
+
+/**
+ * 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: string, role: 'build' | 'review'): string {
+    const bundle = bundle_for(stack);
+    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}.`;
+}