@plainconceptsplatform/workflows 1.1.1 → 1.2.0

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

@@ -3,7 +3,8 @@ name: Capture evidence
 description: >
   Reads a pull request's verification plans (written by the harness skill pc-repo-verify) and,
   in capture mode, replays them in headless Chromium against the running app, writing one JPEG
-  per waypoint plus manifest.json and comment.md. Inspect mode only reports whether any plan is
+  per waypoint under files/<plan directory>/evidence/, laid out as the repository is, plus
+  manifest.json and comment.md. Inspect mode only reports whether any plan is
   replayable, at which address, and with which start command. No model, no network beyond
   installing its two pinned packages.
 inputs:

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

@@ -8,7 +8,10 @@
 //     prints {"runnable","url","start","plans"} as JSON, so the workflow knows whether to start
 //     the app at all and which address to wait for
 //   node capture.mjs capture <repo-root> <out-dir> <plan.md>...
-//     writes NN-<capture>.jpg per waypoint plus manifest.json and comment.md into <out-dir>
+//     writes one screenshot per waypoint under <out-dir>/files/, laid out as the repository is:
+//     <plan's directory>/evidence/NN-<capture>.jpg beside a manifest.json for that plan, so the
+//     publish job copies files/ over the default branch as is. Writes the run's manifest.json and
+//     comment.md into <out-dir>
 //   node capture.mjs unreached <repo-root> <out-dir> <plan.md>...
 //     the app never answered: writes manifest.json and comment.md saying so, and nothing else
 //
@@ -16,7 +19,7 @@
 // imports are bare: ESM resolves them from the file's own directory, never from NODE_PATH.
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, posix } from "node:path";
 import { pathToFileURL } from "node:url";
 
 const DEFAULT_URL = "http://localhost:3000";
