@event4u/agent-config 9.12.0 → 9.13.0

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

@@ -17,7 +17,7 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
-import { placeholder_paths } from './design.js';
+import { has_design_system, placeholder_paths, provided_artifact } from './design.js';
 import {
     is_ambiguous_stack,
     bundle_line,
@@ -51,6 +51,17 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
             'agent directive `ui-apply-<stack>` → skill ' +
             'bundle implements the brief and writes the envelope back',
     },
+    {
+        code: 'apply_coverage_missing',
+        trigger:
+            'a provided artifact is in state.ui_design but the ui_apply ' +
+            'envelope carries no coverage report, or the report leaves a ' +
+            'declared interaction / keyframe / asset unaccounted for',
+        resolution:
+            'agent writes ui_apply.coverage = {honoured: [], translated: [], ' +
+            'flagged: []} naming every declared item exactly once — a dropped ' +
+            'handler belongs in `flagged`, never in silence',
+    },
     {
         code: 'apply_placeholders_in_output',
         trigger:
@@ -89,10 +100,122 @@ export function run(state: DeliveryState): StepResult {
         return _halt_placeholders(state, violations);
     }
 
+    const provided = provided_artifact(state.ui_design as Record<string, Any> | null);
+    if (provided !== null) {
+        const gaps = coverage_gaps(provided, envelope['coverage']);
+        if (gaps.length > 0) {
+            return _halt_coverage(state, provided, gaps);
+        }
+    }
+
     _record_changes(state, envelope);
     return new StepResult({ outcome: Outcome.SUCCESS });
 }
 
+/** Buckets the coverage report must sort every declared item into. */
+export const COVERAGE_BUCKETS: ReadonlyArray<string> = ['honoured', 'translated', 'flagged'];
+
+/** Declared-item lists a port has to account for, in report order. */
+export const COVERED_INVENTORIES: ReadonlyArray<string> = [
+    'interactions',
+    'keyframes',
+    'assets',
+];
+
+/**
+ * Return every reason the coverage report fails to account for the artifact.
+ *
+ * The fidelity ledger the port case never had. `apply` used to validate its
+ * output with a single placeholder substring scan and nothing else, so a
+ * dropped handler or a lost keyframe left no trace anywhere — the loss was
+ * structurally silent, not merely unreported. Requiring each declared item to
+ * appear in exactly one bucket turns that silence into a halt: a handler the
+ * port could not carry has to be written down in `flagged`.
+ *
+ * Matching is substring containment against the bucket entries, so an entry
+ * may carry its own explanation ("submit handler — translated to a form
+ * action") and still count as accounting for `submit handler`.
+ */
+export function coverage_gaps(
+    provided: Record<string, Any>,
+    coverage: Any,
+): string[] {
+    const gaps: string[] = [];
+    if (!_isDict(coverage)) {
+        return [
+            'no `coverage` report in the apply envelope — a provided artifact ' +
+                'requires one',
+        ];
+    }
+    const entries: string[] = [];
+    for (const bucket of COVERAGE_BUCKETS) {
+        const value = coverage[bucket];
+        if (value === undefined) {
+            gaps.push(`\`coverage.${bucket}\` is missing (use an empty list if nothing qualifies)`);
+            continue;
+        }
+        if (!Array.isArray(value)) {
+            gaps.push(`\`coverage.${bucket}\` must be a list of strings`);
+            continue;
+        }
+        for (const item of value) {
+            if (typeof item === 'string' && item !== '') {
+                entries.push(item.toLowerCase());
+            }
+        }
+    }
+    for (const inventory of COVERED_INVENTORIES) {
+        const declared = provided[inventory];
+        if (!Array.isArray(declared)) continue;
+        for (const item of declared) {
+            if (typeof item !== 'string' || item === '') continue;
+            const needle = item.toLowerCase();
+            if (!entries.some((entry) => entry.includes(needle))) {
+                gaps.push(
+                    `\`${inventory}\`: \`${item}\` appears in no coverage bucket`,
+                );
+            }
+        }
+    }
+    return gaps;
+}
+
+/** BLOCKED halt — the port did not account for what the artifact declared. */
+function _halt_coverage(
+    state: DeliveryState,
+    provided: Record<string, Any>,
+    gaps: string[],
+): StepResult {
+    const directive = _resolve_directive(state);
+    const contract = has_design_system(provided)
+        ? 'A `design-system.json` came with this artifact, so its token values ' +
+          'are honoured verbatim — say which, and which you had to translate.'
+        : 'No `design-system.json` came with this artifact, so every token ' +
+          'value you did not read from it belongs in `translated` or `flagged`.';
+    const lines: string[] = [
+        agent_directive(directive),
+        '> Apply rejected: this is a port of a provided artifact, and the ' +
+            'coverage report does not account for it.',
+        `> ${contract}`,
+        '> Unaccounted:',
+    ];
+    for (const gap of gaps) {
+        lines.push(`> - ${gap}`);
+    }
+    lines.push(
+        '> Write `ui_apply.coverage = {honoured: [...], translated: [...], ' +
+            'flagged: [...]}` naming every declared interaction, keyframe, and ' +
+            'asset exactly once. A handler the port could not carry goes in ' +
+            '`flagged` with the reason — never in silence.',
+    );
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message:
+            `UI apply rejected: ${gaps.length} coverage gap(s) against the provided artifact.`,
+    });
+}
+
 /** Return the agent-written `ui_apply` envelope, or `null`. */
 function _apply_envelope(state: DeliveryState): Record<string, Any> | null {
     const data = _pyTruthy(state.ticket) ? state.ticket : {};
@@ -143,20 +266,38 @@ function _delegate_to_stack_skill(state: DeliveryState): StepResult {
                 'the open question is which project to build for.',
         });
     }
