@plainconceptsplatform/workflows 1.17.0 → 1.18.0

package/loops/actions/capture-mockup/action.yml

@@ -0,0 +1,91 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/capture-mockup/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Capture mockup
+description: >
+  Checks a UX mockup folder (index.html and mockup.json, written by the harness skill
+  pc-plan-mockup) against its contract and, when it holds, renders it in headless Chromium at
+  desktop and mobile widths. Writes index.html, mockup.json, desktop.png and mobile.png to the
+  output folder. A mockup that breaks the contract is reported and not rendered. No model, and the
+  browser runs with no network.
+inputs:
+  mockup-dir:
+    description: Folder holding index.html and mockup.json.
+    required: true
+  out-dir:
+    description: Where the rendered folder is written.
+    required: true
+  playwright-version:
+    description: playwright-core version. Must match the mcr.microsoft.com/playwright image tag the render runs in.
+    required: false
+    default: '1.62.1'
+outputs:
+  valid:
+    description: true when the mockup met the contract and was rendered.
+    value: ${{ steps.render.outputs.valid }}
+  problems:
+    description: Why the mockup was refused, one reason per line. Empty when valid.
+    value: ${{ steps.check.outputs.problems }}
+  title:
+    description: The mockup's title from mockup.json.
+    value: ${{ steps.check.outputs.title }}
+runs:
+  using: composite
+  steps:
+    - name: Check the mockup against its contract
+      id: check
+      shell: bash
+      env:
+        MOCKUP_DIR: ${{ inputs.mockup-dir }}
+        ACTION_DIR: ${{ github.action_path }}
+      run: |
+        set -euo pipefail
+        report="$(node "$ACTION_DIR/capture.mjs" validate "$MOCKUP_DIR")"
+        valid="$(jq -r '.valid' <<<"$report")"
+        echo "valid=$valid" >> "$GITHUB_OUTPUT"
+        echo "title=$(jq -r '.mockup.title // ""' <<<"$report" | tr -d '\n')" >> "$GITHUB_OUTPUT"
+        {
+          echo "problems<<MOCKUP_EOF"
+          jq -r '.problems[]' <<<"$report"
+          echo "MOCKUP_EOF"
+        } >> "$GITHUB_OUTPUT"
+        if [ "$valid" != "true" ]; then
+          jq -r '.problems[] | "::warning::mockup refused: " + .' <<<"$report"
+        fi
+
+    - name: Render the mockup
+      id: render
+      shell: bash
+      env:
+        VALID: ${{ steps.check.outputs.valid }}
+        MOCKUP_DIR: ${{ inputs.mockup-dir }}
+        OUT_DIR: ${{ inputs.out-dir }}
+        PLAYWRIGHT_VERSION: ${{ inputs.playwright-version }}
+        ACTION_DIR: ${{ github.action_path }}
+      run: |
+        set -euo pipefail
+        if [ "$VALID" != "true" ]; then
+          echo "valid=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        runner="$RUNNER_TEMP/capture-mockup"
+        mkdir -p "$runner" "$OUT_DIR"
+        # A copy beside its node_modules: ESM resolves bare imports from the file's own directory.
+        cp "$ACTION_DIR/capture.mjs" "$runner/capture.mjs"
+        if [ ! -d "$runner/node_modules/playwright-core" ]; then
+          npm install --prefix "$runner" --no-save --no-package-lock --no-audit --no-fund \
+            "playwright-core@${PLAYWRIGHT_VERSION}"
+        fi
+        src="$(cd "$MOCKUP_DIR" && pwd)"
+        out="$(cd "$OUT_DIR" && pwd)"
+        if command -v docker > /dev/null 2>&1; then
+          # The Playwright image carries Chromium and its libraries; the runner has neither. No
+          # network at all: the HTML was written by an agent and has no reason to reach anything.
+          docker run --rm --network none --ipc host \
+            --user "$(id -u):$(id -g)" -e HOME=/tmp \
+            -v "$runner:$runner:ro" -v "$src:$src:ro" -v "$out:$out" \
+            "mcr.microsoft.com/playwright:v${PLAYWRIGHT_VERSION}-noble" \
+            node "$runner/capture.mjs" render "$src" "$out"
+        else
+          node "$runner/node_modules/playwright-core/cli.js" install --only-shell chromium
+          node "$runner/capture.mjs" render "$src" "$out"
+        fi
+        echo "valid=true" >> "$GITHUB_OUTPUT"

package/loops/actions/capture-mockup/capture.mjs

