forgedock 1.0.17 → 1.0.18

package/bin/forgedock.mjs

@@ -204,7 +204,7 @@ function stripJsonc(raw) {
     if (ch === "/" && i + 1 < len && raw[i + 1] === "*") {
       i += 2;
       while (i + 1 < len && !(raw[i] === "*" && raw[i + 1] === "/")) i++;
-      i += 2;
+      if (i + 1 < len) i += 2; // only advance past */ if terminator was found
       continue;
     }
 
@@ -240,7 +240,7 @@ function stripJsonc(raw) {
         if (j + 1 < len && raw[j] === "/" && raw[j + 1] === "*") {
           j += 2;
           while (j + 1 < len && !(raw[j] === "*" && raw[j + 1] === "/")) j++;
-          j += 2;
+          if (j + 1 < len) j += 2; // only advance past */ if terminator was found
           advanced = true;
         }
       }
@@ -321,6 +321,51 @@ function atomicWriteFile(filePath, content) {
   }
 }
 
+/**
+ * Idempotently write a `.symlink-source` sentinel file to TARGET_DIR
+ * (~/.claude/commands/) so other installers can detect that ForgeDock
+ * owns this namespace.
+ *
+ * The sentinel is a plain UTF-8 text file (not a symlink) containing
+ * the source path, a reinstall hint, and the install timestamp.  It is
+ * updated on every install so the timestamp stays fresh.  Write failures
+ * are non-fatal — the function returns 'failed' and the caller logs a
+ * warning; install continues regardless.
+ *
+ * Calling convention matches the other state-write helpers:
+ *   'written'  — sentinel was newly created or refreshed
+ *   'failed'   — an error occurred (non-fatal; install continues)
+ *
+ * <!-- Added: forge#1038 -->
+ *
+ * @returns {'written' | 'failed'}
+ */
+function writeSymlinkSentinel() {
+  const sentinelPath = join(TARGET_DIR, ".symlink-source");
+  const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+  const content =
+    `# ForgeDock command symlinks — DO NOT REPOINT\n` +
+    `# Source: ${COMMANDS_DIR}\n` +
+    `#\n` +
+    `# These symlinks are managed by ForgeDock (https://forgedock.com).\n` +
+    `# ForgeDock owns the global ~/.claude/commands/ namespace.\n` +
+    `# Project-specific commands should install to the project's\n` +
+    `# .claude/commands/ directory instead (Claude Code merges both;\n` +
+    `# project-local commands win on name collisions).\n` +
+    `#\n` +
+    `# Running another installer here will silently repoint these\n` +
+    `# symlinks, breaking all ForgeDock commands globally.\n` +
+    `#\n` +
+    `# To reinstall ForgeDock: npx forgedock install\n` +
+    `# Last installed: ${timestamp}\n`;
+  try {
+    atomicWriteFile(sentinelPath, content);
+    return "written";
+  } catch {
+    return "failed";
+  }
+}
+
 /**
  * Install the ForgeDock SessionStart hook into ~/.claude/settings.json
  * idempotently. Does not modify any existing hooks unrelated to ForgeDock.
@@ -566,9 +611,18 @@ function injectManagedBlock(filePath) {
           "[\\s\\S]*?" +
           escapeRegExp(CLAUDE_BLOCK_END),
       );
+      if (!blockRegex.test(existing)) {
+        // Should not happen: both markers were confirmed above via includes() and
+        // indexOf() ordering. Guard against silent misclassification — if the regex
+        // somehow fails to match, replaced === existing would incorrectly return
+        // 'unchanged' instead of surfacing the broken state.
+        throw new Error(
+          `injectManagedBlock: regex failed to match markers in ${filePath}`,
+        );
+      }
       const replaced = existing.replace(blockRegex, managed);
       if (replaced === existing) {
-        // Regex matched but content was already identical
+        // Content between markers was already identical to the managed block
         return "unchanged";
       }
       atomicWriteFile(filePath, replaced);
@@ -754,8 +808,12 @@ function removeForgeHomeFromProfile(profilePath) {
   // Step 1: Remove the 2-line ForgeDock block (comment + export), preceded
   // by an optional leading blank line that install() inserts.
   // The \r? handles profiles with CRLF line endings.
+  // The value pattern (?:[^"\\]|\\.)*  matches a double-quoted shell string
+  // that may contain backslash-escape sequences (e.g. \" or \\) written by
+  // shellEscapeDoubleQuotedPath(). The simpler [^"]* would stop prematurely
+  // at the escaped-quote character inside \", failing to match the full line.
   let cleaned = content.replace(
-    /\r?\n[ \t]*# ForgeDock — autonomous development pipeline\r?\nexport FORGE_HOME="[^"]*"\r?\n/g,
+    /\r?\n[ \t]*# ForgeDock — autonomous development pipeline\r?\nexport FORGE_HOME="(?:[^"\\]|\\.)*"\r?\n/g,
     "\n",
   );
 
@@ -820,6 +878,16 @@ async function linkCommands(step) {
         if (current === file) {
           skipped++;
         } else {
+          // Symlink points to a different source — warn if it appears to belong
+          // to another Forge/ForgeDock installation (i.e. not a broken link that
+          // already pointed here under a different absolute path).
+          // Only emit the warning once per install to avoid log spam.
+          // <!-- Added: forge#1038 -->
+          if (!current.startsWith(COMMANDS_DIR)) {
+            step.note(
+              yellow(`collision: ${rel} was → ${current} — repointing to ForgeDock`),
+            );
+          }
           try {
             await symlink(file, target + ".tmp");
             const { rename } = await import("fs/promises");
@@ -986,6 +1054,29 @@ async function install() {
     {
       label: "Checking environment",
       async run(step) {
+        // Worktree guard — refuse to install when FORGE_HOME is a git worktree.
+        // In a worktree, FORGE_HOME/.git is a regular file (not a directory).
+        // Installing from a worktree would bake an ephemeral path into the
+        // symlinks and SessionStart hook; the path breaks when the worktree
+        // is cleaned up, taking all Forge commands offline globally.
+        // <!-- Added: forge#1037 -->
+        const gitPath = join(FORGE_HOME, ".git");
+        let gitStat = null;
+        try {
+          gitStat = await lstat(gitPath);
+        } catch (err) {
+          if (err.code !== "ENOENT") throw err;
+          // .git absent — npm install or detached checkout; not a worktree.
+        }
+        if (gitStat !== null && gitStat.isFile()) {
+          throw new Error(
+            `install() is running from a git worktree (${FORGE_HOME}).\n` +
+            `  Installing from a worktree would repoint ~/.claude/commands/ symlinks\n` +
+            `  to an ephemeral path that breaks when the worktree is deleted.\n` +
+            `  Run \`npx forgedock install\` from the main repository clone instead.`,
+          );
+        }
+
         await mkdir(TARGET_DIR, { recursive: true });
         step.note(cyan(TARGET_DIR));
       },
@@ -1000,6 +1091,20 @@ async function install() {
         );
       },
     },
+    {
+      label: "Writing namespace sentinel",
+      async run(step) {
+        // Write .symlink-source to ~/.claude/commands/ so other installers
+        // can detect that ForgeDock owns this namespace. Non-fatal on failure.
+        // <!-- Added: forge#1038 -->
+        const result = writeSymlinkSentinel();
+        if (result === "failed") {
+          step.note("could not write .symlink-source — run npx forgedock install again to retry");
+        } else {
+          step.note(cyan(join(TARGET_DIR, ".symlink-source")));
+        }
+      },
+    },
     {
       label: "Linking scripts",
       async run(step) {
@@ -1036,7 +1141,12 @@ async function install() {
               // Either not present, or set to a stale path — refresh it.
               if (content.includes("FORGE_HOME")) {
                 // Strip the old block before appending the updated one.
-                removeForgeHomeFromProfile(profile);
+                const removeResult = removeForgeHomeFromProfile(profile);
+                if (removeResult === "failed") {
+                  // Removal failed — old export still present. Skip append to
+                  // avoid writing a duplicate FORGE_HOME export. (ref: forge#846)
+                  continue;
+                }
               }
               appendFileSync(
                 profile,
@@ -1158,8 +1268,17 @@ async function uninstall() {
           console.log(`  ${RED}Removed${RESET}: ${rel}`);
           removed++;
         }
+      } else if (
+        readFileSync(file, "utf-8") === readFileSync(target, "utf-8")
+      ) {
+        // Regular file installed by ForgeDock in copy mode — content matches.
+        const { unlink } = await import("fs/promises");
+        await unlink(target);
+        console.log(`  ${RED}Removed${RESET}: ${rel}`);
+        removed++;
       }
-    } catch {
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
       // Doesn't exist — nothing to do
     }
   }
@@ -1580,6 +1699,14 @@ async function init(fromInstall = false) {
     .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
     .join(" ");
 
+  // Pre-escape values for embedding in YAML double-quoted strings.
+  // Backslash must be escaped first to avoid double-escaping.
+  const safeOwner = owner.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const safeRepo = repo.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const safeProjectName = projectName.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const safeDefaultBranch = defaultBranch.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const safeStagingBranch = stagingBranch.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+
   const content = `# forge.yaml — ForgeDock Configuration
 #
 # Auto-generated by: npx forgedock init
@@ -1595,9 +1722,9 @@ async function init(fromInstall = false) {
 # =============================================================================
 
 project:
-  name: "${projectName}"
-  owner: "${owner}"
-  repo: "${repo}"
+  name: "${safeProjectName}"
+  owner: "${safeOwner}"
+  repo: "${safeRepo}"
   description: "${description.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"
 
 # =============================================================================
@@ -1613,8 +1740,8 @@ paths:
 # =============================================================================
 
 branches:
-  default: "${defaultBranch}"
-  staging: "${stagingBranch}"
+  default: "${safeDefaultBranch}"
+  staging: "${safeStagingBranch}"
   feature_pattern: "milestone/{slug}"
 
 # =============================================================================
@@ -1624,22 +1751,22 @@ branches:
 
 # repos:
 #   default:
-#     repo: "${owner}/${repo}"
-#     staging_branch: "${stagingBranch}"
+#     repo: "${safeOwner}/${safeRepo}"
+#     staging_branch: "${safeStagingBranch}"
 #   satellites:
 #     - prefix: "mcp"
-#       repo: "${owner}/your-satellite-repo"
+#       repo: "${safeOwner}/your-satellite-repo"
 #       staging_branch: "main"
 #       local_path: "${join(cwd, "..", "your-satellite-repo").replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"
 
 # =============================================================================
 # PROJECT BOARD (OPTIONAL)
 # GitHub Projects v2 integration.
-# To find IDs: gh project list --owner ${owner}
+# To find IDs: gh project list --owner ${safeOwner}
 # =============================================================================
 
 # project_board:
-#   owner: "${owner}"
+#   owner: "${safeOwner}"
 #   project_number: 1
 #   project_id: "PVT_kwHOxxxxxxxxxxxxxxxx"
 #   field_ids:
@@ -1665,9 +1792,37 @@ branches:
 # =============================================================================
 
 # verification:
-#   health_endpoint: "https://api.${repo}.io/health"
+#   health_endpoint: "https://api.${safeRepo}.io/health"
 #   health_patterns:
 #     - '"status": "ok"'
+#
+#   # Integration test suites run by /test-gate against the provisioned cluster.
+#   # Each entry specifies a logical cluster (matched to test_services), the shell
+#   # command to execute, and the working directory (relative to project root).
+#   # Used by: test-gate (Phase 3 Provision + Phase 4 Fan out)
+#   #
+#   # integration_tests:
+#   #   - cluster: "api"
+#   #     command: "pytest tests/integration/ -q --tb=short"
+#   #     working_dir: "."
+#
+#   # Maps logical cluster names (from integration_tests) to running container
+#   # names. /test-gate checks these containers are live before running tests.
+#   # Omit entries for clusters that do not use Docker.
+#   # Used by: test-gate (Phase 3 Provision)
+#   #
+#   # test_services:
+#   #   api: "${safeRepo}-api-blue"
+#   #   worker: "${safeRepo}-worker-blue"
+#
+#   # Controls /test-gate posture at the staging-to-main deploy boundary.
+#   # posture: blocking (default) or advisory.
+#   # override_phrase: exact comment text an operator posts to bypass a BLOCK.
+#   # Used by: test-gate (Phase 7 Verdict), review-pr-staging (Phase 6.5)
+#   #
+#   # test_gate:
+#   #   posture: "blocking"
+#   #   override_phrase: "OVERRIDE: shipping with test failures \u2014"
 `;
 
   atomicWriteFile(outputPath, content);
@@ -1866,6 +2021,7 @@ async function status(dir) {
  *   6. CLAUDE.md has the ForgeDock behavioral block (cwd)
  *   7. Required workflow labels exist on the GitHub repo (needs forge.yaml + gh auth)
  *   8. FORGE_HOME environment variable is set
+ *   9. Playwright MCP registered in ~/.claude/mcp_servers.json (advisory warn — required for /qa-sweep)
  *
  * Exits with code 0 if all checks pass, code 1 if any fail.
  */
