@event4u/agent-config 9.12.0 → 9.14.0

package/dist/agent-src/skills/overbuild-review-lens/SKILL.md

@@ -0,0 +1,201 @@
+---
+model_tier: high
+name: overbuild-review-lens
+description: "Use when a diff builds more than the task needs — code that should not exist, a dependency the platform already covers, or a clever form where a flat one reads better. Deletion-hunting, not quality."
+personas:
+  - senior-engineer
+domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# overbuild-review-lens
+
+> A deletion-hunting lens. It asks one question the other judges never
+> ask: **should this code exist at all?** Sibling of
+> [`architecture-review-lens`](../architecture-review-lens/SKILL.md) and
+> the `judge-*` family — never overlaps with them.
+
+## When to use
+
+- A diff adds a helper, a wrapper, a config layer, an abstraction, or a
+  dependency.
+- A rewrite, v2, or large refactor landed — the peak over-build context
+  (see [`minimal-safe-diff-mechanics`](../../../docs/guidelines/agent-infra/minimal-safe-diff-mechanics.md)
+  § The sanctioned-rewrite trap).
+- A reviewer asks "is all of this needed?", "could the platform do
+  this?", or "why is this so clever?".
+
+Do NOT use when:
+
+- The concern is whether the code is **correct** — route to
+  [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md).
+- The concern is **security** — route to
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md).
+- The concern is **naming, single-responsibility, or convention fit** of
+  code whose existence is not in question — route to
+  [`judge-code-quality`](../judge-code-quality/SKILL.md). That judge asks
+  *is this code malformed*; this lens asks *should it exist*.
+- The concern is **performance** — route to
+  [`performance`](../performance/SKILL.md). Speed is out of scope here.
+- The diff is documentation-only or formatting-only.
+
+## The scope fence — read this before the first finding
+
+```
+CORRECTNESS, SECURITY AND PERFORMANCE ARE OUT OF SCOPE FOR THIS LENS.
+THE MINIMUM RUNNABLE CHECK IS NEVER FLAGGED FOR DELETION.
+A SIZE REDUCTION THAT DROPS A GUARD IS A LOSS, NOT A FINDING.
+```
+
+The measured failure mode this fence exists for: a bare "make it
+simpler" critic was the only arm in a controlled comparison that dropped
+a safety guard — the three lines it saved were a path-traversal check.
+Tests, validation, authorization checks, tenant scoping, and error paths
+that can actually occur are **not** over-build. If removing something
+would reduce coverage of a real case, it is not a finding here.
+
+## Procedure
+
+### 1. Establish what the task actually asked for
+
+Read the ticket / prompt, not just the diff. Over-build is measured
+against the **requirement**, not against your taste. Anything the diff
+adds beyond the requirement is a candidate; anything the requirement
+demands is not, however large.
+
+### 2. Walk each addition down the solution-size ladder
+
+For every new unit (function, class, module, config key, dependency),
+find the highest rung that would have carried it — see
+[`agent-interaction-and-decision-quality`](../../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md)
+§ 8b-ladder:
+
+| Tag | Meaning | The evidence that makes it a finding |
+|---|---|---|
+| `delete:` | This should not exist at all | A fence line (see § 3) — mandatory |
+| `stdlib:` | The language stdlib or framework already does it | Name the exact API and show it is equivalent |
+| `native:` | The OS / runtime / browser / database already does it | Name the platform capability and its availability floor |
+| `yagni:` | Built for a requirement nobody stated | Quote the requirement it exceeds |
+| `shrink:` | Must exist, but smaller | Name the lines that carry no requirement |
+| `flatten:` | Must exist, but in a **simpler form** | Name the cognitive cost, not the line count |
+
+`flatten:` is the shape-axis inverse of `shrink:` — same logic, simpler
+form, **even when that costs a line or two**. Without it the lens only
+ever argues downward and becomes a golfing engine. A nested ternary
+replaced by an `if` block is a valid `flatten:` finding even though the
+diff grows.
+
+### 3. Every `delete:` carries a fence line — no exceptions
+
+Chesterton's Fence, operationalised. Agents are documented as
+especially fence-blind: complex code reads as an invitation to simplify
+when the complexity may exist for a reason the reader has no context
+for. This does not restate
+[`minimal-safe-diff`](../../../src/rules/minimal-safe-diff.md)'s "never
+delete code that *looks* dead without proof" — it is the output contract
+that makes the proof visible.
+
+The fence line has three fields, all required:
+
+```
+Fence: why=<why the code existed — blame, test, issue, or "unknown">
+       safe=<the evidence that removal is safe>
+       covered=<yes|no|partial — was the removed path under test?>
+```
+
+- `why=unknown` is a legal value and it is **not** a pass. It downgrades
+  the finding to a question for the author, never an instruction.
+- `covered=` is the one machine-checkable input to an otherwise
+  archaeological judgement (the Beyoncé rule: if you liked it, you put a
+  test on it). Deleting *tested* behaviour trips a test and is visible;
+  deleting *untested* behaviour breaks silently — so `covered=no` is
+  surfaced as **higher** risk, not as equivalent.
+
+### 4. Emit the null when there is nothing to cut
+
+```
+A LENS THAT CANNOT SAY "NOTHING TO CUT" IS A FINDING GENERATOR.
+```
+
+A lean diff must produce the honest null, not an invented finding. This
+is the load-bearing output, not a fallback: a reviewer who sees findings
+on every diff stops reading them.
+
+### 5. Validate before emitting
+
+- Every finding has a `file:line` and exactly one tag from § 2.
+- Every `delete:` has all three fence fields.
+- No finding restates a correctness, security, or performance concern.
+- The net-lines summary counts `flatten:` findings honestly, including
+  the ones that **add** lines.
+- Zero findings → emit the null block, not an empty issues list.
+
+## Output format
+
+The verdict block carries these ordered fields:
+
+1. `Lens:` — fixed value `overbuild-review-lens`
+2. `Target:` — the diff range or file set reviewed
+3. `Verdict:` — exactly one of `lean` / `trim` / `overbuilt`
+4. `Findings:` — one line per finding: tag, `file:line`, one sentence;
+   `delete:` findings carry their `Fence:` line directly beneath
+5. `Net:` — lines removable if every finding is applied, stated as a
+   signed number so a line-adding `flatten:` is visible
+
+```
+Lens:    overbuild-review-lens
+Target:  <branch / diff range>
+
+Verdict: lean | trim | overbuilt
+
+Findings:
+1. stdlib:  src/util/uuid.ts:1     Hand-rolled v4 generator; crypto.randomUUID covers it.
+2. delete:  src/config/flags.ts:12 Flag read by nothing since the feature shipped.
+   Fence: why=guarded the 2026-03 rollout  safe=zero readers, grep clean  covered=no
+3. flatten: src/parser.ts:88       Nested ternary; an if/else reads flat (+2 lines).
+
+Net: -34 lines
+```
+
+The null, when there is nothing to cut — emit verbatim, do not
+paraphrase:
+
+```
+Lens:    overbuild-review-lens
+Target:  <branch / diff range>
+
+Verdict: lean
+
+Findings: none — nothing in this diff exceeds the stated requirement.
+
+Net: 0 lines
+```
+
+## Gotcha
+
+- **The requirement is the yardstick, not your preference.** A large
+  diff that the ticket demanded is not over-built. Say so and emit the
+  null.
+- **`covered=no` makes a deletion riskier, not more attractive.** The
+  absence of a test is the absence of a tripwire.
+- **A `flatten:` finding that saves lines is suspicious.** If it is
+  shorter *and* simpler it is probably a `shrink:`; `flatten:` exists
+  for the cases where simplicity costs length.
+- **Never flag the minimum runnable check.** One happy-path test is not
+  over-build; it is the floor.
+- **Do not count `delete:` lines that git already removed.** The net
+  figure is about the diff as proposed, not the diff's own deletions.
+
+## Do NOT
+
+- Do NOT emit a `delete:` finding without all three fence fields — the
+  output contract rejects it.
+- Do NOT invent a finding to avoid an empty report.
+- Do NOT review correctness, security, or performance — other surfaces
+  own those, and a size argument against a guard is the canonical
+  failure this lens is fenced against.
+- Do NOT report a size number as a score. A size metric is a
+  measurement, never a target.

