@event4u/agent-config 9.11.0 → 9.13.0

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

@@ -44,6 +44,33 @@ export const PLACEHOLDER_PATTERNS: ReadonlyArray<string> = [
     'xxx',
 ];
 
+/**
+ * Optional brief key carrying a user-supplied design artifact.
+ *
+ * The brief's five required keys are a lossy projection of a finished
+ * artifact: `layout` is prose, not a spacing scale, and there is no slot at
+ * all for easing, hover behaviour, handlers, or assets. Before this key the
+ * pipeline had no channel for a handed-over design, so it rebuilt one from
+ * the five-key abstraction and said nothing about the difference. This slot
+ * is that channel — one more input to the same step, never a parallel track.
+ */
+export const PROVIDED_ARTIFACT_KEY = 'provided_artifact';
+
+/**
+ * What the five-key brief cannot carry from a provided artifact.
+ *
+ * Stated to the user **before** any regeneration, not discovered afterwards.
+ * A supplied `design-system.json` closes the first two; the rest are closed
+ * only by the coverage report `apply` demands.
+ */
+export const UNCARRIED_BY_THE_BRIEF: ReadonlyArray<string> = [
+    'exact spacing values — `layout` is prose, not a scale',
+    'easing curves and animation timing',
+    'hover / focus / active behaviour',
+    'event handlers and the interactions they drive',
+    'the asset manifest (images, icons, fonts the artifact references)',
+];
+
 export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
     {
         code: 'design_missing',
@@ -61,6 +88,17 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
             'agent re-runs the brief with final strings; ' +
             'halt lists the offending microcopy keys',
     },
+    {
+        code: 'design_provided_without_contract',
+        trigger:
+            'state.ui_design.provided_artifact is set but carries no ' +
+            'design_system, and the loss has not been acknowledged — the ' +
+            'brief would silently regenerate what it cannot carry',
+        resolution:
+            'user supplies a design-system.json (honoured verbatim), or ' +
+            'acknowledges the named losses so the port proceeds with them ' +
+            'stated up front',
+    },
     {
         code: 'design_unconfirmed',
         trigger: 'brief is well-formed but design_confirmed is unset/False',
@@ -123,6 +161,11 @@ export function run(state: DeliveryState): StepResult {
         return _halt_placeholders(state, placeholders);
     }
 
+    const provided = provided_artifact(designDict);
+    if (provided !== null && !_contract_or_loss_acknowledged(provided)) {
+        return _halt_provided_without_contract(state, provided);
+    }
+
     if (designDict['design_confirmed'] === true) {
         return new StepResult({ outcome: Outcome.SUCCESS });
     }
@@ -238,6 +281,81 @@ function _walk_placeholders(node: Any, prefix: string, violations: string[]): vo
     }
 }
 
