@event4u/agent-config 9.12.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

@@ -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/src/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/src/config/agent-settings.template.yml

@@ -1115,6 +1115,14 @@ hooks:
   # is permanent; deprecation notice lands at the next major, removal the
   # major after — unless external evidence (a consumer case the graph answers
   # and grep cannot) appears first.
+  #
+  # The engine's parser pair is NO LONGER a runtime dependency (~51 MB that
+  # every consumer installed for a path none of them can reach); it is a
+  # devDependency, which npm does not install for consumers. Flipping this to
+  # `true` is therefore not sufficient — install the ABI-locked pair too:
+  #   npm i web-tree-sitter@0.24.7 tree-sitter-wasms@0.1.13
+  # Both versions are exact because the pair is ABI-coupled (grammar ABI 14).
+  # The loader raises this same hint if the pair is missing.
   code_graph:
     enabled: false
 

package/src/scripts/_lib/counted_probe.ts

@@ -0,0 +1,142 @@
+/**
+ * Bounded shell-out for probes that parse a count or a list out of stdout.
+ *
+ * `spawnSync` buffers the child's whole stdout in memory and fails with
+ * `ENOBUFS` past `maxBuffer`, whose default is 1 MiB. A probe that treats that
+ * failure as "no output" reports **zero** — and zero, for a counting probe, is
+ * indistinguishable from a clean result. That is how a release shipped without
+ * its `Tests:` footer: the `vitest list` output had grown to 1,254,812 bytes,
+ * the probe degraded silently, and the omission surfaced only as a red gate
+ * downstream.
+ *
+ * Raising the buffer alone just moves the cliff. The invariant this module
+ * enforces is the other half: **a truncated read is an error, never a zero.**
+ *
+ * The distinction that matters:
+ *
+ * - `ENOBUFS` — the command *succeeded* and we lost its output. There is no
+ *   honest count to report, so this throws.
+ * - `ENOENT` / non-zero exit — the command did not run, or ran and failed.
+ *   The caller may legitimately degrade (a dev box without `npx`), so these
+ *   are reported as a typed outcome rather than thrown.
+ *
+ * Scope note: this is deliberately not a general exec wrapper. It covers the
+ * counting/listing class, where a short read silently manufactures a passing
+ * result.
+ */
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+
+/**
+ * Default ceiling: 64 MiB.
+ *
+ * ~50× the largest listing this repository currently produces, at no cost
+ * when the output is small — `maxBuffer` is a ceiling, not an allocation.
+ */
+export const DEFAULT_PROBE_MAX_BUFFER = 64 * 1024 * 1024;
+
+/** Raised when a probe's output exceeded the buffer, so its count is unknowable. */
+export class ProbeOverflowError extends Error {
+    constructor(
+        readonly command: string,
+        readonly maxBuffer: number,
+    ) {
+        super(
+            `probe \`${command}\` exceeded its ${Math.round(maxBuffer / (1024 * 1024))} MiB ` +
+                'output buffer — the read was truncated, so any count derived from it ' +
+                'would be wrong. This is an error rather than a zero on purpose: a ' +
+                'counting probe that degrades to zero reports a clean result it never ' +
+                'measured. Raise the buffer or narrow the command.',
+        );
+        this.name = 'ProbeOverflowError';
+    }
+}
+
+export interface ProbeOptions {
+    readonly cwd?: string;
+    readonly maxBuffer?: number;
+    readonly timeout?: number;
+    readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface ProbeResult {
+    /** True when the command ran and exited 0. */
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly status: number | null;
+    /** Populated when the command could not be run or failed; never set for overflow (that throws). */
+    readonly failure: string | null;
+}
+
+/**
+ * Run a command and capture stdout with an explicit buffer ceiling.
+ *
+ * @throws {ProbeOverflowError} when the child's output exceeded `maxBuffer`.
+ */
+export function runCountedProbe(
+    command: string,
+    args: readonly string[],
+    opts: ProbeOptions = {},
+): ProbeResult {
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_PROBE_MAX_BUFFER;
+    const res: SpawnSyncReturns<string> = spawnSync(command, [...args], {
+        cwd: opts.cwd,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        maxBuffer,
+        ...(opts.timeout === undefined ? {} : { timeout: opts.timeout }),
+        ...(opts.env === undefined ? {} : { env: opts.env }),
+    });
+    return interpretProbeResult(res, `${command} ${args.join(' ')}`.trim(), maxBuffer);
+}
+
+/**
+ * Classify a finished spawn. Split out from `runCountedProbe` so the failure
+ * modes are unit-testable without spawning a real, slow, large-output child.
+ *
+ * @throws {ProbeOverflowError} on `ENOBUFS`.
+ */
+export function interpretProbeResult(
+    res: {
+        error?: (Error & { code?: string }) | undefined;
+        status: number | null;
+        stdout: string | null;
+        stderr?: string | null;
+    },
+    command: string,
+    maxBuffer: number = DEFAULT_PROBE_MAX_BUFFER,
+): ProbeResult {
+    const stdout = res.stdout ?? '';
+    const stderr = res.stderr ?? '';
+    if (res.error) {
+        if (res.error.code === 'ENOBUFS') {
+            throw new ProbeOverflowError(command, maxBuffer);
+        }
+        return {
+            ok: false,
+            stdout,
+            stderr,
+            status: res.status,
+            failure: `${res.error.code ?? res.error.message}`,
+        };
+    }
+    if ((res.status ?? 1) !== 0) {
+        return {
+            ok: false,
+            stdout,
+            stderr,
+            status: res.status,
+            failure: `exited ${res.status ?? '(null)'}`,
+        };
+    }
+    return { ok: true, stdout, stderr, status: res.status, failure: null };
+}
+
+/** Non-empty, trimmed lines of a successful probe — the usual "list" shape. */
+export function probeLines(result: ProbeResult): string[] {
+    if (!result.ok) return [];
+    return result.stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}

package/src/scripts/_lib/overbuild_lens_contract.ts

@@ -0,0 +1,196 @@
+/**
+ * Output-contract parser + scorer for `overbuild-review-lens`.
+ *
+ * The lens's own SKILL.md states an output contract. This is the half of that
+ * contract a machine can check: tag grammar, the mandatory Chesterton's-Fence
+ * line on every `delete:` finding, the honest-null form, and the sign of the
+ * net-lines figure. Whether a live model *finds the plant* in a fixture is not
+ * checkable here — that needs a scored eval run — and the split is stated in
+ * `tests/fixtures/overbuild-lens/README.md` rather than blurred.
+ *
+ * Deliberately dependency-free and side-effect-free: parse a string, return a
+ * verdict. Nothing reads the filesystem or the network.
+ */
+
+/** The six tags the lens may emit. Anything else is a contract violation. */
+export const LENS_TAGS = ['delete', 'stdlib', 'native', 'yagni', 'shrink', 'flatten'] as const;
+export type LensTag = (typeof LENS_TAGS)[number];
+
+export const LENS_VERDICTS = ['lean', 'trim', 'overbuilt'] as const;
+export type LensVerdict = (typeof LENS_VERDICTS)[number];
+
+export interface LensFinding {
+    tag: LensTag;
+    location: string;
+    text: string;
+    /** Present only on `delete:` findings; the contract requires it there. */
+    fence?: { why: string; safe: string; covered: string };
+}
+
+export interface ParsedLensOutput {
+    verdict: LensVerdict | null;
+    findings: LensFinding[];
+    isNull: boolean;
+    netLines: number | null;
+    /** Contract violations found while parsing. Empty means the shape is legal. */
+    errors: string[];
+}
+
+const _TAG_RE = new RegExp(
+    String.raw`^\s*\d+\.\s+(` + LENS_TAGS.join('|') + String.raw`):\s+(\S+)\s+(.*\S)\s*$`,
+);
+const _FENCE_RE =
+    /^\s*Fence:\s*why=(.+?)\s+safe=(.+?)\s+covered=(yes|no|partial)\s*$/;
+const _VERDICT_RE = /^\s*Verdict:\s*(\S+)\s*$/;
+const _NET_RE = /^\s*Net:\s*([+-]?\d+)\s+lines?\s*$/;
+const _NULL_RE = /^\s*Findings:\s*none\b/;
+const _COVERED_VALUES = new Set(['yes', 'no', 'partial']);
+
+/**
+ * Parse a lens verdict block. Never throws — a malformed block comes back with
+ * a populated `errors` array, because a parser that throws on bad input cannot
+ * report *how many* ways the input was bad.
+ */
+export function parseLensOutput(raw: string): ParsedLensOutput {
+    const lines = raw.split('\n');
+    const errors: string[] = [];
+    const findings: LensFinding[] = [];
+    let verdict: LensVerdict | null = null;
+    let netLines: number | null = null;
+    let isNull = false;
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line: string = lines[i] ?? '';
+
+        const v = line.match(_VERDICT_RE);
+        if (v) {
+            if ((LENS_VERDICTS as readonly string[]).includes(v[1] ?? '')) {
+                verdict = v[1] as LensVerdict;
+            } else {
+                errors.push(`unknown verdict \`${v[1]}\` (allowed: ${LENS_VERDICTS.join('/')})`);
+            }
+            continue;
+        }
+
+        const n = line.match(_NET_RE);
+        if (n) {
+            netLines = Number.parseInt(n[1] ?? '0', 10);
+            continue;
+        }
+
+        if (_NULL_RE.test(line)) {
+            isNull = true;
+            continue;
+        }
+
+        const m = line.match(_TAG_RE);
+        if (!m) {
+            // An unrecognised numbered line is a finding the grammar rejects.
+            if (/^\s*\d+\.\s+\S+:/.test(line)) {
+                errors.push(`line ${i + 1}: not a legal tag — \`${line.trim()}\``);
+            }
+            continue;
+        }
+
+        const finding: LensFinding = {
+            tag: m[1] as LensTag,
+            location: m[2] ?? '',
+            text: m[3] ?? '',
+        };
+
+        if (finding.tag === 'delete') {
+            const fenceLine: string = lines[i + 1] ?? '';
+            const f = fenceLine.match(_FENCE_RE);
+            if (!f) {
+                errors.push(
+                    `line ${i + 1}: \`delete:\` finding at ${finding.location} has no valid ` +
+                        'Fence line (why= / safe= / covered=yes|no|partial)',
+                );
+            } else {
+                const covered = f[3] ?? '';
+                finding.fence = {
+                    why: (f[1] ?? '').trim(),
+                    safe: (f[2] ?? '').trim(),
+                    covered,
+                };
+                if (!_COVERED_VALUES.has(covered)) {
+                    errors.push(`line ${i + 2}: covered= must be yes|no|partial`);
+                }
+            }
+        }
+
+        findings.push(finding);
+    }
+
+    if (verdict === null) errors.push('no `Verdict:` line');
+    if (netLines === null) errors.push('no `Net: <n> lines` line');
+    if (isNull && findings.length > 0) {
+        errors.push('emitted the null AND findings — pick one');
+    }
+    if (!isNull && findings.length === 0) {
+        errors.push('no findings and no null block — the null is mandatory, not optional');
+    }
+    if (verdict === 'lean' && findings.length > 0) {
+        errors.push('`lean` verdict with findings — a lean diff has nothing to cut');
+    }
+    if (verdict !== 'lean' && isNull) {
+        errors.push('null block with a non-`lean` verdict');
+    }
+
+    return { verdict, findings, isNull, netLines, errors };
+}
+
+export interface ExpectedLabels {
+    verdict: string;
+    must_tags: string[];
+    forbidden_tags: string[];
+    must_be_null: boolean;
+    net_sign: 'negative' | 'zero' | 'positive';
+    requires_fence?: boolean;
+}
+
+/**
+ * Score a parsed output against a fixture's expected labels. Returns the list
+ * of failures — empty means the output is correct for that fixture.
+ */
+export function scoreAgainstExpected(
+    parsed: ParsedLensOutput,
+    expected: ExpectedLabels,
+): string[] {
+    const failures = [...parsed.errors];
+
+    if (parsed.verdict !== expected.verdict) {
+        failures.push(`verdict ${parsed.verdict} ≠ expected ${expected.verdict}`);
+    }
+    if (parsed.isNull !== expected.must_be_null) {
+        failures.push(
+            expected.must_be_null
+                ? 'expected the honest null, got findings (invented a finding on a lean diff)'
+                : 'expected findings, got the null (missed the plant)',
+        );
+    }
+
+    const seen = new Set(parsed.findings.map((f) => f.tag));
+    for (const tag of expected.must_tags) {
+        if (!seen.has(tag as LensTag)) failures.push(`missing required tag \`${tag}:\``);
+    }
+    for (const tag of expected.forbidden_tags) {
+        if (seen.has(tag as LensTag)) failures.push(`emitted forbidden tag \`${tag}:\``);
+    }
+
+    if (expected.requires_fence) {
+        const unfenced = parsed.findings.filter((f) => f.tag === 'delete' && !f.fence);
+        if (unfenced.length > 0) failures.push('a `delete:` finding is missing its fence');
+    }
+
+    const sign =
+        parsed.netLines === null ? 'unknown'
+        : parsed.netLines < 0 ? 'negative'
+        : parsed.netLines > 0 ? 'positive'
+        : 'zero';
+    if (sign !== expected.net_sign) {
+        failures.push(`net-lines sign ${sign} ≠ expected ${expected.net_sign}`);
+    }
+
+    return failures;
+}