+    const provided = provided_artifact(state.ui_design as Record<string, Any> | null);
+    const lines: string[] = [
+        agent_directive(directive),
+        `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
+        bundle_line(state.stack, 'build', stack_label),
+        '> Microcopy is locked — every button label, empty-state ' +
+            'message, and validation message must come verbatim from ' +
+            '`state.ui_design.microcopy`.',
+    ];
+    if (provided !== null) {
+        lines.push(
+            '> This is a **port**: `state.ui_design.provided_artifact` is the ' +
+                'spec. Build it 1:1' +
+                (has_design_system(provided)
+                    ? ', and read token values from its `design_system` rather ' +
+                      'than re-deriving them.'
+                    : '; no `design_system` came with it, so anything you cannot ' +
+                      'read from the artifact is a translation you have to name.'),
+            '> The envelope must carry `coverage: {honoured, translated, ' +
+                'flagged}` accounting for every declared interaction, keyframe, ' +
+                'and asset exactly once — apply rejects the envelope otherwise.',
+        );
+    }
+    lines.push(
+        '> 1. Continue — implement the brief and write a ' +
+            '`ui_apply` envelope back into state.ticket ' +
+            '(rendered: {path: text}, files: [...])',
+        '> 2. Abort — drop this UI request',
+    );
     return new StepResult({
         outcome: Outcome.BLOCKED,
-        questions: [
-            agent_directive(directive),
-            `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
-            bundle_line(state.stack, 'build', stack_label),
-            '> Microcopy is locked — every button label, empty-state ' +
-                'message, and validation message must come verbatim from ' +
-                '`state.ui_design.microcopy`.',
-            '> 1. Continue — implement the brief and write a ' +
-                '`ui_apply` envelope back into state.ticket ' +
-                '(rendered: {path: text}, files: [...])',
-            '> 2. Abort — drop this UI request',
-        ],
+        questions: lines,
         message: `UI apply pending; delegating to \`${directive}\` for stack \`${stack_label}\`.`,
     });
 }

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])}`,
+            );
+        }
+    }
 }
 
 /**

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-08-01T06:24:46Z`
+- Generated: `2026-08-02T08:46:05Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._