@momentiq/dark-factory-cli 2.18.0 → 3.0.1

package/skills/designer-brief/SKILL.md.tmpl

@@ -0,0 +1,74 @@
+---
+name: designer-brief
+description: Use when a non-technical operator (designer, PM, or founder) in Designer Mode asks for a non-trivial UI change — capture their intent as a short brief (What, Why, Done-when, Out-of-bounds) at .darkfactory/briefs/ before building. Tiny, obvious single-shot asks skip the brief and go straight to /designer-build.
+---
+
+# /designer-brief — capture intent before building
+
+Designer Mode pairs a non-technical operator with an agent that owns every
+technical decision. This skill is the **plan-time** step for {{REPO_NAME}}: it
+turns a product ask into a one-glance brief the operator approves before you
+write a line of code, so "done" has an agreed shape.
+
+Everything below is **your** procedure. The operator never sees a brief
+template, a file path, or this doctrine — they see one plain-language summary
+and answer at most a question or two.
+
+## When to write a brief (and when to skip)
+
+Write a brief when the ask is **non-trivial** — a new section, page, or flow, or
+a change that spans several surfaces or has more than one "done" condition
+("add a testimonials section", "make onboarding feel calmer").
+
+**Skip it** — the single-shot path — for tiny, unambiguous polish where the
+change and its "done" are obvious in one look ("the pricing cards feel
+cramped", "this heading is the wrong blue"). Go straight to `/designer-build`,
+screenshot before/after, and confirm.
+
+When unsure, prefer a brief — it is three sentences and a checklist, not a spec.
+
+## The brief
+
+Write it to `.darkfactory/briefs/<date>-<slug>.md`, where `<date>` is today in
+`YYYY-MM-DD` form and `<slug>` is a short kebab-case name for the ask
+(`.darkfactory/briefs/2026-07-03-testimonials-section.md`). Four sections, all
+in the operator's product language — no framework, file, or component names:
+
+```markdown
+# <Title of the ask>
+
+## What
+One sentence: the change, as the operator would describe it.
+
+## Why
+The outcome they want — what a visitor or user feels or can now do.
+
+## Done-when
+- [ ] An observable, checkable acceptance item in plain language.
+- [ ] Another one. Each is something you can *show* on screen.
+- [ ] …
+
+## Out-of-bounds
+- What this deliberately does NOT touch (keeps scope honest and points at handoffs).
+```
+
+The **Done-when checkboxes are the acceptance contract.** Write each as
+something you can demonstrate with a screenshot or a visible behavior — they
+become what `/designer-ship` verifies and what closeout proves. Vague items
+("looks nicer") are not acceptance items; make them observable ("the
+testimonials read comfortably on a phone without pinching").
+
+## Filling gaps — ask product questions only
+
+If the ask is underspecified, ask **only product or visual questions**, one at a
+time, multiple-choice with 2–3 concrete options plus "you decide"
+("Should testimonials show a photo, or just a name and quote?"). Never ask about
+frameworks, data, files, or state — decide those yourself from the repo's
+existing conventions and `DESIGN.md`.
+
+## Approve in one glance
+
+Show the operator the essence, not the file: *"Here's what I'll build — a
+testimonials section with three quotes and photos, on the home page. It won't
+touch sign-in or your data. Look right?"* On yes, hand off to `/designer-build`.
+Keep the brief file updated if the ask shifts mid-build.

package/skills/designer-brief/skill.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "../skill-schema.json",
+  "name": "designer-brief",
+  "version": "1.0.0",
+  "summary": "Designer Mode: turn a non-technical operator's intent into a short brief (What/Why/Done-when/Out-of-bounds) at .darkfactory/briefs/ before building; tiny obvious asks skip straight to /designer-build.",
+  "originatingRepo": "momentiq-ai/dark-factory",
+  "files": [
+    { "template": "SKILL.md.tmpl", "target": "SKILL.md" }
+  ],
+  "variables": {
+    "REPO_NAME": {
+      "description": "Display name of the consumer repo (e.g. 'Taxpilot').",
+      "source": "darkfactory.yaml: repo.displayName",
+      "default": "this repo"
+    }
+  }
+}

package/skills/designer-build/SKILL.md.tmpl

@@ -0,0 +1,63 @@
+---
+name: designer-build
+description: Use when implementing a Designer Mode change within the mode's write scopes — reuse the repo's design system, run the dev server, and capture before/after screenshots each visual iteration until the operator says it looks right. Follows /designer-brief (or a tiny single-shot ask), precedes /designer-ship.
+---
+
+# /designer-build — implement within scope, verify visually
+
+This is the **build loop** of Designer Mode for {{REPO_NAME}}. You implement the
+change, prove it visually, and iterate on the operator's product feedback —
+never on code they have to read.
+
+The operator sees screenshots and plain sentences. They never see diffs, file
+trees, terminals, or component names.
+
+## Stay in scope
+
+Work only inside the mode's `writeScopes`. The PreToolUse guard
+(`df mode guard`) enforces the scopes and `protectedPaths` at the tool level —
+if a call is denied, **do not retry or route around it.** A denial means the ask
+needs an engineer: stop and use `/designer-handoff`. (`df mode status` confirms
+the active mode and its editable areas.)
+
+## Reuse the design system — don't invent
+
+`DESIGN.md` is the design source of truth (its tokens are injected into your
+session context):
+
+- Take every color, font size, and spacing value from `DESIGN.md` tokens. Do
+  not hand-pick hex values or one-off spacings.
+- **Reuse existing components before creating anything new** — extend a
+  component, don't fork it. Match the patterns already in the codebase.
+- Never remove accessibility affordances (focus rings, labels, alt text,
+  contrast). A change that would is out-of-bounds → `/designer-handoff`.
+
+## The visual loop (show, don't tell)
+
+1. **Baseline.** Start the dev server using the mode catalog's
+   `devServer.command` (e.g. `npm run dev`) at its configured URL. With the
+   Playwright MCP, screenshot the route(s) and state(s) you're about to change —
+   this is the **BEFORE**.
+2. **Change.** Implement one coherent step within scope.
+3. **AFTER.** Re-screenshot the same route(s) and state(s). Include the
+   responsive and empty/error states the Done-when items care about (e.g. a
+   phone width).
+4. **Show the operator** the before/after and describe the change in one
+   sentence: *"Here's the testimonials section — three quotes, easy to read on a
+   phone. Want the quotes bigger?"*
+5. **Iterate** on their product feedback ("make it warmer", "tighten the
+   spacing") — repeat steps 2–4 until they say it looks right. Keep each
+   iteration a small, screenshotted step.
+
+Keep the final before/after screenshots — `/designer-ship` embeds them in the PR
+so reviewers and the operator see the change, and the visual-evidence route
+binds them to the shipped commit.
+
+## Translate, never dump
+
+If something goes wrong (a build error, a failing check), say what it means in
+one sentence and what you're doing about it — never paste the raw error. Decide
+all implementation details yourself, following repo conventions; ask the
+operator only product or visual questions, multiple-choice, one at a time.
+
+When the operator says it looks right, hand off to `/designer-ship`.

package/skills/designer-build/skill.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "../skill-schema.json",
+  "name": "designer-build",
+  "version": "1.0.0",
+  "summary": "Designer Mode: implement within the mode's write scopes, reuse the design system, and run a dev-server + Playwright before/after screenshot loop until the operator says it looks right.",
+  "originatingRepo": "momentiq-ai/dark-factory",
+  "files": [
+    { "template": "SKILL.md.tmpl", "target": "SKILL.md" }
+  ],
+  "variables": {
+    "REPO_NAME": {
+      "description": "Display name of the consumer repo (e.g. 'Taxpilot').",
+      "source": "darkfactory.yaml: repo.displayName",
+      "default": "this repo"
+    }
+  }
+}

package/skills/designer-handoff/SKILL.md.tmpl

@@ -0,0 +1,64 @@
+---
+name: designer-handoff
+description: Use when a Designer Mode ask needs an engineer — it is out-of-scope, touches a protected path, requires a dependency change, or a gate will not converge within the N=2 ceiling. Package a scrubbed, dual-register escalation with df handoff and tell the operator in one plain sentence, framed as progress.
+---
+
+# /designer-handoff — escalate as progress, never as rejection
+
+Some asks legitimately need an engineer. In Designer Mode for {{REPO_NAME}}, that
+is a **first-class outcome**, not a failure — the product answer to a scope
+boundary is a clean handoff that feels like momentum.
+
+## When to hand off
+
+- A tool call was **denied by the mode guard** (outside `writeScopes`, or a
+  `protectedPaths` hit like auth, API, migrations, config, or CI). Do **not**
+  retry or work around a denial.
+- The ask needs a **dependency change** under `dependencyPolicy: none`.
+- A gate finding **won't converge within N=2** fix rounds, or the fix requires
+  work outside your scope.
+
+## Package the artifact with `df handoff`
+
+`df handoff` is Issue-anchored: it reads the composed note on **stdin**, upserts
+it as the dedicated handoff Issue's body, adds the `handoff` label, and leaves it
+unassigned; it prints the Issue URL. Link the relevant PR or issue with
+`--link`:
+
+```bash
+df handoff --link pr:<PR#> <<'EOF'
+<the composed, scrubbed note — see structure below>
+EOF
+```
+
+## Dual-register: two audiences, one artifact
+
+Write the note for the **engineer**, and speak a separate plain sentence to the
+**operator**.
+
+Engineer-facing note (structured, precise):
+
+```markdown
+## Intent
+What the operator asked for, in their words.
+
+## Done so far
+What is already built and where (branch or PR), and what is verified visually.
+
+## Blocked — why
+The specific boundary: which scope, protected path, dependency, or gate — and
+what an engineer needs to decide or do next.
+```
+
+Operator-facing sentence (plain, framed as progress):
+
+> *"That touches sign-in security, which needs an engineer's hands. I've written
+> up exactly what you want and everything I built, and handed it to the team —
+> here's the link. Want to keep going on something else meanwhile?"*
+
+## Scrub before you hand off
+
+The note may be read outside the session — keep it clean. No secrets, no raw
+diffs or stack traces, no internal jargon that leaks implementation the operator
+never saw. State the intent and the blocker; link the PR for the code. Never
+include anything you would not show the operator.

package/skills/designer-handoff/skill.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "../skill-schema.json",
+  "name": "designer-handoff",
+  "version": "1.0.0",
+  "summary": "Designer Mode: package a scrubbed, dual-register df handoff artifact when an ask needs an engineer (out-of-scope, protected path, dependency change, or N=2 gate thrash), framed to the operator as progress.",
+  "originatingRepo": "momentiq-ai/dark-factory",
+  "files": [
+    { "template": "SKILL.md.tmpl", "target": "SKILL.md" }
+  ],
+  "variables": {
+    "REPO_NAME": {
+      "description": "Display name of the consumer repo (e.g. 'Taxpilot').",
+      "source": "darkfactory.yaml: repo.displayName",
+      "default": "this repo"
+    }
+  }
+}

