From aaa4f2d44868263098b9477e96abf3231ab0006c Mon Sep 17 00:00:00 2001
From: Matthew Cochran <matthew@cochranweb.com>
Date: Tue, 4 Aug 2026 18:33:50 -0400
Subject: [PATCH] feat(design): verify that referenced assets exist and are
 local
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Allowing local assets (#4) came with two rules and the pack could check neither.
Both failed live, in the same run.

BROKEN REFERENCES. The operator's brief named the artwork, but the filename list
was lost to a copy/paste slip, so the generator invented plausible names from the
story titles — art/dragon-under-stairs.png, art/gran-1953.png, art/tent-leaked.png,
art/bramble-vet.png — and wrote eight <img> tags pointing at nothing. The
candidate parsed as HTML, passed verify.candidate-renderable, scored, and was
carried toward the human as a legitimate direction. Two sibling candidates gave
up on imagery entirely rather than guess. FOUR generations were spent before
anyone noticed, and only because a person looked at the pixels — no gate in the
pipeline could see it.

NETWORK REFERENCES. "Renders with the network unplugged" is stated in both prompt
layers and verified nowhere. A CDN stylesheet or a hosted webfont renders
perfectly on the machine that made it and degrades silently everywhere else,
including in a headless screenshotter.

verify.assets-resolve scans src / srcset / href / poster and CSS url(...) in both
inline <style> and style="" attributes. A reference that is not a file (data:,
#fragment, mailto:) is ignored rather than resolved. An absolute or
protocol-relative URL is NETWORK_ASSET_REFERENCE on sight — never fetched, since
the point is that the page must not need the network. Anything else must resolve
to a file on disk beside the artifact, or it is BROKEN_ASSET_REFERENCE. A
root-relative path is broken by definition: a self-contained candidate has no
document root.

Wired as a gate in cap.implement.generate-direction, after the renderable check
and before `done`. This is the same discipline the pack already applies to
writes — the agent's claim is not trusted, deterministic code re-opens the
artifact, and a described-but-absent thing is a failure rather than a shrug.

Verified against the real artifacts: the live broken candidate fails naming all
four invented filenames; the candidate that used the five staged plates passes
with checked=5.

Tests: 148 pass (13 new) — the happy paths (markup, CSS url, srcset descriptors,
query strings), both failure modes, precedence when both are present, and the
things that are not file references at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../cap.implement.generate-direction.yaml     |  37 +++-
 scripts-library/assets.test.mjs               | 160 ++++++++++++++++++
 scripts-library/verify.assets-resolve.yaml    | 118 +++++++++++++
 3 files changed, 314 insertions(+), 1 deletion(-)
 create mode 100644 scripts-library/assets.test.mjs
 create mode 100644 scripts-library/verify.assets-resolve.yaml

diff --git a/capabilities/cap.implement.generate-direction.yaml b/capabilities/cap.implement.generate-direction.yaml
index cd693b8..1f5335c 100644
--- a/capabilities/cap.implement.generate-direction.yaml
+++ b/capabilities/cap.implement.generate-direction.yaml
@@ -68,6 +68,7 @@ workflows:
         candidate: { type: object }
     initialState: preparing
     initialContext:
+      assets_ok:   false
       renderable:  false
       candidate:   {}
       reason:      ""
@@ -232,7 +233,7 @@ workflows:
       verify_gate:
         transitions:
           ok:
-            target: done
+            target: checking_assets
             actor: deterministic
             guards:
               - { kind: expr, expr: "$.context.renderable == true" }
@@ -242,6 +243,40 @@ workflows:
             guards:
               - { kind: expr, expr: "$.context.renderable != true" }
 
+      # ASSET REFERENCES (#4 made local assets legal; nothing checked them).
+      # A candidate that references files which are not there renders as a page
+      # full of broken-image icons while parsing perfectly — observed live, and
+      # carried four generations toward a human before anyone noticed. A network
+      # reference is the same class: it renders here and fails everywhere else,
+      # including in the headless screenshotter.
+      checking_assets:
+        goal: Confirm every referenced asset is a local file that exists.
+        transitions:
+          check:
+            target: assets_gate
+            actor: deterministic
+            executor:
+              kind: script
+              subject: verify.assets-resolve
+              args:
+                - "{{ $.workflow.input.out_dir }}/candidate-{{ $.workflow.input.candidate_id }}.html"
+            output:
+              assets_ok: "$.output.json.assets_ok"
+              reason:    "$.output.json.reason"
+
+      assets_gate:
+        transitions:
+          ok:
+            target: done
+            actor: deterministic
+            guards:
+              - { kind: expr, expr: "$.context.assets_ok == true" }
+          broken:
+            target: failed
+            actor: deterministic
+            guards:
+              - { kind: expr, expr: "$.context.assets_ok != true" }
+
       done:
         terminal: true
         outcome: success
diff --git a/scripts-library/assets.test.mjs b/scripts-library/assets.test.mjs
new file mode 100644
index 0000000..2126098
--- /dev/null
+++ b/scripts-library/assets.test.mjs
@@ -0,0 +1,160 @@
+// assets.test.mjs — a referenced asset must actually be there, and must be local.
+//
+// #4 made local assets legal and the pack could check neither of the two rules
+// that came with them. Both failed live:
+//
+//   * The brief that named the artwork lost its filename list to a copy/paste
+//     slip. The generator invented plausible names from the story titles
+//     (`art/dragon-under-stairs.png`) and wrote eight <img> tags pointing at
+//     nothing. The candidate parsed, passed verify.candidate-renderable, scored,
+//     and was on its way to a human as a legitimate direction. Four generations
+//     went by; a person looking at the pixels caught it, not the pipeline.
+//
+//   * "Renders with the network unplugged" is stated in both prompt layers and
+//     verified nowhere. A CDN font would look perfect on the machine that made
+//     it and degrade silently everywhere else.
+//
+// Same discipline the pack already applies to writes: the claim is not trusted,
+// deterministic code re-opens the artifact, and a described-but-absent thing is
+// a failure rather than a shrug.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, writeFileSync, mkdtempSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function bodyRunner(yamlName) {
+  const raw = readFileSync(join(HERE, yamlName), "utf8");
+  const lines = raw.split("\n");
+  const i = lines.findIndex((l) => /^\s*body:\s*\|\s*$/.test(l));
+  assert.ok(i >= 0, `no 'body: |' block in ${yamlName}`);
+  const indent = lines[i].match(/^(\s*)/)[1].length + 2;
+  const out = [];
+  for (let k = i + 1; k < lines.length; k++) {
+    const l = lines[k];
+    if (l.trim() === "") { out.push(""); continue; }
+    if (l.match(/^(\s*)/)[1].length < indent) break;
+    out.push(l.slice(indent));
+  }
+  const file = join(mkdtempSync(join(tmpdir(), "as-")), yamlName.replace(/\.yaml$/, ".js"));
+  writeFileSync(file, out.join("\n"));
+  return file;
+}
+
+const CHECK = bodyRunner("verify.assets-resolve.yaml");
+
+// Build a candidate directory with a real art/ folder, then check some markup.
+function check(bodyHtml, { assets = ["art/plate-one.png"] } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "as-run-"));
+  for (const a of assets) {
+    mkdirSync(join(dir, dirname(a)), { recursive: true });
+    writeFileSync(join(dir, a), "PNGDATA");
+  }
+  const artifact = join(dir, "candidate-c1.html");
+  writeFileSync(artifact, `<!doctype html><html><body>${bodyHtml}</body></html>`);
+  return JSON.parse(execFileSync("node", [CHECK, artifact], { encoding: "utf8" }));
+}
+
+// --- the happy path ---------------------------------------------------------
+
+test("a candidate referencing files that exist passes", () => {
+  const out = check(`<img src="art/plate-one.png" alt="a plate">`);
+  assert.equal(out.assets_ok, true);
+  assert.equal(out.checked, 1);
+});
+
+test("CSS url() references are checked too, not just markup", () => {
+  const out = check(`<div style="background-image:url('art/plate-one.png')"></div>`);
+  assert.equal(out.assets_ok, true);
+  assert.equal(out.checked, 1);
+});
+
+test("srcset candidates are split off their descriptors before resolving", () => {
+  const out = check(
+    `<img srcset="art/plate-one.png 1x, art/plate-two.png 2x" src="art/plate-one.png">`,
+    { assets: ["art/plate-one.png", "art/plate-two.png"] },
+  );
+  assert.equal(out.assets_ok, true);
+});
+
+test("a query string or fragment does not make a real file look missing", () => {
+  const out = check(`<img src="art/plate-one.png?v=2"><img src="art/plate-one.png#frag">`);
+  assert.equal(out.assets_ok, true);
+});
+
+// --- the failure observed live ---------------------------------------------
+
+test("invented filenames are BROKEN_ASSET_REFERENCE", () => {
+  const out = check(`
+    <img src="art/dragon-under-stairs.png" alt="the dragon">
+    <img src="art/gran-1953.png" alt="gran">
+    <img src="art/plate-one.png" alt="a real one">`);
+  assert.equal(out.assets_ok, false);
+  assert.equal(out.reason, "BROKEN_ASSET_REFERENCE");
+  assert.equal(out.missing_count, 2);
+  assert.ok(out.missing.includes("art/dragon-under-stairs.png"));
+  assert.ok(!out.missing.includes("art/plate-one.png"), "the file that exists is not reported");
+});
+
+test("a root-relative path is broken — a self-contained page has no document root", () => {
+  const out = check(`<img src="/art/plate-one.png">`);
+  assert.equal(out.assets_ok, false);
+  assert.equal(out.reason, "BROKEN_ASSET_REFERENCE");
+});
+
+// --- the network rule, finally enforced -------------------------------------
+
+test("a CDN stylesheet is NETWORK_ASSET_REFERENCE", () => {
+  const out = check(`<link rel="stylesheet" href="https://cdn.example.com/x.css">`);
+  assert.equal(out.assets_ok, false);
+  assert.equal(out.reason, "NETWORK_ASSET_REFERENCE");
+  assert.equal(out.network_count, 1);
+});
+
+test("a protocol-relative URL is a network reference too", () => {
+  const out = check(`<img src="//images.example.com/hero.png">`);
+  assert.equal(out.assets_ok, false);
+  assert.equal(out.reason, "NETWORK_ASSET_REFERENCE");
+});
+
+test("a remote webfont in CSS is caught", () => {
+  const out = check(`<style>@font-face{font-family:X;src:url("https://fonts.example.com/x.woff2")}</style>`);
+  assert.equal(out.assets_ok, false);
+  assert.equal(out.network_count, 1);
+});
+
+// Network is the stricter rule and the one that fails on someone else's
+// machine, so it names the reason when both are present.
+test("network takes precedence over broken when both are present", () => {
+  const out = check(`<img src="https://x.example/a.png"><img src="art/nope.png">`);
+  assert.equal(out.reason, "NETWORK_ASSET_REFERENCE");
+  assert.equal(out.missing_count, 1, "the broken one is still reported");
+  assert.equal(out.network_count, 1);
+});
+
+// --- things that are not file references at all ------------------------------
+
+test("data: URIs, anchors and mailto are ignored, not resolved", () => {
+  const out = check(`
+    <img src="data:image/png;base64,iVBORw0KGgo=">
+    <a href="#main">skip</a>
+    <a href="mailto:someone@example.com">mail</a>`);
+  assert.equal(out.assets_ok, true);
+  assert.equal(out.checked, 0, "none of these are files to look for");
+});
+
+test("an inline <svg> needs no assets and passes cleanly", () => {
+  const out = check(`<svg viewBox="0 0 10 10"><circle cx="5" cy="5" r="4"/></svg>`);
+  assert.equal(out.assets_ok, true);
+});
+
+test("an unreadable artifact is a hard error, not a silent pass", () => {
+  assert.throws(() =>
+    execFileSync("node", [CHECK, join(tmpdir(), "no-such-candidate.html")], { encoding: "utf8", stdio: "pipe" }),
+  );
+});
diff --git a/scripts-library/verify.assets-resolve.yaml b/scripts-library/verify.assets-resolve.yaml
new file mode 100644
index 0000000..258ca0f
--- /dev/null
+++ b/scripts-library/verify.assets-resolve.yaml
@@ -0,0 +1,118 @@
+# scripts-library/verify.assets-resolve.yaml
+#
+# Make the two asset rules DETERMINISTIC instead of merely instructed.
+#
+# Allowing local assets (#4) traded one failure mode for two, and the pack could
+# detect neither:
+#
+#   1. A REFERENCE TO A FILE THAT IS NOT THERE. Observed live: the operator's
+#      brief named the artwork but a copy/paste slip dropped the filename list,
+#      so the generator invented plausible names from the story titles —
+#      `art/dragon-under-stairs.png`, `art/gran-1953.png` — and wrote eight
+#      <img> tags pointing at nothing. The candidate parsed as HTML, passed
+#      verify.candidate-renderable, scored, and was carried toward the human as
+#      a legitimate direction. Four generations were spent before anyone noticed,
+#      and only because a human looked at the pixels.
+#
+#   2. A NETWORK REFERENCE. "Renders with the network unplugged" is stated in
+#      both prompt layers and checked by nothing. A CDN stylesheet or a Google
+#      Fonts link would render beautifully on the machine that made it and
+#      degrade silently anywhere else — including in the headless screenshotter.
+#
+# Both are the pack's own discipline applied to the newest surface: the agent's
+# claim is not trusted, deterministic code re-opens the artifact, and a
+# described-but-absent thing is a failure rather than a shrug.
+#
+# WHAT IS SCANNED: src / srcset / href / poster on any element, CSS url(...) in
+# both inline <style> and style="" attributes, and SVG <image href>. Ignored,
+# because they are not file references: data: URIs, fragment-only (#x),
+# mailto:/tel:, and empty values.
+#
+#   Args: [artifact_path]
+#
+# Emits (ALWAYS exit 0 — routing belongs to the caller's gate):
+#   { assets_ok: true,  checked: N, missing: [], network: [], reason: "" }
+#   { assets_ok: false, checked: N, missing: [...], network: [...],
+#     reason: "BROKEN_ASSET_REFERENCE" | "NETWORK_ASSET_REFERENCE" }
+# Only an unreadable artifact is a hard error (exit 2).
+version: "1.0.0"
+scripts:
+  verify.assets-resolve:
+    verb: verify
+    lifecycle: experimental
+    source: design
+    body: |
+      #!/usr/bin/env node
+      // Deterministic asset-reference check. No LLM, no network — it never
+      // FETCHES anything; a network reference is a failure, not a request.
+      const { existsSync, statSync, readFileSync } = require("node:fs");
+      const { dirname, resolve, join } = require("node:path");
+
+      const artifact = process.argv[2];
+      if (!artifact || !existsSync(artifact)) {
+        console.error(JSON.stringify({ error: "ARTIFACT_MISSING", path: artifact || "" }));
+        process.exit(2);
+      }
+      const html = readFileSync(artifact, "utf8");
+      const base = dirname(resolve(artifact));
+
+      const refs = new Set();
+      const add = (v) => {
+        const s = String(v || "").trim();
+        if (s) refs.add(s);
+      };
+
+      // Attribute references. srcset carries a comma-separated candidate list
+      // with descriptors ("a.png 2x"), so split it before taking the URL half.
+      for (const m of html.matchAll(/\b(?:src|href|poster)\s*=\s*["']([^"']+)["']/gi)) add(m[1]);
+      for (const m of html.matchAll(/\bsrcset\s*=\s*["']([^"']+)["']/gi)) {
+        for (const part of m[1].split(",")) add(part.trim().split(/\s+/)[0]);
+      }
+      // CSS url(...) — inline <style> blocks and style="" attributes alike.
+      for (const m of html.matchAll(/url\(\s*["']?([^"')]+)["']?\s*\)/gi)) add(m[1]);
+
+      const missing = [];
+      const network = [];
+      let checked = 0;
+
+      for (const ref of refs) {
+        // Not file references at all.
+        if (/^data:/i.test(ref)) continue;
+        if (/^(?:mailto|tel|javascript):/i.test(ref)) continue;
+        if (ref.startsWith("#")) continue;
+
+        // A network reference: absolute URL or protocol-relative. The page must
+        // render with the network unplugged, so this is a failure on sight —
+        // never something to go and check.
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(ref) || ref.startsWith("//")) {
+          network.push(ref);
+          continue;
+        }
+
+        checked++;
+        // Strip any query/fragment before touching the filesystem.
+        const clean = ref.split("#")[0].split("?")[0];
+        if (!clean) continue;
+        // A root-relative path has no meaning for a self-contained candidate —
+        // there is no document root to resolve it against.
+        const abs = clean.startsWith("/") ? clean : resolve(join(base, clean));
+        if (!existsSync(abs) || !statSync(abs).isFile()) missing.push(ref);
+      }
+
+      if (missing.length === 0 && network.length === 0) {
+        console.log(JSON.stringify({ assets_ok: true, checked, missing: [], network: [], reason: "" }));
+        process.exit(0);
+      }
+      console.log(JSON.stringify({
+        assets_ok: false,
+        checked,
+        // Bounded so a pathological artifact cannot flood the run context; the
+        // counts stay exact.
+        missing: missing.slice(0, 25),
+        network: network.slice(0, 25),
+        missing_count: missing.length,
+        network_count: network.length,
+        // Network is reported first when both are present: it is the stricter
+        // rule and the one that fails on someone else's machine rather than here.
+        reason: network.length ? "NETWORK_ASSET_REFERENCE" : "BROKEN_ASSET_REFERENCE",
+      }));