@plainconceptsplatform/workflows 1.1.1 → 1.2.1

package/dist/catalog-installation.js

@@ -326,7 +326,11 @@ async function preCommitHookUpdate(repositoryPath) {
     if (!await exists(hookPath)) {
         return { target, content: managedLines };
     }
+    // A Windows clone with core.autocrlf checks the hook out with CRLF, which the LF patterns below
+    // never match: every update from Windows appended one more block (one consumer had ten). The
+    // hook is written back with LF, as every managed file is.
     const content = (await readFile(hookPath, "utf8"))
+        .replace(/\r\n/g, "\n")
         .replace("pnpm exec if git diff --cached --name-only -- .github | grep -q .; then", "if git diff --cached --name-only -- .github | grep -q .; then");
     // Replace whatever managed block is there, never append beside it. The previous version
     // recognised only two exact shapes -- the current block and the pre-`if` legacy lines -- and

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:
@@ -20,6 +21,13 @@ inputs:
     description: Where capture and unreached write the screenshots, manifest.json and comment.md.
     required: false
     default: ''
+  sign-in:
+    description: >
+      The repository's own sign-in steps for plans that start signed in (`login:`), relative to the
+      workspace, which is the default branch's checkout. The repository owns the file; without it
+      such a plan replays signed out and its comment says why.
+    required: false
+    default: '.github/evidence/sign-in.yml'
   playwright-version:
     description: playwright-core version. Must match the mcr.microsoft.com/playwright image tag the capture runs in.
     required: false
@@ -74,6 +82,7 @@ runs:
         ROOT: ${{ inputs.root }}
         PLANS: ${{ inputs.plans }}
         OUT_DIR: ${{ inputs.out-dir }}
+        EVIDENCE_SIGN_IN: ${{ inputs.sign-in }}
         PLAYWRIGHT_VERSION: ${{ inputs.playwright-version }}
         # Chromium's own stderr. A browser that dies on launch says why only here.
         DEBUG: pw:browser
@@ -101,7 +110,7 @@ runs:
             if command -v docker > /dev/null 2>&1; then
               # The host network, so the browser reaches the app on localhost where it started;
               # the runner's own user, so what it writes the publish job can read.
-              docker run --rm --network host --ipc host                 --user "$(id -u):$(id -g)" -e HOME=/tmp -e DEBUG                 -e EVIDENCE_SHA -e EVIDENCE_RUN_URL -e EVIDENCE_STEP_TIMEOUT_MS -e EVIDENCE_NAVIGATION_TIMEOUT_MS                 -v "$runner:$runner:ro" -v "$GITHUB_WORKSPACE:$GITHUB_WORKSPACE:ro" -v "$OUT_DIR:$OUT_DIR"                 -w "$GITHUB_WORKSPACE"                 "mcr.microsoft.com/playwright:v${PLAYWRIGHT_VERSION}-noble"                 node "$runner/capture.mjs" capture "$ROOT" "$OUT_DIR" "${plans[@]}"
+              docker run --rm --network host --ipc host                 --user "$(id -u):$(id -g)" -e HOME=/tmp -e DEBUG                 -e EVIDENCE_SHA -e EVIDENCE_RUN_URL -e EVIDENCE_SIGN_IN -e EVIDENCE_STEP_TIMEOUT_MS -e EVIDENCE_NAVIGATION_TIMEOUT_MS                 -v "$runner:$runner:ro" -v "$GITHUB_WORKSPACE:$GITHUB_WORKSPACE:ro" -v "$OUT_DIR:$OUT_DIR"                 -w "$GITHUB_WORKSPACE"                 "mcr.microsoft.com/playwright:v${PLAYWRIGHT_VERSION}-noble"                 node "$runner/capture.mjs" capture "$ROOT" "$OUT_DIR" "${plans[@]}"
             else
               node "$runner/capture.mjs" capture "$ROOT" "$OUT_DIR" "${plans[@]}"
             fi

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,17 @@ 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;
+// The repository's own steps for signing in locally, read from the default branch so a replay of
+// an older pull request finds them too. The repository owns the file: an update never writes it.
+export const SIGN_IN_FILE = ".github/evidence/sign-in.yml";
+const ACCOUNT_PLACEHOLDER = "{account}";
 
 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 +58,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";
@@ -108,15 +133,83 @@ export function normalizePlan(doc) {
     return { n: index + 1, capture, expect: String(raw.expect ?? "").trim(), steps, ignored };
   });
 