@@ -2229,6 +2385,62 @@ async function doctor() {
     }
   }
 
+  // ── Check 9: Playwright MCP registered ────────────────────────────────────
+  // Playwright MCP is a guaranteed ForgeDock dependency for browser automation
+  // commands (/qa-sweep). This check is advisory (warn, not fail) because MCP
+  // server presence is orthogonal to the core ForgeDock install — but missing
+  // it causes /qa-sweep to silently fail mid-sweep.
+  {
+    const mcpServersPath = join(HOME, ".claude", "mcp_servers.json");
+    let playwrightFound = false;
+    let fileReadable = false;
+    let hasMcpServers = false;
+
+    try {
+      const mcpRaw = readFileSync(mcpServersPath, "utf-8");
+      const mcpConfig = JSON.parse(mcpRaw);
+      // Read + parse succeeded — the file exists and contains valid JSON.
+      fileReadable = true;
+      const servers = mcpConfig?.mcpServers;
+      if (servers && typeof servers === "object") {
+        hasMcpServers = true;
+        // Search for a registered server whose name or command references playwright
+        for (const [name, entry] of Object.entries(servers)) {
+          const nameLower = name.toLowerCase();
+          const cmdStr = [
+            entry?.command ?? "",
+            ...(Array.isArray(entry?.args) ? entry.args : []),
+          ].join(" ").toLowerCase();
+          if (nameLower.includes("playwright") || cmdStr.includes("playwright")) {
+            playwrightFound = true;
+            break;
+          }
+        }
+      }
+    } catch {
+      // File absent or unreadable — treat as no MCP servers configured
+    }
+
+    if (!fileReadable) {
+      warn(
+        "Playwright MCP",
+        "No MCP servers file found (~/.claude/mcp_servers.json). Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest",
+      );
+    } else if (!hasMcpServers) {
+      warn(
+        "Playwright MCP",
+        "MCP servers file found (~/.claude/mcp_servers.json) but it has no 'mcpServers' key. Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest",
+      );
+    } else if (playwrightFound) {
+      pass("Playwright MCP", "registered in Claude Code MCP servers");
+    } else {
+      warn(
+        "Playwright MCP",
+        "Not registered — /qa-sweep and browser automation commands will fail. Run: claude mcp add playwright npx @playwright/mcp@latest",
+      );
+    }
+  }
+
   // ── Summary ────────────────────────────────────────────────────────────────
   console.log("");
   if (failures === 0 && warnings === 0) {

package/commands/autopilot.md

@@ -312,6 +312,7 @@ Print a structured report:
 - Issues commented: {count}
 - Orphans closed: {count}
 - Stale labels fixed: {count}
+- Spec-edit impact analyses logged: {count} (FORGE:AUTOPILOT_IMPACT — blast radius surfaced before spec fixes)
 
 ### Recommended Next Steps
 {Prioritized list of what the user should look at or deploy}
@@ -372,6 +373,81 @@ Nothing merges to `main` — you deploy when ready.
 
 Wait for user response. If they adjust, re-select. If they skip, end the cycle.
 
+### 4B.5: Spec-Edit Impact Analysis (MANDATORY before any spec-touching fix) <!-- Added: forge#870 -->
+
+**Goal**: Before autopilot dispatches a fix that edits ForgeDock's own command specs (`commands/*.md`), surface the blast radius of the change so the edit doesn't silently break downstream consumers (every spec that reads a changed FORGE annotation, every command in a changed sub-phase chain, every script/label a touched node feeds).
+
+This step **consumes the read-only query interface** shipped by the Spec Knowledge Graph (`scripts/graph-query.sh`, subcommand `impact`). It does **not** reimplement graph traversal — the blast radius is computed once, in `graph-query.sh`, and autopilot only reads its output.
+
+**When it runs**: for each approved fix target whose affected files (from the issue body's `## Affected Files` section, or the recon finding that created it) include any path matching `commands/*.md`. Non-spec fixes skip this step entirely.
+
+**Graceful degradation**: `graph-query.sh` ships only with the Spec Knowledge Graph. If it is absent (fast-lane repos, or a checkout predating the milestone), **skip with a noted reason — never block the cycle**.
+
+```bash
+GRAPH_QUERY="$(git rev-parse --show-toplevel)/scripts/graph-query.sh"
+
+# For each approved fix target that edits commands/*.md:
+for issue in $SPEC_FIX_TARGETS; do
+  if [ ! -x "$GRAPH_QUERY" ]; then
+    echo "skip impact analysis for #$issue — graph-query.sh not present (Spec Knowledge Graph not installed)"
+    continue
+  fi
+
+  # Derive the spec node(s) the fix changes. Prefer the FORGE annotation or
+  # command/sub-phase named in the issue's Affected Files / recon finding.
+  # graph-query.sh normalizes all of these forms:
+  #   FORGE:CONTRACT  ==  CONTRACT  ==  ann:FORGE:CONTRACT
+  #   work-on:build:implement  ==  cmd:work-on:build:implement
+  #   classify-lane.sh  ==  script:classify-lane.sh
+  #   workflow:merged  ==  label:workflow:merged
+  for node in $CHANGED_SPEC_NODES; do
+    echo "### Impact of changing $node (fix #$issue)"
+    bash "$GRAPH_QUERY" impact "$node" --human
+  done
+done
+```
+
+**Log the result in a FORGE annotation.** Post one `FORGE:AUTOPILOT_IMPACT` comment per spec-touching fix target on its issue, BEFORE invoking `/work-on` in 4C:
+
+```bash
+gh issue comment $issue --body "<!-- FORGE:AUTOPILOT_IMPACT -->
+## Spec-Edit Impact Analysis
+
+**Changed spec node(s)**: \`$CHANGED_SPEC_NODES\`
+**Query**: \`graph-query.sh impact <node> --human\` (Spec Knowledge Graph, read-only)
+
+### Blast Radius (downstream consumers of this change)
+\`\`\`
+$IMPACT_OUTPUT
+\`\`\`
+
+Every command/spec listed above reads the changed annotation or sits in the changed sub-phase chain. The \`/work-on\` build for this fix MUST keep these consumers working — verify the changed field/marker is still produced in the shape they expect.
+
+<!-- FORGE:AUTOPILOT_IMPACT:COMPLETE -->"
+```
+
+If `graph-query.sh` was absent, post the same annotation with the blast-radius block set to `(skipped — Spec Knowledge Graph not installed)` so the skip is auditable.
+
+**Worked example** — autopilot picks up a fix that renames a field inside the `FORGE:CONTRACT` annotation. Before dispatching `/work-on`, it runs:
+
+```bash
+$ graph-query.sh impact FORGE:CONTRACT --human
+Impact (blast radius) of changing ann:FORGE:CONTRACT:
+  cmd:milestone
+  cmd:orchestrate
+  cmd:resume
+  cmd:review-pr
+  cmd:work-on
+  cmd:work-on-monolithic
+  cmd:work-on:build
+  cmd:work-on:build:implement
+  cmd:work-on:review
+```
+
+The summary makes the nine downstream consumers explicit before the edit lands, so the contract-field rename is reviewed against every reader — not discovered as a broken consumer later.
+
+**`FORGE:AUTOPILOT_IMPACT`** is a leaf annotation: autopilot is its only writer and no downstream pipeline phase consumes it. It exists to record the blast radius on the issue thread for human and reviewer visibility.
+
 ### 4C: Execute fixes
 
 For each approved fix target, invoke `/work-on` via the Skill tool:
@@ -403,6 +479,7 @@ FIX_RESULTS.push({
 
 **Merged to staging**: {count}
 **Needs attention**: {list}
+**Spec-edit impact analyses**: {count} blast-radius summaries logged (FORGE:AUTOPILOT_IMPACT) before spec fixes
 
 When ready to deploy, merge `staging` → `main` via GitHub.
 ```

package/commands/design-bench.md

@@ -0,0 +1,176 @@
+---
+description: Run the ABC benchmark — reference URL → design-blind brief → render arms A/B/C → blind judge → scorecard with win-rates over n runs
+argument-hint: [<brief-name>|all] [--n <runs>] [--corpus-version <ver>]
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /design-bench — The ABC Benchmark Rig
+
+**Input**: $ARGUMENTS — a seed brief name (`cadence` | `tender` | `slipstream` | `voltage` | `plume`) or `all`, with optional `--n <runs>` (default 3, min 3) and `--corpus-version <ver>`.
+
+This is the **fitness function** for the UI Taste Harness (milestone #13, issue #878). It is built *before*
+the harness and is the only thing that tells us whether each lever the harness adds actually moves design
+quality. Running this command answers one question: **did arm A (the harness) score higher against the real
+reference (arm C) than it did last time?**
+
+Read [`docs/design/abc-benchmark.md`](../docs/design/abc-benchmark.md) (methodology) before running. The three
+arms, the same-model rule, the C-as-calibration check, the three-layer judging protocol, and the n>=3 rule all
+live there — this command is the executable workflow over that methodology.
+
+**No application runtime.** ForgeDock is a set of command specs. This command is a step-by-step procedure an
+agent executes; the only executable helper is the deterministic aggregator `scripts/bench-scorecard.mjs`.
+
+---
+
+## The three arms (one variable)
+
+| Arm | What it is | How this command produces it |
+|-----|------------|------------------------------|
+| **A** | ForgeDock harness output | Run the brief through `/design` (#888). **Pluggable** — see [Arm A is pluggable](#arm-a-is-pluggable). |
+| **B** | Raw frontier model, one shot | Hand the brief to the model once, no tools, no iteration. |
+| **C** | The real reference page | Capture the brief's real reference URL through the same render pipeline. |
+
+**Hard rule — same generation model for A and B.** The harness is the ONLY difference between A and B; that is
+what makes the A-vs-B delta attributable to the harness. Different models benchmark models, not the harness.
+
+**Validated generation model: `claude-opus-4-6`.** Benchmark results (#878) show a tier-level quality difference: 90% A-vs-B pairwise win-rate with Opus vs 54% with Sonnet, rubric mean 4.11 vs 3.40, slop 1.2 vs 1.8. The canonical baseline going forward is the Opus run. Raw data: `docs/design/fixtures/runs/full-abc-opus/`. Use Opus for both arm A and arm B unless explicitly testing a different model.
+
+---
+
+## Phase 0: Resolve inputs
+
+1. Parse `$ARGUMENTS`: the brief name(s) and `--n` (default 3; **reject n<3** — n=1 is a lie). `all` = every
+   brief under `docs/design/fixtures/briefs/` (excluding `README.md`).
+2. For each brief, load `docs/design/fixtures/briefs/<name>.md`. This is the design-blind input handed to arms
+   A and B.
+3. Load the brief→reference(C) mapping from `docs/design/fixtures/briefs/README.md`. **The mapping is for the
+   judge/calibration record only — it is NEVER shown to the generating arms.** A real brand name leaking into a
+   brief measures recall, not taste, and inflates arm B.
+
+---
+
+## Phase 1: Brief (reference URL → design-blind brief)
+
+The seed briefs are pre-stripped fixtures, so for the seed set this phase is a load, not a derivation.
+
+**To add a new reference URL** (outside the seed set): fetch the page, strip every visual cue (color, type,
+layout, "make it like X"), keep only what the product *does* / who it's for / what the page must communicate,
+and assign an **anonymized** product name. Save as a new fixture and add its mapping row. Follow
+`docs/design/fixtures/briefs/README.md`.
+
+---
+
+## Phase 2: Render arms (kill confounds)
+
+Render **all three arms through the identical pipeline** so the judge compares design, not rendering artifacts.
+
+For each of the `--n` runs per brief:
+
+1. **Arm A** — run the brief through `/design` (#888) → self-contained HTML.
+2. **Arm B** — one-shot the SAME model with the brief → self-contained HTML. No tools, no iteration.
+3. **Arm C** — the real reference URL.
+
+Render every arm with **Playwright** (milestone render dependency) at:
+
+- **1440px** desktop and **390px** mobile,
+- `networkidle` + fonts loaded before capture,
+- **full-page** screenshot.
+
+For arm C, trim cookie banners / hero video and **record any trim applied** in the run record (reproducibility).
+
+> **Arm A is pluggable.** Until `/design` (#888) lands, arm A is produced by a clearly-labeled manual hook:
+> generate arm A by hand using the harness method-of-the-day and drop its HTML into the run record marked
+> `arm_a_source: manual`. The rig — brief loading, render protocol, judging, scorecard — is fully operational
+> without #888. When #888 lands, replace the manual hook with the `/design` invocation; nothing else changes.
+> **Do NOT block the benchmark on #888.**
+
+---
+
+## Phase 3: Judge (three layers)
+
+The judge is a **named, independent stage**. See [Anti-Goodhart](#anti-goodhart) — it MUST NOT be the harness's
+own critique loop (#882).
+
+For each run, produce judge output in the [runs-file schema](../docs/design/abc-benchmark.md#scorecard-schema):
+
+### Layer 1 — Blind randomized pairwise (primary)
+Show the judge two **anonymized** screenshots in **shuffled** order and ask: *"Which reads more like a
+professionally designed, well-funded SaaS landing page?"* Run **A-vs-C, B-vs-C, A-vs-B**. Record the winner
+(`"A" | "B" | "C" | "tie"`) per comparison. Screenshots carry no arm labels.
+
+### Layer 2 — Rubric (1–5 per arm)
+Score each arm on: hierarchy, typography, color discipline, whitespace rhythm, originality-vs-slop, mobile.
+
+### Layer 3 — Slop detector (binary)
+Run the anti-slop negatives checklist (corpus #880) over each arm; record the count of negatives present
+(lower is better).
+
+Append each run to the brief's `runs[]` array in the runs file.
+
+---
+
+## Phase 4: Scorecard
+
+Aggregate deterministically:
+
+```bash
+node scripts/bench-scorecard.mjs runs.json > scorecard.json
+```
+
+The aggregator (see `scripts/bench-scorecard.mjs`):
+- **rejects any product with n<3 runs** (exit 1) — enforces the no-point-estimate rule,
+- emits **win-rate vs C** per arm (overall + per-product), the **A-vs-B harness delta**, **rubric mean+stdev**
+  per arm/dimension, **mean slop** per arm,
+- runs the **judge-calibration check**: C must beat A and B in the pairwise; any run where C loses is listed in
+  `judge_calibration.miscalibrated_runs` and the command exits 2 with a warning. A real reference losing to a
+  generated arm is a judge defect, not a harness win — treat those runs as suspect.
+
+Post the result as a `FORGE:BENCH_SCORECARD` annotation (registered in
+[`docs/FORGE-PROTOCOL.md`](../docs/FORGE-PROTOCOL.md)) on the tracking issue:
+
+```bash
+gh issue comment <ISSUE> --body "<!-- FORGE:BENCH_SCORECARD -->
+## ABC Benchmark Scorecard
+
+**Corpus version**: <ver> · **Generation model (A & B)**: <model> (canonical: claude-opus-4-6) · **Judge model**: <independent judge>
+**Products**: <n_products> · **Runs/product**: <n>
+
+| Arm | Win-rate vs C | A-vs-B | Mean slop |
+|-----|---------------|--------|-----------|
+| A   | <wr>          | <a_vs_b> | <slop_A> |
+| B   | <wr>          | —        | <slop_B> |
+
+**Judge calibration**: <ok | MISCALIBRATED — N runs where C lost (suspect)>
+
+\`\`\`json
+<scorecard.json>
+\`\`\`
+
+<!-- FORGE:BENCH_SCORECARD:COMPLETE -->"
+```
+
+---
+
+## Two non-negotiable rules
+
+### n=1 is a lie
+Taste output is high-variance. Run **3–5 generations per arm across 3–5 products** and report **distributions**.
+The aggregator hard-fails on n<3.
+
+### Anti-Goodhart
+The benchmark judge **MUST be independent from the harness's own critique loop (#882)**. Optimizing against the
+same judge that scores the benchmark is training to the test — the number rises while real quality does not. The
+benchmark judge uses its own prompt and is a distinct stage; it does not reuse the #882 critique judge.
+
+---
+
+## Acceptance (issue #878)
+
+- [x] Reproducible command/workflow: reference URL → brief → render arms → judge → scorecard.
+- [x] Arms A/B/C defined; same generation model for A and B; C = gold standard + judge calibration.
+- [x] Three judging layers: blind randomized pairwise, 1–5 rubric, binary slop detector.
+- [x] n=3–5 across 3–5 products; distributions reported; n=1 rejected by the aggregator.
+- [x] Benchmark judge independent from the #882 critique loop (anti-Goodhart).
+- [x] Five seed briefs as fixtures (Cadence/Tender/Slipstream/Voltage/Plume), anonymized + mapped to C.
+- [x] Arm A pluggable — rig runs now, plugs into `/design` (#888) when it lands.