+/**
+ * Return the supplied-artifact envelope, or `null` when none was handed over.
+ *
+ * Exported because `apply` needs the same answer — the coverage report it
+ * demands exists only for a port, and a second copy of "is this a port?"
+ * would be the drift this package has paid for before (see the shared
+ * `placeholder_paths` walker above).
+ */
+export function provided_artifact(
+    design: Record<string, Any> | null | undefined,
+): Record<string, Any> | null {
+    if (!_isDict(design)) return null;
+    const provided = design[PROVIDED_ARTIFACT_KEY];
+    if (!_isDict(provided) || Object.keys(provided).length === 0) return null;
+    return provided;
+}
+
+/** True when a machine-readable contract came with the artifact. */
+export function has_design_system(provided: Record<string, Any>): boolean {
+    return _isDict(provided['design_system']) && _pyTruthy(provided['design_system']);
+}
+
+/** The port may proceed: either a contract exists, or the losses were stated and accepted. */
+function _contract_or_loss_acknowledged(provided: Record<string, Any>): boolean {
+    return has_design_system(provided) || provided['loss_acknowledged'] === true;
+}
+
+/**
+ * BLOCKED halt — an artifact was handed over with no contract behind it.
+ *
+ * This is the honest-refusal branch. The pipeline *can* rebuild the artifact
+ * from the five-key brief; what it must not do is rebuild it silently. The
+ * halt names every value the brief cannot carry, then asks. Answering
+ * option 1 sets `loss_acknowledged` and the same losses are on the record.
+ */
+function _halt_provided_without_contract(
+    state: DeliveryState,
+    provided: Record<string, Any>,
+): StepResult {
+    const preview = _preview_input(state);
+    const ref = typeof provided['path'] === 'string' && provided['path'] !== ''
+        ? String(provided['path'])
+        : 'the provided artifact';
+    const lines: string[] = [
+        `> Input: ${preview}`,
+        `> \`${ref}\` is a finished design handed over as the spec, and no ` +
+            '`design-system.json` came with it. The design brief carries five ' +
+            'keys (layout, components, states, microcopy, a11y) — everything ' +
+            'below is outside them and would be rebuilt from taste rather than ' +
+            'read from your artifact:',
+    ];
+    for (const loss of UNCARRIED_BY_THE_BRIEF) {
+        lines.push(`> - ${loss}`);
+    }
+    lines.push(
+        '> 1. Proceed — port it with those five losses on the record; `apply` ' +
+            'still has to report what it honoured, translated, and flagged',
+        '> 2. Supply a `design-system.json` — its token values are then ' +
+            'honoured verbatim instead of re-derived',
+        '> 3. Abort — drop this UI request',
+        '',
+        '**Recommendation: 2 — Supply the contract** — it is the only option ' +
+            'that closes the spacing and easing losses at the source. Caveat: ' +
+            'pick 1 when no extractor is available; the port then proceeds with ' +
+            'the gap stated rather than hidden.',
+    );
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message:
+            'UI design halted: a provided artifact carries no design-system.json; ' +
+            `${UNCARRIED_BY_THE_BRIEF.length} value class(es) cannot be carried by the brief.`,
+    });
+}
+
 /** Render a one-line preview of the input being designed. */
 function _preview_input(state: DeliveryState): string {
     const data = (_isDict(state.ticket) ? state.ticket : {}) as Record<string, Any>;

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

@@ -16,7 +16,7 @@ import {
     agent_directive,
 } from '../../delivery_state.js';
 import {
-    UNSUPPORTED_LANE,
+    is_ambiguous_stack,
     bundle_line,
     unsupported_stack_questions,
 } from './stack_bundles.js';
@@ -116,6 +116,41 @@ function _pyTruthy(value: Any): boolean {
     return true;
 }
 
+/**
+ * Findings the provided artifact already answers — informational, never
+ * fix-worthy.
+ *
+ * A port carries its source's aesthetic on purpose. Left unfiltered, a
+ * finding like "cream palette reads as scaffold-default" is indistinguishable
+ * from a real defect, so the polish loop spends a round editing the port away
+ * from the spec the user approved — the exact regression `daf-slop-vs-provided`
+ * witnesses. Marking the finding rather than deleting it keeps it visible in
+ * the review output; what changes is that it no longer drives a round.
+ *
+ * Scope is strict, and the burden sits with the marker: only a decision the
+ * artifact **actually covers** may carry the flag. Generative work in the same
+ * run is not artifact-covered and stays fully subject to the anti-slop scan.
+ */
+export const ARTIFACT_COVERED_KEY = 'artifact_covered';
+
+/** True when this finding is answered by the provided artifact. */
+function _is_artifact_covered(finding: Any): boolean {
+    return _isDict(finding) && finding[ARTIFACT_COVERED_KEY] === true;
+}
+
+/** Split findings into the ones that drive rounds and the informational rest. */
+export function partition_artifact_covered(findings: ReadonlyArray<Any>): {
+    actionable: Any[];
+    informational: Any[];
+} {
+    const actionable: Any[] = [];
+    const informational: Any[] = [];
+    for (const finding of findings) {
+        (_is_artifact_covered(finding) ? informational : actionable).push(finding);
+    }
+    return { actionable, informational };
+}
+
 /** Apply the polish-loop gate. */
 export function run(state: DeliveryState): StepResult {
     const review = _pyTruthy(state.ui_review) ? (state.ui_review as Record<string, Any>) : {};
@@ -125,6 +160,11 @@ export function run(state: DeliveryState): StepResult {
     }
     const review_clean = _pyTruthy(review['review_clean']);
 
+    // Artifact-covered findings are dropped from the round-driving set before
+    // anything else reads it — including the ceiling check, so a port cannot
+    // burn its two rounds on findings it was never allowed to act on.
+    findings = partition_artifact_covered(findings as Any[]).actionable;
+
     if (review_clean || (findings as Any[]).length === 0) {
         return new StepResult({ outcome: Outcome.SUCCESS });
     }
@@ -195,12 +235,15 @@ function _delegate_to_polish_skill(
     ceiling: number,
 ): StepResult {
     const directive = _resolve_directive(state);
-    const unsupported_label = _stack_label(state);
-    if (unsupported_label === UNSUPPORTED_LANE) {
+    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'),
-            message: 'UI polish refused: frontend framework not modelled by any lane.',
+            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);
@@ -222,7 +265,7 @@ function _delegate_to_polish_skill(
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Polish round ${next_round} of ${ceiling}.`,
-            bundle_line(stack_label, 'build'),
+            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

@@ -17,7 +17,7 @@ import {
     agent_directive,
 } from '../../delivery_state.js';
 import {
-    UNSUPPORTED_LANE,
+    is_ambiguous_stack,
     bundle_line,
     unsupported_stack_questions,
 } from './stack_bundles.js';
@@ -192,11 +192,15 @@ 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) {
+    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'),
-            message: 'UI review refused: frontend framework not modelled by any lane.',
+            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({
@@ -205,7 +209,7 @@ function _delegate_to_review_skill(state: DeliveryState): StepResult {
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Reviewing rendered components ` +
                 'against the locked design brief.',
-            bundle_line(stack_label, 'review'),
+            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

@@ -39,14 +39,24 @@ export interface StackBundle {
 }
 
 /**
- * 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.
+ * 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-component-architect', 'tailwind-engineer'];
+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'];
@@ -57,6 +67,16 @@ const GENERIC_REVIEW: ReadonlyArray<string> = ['design-review'];
  * 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,
@@ -113,7 +133,7 @@ export const STACK_BUNDLES: Readonly<Record<string, StackBundle>> = {
  * 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']);
+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']);
@@ -126,31 +146,81 @@ const NATIVELY_GENERIC_LANES: ReadonlySet<string> = new Set(['plain']);
  */
 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);
+/**
+ * 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 on an unmodelled framework.
+ * Questions for the refusal halt when detection cannot say what the project is.
  *
- * 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.
+ * 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): 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`).',
+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;
 }
 
 /**
@@ -161,8 +231,19 @@ export function unsupported_stack_questions(step: string): string[] {
  * 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);
+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)) {
@@ -177,3 +258,75 @@ export function bundle_line(stack: string, role: 'build' | 'review'): string {
     }
     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)),
+    };
+}