+  const login = parseLogin(doc.login ?? environment.login, environment);
   return {
     status: "runnable",
     url: String(doc.url ?? environment.url ?? DEFAULT_URL).trim() || DEFAULT_URL,
     start: String(doc.start ?? environment.start ?? "").trim(),
     viewport: parseViewport(doc.viewport ?? environment.viewport),
+    ...(login ? { login } : {}),
     waypoints,
   };
 }
 
+// A plan that starts signed in says so with `login`, rather than signing in in its first
+// waypoint. The plans written before that waypoint signed in name a mechanism (`login: mock-sso`)
+// and say whom in prose ("Sign in as Bob Builder"), so the prose travels along as a hint. A plan
+// can also name the account (`login: { account: Bob Builder }`) or spell out its own steps.
+export function parseLogin(value, environment = {}) {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (Array.isArray(value)) return { steps: value };
+  if (isObject(value) && Array.isArray(value.steps)) return { steps: value.steps };
+  if (isObject(value) && value.account !== undefined) return { account: String(value.account) };
+  const hint = Object.values(environment).filter((text) => typeof text === "string").join("\n");
+  return { hint };
+}
+
+// The account a plan's prose asks for: one of the repository's accounts right after "sign in as",
+// the earliest when the prose names several. Only an account the repository lists can match.
+export function accountNamed(text, accounts) {
+  let best;
+  for (const account of accounts) {
+    const escaped = account.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const at = String(text ?? "").search(new RegExp(`sign(?:ed)?[\\s-]*in\\s+as\\s+(?:the\\s+)?${escaped}\\b`, "i"));
+    if (at >= 0 && (best === undefined || at < best.at)) best = { account, at };
+  }
+  return best?.account;
+}
+
+// Reads the repository's sign-in: the steps, in the journey's own step syntax, with `{account}`
+// where the account goes, and the accounts a plan can ask for, the first being the default.
+export function parseSignIn(text, parseYaml) {
+  const doc = parseYaml(String(text));
+  if (!isObject(doc) || !Array.isArray(doc.steps) || doc.steps.length === 0) {
+    throw new Error("the sign-in needs a steps list");
+  }
+  return { accounts: asArray(doc.accounts).map((account) => String(account)), steps: doc.steps };
+}
+
+const fillAccount = (value, account) =>
+  typeof value === "string"
+    ? value.split(ACCOUNT_PLACEHOLDER).join(account)
+    : Array.isArray(value)
+      ? value.map((item) => fillAccount(item, account))
+      : isObject(value)
+        ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fillAccount(item, account)]))
+        : value;
+
+// A first waypoint that clicks one of the repository's accounts signs the plan in itself, as some
+// plans that also say `login:` do. Signing in before it would leave that click nothing to find.
+function signsItselfIn(plan, accounts) {
+  const names = new Set(accounts.map((account) => account.toLowerCase()));
+  return (plan.waypoints[0]?.steps ?? []).some((step) =>
+    step.action === "click" && [step.locator?.text, step.locator?.name].some((name) => name !== undefined && names.has(name.toLowerCase())),
+  );
+}
+
+// The steps that sign a plan in before its first waypoint, or why there are none to run.
+export function signInFor(plan, signIn) {
+  const login = plan.login;
+  if (!login) return undefined;
+  const parsed = (raw) => raw.map(parseStep).filter((step) => step.ignored === undefined);
+  if (login.steps) return { steps: parsed(login.steps) };
+  if (!signIn) return { steps: [], error: `the plan starts signed in, but the repository has no ${SIGN_IN_FILE}` };
+  if (signIn.error) return { steps: [], error: signIn.error };
+  if (signsItselfIn(plan, signIn.accounts)) return undefined;
+  const account = login.account ?? accountNamed(login.hint, signIn.accounts) ?? signIn.accounts[0] ?? "";
+  return { ...(account ? { account } : {}), steps: parsed(fillAccount(signIn.steps, account)) };
+}
+
 function locatorOf(value) {
   if (typeof value === "string") return { text: value };
   if (!isObject(value)) return undefined;
@@ -422,14 +515,30 @@ 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);
   page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
 
   const results = [];