@@ -27,6 +30,13 @@ const NAVIGATION_TIMEOUT_MS = Number(process.env.EVIDENCE_NAVIGATION_TIMEOUT_MS
 // is the commit that job pushes, so the comment is written here and the publish job fills it in.
 export const IMAGE_BASE = "__EVIDENCE_BASE__";
 export const MARKER = "<!-- agentic-evidence -->";
+// Opens the machine-readable copy of the manifest at the end of the comment, which is what other
+// tools read (Project Health shows the screenshots with each issue) instead of parsing markdown.
+export const EMBED_MARKER = "agentic-evidence-manifest";
+// The folder beside each verification plan that keeps its screenshots.
+export const EVIDENCE_DIR = "evidence";
+// Stays well under GitHub's 65,536 character comment limit with the markdown above it.
+const EMBED_LIMIT = 30000;
 
 const ACTIONS = new Set(["open", "click", "dblclick", "fill", "press", "select", "check", "uncheck", "hover", "wait"]);
 const LOCATOR_KEYS = ["role", "text", "label", "placeholder", "testid", "alt", "title", "css"];
@@ -44,6 +54,17 @@ export function slug(value) {
   return text.slice(0, 60) || "waypoint";
 }
 
+// The directory a plan lives in, which is where its screenshots are kept. The path comes from the
+// pull request's file list, so it is repository-relative; anything that could climb out of the
+// repository is refused rather than written.
+export function planDir(planPath) {
+  const dir = posix.dirname(String(planPath).replace(/\\/g, "/"));
+  if (dir === "." || dir.startsWith("/") || dir.split("/").includes("..")) {
+    throw new Error(`unsafe plan path ${planPath}`);
+  }
+  return dir;
+}
+
 // The change a plan belongs to, from its directory. Archived changes carry a date prefix.
 export function changeName(planPath) {
   return basename(dirname(planPath)).replace(/^\d{4}-\d{2}-\d{2}-/, "") || "change";
@@ -422,7 +443,7 @@ async function runStep(page, step, baseUrl) {
   }
 }
 
-async function replay(browser, plan, outDir, prefix) {
+async function replay(browser, plan, outDir, dir) {
   const context = await browser.newContext({ viewport: plan.viewport, ignoreHTTPSErrors: true });
   const page = await context.newPage();
   page.setDefaultTimeout(STEP_TIMEOUT_MS);
@@ -442,10 +463,11 @@ async function replay(browser, plan, outDir, prefix) {
           break;
         }
       }
-      const file = `${prefix}${String(waypoint.n).padStart(2, "0")}-${waypoint.capture}.jpg`;
+      // Repository-relative, so the comment, the manifest and the commit all name the same path.
+      const file = `${dir}/${EVIDENCE_DIR}/${String(waypoint.n).padStart(2, "0")}-${waypoint.capture}.jpg`;
       let captured = false;
       try {
-        await page.screenshot({ path: join(outDir, file), type: "jpeg", quality: 70, fullPage: true });
+        await page.screenshot({ path: join(outDir, "files", file), type: "jpeg", quality: 70, fullPage: true });
         captured = true;
       } catch (error) {
         errors.push(`screenshot: ${firstLine(error)}`);
@@ -459,7 +481,7 @@ async function replay(browser, plan, outDir, prefix) {
         errors,
         ignored: waypoint.ignored,
       });
-      console.log(`${prefix}${waypoint.n} ${waypoint.capture}: ${errors.length === 0 ? "ok" : errors.join("; ")}`);
+      console.log(`${dir} ${waypoint.n} ${waypoint.capture}: ${errors.length === 0 ? "ok" : errors.join("; ")}`);
     }
   } finally {
     await context.close();
@@ -471,11 +493,58 @@ async function replay(browser, plan, outDir, prefix) {
 
 const escapeMarkdown = (text) => String(text).replace(/([\\`*_[\]<>|])/g, "\\$1");
 
+// The manifest other tools read, as an HTML comment so it never renders. JSON can carry `--` only
+// inside strings, where `\u002d` means the same character, so escaping it keeps the comment closed.
+export function embedManifest(manifest) {
+  const compact = (keepExpect) => ({
+    version: 2,
+    base: IMAGE_BASE,
+    sha: manifest.sha ?? "",
+    runUrl: manifest.runUrl ?? "",
+    ...(manifest.app ? { app: manifest.app } : {}),
+    plans: (manifest.plans ?? []).map((plan) => ({
+      path: plan.path,
+      change: plan.change,
+      status: plan.status,
+      ...(plan.reason ? { reason: plan.reason } : {}),
+      ...(plan.waypoints
+        ? {
+            waypoints: plan.waypoints.map((w) => ({
+              n: w.n,
+              capture: w.capture,
+              ...(keepExpect && w.expect ? { expect: w.expect } : {}),
+              reached: w.reached,
+              file: w.file,
+            })),
+          }
+        : {}),
+    })),
+  });
+  let json = JSON.stringify(compact(true));
+  if (json.length > EMBED_LIMIT) json = JSON.stringify(compact(false));
+  if (json.length > EMBED_LIMIT) return "";
+  return `<!-- ${EMBED_MARKER}\n${json.replace(/-(?=-)/g, "\\u002d")}\n-->`;
+}
+
+// Reads the embedded manifest back out of a comment body, or null when there is none.
+export function readEmbeddedManifest(body) {
+  const match = String(body ?? "").match(new RegExp(`<!-- ${EMBED_MARKER}\\n([\\s\\S]*?)\\n-->`));
+  if (!match) return null;
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+
 export function renderComment(manifest) {
   const lines = [MARKER, "## Visual evidence", ""];
   const short = manifest.sha ? manifest.sha.slice(0, 7) : "";
   const run = manifest.runUrl ? ` ([run](${manifest.runUrl}))` : "";
   lines.push(`The verification plan replayed against \`${short}\`, the head of this pull request${run}.`, "");
+  if ((manifest.plans ?? []).some((plan) => plan.status === "captured")) {
+    lines.push(`The screenshots are kept beside each plan, in its \`${EVIDENCE_DIR}/\` folder on the default branch.`, "");
+  }
 
   if (manifest.app && manifest.app.started === false) {
     lines.push(`Nothing was captured: the app did not answer at ${manifest.app.url} within ${manifest.app.waitedSeconds} seconds of \`${manifest.app.start}\`. The run log has the app's output.`, "");
@@ -503,6 +572,8 @@ export function renderComment(manifest) {
     }
     lines.push("</details>", "");
   }
+  const embedded = embedManifest(manifest);
+  if (embedded) lines.push(embedded, "");
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
@@ -541,19 +612,18 @@ async function capture(root, outDir, paths) {
   await mkdir(outDir, { recursive: true });
   const plans = await loadPlans(root, paths, parse);
   const runnable = plans.filter((plan) => plan.status === "runnable");
-  const manifest = { version: 1, plans: [] };
+  const manifest = { version: 2, plans: [] };
 
   const browser = runnable.length > 0 ? await chromium.launch({ headless: true }) : undefined;
   try {
-    let index = 0;
     for (const plan of plans) {
       if (plan.status !== "runnable") {
         manifest.plans.push({ path: plan.path, change: plan.change, status: plan.status, reason: plan.reason ?? "" });
         continue;
       }
-      index++;
-      const prefix = runnable.length > 1 ? `${index}-` : "";
-      const waypoints = await replay(browser, plan, outDir, prefix);
+      const dir = planDir(plan.path);
+      await mkdir(join(outDir, "files", dir, EVIDENCE_DIR), { recursive: true });
+      const waypoints = await replay(browser, plan, outDir, dir);
       manifest.plans.push({ path: plan.path, change: plan.change, status: "captured", url: plan.url, waypoints });
     }
   } finally {
@@ -573,6 +643,12 @@ async function main(argv) {
     const manifest = await capture(root, outDir, paths);
     manifest.sha = process.env.EVIDENCE_SHA ?? "";
     manifest.runUrl = process.env.EVIDENCE_RUN_URL ?? "";
+    // Each plan keeps its own record beside its screenshots, so the folder explains itself on the
+    // default branch without the pull request comment.
+    for (const plan of manifest.plans.filter((p) => p.status === "captured")) {
+      const record = { version: 2, sha: manifest.sha, runUrl: manifest.runUrl, plan };
+      await writeFile(join(outDir, "files", planDir(plan.path), EVIDENCE_DIR, "manifest.json"), `${JSON.stringify(record, null, 2)}\n`);
+    }
     await writeFile(join(outDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
     await writeFile(join(outDir, "comment.md"), renderComment(manifest));
     const shots = manifest.plans.flatMap((plan) => plan.waypoints ?? []).filter((waypoint) => waypoint.file).length;
@@ -586,7 +662,7 @@ async function main(argv) {
     await mkdir(outDir, { recursive: true });
     const plans = await loadPlans(root, paths, parse);
     const manifest = {
-      version: 1,
+      version: 2,
       sha: process.env.EVIDENCE_SHA ?? "",
       runUrl: process.env.EVIDENCE_RUN_URL ?? "",
       app: {

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

@@ -1723,7 +1723,7 @@ else
     echo "FAIL: evidence.yml's publish job holds a write token and must not check out or run repository code" >&2
   fi
   ev_absent 'secrets\.' "$EVIDENCE_YML" 'evidence.yml must need no secret; GITHUB_TOKEN is enough'
-  ev_absent 'gh (issue|pr) comment.*--attach' "$EVIDENCE_YML" 'gh --attach refuses installation tokens; publish through the evidence branch'
+  ev_absent 'gh (issue|pr) comment.*--attach' "$EVIDENCE_YML" 'gh --attach refuses installation tokens; commit the screenshots beside their plans'
 fi
 
 # The retired worker stays retired: nothing dispatches it and nothing waits for it.

package/loops/docs/diagrams.md

@@ -626,7 +626,10 @@ earlier versions of them passed against a deliberately broken guard and were rew
 
 Archives what a merged pull request looks like. Not an agent: the plan was written by the agent that
 implemented the change (`pc-repo-verify`), and this replays it. The router calls it when a pull
-request merges, and `operation=evidence` runs it by hand. Nothing waits on it and nothing reads it.
+request merges, and `operation=evidence` runs it by hand. Nothing waits on it. The screenshots are
+committed beside each plan, in an `evidence/` folder on the default branch, so the record stays with
+the change it proves; the comment embeds a manifest that Project Health reads. A pull request that
+is not merged has no plan on the default branch, so its screenshots stay in the run's artifact.
 The capture job runs the pull request's code with a read-only token; only the publish job writes,
 and it runs no repository code.
 
@@ -645,8 +648,8 @@ flowchart TD
     evUp -.->|"no, after the timeout"| evUnreached
     evReplay["replay each waypoint<br/>in headless Chromium,<br/>one JPEG per waypoint"] --> evPublish
     evUnreached["record why nothing<br/>was captured"] --> evPublish
-    evPublish["publish (GITHUB_TOKEN)<br/>commit to the orphan evidence branch,<br/>upsert one comment"] --> evDone
-    evDone(("Archived<br/>on the pull request"))
+    evPublish["publish (GITHUB_TOKEN)<br/>commit beside each plan,<br/>evidence/ on the default branch,<br/>upsert one comment"] --> evDone
+    evDone(("Archived<br/>beside the plan"))
     evIdle(("Nothing to capture"))
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033

package/loops/workflows/evidence.yml

@@ -3,15 +3,16 @@ name: "Agentics: Evidence"
 
 # Archives what a merged pull request looks like. The agent that implemented the change wrote a
 # verification plan with the harness skill pc-repo-verify; this replays that plan against the
-# app, with no model, and keeps one screenshot per waypoint on the pull request. The router calls
-# it when a pull request merges, and operation=evidence runs it by hand for any pull request.
-# Nothing waits on it and nothing reads it: it is the record, not a gate.
+# app, with no model, and keeps one screenshot per waypoint beside the plan it came from. The
+# router calls it when a pull request merges, and operation=evidence runs it by hand for any pull
+# request. Nothing waits on it: it is the record, not a gate. Project Health reads the manifest
+# embedded in the comment to show the screenshots with each issue.
 #
 # Two jobs, because one runs the pull request's code and the other writes. `capture` checks out
 # the head, starts the app and drives Chromium with a read-only token and no secret. `publish`
-# checks nothing out: it takes the images as an artifact, commits them to the orphan `evidence`
-# branch and writes one comment. Both use GITHUB_TOKEN, so a repository configures nothing, and
-# nothing either job writes raises another workflow event.
+# checks nothing out: it takes the images as an artifact, commits them into an `evidence/` folder
+# beside each plan on the default branch and writes one comment. Both use GITHUB_TOKEN, so a
+# repository configures nothing, and nothing either job writes raises another workflow event.
 #
 # This replaced agent-visual-verify, which never produced a screenshot: it ran only on pull
 # requests nobody would review, raced the merge it was dispatched before, re-planned with a model
@@ -35,8 +36,10 @@ env:
   EVIDENCE_START_TIMEOUT_SECONDS: "900"
   # The SDK when a repository has .NET projects but no global.json to say which.
   EVIDENCE_DOTNET_VERSION: "10.0.x"
-  EVIDENCE_BRANCH: evidence
   EVIDENCE_MARKER: "<!-- agentic-evidence -->"
+  # How long the run keeps the screenshots it could not archive: a pull request that is not merged
+  # has no plan on the default branch to keep them beside.
+  EVIDENCE_ARTIFACT_DAYS: "14"
   # The capture runs in mcr.microsoft.com/playwright at this tag, pre-pulled by the runner image
   # (runners/versions.env), so the two move together.
   PLAYWRIGHT_VERSION: "1.62.1"
@@ -66,8 +69,11 @@ jobs:
             const pull_number = Number(process.env.PR_NUMBER);
             const { data: pr } = await github.rest.pulls.get({ ...context.repo, pull_number });
             const files = await github.paginate(github.rest.pulls.listFiles, { ...context.repo, pull_number, per_page: 100 });
+            // A plan that was only moved (the archive step, in a later pull request) is skipped: its
+            // evidence/ folder moves with it, so replaying it would only repeat the record.
             const plans = files
               .filter((file) => file.status !== 'removed' && /(^|\/)verification-plan\.md$/.test(file.filename))
+              .filter((file) => !(file.status === 'renamed' && file.changes === 0))
               .map((file) => file.filename);
             core.setOutput('sha', pr.head.sha);
             core.setOutput('plans', plans.join('\n'));
@@ -185,6 +191,25 @@ jobs:
             echo "::group::Last lines of the app's output"
             tail -n 80 "$log" || true
             echo "::endgroup::"
+            # An orchestrator (Aspire, compose) keeps each service's output to itself, so the
+            # start command's own log rarely says which service never came up. Show them.
+            echo "::group::Listening ports"
+            (ss -ltnp 2>/dev/null || netstat -ltnp 2>/dev/null) | head -n 40 || true
+            echo "::endgroup::"
+            echo "::group::Containers"
+            docker ps -a --format '{{.Names}}  {{.Status}}  {{.Image}}' 2>/dev/null || true
+            echo "::endgroup::"
+            for id in $(docker ps -aq 2>/dev/null); do
+              echo "::group::Container $(docker inspect -f '{{.Name}}' "$id" 2>/dev/null)"
+              docker logs --tail 60 "$id" 2>&1 || true
+              echo "::endgroup::"
+            done
+            for f in "$HOME"/.aspire/logs/*.log; do
+              [ -f "$f" ] || continue
+              echo "::group::$f"
+              tail -n 200 "$f" || true
+              echo "::endgroup::"
+            done
           fi
 
       - name: Replay the plans
@@ -240,7 +265,7 @@ jobs:
         with:
           name: evidence-pr-${{ inputs.pr-number }}
           path: ${{ runner.temp }}/evidence
-          retention-days: 3
+          retention-days: ${{ env.EVIDENCE_ARTIFACT_DAYS }}
           if-no-files-found: error
 
   publish:
@@ -259,72 +284,113 @@ jobs:
           name: evidence-pr-${{ inputs.pr-number }}
           path: ${{ runner.temp }}/evidence
 
-      # An orphan branch rather than the default branch: the images stay out of every build, every
-      # diff and every review, and a clone that only wants the code can leave the branch behind.
-      # One folder per pull request, so two publishes never touch the same file and a lost push
-      # race is a retry, never a conflict.
-      - name: Commit the screenshots to the evidence branch
-        id: branch
+      - name: Read the pull request
+        id: pr
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PR_NUMBER: ${{ inputs.pr-number }}
+        with:
+          script: |
+            const { data: pr } = await github.rest.pulls.get({ ...context.repo, pull_number: Number(process.env.PR_NUMBER) });
+            core.setOutput('merged', pr.merged ? 'true' : 'false');
+            core.setOutput('branch', pr.base.ref);
+
+      # Beside each plan on the default branch, where the plan itself is archived: the record stays
+      # with the change it proves, and moves with it if the change folder ever moves. Only a merged
+      # pull request's plans are there to keep it beside. A sparse, blob-less fetch reads only the
+      # plan folders, and [skip ci] plus GITHUB_TOKEN keep the commit from starting any workflow.
+      - name: Commit the screenshots beside their plans
+        id: archive
+        if: steps.pr.outputs.merged == 'true'
         env:
           TOKEN: ${{ github.token }}
           REPO: ${{ github.repository }}
           SERVER: ${{ github.server_url }}
-          BRANCH: ${{ env.EVIDENCE_BRANCH }}
+          BRANCH: ${{ steps.pr.outputs.branch }}
           PR: ${{ inputs.pr-number }}
         run: |
           set -euo pipefail
-          src="$RUNNER_TEMP/evidence"
-          if ! compgen -G "$src/*.jpg" > /dev/null; then
+          src="$RUNNER_TEMP/evidence/files"
+          if [ ! -d "$src" ] || [ -z "$(find "$src" -name '*.jpg' -print -quit)" ]; then
             echo "No screenshots to keep; the comment records why."
             echo "base=" >> "$GITHUB_OUTPUT"
             exit 0
           fi
 
-          work="$RUNNER_TEMP/evidence-branch"
+          # Each folder holding screenshots is <plan directory>/evidence.
+          mapfile -t dirs < <(cd "$src" && find . -type d -name evidence | sed 's|^\./||; s|/evidence$||' | sort)
+
+          work="$RUNNER_TEMP/evidence-commit"
           rm -rf "$work"
-          mkdir -p "$work"
+          auth="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          # Blob-less and sparse: only the plan folders are downloaded, however large the repository.
+          git -c "http.${SERVER}/.extraheader=${auth}" clone -q --filter=blob:none --no-checkout --depth=1 \
+            --branch "$BRANCH" "${SERVER}/${REPO}.git" "$work"
           cd "$work"
-          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 "http.${SERVER}/.extraheader" "AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
-          git remote add origin "${SERVER}/${REPO}.git"
+          patterns=()
+          for dir in "${dirs[@]}"; do patterns+=("/$dir/"); done
+          git sparse-checkout set --no-cone "${patterns[@]}"
 
           pushed=false
+          missing=()
           for attempt in 1 2 3 4 5; do
-            if git ls-remote --exit-code --heads origin "$BRANCH" > /dev/null 2>&1; then
-              git fetch -q --depth=1 origin "$BRANCH"
-              git checkout -q -f -B "$BRANCH" FETCH_HEAD
+            if [ "$attempt" -eq 1 ]; then
+              git checkout -q "$BRANCH"
             else
-              git checkout -q -f --orphan "$BRANCH"
-              git rm -rqf --cached . > /dev/null 2>&1 || true
-              printf '%s\n' "# Evidence" "" \
-                "Screenshots the evidence workflow replayed from each merged pull request's verification plan, one folder per pull request." \
-                "Written by a workflow, never by hand. Nothing here is built, deployed or merged." > README.md
-              git add README.md
+              git fetch -q --depth=1 origin "$BRANCH"
+              git reset -q --hard FETCH_HEAD
             fi
-
-            rm -rf "pr-$PR"
-            mkdir -p "pr-$PR"
-            cp "$src"/*.jpg "$src/manifest.json" "pr-$PR/"
-            git add -A "pr-$PR"
+            missing=()
+            for dir in "${dirs[@]}"; do
+              # A plan moved or removed since the merge has no folder to keep the record in.
+              if [ ! -f "$dir/verification-plan.md" ]; then
+                missing+=("$dir")
+                continue
+              fi
+              rm -rf "$dir/evidence"
+              mkdir -p "$dir/evidence"
+              cp -R "$src/$dir/evidence/." "$dir/evidence/"
+              git add -A "$dir/evidence"
+            done
             if git diff --cached --quiet; then
               pushed=true
               break
             fi
-            git commit -q -m "evidence: pull request #$PR"
+            git commit -q -m "evidence: screenshots for #$PR [skip ci]"
             if git push -q origin "HEAD:refs/heads/$BRANCH"; then
               pushed=true
               break
             fi
-            echo "Another publish moved $BRANCH first (attempt $attempt); retrying on its new tip."
+            echo "$BRANCH moved before the push (attempt $attempt); retrying on its new tip."
             sleep $((attempt * 3))
           done
-          [ "$pushed" = "true" ] || { echo "::error::could not push to $BRANCH after 5 attempts"; exit 1; }
+          if [ "$pushed" != "true" ]; then
+            # A protected default branch refuses the push. The comment says so, and the run's
+            # artifact keeps the screenshots, so the merge that already happened stays green.
+            echo "::warning::could not push the screenshots to $BRANCH after 5 attempts"
+            echo "base=" >> "$GITHUB_OUTPUT"
+            echo "reason=the push to $BRANCH was refused" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ "${#missing[@]}" -eq "${#dirs[@]}" ]; then
+            echo "None of the plans is on $BRANCH any more; nothing was kept."
+            echo "base=" >> "$GITHUB_OUTPUT"
+            echo "reason=none of the plans is on $BRANCH any more" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
 
           sha="$(git rev-parse HEAD)"
-          echo "base=${SERVER}/${REPO}/raw/${sha}/pr-${PR}" >> "$GITHUB_OUTPUT"
-          echo "Screenshots kept at ${SERVER}/${REPO}/tree/${sha}/pr-${PR}"
+          echo "base=${SERVER}/${REPO}/raw/${sha}" >> "$GITHUB_OUTPUT"
+          {
+            echo "missing<<EOF"
+            printf '%s\n' "${missing[@]}"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+          echo "Screenshots kept at ${SERVER}/${REPO}/tree/${sha} beside $(( ${#dirs[@]} - ${#missing[@]} )) plan(s)"
 
       # GITHUB_TOKEN on purpose: its comment raises no workflow event, so the router does not wake
       # up to read its own record. One comment per pull request, rewritten on a re-run.
@@ -333,14 +399,56 @@ jobs:
         env:
           PR_NUMBER: ${{ inputs.pr-number }}
           MARKER: ${{ env.EVIDENCE_MARKER }}
-          IMAGE_BASE: ${{ steps.branch.outputs.base }}
+          MERGED: ${{ steps.pr.outputs.merged }}
+          IMAGE_BASE: ${{ steps.archive.outputs.base }}
+          MISSING: ${{ steps.archive.outputs.missing }}
+          REASON: ${{ steps.archive.outputs.reason }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          ARTIFACT_DAYS: ${{ env.EVIDENCE_ARTIFACT_DAYS }}
         with:
           script: |
             const fs = require('node:fs');
             const path = require('node:path');
             const issue_number = Number(process.env.PR_NUMBER);
-            const source = fs.readFileSync(path.join(process.env.RUNNER_TEMP, 'evidence', 'comment.md'), 'utf8');
-            const body = source.split('__EVIDENCE_BASE__').join(process.env.IMAGE_BASE);
+            const evidence = path.join(process.env.RUNNER_TEMP, 'evidence');
+            let source = fs.readFileSync(path.join(evidence, 'comment.md'), 'utf8');
+            const base = process.env.IMAGE_BASE ?? '';
+            const missing = (process.env.MISSING ?? '').split('\n').map((line) => line.trim()).filter(Boolean);
+            const kept = (file) => Boolean(base) && !missing.some((dir) => file.startsWith(`${dir}/evidence/`));
+
+            // An image that was not archived would render broken: its line goes, and a note says
+            // the run's artifact has it instead.
+            source = source.replace(/^!\[[^\]]*\]\(__EVIDENCE_BASE__\/([^)]*)\)\n?/gm, (line, file) => (kept(file) ? line : ''));
+            const shots = fs.readdirSync(evidence, { recursive: true }).some((name) => String(name).endsWith('.jpg'));
+            if (!base) source = source.replace(/^The screenshots are kept beside each plan.*\n\n?/m, '');
+            if (shots && (!base || missing.length > 0)) {
+              const why = process.env.MERGED !== 'true'
+                ? 'the pull request is not merged, so its plans are not on the default branch'
+                : !base
+                  ? (process.env.REASON || 'the screenshots could not be committed')
+                  : `${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} no longer on the default branch`;
+              source = source.replace('## Visual evidence\n', `## Visual evidence\n\n> Not archived: ${why}. The screenshots are in [the run](${process.env.RUN_URL})'s artifact for ${process.env.ARTIFACT_DAYS} days.\n`);
+            }
+
+            // The embedded manifest is what other tools read, so it says exactly what was kept: the
+            // base where the files are, and no file for a screenshot that was not archived. It sits
+            // in an HTML comment, which a `--` would close; `\u002d` is the same to a JSON reader.
+            source = source.replace(/<!-- agentic-evidence-manifest\n([\s\S]*?)\n-->/, (block, json) => {
+              let data;
+              try {
+                data = JSON.parse(json);
+              } catch {
+                return block;
+              }
+              data.base = base || null;
+              for (const plan of data.plans ?? []) {
+                for (const waypoint of plan.waypoints ?? []) {
+                  if (waypoint.file && !kept(waypoint.file)) waypoint.file = null;
+                }
+              }
+              return `<!-- agentic-evidence-manifest\n${JSON.stringify(data).replace(/-(?=-)/g, '\\u002d')}\n-->`;
+            });
+            const body = source.split('__EVIDENCE_BASE__').join(base);
             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/loops/workflows/work-router.yml

@@ -630,8 +630,8 @@ jobs:
       AGENTMEMORY_SECRET: ${{ secrets.AGENTMEMORY_SECRET }}
 
   # Screenshots of a merged pull request, replayed from the verification plan its implementation
-  # wrote and archived on the pull request. Plain YAML with no model, so no secret is passed and the
-  # grant is exactly what the publish job writes: the evidence branch and one comment. Its capture
+  # wrote and archived beside that plan. Plain YAML with no model, so no secret is passed and the
+  # grant is exactly what the publish job writes: one commit of evidence/ folders and one comment. Its capture
   # job runs the pull request's code with read-only access; only publish holds these writes, and it
   # runs no repository code.
   call-evidence:

package/package.json

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