@@ -0,0 +1,132 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/actions/capture-mockup/capture.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+//
+// Checks a UX mockup against the contract in the agent harness (pc-plan-mockup's
+// mockup-contract.md) and renders it to PNG. No model runs here: the mockup was written by the
+// refine agent or by a person with /plan-mockup, and this only checks and photographs it.
+//
+//   node capture.mjs validate <mockup-dir>
+//     prints {"valid","problems","mockup"} as JSON and exits 0 either way
+//   node capture.mjs render <mockup-dir> <out-dir>
+//     copies index.html and mockup.json to <out-dir> and writes desktop.png and mobile.png there
+//
+// The HTML is agent-written, so the browser runs with every request outside the file refused,
+// and the action runs it in a container with no network at all.
+
+import { copyFile, mkdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const MAX_HTML_BYTES = 400 * 1024;
+export const BANNER = "UX mockup: intent, not a spec";
+export const VIEWPORTS = [
+  { file: "desktop.png", width: 1440, height: 900 },
+  { file: "mobile.png", width: 390, height: 844 },
+];
+const SECTION_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const STATES = new Set(["default", "empty", "loading", "error", "success", "disabled", "mobile"]);
+
+const attributeValues = (html, name) =>
+  [...html.matchAll(new RegExp(`\\b${name}\\s*=\\s*["']([^"']*)["']`, "gi"))].map((match) => match[1].trim());
+
+// What the contract forbids, as the reasons a person reading the run would want.
+export function htmlProblems(html) {
+  const problems = [];
+  if (Buffer.byteLength(html, "utf8") > MAX_HTML_BYTES) problems.push(`index.html is over ${MAX_HTML_BYTES / 1024} KB`);
+  if (/\b(?:src|href|action|poster|srcset)\s*=\s*["']?\s*(?:https?:)?\/\//i.test(html)) problems.push("index.html loads something from another host");
+  if (/url\(\s*["']?\s*(?:https?:)?\/\//i.test(html) || /@import\s+(?:url\()?\s*["']?\s*(?:https?:)?\/\//i.test(html)) problems.push("index.html styles load something from another host");
+  if (/<script\b[^>]*\bsrc\s*=/i.test(html)) problems.push("index.html loads a script file");
+  if (/<link\b[^>]*\brel\s*=\s*["']?stylesheet/i.test(html)) problems.push("index.html links a stylesheet file");
+  if (!html.includes(BANNER)) problems.push(`index.html has no "${BANNER}" banner`);
+  return problems;
+}
+
+export function mockupProblems(mockup, html) {
+  const problems = [];
+  if (mockup === null || typeof mockup !== "object" || Array.isArray(mockup)) return ["mockup.json is not an object"];
+  if (mockup.version !== 1) problems.push("mockup.json version is not 1");
+  if (typeof mockup.title !== "string" || !mockup.title.trim()) problems.push("mockup.json has no title");
+  const sections = Array.isArray(mockup.sections) ? mockup.sections : [];
+  if (sections.length === 0) problems.push("mockup.json lists no sections");
+  const ids = sections.map((section) => section?.id);
+  for (const id of ids) {
+    if (typeof id !== "string" || !SECTION_ID.test(id)) problems.push(`section id ${JSON.stringify(id)} is not kebab-case`);
+  }
+  const inHtml = attributeValues(html, "data-mockup-section");
+  if (inHtml.length === 0) problems.push("index.html has no data-mockup-section");
+  const missing = ids.filter((id) => typeof id === "string" && !inHtml.includes(id));
+  if (missing.length > 0) problems.push(`sections missing from index.html: ${missing.join(", ")}`);
+  const undeclared = [...new Set(inHtml)].filter((id) => !ids.includes(id));
+  if (undeclared.length > 0) problems.push(`sections in index.html but not in mockup.json: ${undeclared.join(", ")}`);
+  const components = Array.isArray(mockup.components) ? mockup.components : [];
+  if (components.length === 0) problems.push("mockup.json maps no components");
+  for (const entry of components) {
+    if (!entry || typeof entry.component !== "string" || typeof entry.path !== "string" || !entry.component || !entry.path) {
+      problems.push(`component entry ${JSON.stringify(entry)} needs a component and a path`);
+    } else if (entry.section !== undefined && !ids.includes(entry.section)) {
+      problems.push(`component ${entry.component} names unknown section ${entry.section}`);
+    }
+  }
+  if (attributeValues(html, "data-component").length === 0) problems.push("index.html has no data-component");
+  for (const state of Array.isArray(mockup.states) ? mockup.states : []) {
+    if (typeof state !== "string" || (!STATES.has(state) && !SECTION_ID.test(state))) problems.push(`state ${JSON.stringify(state)} is not a known or kebab-case state`);
+  }
+  return problems;
+}
+
+export async function validate(dir) {
+  let html;
+  try {
+    html = await readFile(join(dir, "index.html"), "utf8");
+  } catch {
+    return { valid: false, problems: ["index.html is missing"], mockup: null };
+  }
+  let mockup;
+  try {
+    mockup = JSON.parse(await readFile(join(dir, "mockup.json"), "utf8"));
+  } catch {
+    return { valid: false, problems: ["mockup.json is missing or not JSON", ...htmlProblems(html)], mockup: null };
+  }
+  const problems = [...htmlProblems(html), ...mockupProblems(mockup, html)];
+  return { valid: problems.length === 0, problems, mockup };
+}
+
+export async function render(dir, out) {
+  const { chromium } = await import("playwright-core");
+  await mkdir(out, { recursive: true });
+  await copyFile(join(dir, "index.html"), join(out, "index.html"));
+  await copyFile(join(dir, "mockup.json"), join(out, "mockup.json"));
+  const page_url = pathToFileURL(join(out, "index.html")).href;
+  const browser = await chromium.launch({ headless: true });
+  try {
+    for (const viewport of VIEWPORTS) {
+      const context = await browser.newContext({ viewport: { width: viewport.width, height: viewport.height }, javaScriptEnabled: true });
+      // The contract already refuses remote URLs; this makes a slip harmless rather than a request.
+      await context.route("**/*", (route) => (route.request().url().startsWith("file:") ? route.continue() : route.abort()));
+      const page = await context.newPage();
+      await page.goto(page_url, { waitUntil: "load", timeout: 30000 });
+      await page.screenshot({ path: join(out, viewport.file), type: "png", fullPage: true });
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+  for (const viewport of VIEWPORTS) await stat(join(out, viewport.file));
+}
+
+async function main(argv) {
+  const [mode, dir, out] = argv;
+  if (mode === "validate" && dir) {
+    process.stdout.write(`${JSON.stringify(await validate(dir))}\n`);
+    return 0;
+  }
+  if (mode === "render" && dir && out) {
+    await render(dir, out);
+    return 0;
+  }
+  process.stderr.write("usage: capture.mjs validate <mockup-dir> | render <mockup-dir> <out-dir>\n");
+  return 2;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/loops/actions/load-mockup/action.yml

@@ -0,0 +1,72 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/load-mockup/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Load mockup
+description: >
+  Copies an issue's published UX mockup from the mockups branch into a local folder for the agent
+  to read. The folder is the one the issue's mockup section names (a split child names its
+  parent's), else issue-<number>. Writes nothing and reports found=false when there is no mockup.
+inputs:
+  token:
+    description: Token with contents read on this repository.
+    required: true
+  issue-number:
+    description: Issue whose mockup to load.
+    required: true
+  branch:
+    description: Branch the mockups are published on.
+    required: false
+    default: mockups
+  out-dir:
+    description: Folder the mockup files are written to.
+    required: true
+outputs:
+  found:
+    description: true when a mockup was copied.
+    value: ${{ steps.load.outputs.found }}
+  folder:
+    description: The branch folder it came from, such as issue-42.
+    value: ${{ steps.load.outputs.folder }}
+runs:
+  using: composite
+  steps:
+    - name: Copy the mockup
+      id: load
+      uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+      env:
+        ISSUE_NUMBER: ${{ inputs.issue-number }}
+        BRANCH: ${{ inputs.branch }}
+        OUT_DIR: ${{ inputs.out-dir }}
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const fs = require('fs');
+          const path = require('path');
+          const issue_number = Number(process.env.ISSUE_NUMBER);
+          const ref = process.env.BRANCH;
+          const { data: issue } = await github.rest.issues.get({ ...context.repo, issue_number });
+          const named = /<!-- agent-mockup: (issue-\d+) -->/.exec(issue.body || '');
+          const folder = named ? named[1] : `issue-${issue_number}`;
+          let entries;
+          try {
+            ({ data: entries } = await github.rest.repos.getContent({ ...context.repo, path: folder, ref }));
+          } catch (error) {
+            if (error.status !== 404) throw error;
+            core.info(`No mockup at ${ref}:${folder}.`);
+            core.setOutput('found', 'false');
+            return;
+          }
+          const files = (Array.isArray(entries) ? entries : []).filter((entry) => entry.type === 'file');
+          if (!files.some((entry) => entry.name === 'index.html')) {
+            core.info(`${ref}:${folder} has no index.html.`);
+            core.setOutput('found', 'false');
+            return;
+          }
+          fs.mkdirSync(process.env.OUT_DIR, { recursive: true });
+          // The blob API returns base64 for any size, where the contents API leaves files over
+          // 1 MB empty and a full-page screenshot can be larger than that.
+          for (const entry of files) {
+            const { data } = await github.rest.git.getBlob({ ...context.repo, file_sha: entry.sha });
+            fs.writeFileSync(path.join(process.env.OUT_DIR, entry.name), Buffer.from(data.content, 'base64'));
+          }
+          core.info(`Loaded ${files.length} file(s) from ${ref}:${folder}.`);
+          core.setOutput('found', 'true');
+          core.setOutput('folder', folder);

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -792,6 +792,9 @@ for ci in "${WORKFLOWS_DIR}/ci.yml" "${WORKFLOWS_DIR}/app-ci.yml"; do
 done
 for template in "${HERE}/../../templates/ci/"*.yml; do
   [ -f "$template" ] || continue
+  # Only a template that runs on pull requests has a verdict to hand over. The weekly mutation
+  # run is deliberately never on a pull request (quality-mutation.yml), so it has none.
+  grep -qE '^  pull_request(_target)?:' "$template" || continue
   if grep -q 'operation=merge-train' "$template" && ! grep -q "pull_request.user.type == 'Bot'" "$template"; then
     PASS=$((PASS + 1))
   else
@@ -2265,6 +2268,70 @@ fi
 
 if [ "$EV_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
+echo "── UX mockups ────────────────────────────────────────────────────────────"
+
+# Refine draws a mockup (harness skill pc-plan-mockup) for frontend stories; implement reads it as
+# intent. The mockup is agent-written HTML, so it is rendered where nothing can be written and
+# published where nothing from the repository runs, exactly like evidence's screenshots.
+MK_OK=1
+mk() {
+  grep -qE "$1" "$2" || { MK_OK=0; echo "FAIL: mockups: $3" >&2; }
+}
+for action in capture-mockup load-mockup; do
+  [ -f "${HERE}/../${action}/action.yml" ] || { MK_OK=0; echo "FAIL: mockups: the ${action} action is missing" >&2; }
+done
+[ -f "${HERE}/../capture-mockup/capture.mjs" ] || { MK_OK=0; echo "FAIL: mockups: capture-mockup has no capture.mjs" >&2; }
+grep -q -- '--network none' "${HERE}/../capture-mockup/action.yml" ||
+  { MK_OK=0; echo "FAIL: mockups: the render must run with no network; the HTML is agent-written" >&2; }
+
+if worker_installed refine; then
+  REFINE_WORKER_MD="${WORKFLOWS_DIR}/agent-refine.md"
+  for key in MOCKUP_PATHS MOCKUP_BRANCH MOCKUP_DIR MOCKUP_PLAYWRIGHT_VERSION MOCKUP_INTENT_LINE; do
+    mk "^  ${key}: " "$REFINE_WORKER_MD" "agent-refine.md env does not declare ${key}"
+  done
+  mk 'skill\("pc-plan-mockup"\)' "$REFINE_WORKER_MD" 'refine never calls pc-plan-mockup'
+  mk 'uses: \./\.github/actions/load-mockup' "$REFINE_WORKER_MD" 'refine does not load an existing mockup for the agent'
+  mk 'Mockup sections: <ids>' "$REFINE_WORKER_MD" 'split children are not told to name their mockup sections'
+  render_job="$(sed -n '/^  mockup_render:/,/^  mockup_publish:/p' "$REFINE_WORKER_MD")"
+  publish_job="$(sed -n '/^  mockup_publish:/,/^  conclude:/p' "$REFINE_WORKER_MD")"
+  if [ -z "$render_job" ] || [ -z "$publish_job" ]; then
+    MK_OK=0; echo "FAIL: mockups: refine has no mockup_render and mockup_publish jobs" >&2
+  fi
+  # A custom job that does not need the agent is hoisted before it by gh-aw, and publish then
+  # closes a cycle through render: the compiler refuses the whole worker.
+  grep -qE '^    needs: \[activation, agent, mockup_render\]' <<<"$publish_job" ||
+    { MK_OK=0; echo "FAIL: mockups: mockup_publish must need agent, or gh-aw hoists it into a cycle" >&2; }
+  if grep -qE 'secrets\.|contents: write|issues: write' <<<"$render_job"; then
+    MK_OK=0; echo "FAIL: mockups: mockup_render runs agent-written HTML and must hold no secret and no write" >&2
+  fi
+  if grep -qE 'actions/checkout|uses: \./' <<<"$publish_job"; then
+    MK_OK=0; echo "FAIL: mockups: mockup_publish holds a write token and must not check out or run repository code" >&2
+  fi
+  grep -qF 'git push -q origin "HEAD:refs/heads/$BRANCH"' <<<"$publish_job" ||
+    { MK_OK=0; echo "FAIL: mockups: the mockup must be pushed to MOCKUP_BRANCH and nowhere else" >&2; }
+  for job in "$render_job" "$publish_job"; do
+    grep -q 'continue-on-error: true' <<<"$job" ||
+      { MK_OK=0; echo "FAIL: mockups: a mockup job must never fail the refinement" >&2; }
+  done
+  conclude_needs="$(grep -E '^    needs: \[activation, agent, safe_outputs, validate_output' "$REFINE_WORKER_MD" | grep 'mockup_publish' || true)"
+  [ -n "$conclude_needs" ] || { MK_OK=0; echo "FAIL: mockups: conclude must wait for mockup_publish to stamp the section" >&2; }
+  mk 'name: Record the mockup on the issue' "$REFINE_WORKER_MD" 'conclude never records the mockup on the issue'
+fi
+
+if worker_installed implement; then
+  mk 'uses: \./\.github/actions/load-mockup' "$IMPLEMENT_WORKER_MD" 'implement does not load the mockup for the agent'
+  mk 'The UX mockup is intent, not a spec' "$IMPLEMENT_WORKER_MD" 'implement does not say the mockup is intent, not a spec'
+  mk 'Never copy its markup' "$IMPLEMENT_WORKER_MD" 'implement does not forbid copying the mockup markup'
+fi
+if worker_installed merge-gate; then
+  mk 'looks different from it is never a finding' "$MERGE_GATE_WORKER_MD" 'merge-gate may count a visual difference from the mockup as a finding'
+  mk 'never the mockup' "$MERGE_GATE_WORKER_MD" 'merge-gate may judge acceptance criteria against the mockup'
+fi
+[ -f "${HERE}/../../templates/quality-gates/.semgrep/platform-mockup-leak.yml" ] ||
+  { MK_OK=0; echo "FAIL: mockups: the Semgrep rule that catches copied mockup markup is missing" >&2; }
+
+if [ "$MK_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
 echo "── Expression functions ──────────────────────────────────────────────────"
 
 # GitHub's expression language has eleven functions and no more. There is no `split()`, no
@@ -3671,7 +3738,9 @@ if worker_installed implement; then
     STACK_OK=0
     echo "FAIL: agent-implement.md declares allowed-base-branches more than once or not at all" >&2
   fi
-  if ! sed -n '/allowed-base-branches:/,/^  [a-z]/p' "$IMPLEMENT_WORKER_MD" | grep -q '"main"'; then
+  # `grep -q` would exit on the first match and SIGPIPE the sed still writing, which pipefail
+  # reports as a failure: the check passed or failed on timing. Read the whole block instead.
+  if ! sed -n '/allowed-base-branches:/,/^  [a-z]/p' "$IMPLEMENT_WORKER_MD" | grep '"main"' >/dev/null; then
     STACK_OK=0
     echo "FAIL: agent-implement.md allowed-base-branches dropped the default branch" >&2
   fi

package/loops/docs/diagrams.md

@@ -253,6 +253,10 @@ estimate of 8 or more is split into children of 3 to 5 points, and each child wa
 alone. A slice smaller than 3 points is a fragment and is folded into a sibling.
 The refined story is wrapped in the repository's own issue form, and when questions remain the
 worker leaves a temporal draft on the issue and asks everything in one batched comment.
+A frontend story gets a UX mockup first: the one a person published with `/plan-mockup`, or one the
+harness skill `pc-plan-mockup` draws from the repository's own tokens and components. Two jobs with
+no model render it and push it to the `mockups` branch, and conclude stamps the picture, the link
+and the component table on the issue, and each child's own sections on each child.
 
 ```mermaid
 flowchart TD
@@ -262,7 +266,13 @@ flowchart TD
     refExplore("Explore (rung 5)<br/>one work unit at a time,<br/>self-answer from the code,<br/>at most 5 questions each") --> refClassify
     refClassify{"Trivial?<br/>every TRIVIAL_CRITERIA<br/>condition holds"}
     refClassify -->|yes| refTrivial
-    refClassify -->|no| refStory
+    refClassify -->|no| refUi
+    refUi{"Frontend?<br/>a work unit matches MOCKUP_PATHS"}
+    refUi -->|yes| refMockup
+    refUi -->|no| refStory
+    refMockup("Mockup (rung 5)<br/>keep the published one,<br/>or pc-plan-mockup draws it") --> refStory
+    refMockup -.->|"after the agent"| refPublish
+    refPublish("Render and publish (no model)<br/>PNG at 1440 and 390 on mockups,<br/>section stamped on issue and children")
     refTrivial("Trivial plan<br/>marker, summary, checklist<br/>no Gherkin, no diagram") --> refEstimate
     refStory("Story<br/>Given/When/Then per work unit,<br/>grounded in the code") --> refWrap
     refStory -.->|"cannot ground it"| refFail
@@ -290,8 +300,8 @@ flowchart TD
     classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class refStart start
-    class refReserve,refFacts,refExplore,refTrivial,refStory,refWrap,refProse,refStack action
-    class refClassify,refEstimate,refSplit,refOutcome decision
+    class refReserve,refFacts,refExplore,refMockup,refPublish,refTrivial,refStory,refWrap,refProse,refStack action
+    class refClassify,refUi,refEstimate,refSplit,refOutcome decision
     class refFail failure
     class refDone,refAsk,refChildren success
 ```
@@ -302,6 +312,8 @@ flowchart TD
 
 Writes the code and opens one pull request. It stops there: the merge decision belongs to the gate,
 because waiting for CI inside this run would hold a fleet machine doing nothing.
+A UX mockup on the issue is read as intent: the agent builds with the components its table names
+and never copies its markup, which the Semgrep rule `platform-mockup-markup-in-code` would fail.
 
 ```mermaid
 flowchart TD
@@ -310,7 +322,7 @@ flowchart TD
     implEligible -.->|no| implIdle
     implEligible -->|yes| implReserve
     implReserve("Reserve (rung 4)<br/>bot-working") --> implFacts
-    implFacts("Facts (rung 3)<br/>Issue and comments to disk") --> implCheck
+    implFacts("Facts (rung 3)<br/>Issue, comments and its UX mockup,<br/>if refine made one, to disk") --> implCheck
     implCheck{"Trivial marker<br/>left by refine?"}
     implCheck -->|yes| implTodos
     implCheck -->|no| implCode

package/loops/templates/ci/app-ci-node-monorepo.yml

@@ -170,7 +170,12 @@ jobs:
     runs-on: agents-arc
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - run: docker run --rm -v "${{ github.workspace }}:/src" -w /src "$SEMGREP_IMAGE" semgrep scan --error --metrics=off --oss-only --disable-version-check --config p/default --config p/security-audit --config p/secrets --config p/typescript --config p/react --exclude-rule yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+      # `.semgrep/` holds the family rules (empty catch blocks, mockup markup in code) when the
+      # quality-gates template is installed; without it the scan runs the registry rules alone.
+      - run: |
+          local_rules=()
+          [ -d .semgrep ] && local_rules=(--config .semgrep/)
+          docker run --rm -v "${{ github.workspace }}:/src" -w /src "$SEMGREP_IMAGE" semgrep scan --error --metrics=off --oss-only --disable-version-check --config p/default --config p/security-audit --config p/secrets --config p/typescript --config p/react "${local_rules[@]}" --exclude-rule yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
 
   sbom:
     name: SBOM (CycloneDX)

package/loops/templates/quality-gates/.semgrep/platform-mockup-leak.yml

@@ -0,0 +1,45 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/.semgrep/platform-mockup-leak.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+# A UX mockup (the harness skill pc-plan-mockup, published on the `mockups` branch) states intent,
+# not a spec. The code that implements it is built from the repository's own components, never
+# from the mockup's markup. Its markers are the tell that markup was copied instead: every region
+# carries `data-mockup-section`, and every component stand-in a `data-component` naming a source
+# path, a package export or `new:<Name>`. Run by the blocking Semgrep scan via `--config .semgrep/`.
+#
+# A `data-component` attribute an application uses for its own reasons is left alone: only the
+# mockup's reference forms are flagged. There is no exemption comment by design; rebuild the part
+# from the components the mockup's table names.
+rules:
+  - id: platform-mockup-markup-in-code
+    languages: [generic]
+    severity: ERROR
+    message: >-
+      UX mockup markup in the code: a mockup states intent, not a spec. Build this part with the
+      real component the mockup's component table names, and remove the mockup's
+      `data-mockup-section` and `data-component` attributes and its styles.
+    metadata:
+      category: hygiene
+    paths:
+      include:
+        - "*.ts"
+        - "*.tsx"
+        - "*.js"
+        - "*.jsx"
+        - "*.mjs"
+        - "*.html"
+        - "*.cshtml"
+        - "*.razor"
+        - "*.vue"
+        - "*.svelte"
+        - "*.css"
+        - "*.scss"
+      exclude:
+        - ".mockups/"
+        - "node_modules/"
+        - ".agents/"
+        - ".opencode/"
+        - ".github/"
+        - "dist/"
+        - "out/"
+    pattern-either:
+      - pattern-regex: data-mockup-section\s*=
+      - pattern-regex: data-component\s*=\s*["'{`]?\s*(new:|@[\w.-]+/|[\w.-]+/[\w./-]+\.(tsx|ts|jsx|js|vue|svelte|cshtml|razor))

package/loops/workflows/agent-implement.md

@@ -79,6 +79,10 @@ env:
   RETRY_UNDER_MINUTES: "6"
   INCOMPLETE_COMMENT: "Automated implementation ran and ended without an outcome. The issue is released and flagged for review: a run that got this far and still failed will fail the same way again."
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/implementation-context.json
+  # The UX mockup refine or a person published for this issue (a split child reads its parent's),
+  # copied here before the agent starts. Context only: the prompt says how it may be used.
+  MOCKUP_BRANCH: mockups
+  MOCKUP_DIR: /tmp/gh-aw/agent/mockup
   GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
 description: |
   Implements an issue and opens a pull request. Stops there: the merge decision belongs to
@@ -671,6 +675,14 @@ steps:
       issue-number: ${{ inputs.issue-number }}
       output-path: ${{ env.ISSUE_CONTEXT_PATH }}
 
+  - name: Load the issue's mockup for the agent
+    uses: ./.github/actions/load-mockup
+    with:
+      token: ${{ github.token }}
+      issue-number: ${{ inputs.issue-number }}
+      branch: ${{ env.MOCKUP_BRANCH }}
+      out-dir: ${{ env.MOCKUP_DIR }}
+
   # Done here, deterministically, because a branch is not a judgement. A local branch needs no
   # credentials, so this works in the sandbox; the agent only commits to it. A leftover local
   # branch of the same name (a retried job on a reused workspace) is switched to, never reset.
@@ -820,6 +832,16 @@ timeout-minutes: 180
        Adhere to ${{ env.REPO_RULES }}, ${{ env.ARCHITECTURE_RULES }} and
        ${{ env.TESTING_RULES }}.
 
+   **The UX mockup is intent, not a spec**, on both paths. When `${{ env.MOCKUP_DIR }}/index.html`
+   exists, the issue was refined with a mockup: read `mockup.json` there, and the HTML or
+   `desktop.png` when the layout matters. It tells you the flow, the regions, the states and,
+   in its component table, which real component each part of the screen is built with (`new:`
+   marks one this change creates). Build with those components and the repository's own
+   `DESIGN.md`, styles and conventions. Never copy its markup, its CSS or its `data-mockup-section`
+   and `data-component` attributes into the code, and never add the mockup to the repository: a
+   gate fails the pull request that does. Where the mockup and an acceptance criterion
+   disagree, the criterion wins.
+
    **WORK IN FEW TURNS**, on both paths. Every turn is a model call of three to twenty
    seconds, and the turns, not the commands, are most of a run. Read a file whole, or in
    ranges of a few hundred lines, once; never eight or fifteen lines at a time. Put
@@ -845,10 +867,19 @@ timeout-minutes: 180
      the code you changed (web: `pnpm exec vitest related --run <changed files>`; .NET:
      `dotnet test <the test project> --filter <the test classes>`). Do not run integration,
      end-to-end, mutation or coverage suites here, and do not run the whole test suite to be safe:
-     the repository's CI runs all of it on your pull request before anything merges, on a runner
-     that has the database and the browsers this sandbox lacks. The verification commands above are
-     the repository's quick check for that reason. A full suite in the agent is the slowest part of
-     a run and repeats what CI does anyway.
+     the repository's CI runs them, on a runner that has the database and the browsers this
+     sandbox lacks. The verification commands above are the repository's quick check for that
+     reason. A full suite in the agent is the slowest part of a run and repeats what CI does
+     anyway.
+
+     **Not running the end-to-end tests does not make them someone else's.** When your change
+     moves, renames or removes something a person clicks or reads (a button, a label, a heading, a
+     route, a table), or changes what happens after a click, search the end-to-end tests for it
+     (their selectors, the text they assert, the routes they open) and update every test that
+     uses it in this pull request. Do this even when the repository runs those tests only at night
+     or on a schedule: then nothing on the pull request fails, and the suite breaks the morning
+     after the merge with no author attached. Pliny-Bot #1506 was ten journeys broken that way by
+     Bot Studio changes that merged without their end-to-end tests.
 
      **Run them once, on the final tree.** They are slow: Pliny-Bot's `pnpm verify` is about
      twenty minutes of work on this runner. `pc-plan-apply` runs them in its verify step, and

package/loops/workflows/agent-merge-gate.md

@@ -1182,6 +1182,10 @@ timeout-minutes: 120
    It is an attention list, not a verdict. Touching one of those areas is not a finding. A
    defect you can demonstrate in one of them is.
 
+   A UX mockup on the issue (its `## UX mockup` section) states intent, not a spec. A screen
+   that looks different from it is never a finding. Mockup markup copied into the code is one:
+   `data-mockup-section` or `data-component` attributes, or the mockup's inline styles.
+
    **5b. Have each candidate verified independently.** Do not be the one who checks your own
    work. Hand each candidate off for verification as a claim on its own: the file, the line,
    what you think is wrong, and what would settle it. Do not pass on the reasoning that produced
@@ -1201,7 +1205,9 @@ timeout-minutes: 120
    reassurance about their absence.
 
    **5c. Check the acceptance criteria.** The issue context at `${{ env.ISSUE_CONTEXT_PATH }}`
-   says what this change was supposed to do. Confirm the diff does it. The double-check the
+   says what this change was supposed to do. Confirm the diff does it. The acceptance criteria
+   are the test, never the mockup: a criterion is unmet by behaviour, not by a look that differs
+   from the picture. The double-check the
    rest of this step asks you to do is the gate's own: a defect an agent did not notice and CI
    did not catch is a more expensive rollback than a wrong auto-merge.
 

package/loops/workflows/agent-refine.md

@@ -25,6 +25,15 @@ env:
   # tools, so a repository built on anything else can never match it and always takes the long,
   # expensive path. Every condition must hold for a change to be trivial.
   TRIVIAL_CRITERIA: "It touches 1-3 files: stylesheets, style utility classes, text labels or markup only. No business logic: no services, controllers, domain models, calculations, validations. No data model: no entities, migrations, DTOs, API contracts. No security surface: no auth, authorization, secrets, tokens, permissions. No infrastructure: no deployment templates, containers, CI or deploy configuration. It does not touch shared libraries or multi-team contracts."
+  # A standard-path story whose work units change files matching these globs (space-separated)
+  # gets a UX mockup from the harness skill pc-plan-mockup before the story is written. Empty
+  # turns mockups off. The render and publish jobs put it on MOCKUP_BRANCH at issue-<n>/, and
+  # conclude stamps the picture, the link and the component table on the issue.
+  MOCKUP_PATHS: "apps/web/**"
+  MOCKUP_BRANCH: mockups
+  MOCKUP_DIR: /tmp/gh-aw/agent/mockup
+  MOCKUP_PLAYWRIGHT_VERSION: "1.62.1"
+  MOCKUP_INTENT_LINE: "UX mockup: intent, not a spec. Build with the components listed."
   REFINE_LABEL: refine
   REFINED_LABEL: refined
   WORKING_LABEL: bot-working
@@ -281,8 +290,130 @@ jobs:
           comment-prefix: ${{ env.SAFE_OUTPUT_COMMENT_PREFIX }}
           issue-number: ${{ inputs.issue-number }}
           questions-line: ${{ env.QUESTIONS_LINE }}
-  conclude:
+  # The mockup's two jobs, split like evidence's: the render reads what an agent wrote and runs a
+  # browser on it, so it holds no write permission and no secret; the publish job writes, so it
+  # checks nothing out and runs nothing from the repository. Neither can fail the refinement: a
+  # mockup that breaks its contract, or a push that is refused, leaves the story without a picture.
+  mockup_render:
     needs: [activation, agent, safe_outputs, validate_output]
+    if: >
+      always() &&
+      needs.validate_output.outputs.valid == 'true'
+    runs-on: agents-arc
+    timeout-minutes: 15
+    continue-on-error: true
+    permissions:
+      contents: read
+    outputs:
+      rendered: ${{ steps.capture.outputs.valid }}
+    steps:
+      - name: Checkout workflow actions
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Download agent output
+        uses: ./.github/actions/download-agent-output
+        with:
+          artifact-name: ${{ needs.activation.outputs.artifact_prefix }}agent
+      # A new mockup from this pass wins. An existing one is rendered only when it was published
+      # without screenshots, which is how /plan-mockup publishes when no browser was at hand.
+      - name: Pick the mockup to render
+        id: pick
+        env:
+          MOCKUP_DIR: ${{ env.MOCKUP_DIR }}
+        run: |
+          set -euo pipefail
+          rel="agent-artifact/${MOCKUP_DIR#/tmp/gh-aw/}"
+          dir=''
+          if [ -f "$rel/new/index.html" ]; then
+            dir="$rel/new"
+          elif [ -f "$rel/existing/index.html" ] && [ ! -f "$rel/existing/desktop.png" ]; then
+            dir="$rel/existing"
+          fi
+          echo "dir=$dir" >> "$GITHUB_OUTPUT"
+          echo "Mockup to render: ${dir:-none}"
+      - name: Check and render the mockup
+        id: capture
+        if: steps.pick.outputs.dir != ''
+        uses: ./.github/actions/capture-mockup
+        with:
+          mockup-dir: ${{ steps.pick.outputs.dir }}
+          out-dir: ${{ runner.temp }}/mockup
+          playwright-version: ${{ env.MOCKUP_PLAYWRIGHT_VERSION }}
+      - name: Keep the rendered mockup
+        if: steps.capture.outputs.valid == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ${{ needs.activation.outputs.artifact_prefix }}mockup
+          path: ${{ runner.temp }}/mockup
+          retention-days: 7
+          if-no-files-found: error
+  mockup_publish:
+    needs: [activation, agent, mockup_render]
+    if: always() && needs.mockup_render.outputs.rendered == 'true'
+    runs-on: agents-arc
+    timeout-minutes: 10
+    continue-on-error: true
+    permissions:
+      contents: write
+    steps:
+      - name: Download the rendered mockup
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ${{ needs.activation.outputs.artifact_prefix }}mockup
+          path: ${{ runner.temp }}/mockup
+      # One orphan branch holds every mockup, a folder per issue, replaced on every publish.
+      # GITHUB_TOKEN and [skip ci] keep the push from starting any workflow.
+      - name: Push the mockup to its branch
+        env:
+          TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SERVER: ${{ github.server_url }}
+          BRANCH: ${{ env.MOCKUP_BRANCH }}
+          ISSUE: ${{ inputs.issue-number }}
+        run: |
+          set -euo pipefail
+          src="$RUNNER_TEMP/mockup"
+          folder="issue-${ISSUE}"
+          work="$RUNNER_TEMP/mockup-branch"
+          rm -rf "$work"
+          mkdir -p "$work"
+          cd "$work"
+          auth="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git init -q
+          git config "http.${SERVER}/.extraheader" "$auth"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config core.sparseCheckout true
+          echo "/${folder}/" > .git/info/sparse-checkout
+          git remote add origin "${SERVER}/${REPO}.git"
+
+          for attempt in 1 2 3 4 5; do
+            if git fetch -q --depth=1 --filter=blob:none origin "refs/heads/$BRANCH" 2>/dev/null; then
+              git checkout -q -f -B "$BRANCH" FETCH_HEAD
+            else
+              git checkout -q --orphan "mockups-$attempt"
+              git rm -rq --cached . >/dev/null 2>&1 || true
+            fi
+            rm -rf "$folder"
+            mkdir -p "$folder"
+            cp -R "$src/." "$folder/"
+            git add -A "$folder"
+            if git diff --cached --quiet; then
+              echo "The mockup on $BRANCH is already current."
+              exit 0
+            fi
+            git commit -q -m "mockup: issue #${ISSUE} [skip ci]"
+            if git push -q origin "HEAD:refs/heads/$BRANCH"; then
+              echo "Published ${SERVER}/${REPO}/tree/$(git rev-parse HEAD)/${folder}"
+              exit 0
+            fi
+            echo "$BRANCH moved before the push (attempt $attempt); retrying on its new tip."
+            sleep $((attempt * 3))
+          done
+          echo "::warning::could not push the mockup to $BRANCH after 5 attempts"
+  conclude:
+    needs: [activation, agent, safe_outputs, validate_output, mockup_render, mockup_publish]
     # `always()` is load-bearing: without it GitHub prepends `success()`, which returns false
     # if any needed job was skipped. The historical trigger was the size gate's refuse_big_issue
     # skip-poisoning activation (Pliny-Bot #321) -- that gate is gone at 1.15.0, but a skip in
@@ -329,6 +460,106 @@ jobs:
           create-issues: 'true'
           fallback-issue-number: ${{ inputs.issue-number }}
           parent-issue: ${{ needs.validate_output.outputs.outcome == 'split' && inputs.issue-number || '' }}
+      # The mockup section, written by the workflow because gh-aw strips the HTML comments that
+      # delimit it from anything the agent writes, and re-written on every pass because the agent
+      # replaces the whole body. Read from the branch, so a mockup a person published with
+      # /plan-mockup is linked the same way as one this run rendered. A split child gets its
+      # parent's mockup and the sections its `Mockup sections:` line names. Best-effort: no
+      # mockup, or a failed read, leaves the bodies as the agent wrote them.
+      - name: Record the mockup on the issue
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          ISSUE: ${{ inputs.issue-number }}
+          BRANCH: ${{ env.MOCKUP_BRANCH }}
+          OUTCOME: ${{ needs.validate_output.outputs.outcome }}
+          INTENT: ${{ env.MOCKUP_INTENT_LINE }}
+          SPLIT_PARENT_PREFIX: ${{ env.SPLIT_PARENT_PREFIX }}
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const START = '<!-- agent-mockup:start -->';
+            const END = '<!-- agent-mockup:end -->';
+            const parent = Number(process.env.ISSUE);
+            const folder = `issue-${parent}`;
+            const ref = process.env.BRANCH;
+            const site = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}`;
+
+            let sha;
+            let mockup;
+            let names;
+            try {
+              ({ data: { commit: { sha } } } = await github.rest.repos.getBranch({ ...context.repo, branch: ref }));
+              const { data: entries } = await github.rest.repos.getContent({ ...context.repo, path: folder, ref: sha });
+              names = new Set(entries.map((entry) => entry.name));
+              const { data: file } = await github.rest.repos.getContent({ ...context.repo, path: `${folder}/mockup.json`, ref: sha });
+              mockup = JSON.parse(Buffer.from(file.content, 'base64').toString('utf8'));
+            } catch (error) {
+              if (error.status === 404) {
+                core.info(`No mockup at ${ref}:${folder}.`);
+                return;
+              }
+              throw error;
+            }
+
+            const cell = (value) => String(value ?? '').replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+            const raw = (name) => `${site}/raw/${sha}/${folder}/${name}`;
+            const blob = (name) => `${site}/blob/${sha}/${folder}/${name}`;
+            const known = (mockup.sections ?? []).map((section) => section.id);
+
+            const section = (only) => {
+              const rows = (mockup.components ?? []).filter((entry) => !only || only.includes(entry.section));
+              const lines = [START, `<!-- agent-mockup: ${folder} -->`, '## UX mockup', '', `**${cell(mockup.title)}.** ${process.env.INTENT}`, ''];
+              if (only) lines.push(`This issue builds ${only.map((id) => `\`${id}\``).join(', ')}.`, '');
+              if (names.has('desktop.png')) lines.push(`![Mockup at desktop width](${raw('desktop.png')})`, '');
+              const links = [`[The HTML](${blob('index.html')})`];
+              if (names.has('mobile.png')) links.push(`[mobile width](${raw('mobile.png')})`);
+              links.push(`[mockup.json](${blob('mockup.json')})`);
+              lines.push(`${links.join(' · ')}: download the HTML and open it in a browser to see every state.`, '');
+              if (rows.length > 0) {
+                lines.push('| Section | Element | Build it with | Where |', '|---|---|---|---|');
+                for (const row of rows) {
+                  const where = row.path === 'new' ? 'new component' : `\`${cell(row.path)}\``;
+                  lines.push(`| ${cell(row.section)} | ${cell(row.element)} | ${cell(row.component)} | ${where} |`);
+                }
+                lines.push('');
+              }
+              lines.push(END);
+              return lines.join('\n');
+            };
+
+            const stamp = async (issue_number, block) => {
+              const { data: issue } = await github.rest.issues.get({ ...context.repo, issue_number });
+              const pattern = new RegExp(`${START}[\\s\\S]*?${END}\\n?`, 'g');
+              const cleaned = (issue.body ?? '').replace(pattern, '').replace(/\s+$/, '');
+              await github.rest.issues.update({ ...context.repo, issue_number, body: `${cleaned}\n\n${block}\n` });
+              core.info(`Mockup section written on #${issue_number}.`);
+            };
+
+            await stamp(parent, section(null));
+            if (process.env.OUTCOME !== 'split') return;
+
+            let children = [];
+            try {
+              children = (await github.paginate(github.rest.issues.listSubIssues ?? 'GET /repos/{owner}/{repo}/issues/{issue_number}/sub_issues',
+                { ...context.repo, issue_number: parent, per_page: 100 })).map((child) => child.number);
+            } catch (error) {
+              core.info(`Sub-issues unreadable (${error.message}); searching for the split marker.`);
+            }
+            if (children.length === 0) {
+              const { data } = await github.rest.search.issuesAndPullRequests({
+                q: `repo:${context.repo.owner}/${context.repo.repo} is:issue is:open in:body "${process.env.SPLIT_PARENT_PREFIX}${parent} -->"`,
+              });
+              children = data.items.map((item) => item.number);
+            }
+            for (const child of children.filter((number) => number !== parent)) {
+              const { data: issue } = await github.rest.issues.get({ ...context.repo, issue_number: child });
+              const line = /^Mockup sections:\s*(.+)$/im.exec(issue.body ?? '');
+              const only = line
+                ? line[1].split(/[,\s]+/).map((id) => id.replace(/`/g, '').trim()).filter((id) => known.includes(id))
+                : [];
+              await stamp(child, section(only.length > 0 ? only : null));
+            }
       - name: Apply complete refinement labels
         if: needs.validate_output.outputs.outcome == 'complete'
         uses: ./.github/actions/add-issue-labels
@@ -768,6 +999,15 @@ steps:
       token: ${{ github.token }}
       issue-number: ${{ inputs.issue-number }}
       output-path: ${{ env.ISSUE_CONTEXT_PATH }}
+  # A mockup already published for this issue, by a person with /plan-mockup or by an earlier
+  # pass. The agent keeps it unless the author's answers changed the screen.
+  - name: Load the issue's mockup for the agent
+    uses: ./.github/actions/load-mockup
+    with:
+      token: ${{ github.token }}
+      issue-number: ${{ inputs.issue-number }}
+      branch: ${{ env.MOCKUP_BRANCH }}
+      out-dir: ${{ env.MOCKUP_DIR }}/existing
 
 safe-outputs:
   # A failed run is already a red run. An issue per failure buries the real backlog
@@ -873,8 +1113,18 @@ timeout-minutes: 90
    checklist of concrete steps. No "As a / I want / so that" form, no Given/When/Then, no Mermaid.
    Load `@humanizer` and prepare the body, then go directly to step 4 (estimate).
 
-   **Standard path.** Call `skill("pc-plan-story")` and pass it the work units and the exploration
-   findings. `pc-plan-story` owns the story's shape: drafting, coverage gate, repo-docs application,
+   **Standard path.** When `${{ env.MOCKUP_PATHS }}` is not empty and a work unit changes files
+   matching one of its space-separated globs, settle the UX mockup first. A mockup in
+   `${{ env.MOCKUP_DIR }}/existing/` was made by a person or an earlier pass: keep it, unless the
+   author's answers on this pass change what the screen shows. Otherwise call
+   `skill("pc-plan-mockup")` in autonomous mode with the work units and the exploration findings,
+   and have it write `index.html` and `mockup.json` to `${{ env.MOCKUP_DIR }}/new/`; to replace an
+   existing mockup, write the whole new one there. If that skill is not installed, carry on
+   without a mockup. Never put the HTML in a body or a comment: the workflow publishes it and
+   adds the picture, the link and the component table to the issue itself.
+
+   Then call `skill("pc-plan-story")` and pass it the work units and the exploration
+   findings, and tell it the workflow writes the UX section, so the story leaves it out. `pc-plan-story` owns the story's shape: drafting, coverage gate, repo-docs application,
    issue-form discovery and wrapping, humanizer pass, and the structured implementation plan. Do not
    repeat any of those steps yourself. Adhere to ${{ env.REPO_RULES }}.
 
@@ -918,6 +1168,9 @@ timeout-minutes: 90
      `#aw_<id>` to the real issue number once the children exist. Write dependencies only as these
      lines and never set the `blocked_by` field: it takes one reference, and a value naming two
      rejected the item and discarded the whole refinement (Lyceum #45).
+   - when the story has a mockup, a `Mockup sections: <ids>` line naming the `mockup.json`
+     section ids this child builds, comma-separated, so the workflow links the child to its part
+     of the mockup
    - a `Parent feature branch: feat/<parent issue number>` line (for parent #123,
      `Parent feature branch: feat/123`) naming the branch the whole split integrates on:
      each child's pull request targets that branch, never the default branch, the children

package/loops/workflows/evidence.yml

@@ -524,7 +524,33 @@ jobs:
               }
               return `<!-- agentic-evidence-manifest\n${JSON.stringify(data).replace(/-(?=-)/g, '\\u002d')}\n-->`;
             });
-            const body = source.split('__EVIDENCE_BASE__').join(base);
+            let body = source.split('__EVIDENCE_BASE__').join(base);
+
+            // The mockup the issue was refined with, beside what was built, so a reviewer judges
+            // the experience against the intent. Read from the mockup section refine stamps on the
+            // issue; a split child's section carries its parent's mockup. Best-effort: no mockup,
+            // or a failed lookup, leaves the comment as it was.
+            try {
+              const query = `query($owner: String!, $repo: String!, $number: Int!) {
+                repository(owner: $owner, name: $repo) {
+                  pullRequest(number: $number) { closingIssuesReferences(first: 5) { nodes { number body } } }
+                }
+              }`;
+              const result = await github.graphql(query, { ...context.repo, number: issue_number });
+              for (const node of result.repository.pullRequest?.closingIssuesReferences?.nodes ?? []) {
+                const section = /<!-- agent-mockup:start -->([\s\S]*?)<!-- agent-mockup:end -->/.exec(node.body ?? '');
+                const image = section && /!\[[^\]]*\]\([^)\s]+\/desktop\.png\)/.exec(section[1]);
+                if (!image) continue;
+                const block = `### The mockup it was built from (#${node.number})\n\nUX intent, not a spec: a different look is expected, a different flow is worth a look.\n\n${image[0]}\n\n`;
+                body = body.includes('<!-- agentic-evidence-manifest')
+                  ? body.replace('<!-- agentic-evidence-manifest', `${block}<!-- agentic-evidence-manifest`)
+                  : `${body}\n\n${block}`;
+                break;
+              }
+            } catch (error) {
+              core.info(`No mockup added: ${error.message}`);
+            }
+
             const comments = await github.paginate(github.rest.issues.listComments, { ...context.repo, issue_number, per_page: 100 });
             const existing = comments.find((comment) => comment.user?.type === 'Bot' && (comment.body ?? '').includes(process.env.MARKER));
             if (existing) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",