+  let signedIn;
   try {
+    if (plan.signIn) {
+      // Signing in is not a waypoint: nothing is captured, and a failure is recorded while the
+      // journey still runs, so its screenshots show where a missing sign-in left it.
+      const errors = plan.signIn.error ? [plan.signIn.error] : [];
+      for (const step of plan.signIn.steps) {
+        try {
+          await runStep(page, step, plan.url);
+        } catch (error) {
+          errors.push(`${describeStep(step)}: ${firstLine(error)}`);
+          break;
+        }
+      }
+      signedIn = { ...(plan.signIn.account ? { account: plan.signIn.account } : {}), reached: errors.length === 0, errors };
+      console.log(`${dir} sign-in${plan.signIn.account ? ` as ${plan.signIn.account}` : ""}: ${errors.length === 0 ? "ok" : errors.join("; ")}`);
+    }
     for (const waypoint of plan.waypoints) {
       const errors = [];
       for (const step of waypoint.steps) {
@@ -442,10 +551,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,23 +569,70 @@ 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();
   }
-  return results;
+  return { waypoints: results, signedIn };
 }
 
 // ── Report ──────────────────────────────────────────────────────────────────────────────────
 
 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.`, "");
@@ -491,6 +648,10 @@ export function renderComment(manifest) {
       lines.push(`Not replayed: ${escapeMarkdown(plan.reason || plan.status)}.`, "");
       continue;
     }
+    if (plan.signIn) {
+      const as = plan.signIn.account ? ` as ${escapeMarkdown(plan.signIn.account)}` : "";
+      lines.push(plan.signIn.reached ? `Signed in${as} first.` : `> Could not sign in${as} first: ${escapeMarkdown(plan.signIn.errors.join("; "))}`, "");
+    }
     const missed = plan.waypoints.filter((waypoint) => !waypoint.reached).length;
     const summary = `${plan.waypoints.length} waypoint${plan.waypoints.length === 1 ? "" : "s"}${missed > 0 ? `, ${missed} did not reach their state` : ""}`;
     lines.push("<details>", `<summary>${summary}</summary>`, "");
@@ -503,6 +664,8 @@ export function renderComment(manifest) {
     }
     lines.push("</details>", "");
   }
+  const embedded = embedManifest(manifest);
+  if (embedded) lines.push(embedded, "");
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
@@ -535,26 +698,43 @@ async function inspect(root, paths) {
   };
 }
 
+// The repository's sign-in, or null when it has none. The path is relative to the working
+// directory, which is the default branch's checkout, not the pull request head.
+async function loadSignIn(path, parseYaml) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+  return parseSignIn(text, parseYaml);
+}
+
 async function capture(root, outDir, paths) {
   const { parse } = await import("yaml");
   const { chromium } = await import("playwright-core");
   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: [] };
+  let signIn = null;
+  if (runnable.some((plan) => plan.login)) {
+    const path = process.env.EVIDENCE_SIGN_IN || SIGN_IN_FILE;
+    signIn = await loadSignIn(path, parse).catch((error) => ({ error: `${path}: ${firstLine(error)}` }));
+  }
 
   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);
-      manifest.plans.push({ path: plan.path, change: plan.change, status: "captured", url: plan.url, waypoints });
+      const dir = planDir(plan.path);
+      await mkdir(join(outDir, "files", dir, EVIDENCE_DIR), { recursive: true });
+      const { waypoints, signedIn } = await replay(browser, { ...plan, signIn: signInFor(plan, signIn) }, outDir, dir);
+      manifest.plans.push({ path: plan.path, change: plan.change, status: "captured", url: plan.url, ...(signedIn ? { signIn: signedIn } : {}), waypoints });
     }
   } finally {
     await browser?.close();
@@ -573,6 +753,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 +772,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,17 @@ 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, and nothing
+# either job writes raises another workflow event. The one thing a repository may add is its own
+# .github/evidence/sign-in.yml, for plans that start signed in rather than signing in themselves.
 #
 # 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 +37,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 +70,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 +192,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 +266,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 +285,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 +400,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.1",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",