package/skills/designer-ship/SKILL.md.tmpl

@@ -0,0 +1,77 @@
+---
+name: designer-ship
+description: Use when a Designer Mode change is visually approved and ready to ship — confirm the brief's Done-when items, run gates, and open plus auto-merge a PR that carries the designer mode trailer and a Closes #N link with before/after screenshots embedded, relaying pipeline status to the operator in plain language.
+---
+
+# /designer-ship — verify, ship, and relay in plain language
+
+The change is visually approved. This skill takes it through the **unchanged**
+production pipeline for {{REPO_NAME}} — branch, gates, PR, review, merge — and
+narrates it to the operator as outcomes, never as plumbing.
+
+The operator sees "it's in review" and "it's live". They never see git, a diff,
+a PR number, or a critic finding.
+
+## 1. Confirm the acceptance contract
+
+The brief's **Done-when checkboxes are the acceptance criteria.** Before
+shipping, confirm each is satisfied and backed by the before/after screenshots
+from `/designer-build` — a Done-when item with no visible proof is not done.
+
+Make "done" proof-bound, not free text. Where the change has a
+`.darkfactory/objectives.yaml`, verify it and read the closeout proof with
+`df prove` (per-objective proven/pending/failed); see the `/objectives` skill
+for authoring and binding mechanics. (Automated derivation of objectives
+directly from a brief is a later Designer-Mode phase; today, treat the Done-when
+list as the contract and verify each item visually.)
+
+## 2. Run the gates locally first
+
+Run the repo's configured quality gates before pushing (build, tests, and
+type-check as the repo defines them). `df gate-push` runs the local critic on
+HEAD at push time and blocks on unresolved blockers — let it; never bypass a
+gate or ask the operator to.
+
+## 3. Branch, commit, PR — with the mode trailers
+
+Do the work on a branch (a worktree, per repo doctrine), then commit with the
+Designer Mode trailers:
+
+```
+Mode: designer
+Closes #<N>
+```
+
+The `Mode: designer` trailer tags the PR as designer-driven. Today, scope is
+enforced live by the PreToolUse guard during the session, and the change still
+faces the full multi-vendor critic quorum + merge queue like any other PR. The
+deterministic mode-scope critic — which reads this trailer to validate the diff
+against the catalog's writeScopes / protectedPaths / diffBudget and block an
+out-of-scope diff at merge time, even from a jailbroken local session — lands in
+a later Designer-Mode phase; the trailer is the label it will key on.
+`Closes #<N>` links the tracking issue.
+
+Open the PR and embed the **before/after screenshots** in the body so the change
+is visible to reviewers and the operator:
+
+```bash
+gh pr create --base main --title "<plain, conventional-commit title>" \
+  --body "<what changed, before/after screenshots, Closes #<N>>"
+gh pr merge <PR#> --auto --squash
+```
+
+Auto-merge carries the PR into the merge queue; the full critic quorum, required
+checks, and review-thread resolution gate it. You do not admin-merge or bypass.
+
+## 4. Relay status in plain language
+
+Translate pipeline state into outcomes for the operator. Check the PR's
+automated checks (`gh pr checks`) and the merge-queue state, then say it plainly:
+
+- In review: *"It's in review with our automated checks — a couple passed, one
+  still running. I'll tell you when it's live."*
+- Merged: *"It's live."*
+- A check found something: fix it within the N=2 iteration ceiling (re-verify
+  the visuals after each fix). If it won't converge, or the fix needs work
+  outside your scope, switch to `/designer-handoff` — never surface the raw
+  finding or critic jargon to the operator.