package/dist/agent-src/skills/performance/SKILL.md

@@ -28,6 +28,20 @@ Do NOT use when:
 3. Check for N+1 queries on list endpoints.
 4. Search for existing cache services in the project.
 
+**Performance complexity is a claim, and a claim needs evidence.** No cache
+layer, no denormalised column, no materialised view, no read replica ships on
+"this will be slow" — it ships on a profile, a query log, or a timing that names
+the bottleneck. The added complexity is permanent (invalidation bugs, stale
+reads, a second source of truth); the speedup is hypothetical until measured.
+State the measurement in the change, or do not add the mechanism.
+
+**Carve-out — this does not override the `scale-discipline` floor.** Where that
+pack is installed, R-A2 *mandates* an index on every FK and every WHERE / ORDER
+BY column, and R-A4 governs duplicated data by waiver. Those are structural
+defaults that ship with the query, not optimisations awaiting a profiler; the
+evidence gate above applies to *added mechanisms* (caches, denormalisation,
+replicas, bespoke indexes beyond parity), never to the floor's baseline.
+
 ### Step 1: Apply the right fix
 
 | Bottleneck | Fix |

package/dist/agent-src/skills/pixar-storyteller/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: pixar-storyteller
-description: "Use when turning an idea into a Pixar-style animation prompt — character sheet, scene, image, video — anchored in emotional beat, want, obstacle. Triggers 'Pixar prompt', 'animated scene'."
+description: "Use when an idea becomes a Pixar-style animation prompt — character sheet, scene, image, video; emotional beat, want, obstacle. Triggers 'Pixar prompt', 'animated scene'. Live-action → video-director."
 domain: product
 workspaces:
   - small-business
