@event4u/agent-config 9.12.0 → 9.14.0

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

@@ -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 });
     }

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

@@ -669,6 +669,61 @@ function _validate_ui_design(ui_design: JsonValue): void {
                 `required state) or null; got ${pyTypeName(ui_design['states'])}`,
         );
     }
+    _validate_provided_artifact(ui_design['provided_artifact']);
+}
+
+/**
+ * Reject a malformed `ui_design.provided_artifact` envelope; tolerate absence.
+ *
+ * The slot is the port case's only carrier, and both gates that consume it
+ * (`design`'s honest-refusal halt, `apply`'s coverage ledger) branch on its
+ * shape. Shape-checking here rather than in the handlers means a `interactions:
+ * "three"` cannot quietly reduce the coverage ledger to zero declared items —
+ * the same bypass-by-type that `states: "n/a"` used to achieve against the
+ * five-state loop.
+ */
+function _validate_provided_artifact(provided: JsonValue | undefined): void {
+    if (provided === undefined || provided === null) {
+        return;
+    }
+    if (!_isDict(provided)) {
+        throw new SchemaError(
+            'state.ui_design.provided_artifact must be a JSON object or null; ' +
+                `got ${pyTypeName(provided)}`,
+        );
+    }
+    if ('path' in provided && typeof provided['path'] !== 'string') {
+        throw new SchemaError(
+            'state.ui_design.provided_artifact.path must be a string when present',
+        );
+    }
+    if (
+        'design_system' in provided &&
+        provided['design_system'] !== null &&
+        !_isDict(provided['design_system'])
+    ) {
+        throw new SchemaError(
+            'state.ui_design.provided_artifact.design_system must be a JSON ' +
+                `object or null; got ${pyTypeName(provided['design_system'])}`,
+        );
+    }
+    if (
+        'loss_acknowledged' in provided &&
+        typeof provided['loss_acknowledged'] !== 'boolean'
+    ) {
+        throw new SchemaError(
+            'state.ui_design.provided_artifact.loss_acknowledged must be a ' +
+                'boolean when present',
+        );
+    }
+    for (const key of ['interactions', 'keyframes', 'assets']) {
+        if (key in provided && !Array.isArray(provided[key])) {
+            throw new SchemaError(
+                `state.ui_design.provided_artifact.${key} must be a list of ` +
+                    `strings when present; got ${pyTypeName(provided[key])}`,
+            );
+        }
+    }
 }
 
 /**