package/skills/designer-ship/skill.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "../skill-schema.json",
+  "name": "designer-ship",
+  "version": "1.0.0",
+  "summary": "Designer Mode: confirm the brief's Done-when items, run gates, and open + auto-merge a PR with the Mode: designer and Closes #N trailers and before/after screenshots, relaying pipeline status to the operator in plain language.",
+  "originatingRepo": "momentiq-ai/dark-factory",
+  "files": [
+    { "template": "SKILL.md.tmpl", "target": "SKILL.md" }
+  ],
+  "variables": {
+    "REPO_NAME": {
+      "description": "Display name of the consumer repo (e.g. 'Taxpilot').",
+      "source": "darkfactory.yaml: repo.displayName",
+      "default": "this repo"
+    }
+  }
+}

package/skills/objectives/SKILL.md.tmpl

@@ -1,6 +1,6 @@
 ---
 name: objectives
-description: Use at PLAN TIME for any PR that implements a cycle's acceptance criteria — author the verifiable objectives contract before writing code. Run `df objectives derive --cycle <N> --apply` to generate .darkfactory/objectives.yaml from the linked cycle doc's Exit criteria, bind each objective's attestedBy to a real route or test, surface the manifest in your plan for agreement, then declare victory at closeout with `df prove` (not free-text "done").
+description: Use at PLAN TIME for any PR that implements a cycle's (or designer brief's) acceptance criteria — author the verifiable objectives contract before writing code. Run `df objectives derive --cycle <N> --apply` (or `--brief <path>` for a designer brief's Done-when checkboxes) to generate .darkfactory/objectives.yaml from the linked source, bind each objective's attestedBy to a real route or test, surface the manifest in your plan for agreement, then declare victory at closeout with `df prove` (not free-text "done").
 ---
 
 # /objectives — plan-time verifiable objectives authoring
@@ -51,6 +51,21 @@ recognized. Accepted item forms:
 Each criterion must be **one physical line**. Multi-line criteria are
 rejected because only that single line is hashed into the source binding.
 
+**Designer briefs (`--brief`):** for Designer Mode work, derive from a committed
+design brief instead of a cycle doc — `--cycle` and `--brief` are mutually
+exclusive sibling input sources:
+
+```bash
+# One objective per `## Done-when` checkbox in .darkfactory/briefs/<slug>.md
+df objectives derive --brief .darkfactory/briefs/<slug>.md --apply
+```
+
+Each `- [ ]`/`- [x]` checkbox under `## Done-when` becomes one objective with id
+`brief-<slug>#ac<k>` (`<slug>` from the brief filename), `source.kind: brief`, and
+the same `text-hash` binding. The checkbox state is stripped before hashing, so
+marking an item done never moves its hash. Bind / check / prove below are
+identical to the cycle path.
+
 The emitted manifest looks like:
 
 ```yaml

package/skills/verify/producer/ui-visual-surfaces.ts

@@ -0,0 +1,261 @@
+/**
+ * Auto-derived capture surfaces for the Dark Factory **`ui-visual`** verification
+ * route (Designer Mode, cycle 27 Phase C).
+ *
+ * The `playwright` route (`coverage.ts` + `ui-route.producer.spec.ts`) makes a
+ * human hand-author `SURFACES[]` — one entry per URL, with a `covers` glob and a
+ * copy-stable `requiredHeading`. That is right for an engineer who knows the app.
+ * A non-technical Designer-Mode operator cannot. `ui-visual` instead DERIVES the
+ * capture surfaces from the changed Next.js **app-router** files: a changed
+ * `app/pricing/page.tsx` maps to the URL `/pricing`, which the producer navigates
+ * and screenshots. No `SURFACES[]` to edit.
+ *
+ * This module is PURE (no browser, no fs, no Dark Factory / vendor dependency) and
+ * is the load-bearing half of the route — the path→URL mapping and the fail-closed
+ * classification — so it is unit-tested without a browser (mirroring `coverage.ts`).
+ *
+ * ── CONSUMER REFERENCE FILE — ships in the npm tarball next to `coverage.ts`;
+ *    copy it into your repo alongside `ui-visual.producer.spec.ts` and own it.
+ *    `df skills install verify` does NOT overwrite it.
+ */
+
+/** One capture surface derived from a changed app-router file. */
+export interface DerivedSurface {
+  /** URL path to navigate (relative to baseURL), e.g. "/", "/pricing". Dynamic
+   *  routes carry a `:param` placeholder (e.g. "/blog/:slug") and are NOT
+   *  directly navigable — see `dynamic`. */
+  path: string;
+  /** Filesystem-safe slug for the evidence subdir, e.g. "home", "pricing". */
+  slug: string;
+  /** The changed source path this surface is the evidence for. */
+  covers: string;
+  /** True when the route has a `[param]` / `[...catch]` segment: the producer
+   *  cannot navigate it without a concrete value, so it is recorded (for human
+   *  review) rather than auto-captured. */
+  dynamic: boolean;
+}
+
+export interface DerivedSurfacePartition {
+  /** Static, navigable surfaces — the producer captures each. De-duped by slug. */
+  surfaces: DerivedSurface[];
+  /** Dynamic routes touched by the change — recorded (need a concrete param),
+   *  not auto-navigated. De-duped by slug. */
+  dynamic: DerivedSurface[];
+  /** Changed product-UI paths with NO derivable route (a component, a lib, a
+   *  non-`app/` `*.tsx`). Auto-derivation cannot know which page renders a
+   *  component, so these FAIL CLOSED — the change must also touch the page(s)
+   *  that render them, or the operator adds an explicit surface. Mirrors the
+   *  `coverage.ts` fail-closed contract. */
+  uncovered: string[];
+}
+
+// App-router files that render a routable surface. `route.*` (API route
+// handlers) render no UI and are treated as non-visual (exempt). `default.*`
+// (parallel-route fallbacks) render UI at their segment, so they count.
+const ROUTE_FILE_BASENAMES = new Set(["page", "layout", "template", "default"]);
+const ROUTE_FILE_RE = /\.(tsx|jsx|ts|js)$/;
+
+/**
+ * Harness / non-UI files that are EXEMPT from the coverage requirement — the
+ * route's own machinery, styles, tests, type decls, config, data. A change to
+ * ONLY these does not require a capture (there is no rendered surface). Kept in
+ * sync with `coverage.ts`'s `NON_SURFACE_GLOBS` philosophy but self-contained.
+ */
+export const UI_VISUAL_NON_SURFACE_SUFFIXES: readonly string[] = [
+  ".css",
+  ".scss",
+  ".json",
+  ".md",
+  ".mdx",
+  ".d.ts",
+  ".test.ts",
+  ".test.tsx",
+  ".spec.ts",
+  ".spec.tsx",
+];
+
+function isNonSurface(path: string): boolean {
+  const lower = path.toLowerCase();
+  if (UI_VISUAL_NON_SURFACE_SUFFIXES.some((s) => lower.endsWith(s))) return true;
+  // The producer harness itself + Playwright config + test dirs.
+  if (/(^|\/)tests?(\/|$)/.test(lower)) return true;
+  if (/(^|\/)__tests__(\/|$)/.test(lower)) return true;
+  if (/(^|\/)(coverage|ui-visual-surfaces)\.ts$/.test(lower)) return true;
+  if (/playwright[^/]*\.config\.(ts|js|mjs|cjs)$/.test(lower)) return true;
+  if (/\.producer\.spec\.ts$/.test(lower)) return true;
+  return false;
+}
+
+/**
+ * Map one changed source path to a route surface, or `null` when it maps to no
+ * navigable route (a component, a private `_folder` colocation file, a file not
+ * under an `app/` router root, or an API `route.*` handler).
+ */
+export function deriveSurface(changedPath: string): DerivedSurface | null {
+  if (ROUTE_FILE_RE.test(changedPath) === false) return null;
+  const segments = changedPath.split("/");
+  const file = segments[segments.length - 1] ?? "";
+  const dotIdx = file.indexOf(".");
+  const base = dotIdx >= 0 ? file.slice(0, dotIdx) : file;
+  if (!ROUTE_FILE_BASENAMES.has(base)) return null;
+
+  // Locate the app-router root: the LAST `app` segment (handles `web/app/…`,
+  // `apps/web/src/app/…`, `src/app/…`). No `app/` root ⇒ not a routed file.
+  const appIdx = segments.lastIndexOf("app");
+  if (appIdx < 0) return null;
+
+  const routeDirSegments = segments.slice(appIdx + 1, segments.length - 1);
+  const urlSegments: string[] = [];
+  let dynamic = false;
+  for (const seg of routeDirSegments) {
+    // Route groups `(marketing)` and intercepting markers `(.)`,`(..)` — removed
+    // from the URL.
+    if (seg.startsWith("(") && seg.endsWith(")")) continue;
+    // Parallel-route slots `@modal` — not part of the URL.
+    if (seg.startsWith("@")) continue;
+    // Private folders `_components` opt OUT of routing — the file is colocation,
+    // not a route.
+    if (seg.startsWith("_")) return null;
+    // Dynamic segments `[slug]`, `[...all]`, `[[...opt]]` → `:slug` placeholder.
+    const dyn = seg.match(/^\[+\.{0,3}(.+?)\]+$/);
+    if (dyn) {
+      dynamic = true;
+      urlSegments.push(`:${dyn[1]}`);
+      continue;
+    }
+    urlSegments.push(seg);
+  }
+
+  const path = urlSegments.length === 0 ? "/" : `/${urlSegments.join("/")}`;
+  const slug = slugForUrl(urlSegments);
+  return { path, slug, covers: changedPath, dynamic };
+}
+
+function sanitizeSlug(raw: string): string {
+  return raw
+    .replace(/:/g, "")
+    .replace(/[^a-z0-9-]+/gi, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+}
+
+function slugForUrl(urlSegments: readonly string[]): string {
+  if (urlSegments.length === 0) return "home";
+  return sanitizeSlug(urlSegments.join("-"));
+}
+
+/**
+ * Partition changed paths (already restricted to the route's trigger surface —
+ * `web/**` / `*.tsx` — by `playwright-route.sh`) into the surfaces to capture,
+ * the dynamic routes to record, and the uncovered product paths that FAIL CLOSED.
+ *
+ * An empty `changed` (a manual run with the env unset) yields nothing derivable;
+ * the producer falls back to capturing the home surface so evidence is never zero.
+ */
+export function deriveSurfacesFromChangedPaths(
+  changed: readonly string[],
+): DerivedSurfacePartition {
+  const surfacesBySlug = new Map<string, DerivedSurface>();
+  const dynamicBySlug = new Map<string, DerivedSurface>();
+  const uncovered: string[] = [];
+
+  for (const raw of changed) {
+    const path = raw.trim();
+    if (!path) continue;
+    if (isNonSurface(path)) continue; // harness / non-UI — exempt.
+    const surface = deriveSurface(path);
+    if (surface === null) {
+      uncovered.push(path);
+      continue;
+    }
+    const bucket = surface.dynamic ? dynamicBySlug : surfacesBySlug;
+    if (!bucket.has(surface.slug)) bucket.set(surface.slug, surface);
+  }
+
+  return {
+    surfaces: [...surfacesBySlug.values()],
+    dynamic: [...dynamicBySlug.values()],
+    uncovered,
+  };
+}
+
+/**
+ * The home surface, smoke-captured when the change armed the route but derived NO
+ * navigable surface AND touched no dynamic/uncovered path (a harness-only or
+ * signal-less manual run) — so the route never passes with zero evidence.
+ */
+export const UI_VISUAL_HOME_FALLBACK: DerivedSurface = {
+  path: "/",
+  slug: "home",
+  covers: "(smoke)",
+  dynamic: false,
+};
+
+/** The producer's capture decision: what to navigate, or why to fail closed. */
+export interface CapturePlan {
+  /** Surfaces the producer captures (empty when `failClosed` is set). */
+  capture: DerivedSurface[];
+  /** Non-null when the route CANNOT produce real evidence and must fail the run
+   *  (a dynamic page that can't be auto-navigated, or an uncovered product path).
+   *  `null` means the plan is safe to capture. */
+  failClosed: { code: "uncovered" | "dynamic-unmapped"; paths: string[]; message: string } | null;
+}
+
+/**
+ * Decide what the `ui-visual` producer captures for a partition of changed paths,
+ * or whether it must FAIL CLOSED. The fail-closed contract (extracted here so it is
+ * unit-tested without a browser):
+ *
+ *  - `uncovered` path(s) present → fail closed (a bare component can't be evidenced
+ *    by rendering an unrelated surface).
+ *  - `dynamic` route(s) present → fail closed. A `[slug]` / `[...all]` page has no
+ *    auto-navigable URL, so this auto-derive route cannot evidence it; capturing
+ *    anything else (a static sibling, or the home fallback) would be a false pass
+ *    for the changed page. Dynamic pages belong to the engineer `playwright` route
+ *    (hand-authored concrete surfaces). Fail closed even when static surfaces are
+ *    also present — a run is all-or-nothing.
+ *  - otherwise capture the derived static surfaces; if there are none, smoke-capture
+ *    the home surface so evidence is never zero.
+ */
+export function planCapture(partition: DerivedSurfacePartition): CapturePlan {
+  const { surfaces, dynamic, uncovered } = partition;
+
+  if (uncovered.length > 0) {
+    return {
+      capture: [],
+      failClosed: {
+        code: "uncovered",
+        paths: [...uncovered],
+        message:
+          "ui-visual route: the following changed UI path(s) map to NO app-router " +
+          "surface, so this route cannot produce real evidence for them and FAILS " +
+          "CLOSED:\n" +
+          uncovered.map((p) => `  - ${p}`).join("\n") +
+          "\n\nAuto-derivation captures app-router pages (e.g. app/foo/page.tsx → " +
+          "/foo). A bare component has no route: also change (or add a page under " +
+          "app/ that renders) the affected UI, so the capture is real.",
+      },
+    };
+  }
+
+  if (dynamic.length > 0) {
+    return {
+      capture: [],
+      failClosed: {
+        code: "dynamic-unmapped",
+        paths: dynamic.map((d) => d.path),
+        message:
+          "ui-visual route: dynamic app-router page(s) changed. This auto-derive " +
+          "route does NOT support dynamic pages (a `[slug]` / `[...all]` route has " +
+          "no concrete URL to auto-navigate), so it FAILS CLOSED:\n" +
+          dynamic.map((d) => `  - ${d.covers} → ${d.path}`).join("\n") +
+          "\n\nCapture dynamic pages with the engineer `playwright` route instead " +
+          "(its hand-authored SURFACES[] take real params).",
+      },
+    };
+  }
+
+  if (surfaces.length > 0) return { capture: [...surfaces], failClosed: null };
+  return { capture: [UI_VISUAL_HOME_FALLBACK], failClosed: null };
+}

package/skills/verify/producer/ui-visual.config.ts

@@ -0,0 +1,22 @@
+/**
+ * Playwright config for the **`ui-visual` (Designer Mode) verification-route
+ * producer** (cycle 27 Phase C).
+ *
+ * DRY over the base UI-route config: it reuses every setting from
+ * `playwright.ui-route.config.ts` (one chromium project, no retries, optional
+ * storage-state, optional local-preview `webServer`, all the same env knobs) and
+ * changes ONLY `testMatch` so this config runs `ui-visual.producer.spec.ts`
+ * instead of `ui-route.producer.spec.ts`. Kept a separate file so the shared
+ * `playwright-route.sh` can select it via `DF_UI_ROUTE_CONFIG=ui-visual.config.ts`
+ * without disturbing the `playwright` route.
+ *
+ * ── CONSUMER REFERENCE FILE — copy into your repo next to the base config +
+ *    the producer spec and own it. `df skills install verify` does NOT overwrite it.
+ */
+import { defineConfig } from "@playwright/test";
+import base from "./playwright.ui-route.config";
+
+export default defineConfig({
+  ...base,
+  testMatch: /ui-visual\.producer\.spec\.ts$/,
+});