@@ -119,12 +119,15 @@ Any "no" → revise that block.
 
 ## Policies
 
+Paths, enforcement model, and the full set: the
+[media policy preamble](../../../agents/settings/policies/media/README.md).
+
 The Pixar-storyteller skill anchors prompts to named films and studios by design — the policy surface is the largest in the video cluster:
 
-- [`agents/settings/policies/media/style.md`](../../../agents/settings/policies/media/style.md) — naming a film + year as the *primary* anchor crosses the "in the style of [STUDIO]" trigger; surface and refuse without a transformative-intent rationale.
-- [`agents/settings/policies/media/likeness.md`](../../../agents/settings/policies/media/likeness.md) — when a beat references a named animator's signature character (real-person extension of style).
-- [`agents/settings/policies/media/public-figures.md`](../../../agents/settings/policies/media/public-figures.md) — when the storyteller's character is a recognised public figure rendered in Pixar shape.
-- [`agents/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — every Pixar-style output ships with the AI-generation disclosure; parody / commentary cases are flagged for human review.
+- **`style`** — naming a film + year as the *primary* anchor crosses the "in the style of [STUDIO]" trigger; surface and refuse without a transformative-intent rationale.
+- **`likeness`** — when a beat references a named animator's signature character (real-person extension of style).
+- **`public-figures`** — when the storyteller's character is a recognised public figure rendered in Pixar shape.
+- **`disclosure`** — every Pixar-style output ships with the AI-generation disclosure; parody / commentary cases are flagged for human review.
 
 Refuse-and-surface when style ⇒ primary signature, not one influence among several.
 

package/dist/agent-src/skills/scene-expander/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: scene-expander
-description: "Use when expanding a one-line idea into the 12-block Cinematic Scene Blueprint — provider-agnostic, includes optional dialogue + ambient. Triggers 'expand this scene', 'blueprint for X'."
+description: "Use when expanding a one-line idea into the 12-block Cinematic Scene Blueprint — optional dialogue + ambient. Triggers 'expand this scene', 'blueprint for X'. 11-block refine → video-director."
 personas:
   - hollywood-director
 domain: product
@@ -146,13 +146,16 @@ Any "no" → revise that block.
 
 ## Policies
 
+Paths, enforcement model, and the full set: the
+[media policy preamble](../../../agents/settings/policies/media/README.md).
+
 The 12-block Cinematic Scene Blueprint is the policy choke point — every downstream skill (`motion-choreographer`, `video-director`) inherits whatever the blueprint encodes. Before emitting:
 
-- [`agents/settings/policies/media/likeness.md`](../../../agents/settings/policies/media/likeness.md) — when the SUBJECT block names or visually identifies a real person.
-- [`agents/settings/policies/media/public-figures.md`](../../../agents/settings/policies/media/public-figures.md) — when the SUBJECT block is a recognised public figure.
-- [`agents/settings/policies/media/brand-impersonation.md`](../../../agents/settings/policies/media/brand-impersonation.md) — when STYLE / ENVIRONMENT references a recognised brand's visual identity.
-- [`agents/settings/policies/media/style.md`](../../../agents/settings/policies/media/style.md) — when STYLE anchors to a named living artist or studio as the primary signature.
-- [`agents/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — every distributed blueprint output carries the AI-generation disclosure downstream.
+- **`likeness`** — when the SUBJECT block names or visually identifies a real person.
+- **`public-figures`** — when the SUBJECT block is a recognised public figure.
+- **`brand-impersonation`** — when STYLE / ENVIRONMENT references a recognised brand's visual identity.
+- **`style`** — when STYLE anchors to a named living artist or studio as the primary signature.
+- **`disclosure`** — every distributed blueprint output carries the AI-generation disclosure downstream.
 
 Refuse-and-surface at the blueprint layer; do not push policy questions down to the adapter.
 

package/dist/agent-src/skills/supply-chain-intake/SKILL.md

@@ -32,6 +32,16 @@ PIN IT, LOCK IT, CVE-SCAN IT. NEVER PIPE A REMOTE SCRIPT STRAIGHT TO A SHELL.
 
 ## Procedure — intake gate (run in order before adding a dependency)
 
+0. **Do you need a dependency at all?** The cheapest supply-chain risk is the
+   one never taken. Walk the rungs above "installed dependency" first — is it
+   already in the tree (`npm ls <pkg>`, `composer show`, `pip list`), does the
+   stdlib or framework carry it, does the **platform** already do it
+   (`crypto.randomUUID` before a uuid package, `Intl` before a formatting
+   library, `AbortSignal.timeout` before a timeout helper, the database's own
+   full-text / JSON support before an application-side index)? Full ordering:
+   [`agent-interaction-and-decision-quality` § 8b-ladder](../../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md).
+   A dependency added for something already present is permanent cost — install
+   surface, CVE surface, upgrade surface — bought against a capability you had.
 1. **Existence** — confirm the exact string resolves on the real registry, published before your session and with real usage:
    ```bash
    npm view <pkg> version        # non-zero exit = does not exist (hallucination)

package/dist/agent-src/skills/universal-project-analysis/SKILL.md

@@ -31,15 +31,11 @@ Do NOT use when:
 
 ## Mission
 
-Act as the top-level router for deep project investigation.
-
-This skill must:
-
-* confirm whether full-project analysis is justified
-* identify the stack and framework
-* choose the correct analysis mode
-* route to the right specialist analysis skills
-* define the required output for broad project investigations
+Run the deep multi-pass audit itself, and hand each pass to the right
+specialist. Picking *which* skill a request needs in the first place belongs to
+[`analysis-skill-router`](../analysis-skill-router/SKILL.md) — that chooser and
+this orchestrator are deliberately separate files, and the scope test, the
+detection step, and the decision table live there, not here.
 
 This skill must NOT become:
 
@@ -88,9 +84,9 @@ Goal: identify hot paths, find expensive boundaries, route into architecture or
 
 ### 1. Confirm scope
 
-Check whether full-project analysis is really needed.
-Use this skill only if the user wants: broad system understanding, architecture reconstruction, deep multi-layer debugging, broad audit across modules or runtime boundaries.
-If not: route to the narrower specialist skill directly.
+Invoked through the router, this is already settled — proceed. Invoked
+directly, apply the router's scope test before spending a multi-pass audit on
+something a specialist covers.
 
 ### 2. Discover the project
 
@@ -128,36 +124,17 @@ Check:
 * uncertainties are marked
 * conclusions are evidence-based
 
-## Routing map
-
-### Universal analysis skills
-
-* `project-analysis-core`
-* `project-analysis-hypothesis-driven`
-
-### Framework-specific deep dives
-
-* `project-analysis-laravel`
-* `project-analysis-symfony`
-* `project-analysis-zend-laminas`
-* `project-analysis-node-express`
-* `project-analysis-react`
-* `project-analysis-nextjs`
-
-### Optional downstream specialists
-
-* `bug-analyzer`
-* `performance-analysis`
-* `security-audit`
-
-### Ingestion preprocessor
+## Ingestion preprocessor
 
 * `markitdown` — when the project ships PDFs, DOCX, XLSX, PPTX, EPUB,
-  images, or audio that need to feed into any of the analysis skills
-  above. Convert first via the upstream `markitdown-mcp` server, then
+  images, or audio that need to feed into any of the routes in steps 3–4.
+  Convert first via the upstream `markitdown-mcp` server, then
   route the resulting Markdown into the relevant deep-dive skill.
   Never read a binary office format raw.
 
+> The route lists in steps 3 and 4 are the routing map. A second copy of them
+> lived here until 2026-08-02 and was removed — one list, one place.
+
 ## When to add a new framework analysis skill
 
 A framework gets its own `project-analysis-*` skill ONLY if:

package/dist/agent-src/skills/video-director/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: video-director
-description: "Use when turning a scene idea into the 11-block cinematic prompt for live-action AI video — lens, lighting, blocking, motion, negatives. Triggers 'cinematic prompt', 'film-grade scene'."
+description: "Use when a live-action beat becomes the 11-block cinematic prompt — lens, lighting, negatives. Triggers 'cinematic prompt', 'film-grade scene'. Animated → pixar-storyteller; 12-block → scene-expander."
 personas:
   - hollywood-director
 domain: product
@@ -124,13 +124,16 @@ Any "no" → revise that block before handing off.
 
 ## Policies
 
+Paths, enforcement model, and the full set: the
+[media policy preamble](../../../agents/settings/policies/media/README.md).
+
 The 11-block cinematic prompt is live-action shape — real-person and brand-impersonation risks are the highest in the cluster. Before emitting:
 
-- [`agents/settings/policies/media/likeness.md`](../../../agents/settings/policies/media/likeness.md) — when the prompt names or visually identifies a real person on camera.
-- [`agents/settings/policies/media/public-figures.md`](../../../agents/settings/policies/media/public-figures.md) — when the subject is a recognised public figure.
-- [`agents/settings/policies/media/brand-impersonation.md`](../../../agents/settings/policies/media/brand-impersonation.md) — when the prompt copies a journalism / broadcaster / regulated-industry visual identity.
-- [`agents/settings/policies/media/style.md`](../../../agents/settings/policies/media/style.md) — when LIGHT / LENS choices are anchored to a named living cinematographer's signature.
-- [`agents/settings/policies/media/disclosure.md`](../../../agents/settings/policies/media/disclosure.md) — every distributed live-action AI clip carries the non-removable AI-generation disclosure.
+- **`likeness`** — when the prompt names or visually identifies a real person on camera.
+- **`public-figures`** — when the subject is a recognised public figure.
+- **`brand-impersonation`** — when the prompt copies a journalism / broadcaster / regulated-industry visual identity.
+- **`style`** — when LIGHT / LENS choices are anchored to a named living cinematographer's signature.
+- **`disclosure`** — every distributed live-action AI clip carries the non-removable AI-generation disclosure.
 
 Refuse-and-surface at the directorial layer; live-action realism amplifies every policy gap downstream.
 

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.12.0"
+agent_config_version: "9.14.0"
 
 # --- Project identity ---
 project:

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}\`.`,
     });
 }