@openthink/stamp 1.5.2 → 1.6.0

package/dist/index.js

@@ -490,10 +490,20 @@ function validateConfig(input) {
       }
       require_human_merge = r.require_human_merge;
     }
+    let strict_base;
+    if (r.strict_base !== void 0) {
+      if (typeof r.strict_base !== "boolean") {
+        throw new Error(
+          `config.branches.${name}.strict_base must be a boolean`
+        );
+      }
+      strict_base = r.strict_base;
+    }
     branches[name] = {
       required: r.required.map(String),
       ...required_checks ? { required_checks } : {},
-      ...require_human_merge !== void 0 ? { require_human_merge } : {}
+      ...require_human_merge !== void 0 ? { require_human_merge } : {},
+      ...strict_base !== void 0 ? { strict_base } : {}
     };
   }
   const reviewers2 = {};
@@ -2943,7 +2953,7 @@ function branchExists(name, cwd) {
 
 // src/commands/init.ts
 import { existsSync as existsSync9, writeFileSync as writeFileSync7 } from "fs";
-import { join as join5 } from "path";
+import { dirname as dirname4, join as join5 } from "path";
 
 // src/lib/ghRuleset.ts
 import { spawnSync as spawnSync3 } from "child_process";
@@ -3476,6 +3486,11 @@ For local-only / advisory use against this GitHub repo: re-run with \`stamp init
   const dbExisted = existsSync9(stateDbPath);
   const db = openDb(stateDbPath);
   db.close();
+  const prCheckResult = maybeWriteVerifyWorkflow(
+    repoRoot,
+    opts.prCheck,
+    effectiveMode
+  );
   const agentsMdAction = opts.agentsMd === false ? "skipped" : ensureAgentsMd(repoRoot, effectiveMode);
   const claudeMdAction = opts.claudeMd === false ? "skipped" : ensureClaudeMd(repoRoot);
   const scaffoldOrSync = alreadyHasConfig ? "sync" : "scaffold";
@@ -3506,6 +3521,11 @@ For local-only / advisory use against this GitHub repo: re-run with \`stamp init
       `  CLAUDE.md:   ${claudeMdAction} at repo root (auto-loaded by Claude Code)`
     );
   }
+  if (prCheckResult.action !== "skipped") {
+    console.log(
+      `  PR check:    ${prCheckResult.action} ${prCheckResult.path} (stamp/verify-attestation@${VERIFY_ACTION_REF})`
+    );
+  }
   console.log(
     `  models:      ${userCfg.path}${userCfg.created ? " (created \u2014 Sonnet defaults; tweak with `stamp config reviewers set <name> <model-id>`)" : " (existing)"}`
   );
@@ -3524,6 +3544,11 @@ For local-only / advisory use against this GitHub repo: re-run with \`stamp init
     console.error(warning);
     console.error();
   }
+  if (prCheckResult.action !== "skipped") {
+    console.log(
+      "PR-check mode notes:\n  - The workflow runs the verifier on every PR but does NOT block\n    merge by itself. Wire it into branch protection so green-check\n    is required before merge:\n      Settings \u2192 Branches \u2192 main \u2192 Protect \u2192 Require status checks \u2192\n      add `stamp verify` (the workflow's job name) as required.\n  - Operator workflow per PR: stamp review \u2192 stamp attest --into main\n    --push origin \u2192 open PR \u2192 check goes green \u2192 human merges.\n"
+    );
+  }
   if (scaffoldOrSync === "scaffold") {
     if (effectiveMode === "local-only") {
       console.log(
@@ -3811,6 +3836,57 @@ function resolveMode(userMode, remoteClass) {
       return { effectiveMode: "local-only", warnings };
   }
 }
+var VERIFY_ACTION_REF = "v1.6.0";
+function maybeWriteVerifyWorkflow(repoRoot, prCheckOpt, effectiveMode) {
+  const path2 = ".github/workflows/stamp-verify.yml";
+  const fullPath = join5(repoRoot, path2);
+  const defaultForMode = effectiveMode !== "server-gated";
+  const shouldWrite = prCheckOpt ?? defaultForMode;
+  if (!shouldWrite) return { action: "skipped", path: path2 };
+  if (existsSync9(fullPath)) {
+    return { action: "exists", path: path2 };
+  }
+  ensureDir(dirname4(fullPath));
+  writeFileSync7(fullPath, renderVerifyWorkflow());
+  return { action: "wrote", path: path2 };
+}
+function renderVerifyWorkflow() {
+  return [
+    "name: stamp verify",
+    "",
+    `# Runs stamp/verify-attestation@${VERIFY_ACTION_REF} on every PR.`,
+    "# Wire `stamp verify` (this job's name) into branch protection",
+    "# Required Status Checks to make a green attestation a merge",
+    "# precondition.",
+    "",
+    "on:",
+    "  pull_request:",
+    "    branches: [main]",
+    "",
+    "permissions:",
+    "  # checkout + read .stamp/{config,trusted-keys}/ from the base ref",
+    "  contents: read",
+    "  # for the workflow's check-run summary on the PR",
+    "  checks: write",
+    "",
+    "jobs:",
+    "  stamp-verify:",
+    "    name: stamp verify",
+    "    runs-on: ubuntu-latest",
+    "    timeout-minutes: 5",
+    "    steps:",
+    "      - name: checkout",
+    "        uses: actions/checkout@v4",
+    "        with:",
+    "          # Full history so the action can fetch the base ref's tree",
+    "          # and resolve refs/stamp/attestations/*. Shallow clones",
+    "          # would force per-step refetches.",
+    "          fetch-depth: 0",
+    "      - name: stamp/verify-attestation",
+    `        uses: OpenThinkAi/stamp-cli/.github/actions/verify-attestation@${VERIFY_ACTION_REF}`,
+    ""
+  ].join("\n");
+}
 
 // src/commands/invites.ts
 import { spawnSync as spawnSync5 } from "child_process";
@@ -4346,7 +4422,7 @@ import { parse as parseYaml5 } from "yaml";
 // src/commands/server.ts
 import { spawnSync as spawnSync6 } from "child_process";
 import { existsSync as existsSync11, mkdirSync as mkdirSync4, renameSync as renameSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync8 } from "fs";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 import { stringify as stringifyYaml2 } from "yaml";
 
 // src/lib/perRepoKey.ts
@@ -4505,7 +4581,7 @@ function writeConfig(opts) {
     repoRootPrefix: opts.repoRootPrefix
   });
   const path2 = userServerConfigPath();
-  const dir = dirname4(path2);
+  const dir = dirname5(path2);
   if (!existsSync11(dir)) mkdirSync4(dir, { recursive: true, mode: 448 });
   const tmp = `${path2}.tmp.${process.pid}`;
   writeFileSync8(tmp, yaml, { mode: 384 });
@@ -5858,6 +5934,291 @@ function printReviewHistory(repoRoot, limit, diff) {
   );
 }
 
+// src/commands/attest.ts
+import { spawnSync as spawnSync12 } from "child_process";
+import { createHash as createHash7 } from "crypto";
+
+// src/lib/patchId.ts
+import { spawnSync as spawnSync10 } from "child_process";
+function patchIdForSpan(base_sha, head_sha, repoRoot) {
+  const diff = spawnSync10("git", ["diff", `${base_sha}..${head_sha}`], {
+    cwd: repoRoot,
+    // Buffer because diffs can be large and stable across encodings;
+    // patch-id consumes the raw bytes.
+    encoding: "buffer",
+    maxBuffer: 64 * 1024 * 1024
+  });
+  if (diff.status !== 0) {
+    const stderr = diff.stderr?.toString("utf8") ?? "";
+    throw new Error(
+      `git diff ${base_sha}..${head_sha} failed: ${stderr.trim() || "exit " + diff.status}`
+    );
+  }
+  if (diff.stdout.length === 0) {
+    throw new Error(
+      `empty diff between ${base_sha.slice(0, 8)}..${head_sha.slice(0, 8)} \u2014 nothing to attest`
+    );
+  }
+  const result = spawnSync10("git", ["patch-id", "--stable"], {
+    cwd: repoRoot,
+    input: diff.stdout,
+    encoding: "utf8",
+    maxBuffer: 1024
+  });
+  if (result.status !== 0) {
+    const stderr = result.stderr ?? "";
+    throw new Error(
+      `git patch-id --stable failed: ${stderr.trim() || "exit " + result.status}`
+    );
+  }
+  const firstLine = (result.stdout ?? "").trim().split("\n")[0] ?? "";
+  const token = firstLine.split(/\s+/)[0];
+  if (!token || !/^[0-9a-f]{40}$/.test(token)) {
+    throw new Error(
+      `unexpected git patch-id output: ${JSON.stringify(result.stdout.slice(0, 200))}`
+    );
+  }
+  return token;
+}
+
+// src/lib/prAttestation.ts
+import { spawnSync as spawnSync11 } from "child_process";
+var PR_ATTESTATION_SCHEMA_VERSION = 2;
+var MIN_ACCEPTED_PR_ATTESTATION_VERSION = 1;
+var MAX_PR_ATTESTATION_BYTES = 64 * 1024;
+function serializePayload2(p) {
+  return Buffer.from(JSON.stringify(p), "utf8");
+}
+function serializeEnvelope(env) {
+  return Buffer.from(JSON.stringify(env), "utf8");
+}
+function parseEnvelope(bytes) {
+  if (bytes.length === 0 || bytes.length > MAX_PR_ATTESTATION_BYTES) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const env = parsed;
+  if (typeof env.signature !== "string" || !env.signature) return null;
+  if (!env.payload || typeof env.payload !== "object") return null;
+  const p = env.payload;
+  if (typeof p.schema_version !== "number" || p.schema_version < MIN_ACCEPTED_PR_ATTESTATION_VERSION || typeof p.patch_id !== "string" || typeof p.base_sha !== "string" || typeof p.head_sha !== "string" || typeof p.target_branch !== "string" || !Array.isArray(p.approvals) || !Array.isArray(p.checks) || typeof p.signer_key_id !== "string") {
+    return null;
+  }
+  if (p.schema_version >= 2 && typeof p.target_branch_tip_sha !== "string") {
+    return null;
+  }
+  return env;
+}
+function attestationRefName(patch_id) {
+  if (!/^[0-9a-f]{40}$/.test(patch_id)) {
+    throw new Error(
+      `patch_id must be a 40-char lowercase hex string (got ${JSON.stringify(patch_id)})`
+    );
+  }
+  return `refs/stamp/attestations/${patch_id}`;
+}
+function writeAttestationRef(envelope, repoRoot) {
+  const ref = attestationRefName(envelope.payload.patch_id);
+  const bytes = serializeEnvelope(envelope);
+  const hashObject = spawnSync11(
+    "git",
+    ["hash-object", "-w", "--stdin"],
+    { cwd: repoRoot, input: bytes, encoding: "utf8" }
+  );
+  if (hashObject.status !== 0) {
+    const stderr = hashObject.stderr ?? "";
+    throw new Error(
+      `git hash-object failed: ${stderr.trim() || "exit " + hashObject.status}`
+    );
+  }
+  const blob_sha = (hashObject.stdout ?? "").trim();
+  if (!/^[0-9a-f]{40}$/.test(blob_sha)) {
+    throw new Error(`unexpected git hash-object output: ${JSON.stringify(blob_sha)}`);
+  }
+  const updateRef = spawnSync11(
+    "git",
+    ["update-ref", ref, blob_sha],
+    { cwd: repoRoot, encoding: "utf8" }
+  );
+  if (updateRef.status !== 0) {
+    const stderr = updateRef.stderr ?? "";
+    throw new Error(
+      `git update-ref ${ref} failed: ${stderr.trim() || "exit " + updateRef.status}`
+    );
+  }
+  return { ref, blob_sha };
+}
+function readAttestationRef(patch_id, repoRoot) {
+  const ref = attestationRefName(patch_id);
+  const showRef = spawnSync11(
+    "git",
+    ["show-ref", "--verify", "--quiet", ref],
+    { cwd: repoRoot }
+  );
+  if (showRef.status !== 0) return null;
+  const cat = spawnSync11(
+    "git",
+    ["cat-file", "blob", ref],
+    { cwd: repoRoot, encoding: "buffer", maxBuffer: MAX_PR_ATTESTATION_BYTES * 2 }
+  );
+  if (cat.status !== 0) return null;
+  return parseEnvelope(cat.stdout);
+}
+
+// src/commands/attest.ts
+function runAttest(opts) {
+  const repoRoot = findRepoRoot();
+  const config2 = loadConfig(stampConfigFile(repoRoot));
+  const rule = findBranchRule(config2.branches, opts.into);
+  if (!rule) {
+    throw new Error(
+      `no branch rule for "${opts.into}" in .stamp/config.yml. Configured branches: ${Object.keys(config2.branches).join(", ") || "(none)"}.`
+    );
+  }
+  const branchRef = opts.branch ?? "HEAD";
+  const revspec = `${opts.into}..${branchRef}`;
+  const resolved = resolveDiff(revspec, repoRoot);
+  const db = openDb(stampStateDbPath(repoRoot));
+  let approvals;
+  try {
+    const reviews = latestReviews(db, resolved.base_sha, resolved.head_sha);
+    const byReviewer = new Map(reviews.map((r) => [r.reviewer, r]));
+    const missing = [];
+    for (const r of rule.required) {
+      const rev = byReviewer.get(r);
+      if (!rev || rev.verdict !== "approved") missing.push(r);
+    }
+    if (missing.length > 0) {
+      throw new Error(
+        `gate CLOSED: missing approved verdicts for: ${missing.join(", ")}. Run \`stamp status --diff ${revspec}\` to inspect, then \`stamp review --diff ${revspec}\` to review.`
+      );
+    }
+    approvals = rule.required.map((name) => {
+      const rev = byReviewer.get(name);
+      const toolCalls = redactToolCallsForAttestation(
+        parseToolCalls(rev.tool_calls)
+      );
+      return {
+        reviewer: rev.reviewer,
+        verdict: rev.verdict,
+        review_sha: hashHex(rev.issues ?? ""),
+        ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {}
+      };
+    });
+  } finally {
+    db.close();
+  }
+  const baseConfigYaml = showAtRef(
+    resolved.base_sha,
+    ".stamp/config.yml",
+    repoRoot
+  );
+  const baseReviewers = readReviewersFromYaml(baseConfigYaml);
+  approvals = approvals.map((a) => {
+    const def = baseReviewers[a.reviewer];
+    if (!def) {
+      throw new Error(
+        `reviewer "${a.reviewer}" approved the diff but is not defined in .stamp/config.yml at base ${resolved.base_sha.slice(0, 8)}. This shouldn't happen \u2014 runReview reads from the same base. File a bug at https://github.com/OpenThinkAi/stamp-cli/issues.`
+      );
+    }
+    const promptText = showAtRef(resolved.base_sha, def.prompt, repoRoot);
+    const source = readReviewerSource2(a.reviewer, repoRoot);
+    return {
+      ...a,
+      prompt_sha256: hashPromptBytes(Buffer.from(promptText, "utf8")),
+      tools_sha256: hashTools(def.tools),
+      mcp_sha256: hashMcpServers(def.mcp_servers),
+      ...source ? { reviewer_source: source } : {}
+    };
+  });
+  const patch_id = patchIdForSpan(resolved.base_sha, resolved.head_sha, repoRoot);
+  const target_branch_tip_sha = runGit(
+    ["rev-parse", `${opts.into}^{commit}`],
+    repoRoot
+  ).trim();
+  const { keypair } = ensureUserKeypair();
+  const payload = {
+    schema_version: PR_ATTESTATION_SCHEMA_VERSION,
+    patch_id,
+    base_sha: resolved.base_sha,
+    head_sha: resolved.head_sha,
+    target_branch: opts.into,
+    target_branch_tip_sha,
+    approvals,
+    checks: [],
+    // Phase-1 deliberate omission — see file-level comment.
+    signer_key_id: keypair.fingerprint
+  };
+  const signature = signBytes(keypair.privateKeyPem, serializePayload2(payload));
+  const { ref, blob_sha } = writeAttestationRef(
+    { payload, signature },
+    repoRoot
+  );
+  const bar = "\u2500".repeat(72);
+  console.log(bar);
+  console.log(`attested ${branchRef} for merge into '${opts.into}'`);
+  console.log(bar);
+  console.log(`  patch-id:   ${patch_id}`);
+  console.log(
+    `  base\u2192head:  ${resolved.base_sha.slice(0, 8)} \u2192 ${resolved.head_sha.slice(0, 8)}`
+  );
+  console.log(`  signed by:  ${keypair.fingerprint}`);
+  console.log(`  approvals:  ${approvals.map((a) => a.reviewer).join(", ")}`);
+  console.log(`  ref:        ${ref}`);
+  console.log(`  blob:       ${blob_sha.slice(0, 12)}`);
+  console.log(bar);
+  if (opts.pushTo) {
+    pushBranchAndAttestation(opts.pushTo, ref, repoRoot);
+    console.log(
+      `
+\u2713 pushed branch + attestation ref to ${opts.pushTo}. Open the PR; stamp/verify-attestation@v1 will look up refs/stamp/attestations/<patch-id> from your head SHA's diff against the base.`
+    );
+  } else {
+    console.log(
+      `
+Next: push the branch + attestation ref to your remote, open a PR, and let stamp/verify-attestation@v1 (the GH Action) confirm it. To do both pushes in one shot:
+
+    git push <remote> HEAD ${ref}
+
+Or re-run with --push <remote> next time.`
+    );
+  }
+}
+function pushBranchAndAttestation(remote, attestationRef, repoRoot) {
+  const result = spawnSync12(
+    "git",
+    ["push", "--atomic", remote, "HEAD", attestationRef],
+    { cwd: repoRoot, stdio: "inherit" }
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const exit = result.status === null ? "(killed by signal)" : `exit ${result.status}`;
+    throw new Error(
+      `git push --atomic ${remote} HEAD ${attestationRef} failed (${exit}). The attestation ref is still in the local repo at ${attestationRef} \u2014 re-run with --push ${remote} after fixing the cause, or push manually.`
+    );
+  }
+}
+function hashHex(s) {
+  return createHash7("sha256").update(s, "utf8").digest("hex");
+}
+function readReviewerSource2(reviewerName, repoRoot) {
+  const path2 = `.stamp/reviewers/${reviewerName}.lock.json`;
+  if (!pathExistsAtRef("HEAD", path2, repoRoot)) return null;
+  const raw = runGit(["show", `HEAD:${path2}`], repoRoot);
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.source === "string" && typeof parsed.ref === "string") {
+      return { source: parsed.source, ref: parsed.ref };
+    }
+  } catch {
+  }
+  return null;
+}
+
 // src/commands/prune.ts
 import { existsSync as existsSync16, readdirSync as readdirSync4, statSync as statSync2, unlinkSync as unlinkSync3 } from "fs";
 import { join as join10 } from "path";
@@ -6123,7 +6484,7 @@ function loadOrEmpty() {
 }
 
 // src/commands/reviewers.ts
-import { spawnSync as spawnSync10 } from "child_process";
+import { spawnSync as spawnSync13 } from "child_process";
 import {
   existsSync as existsSync19,
   readFileSync as readFileSync13,
@@ -6767,7 +7128,7 @@ function buildConfigYamlHint(reviewerName, tools, mcpServers) {
 }
 function launchEditor(path2) {
   const editor = process.env["EDITOR"] ?? process.env["VISUAL"] ?? (process.platform === "win32" ? "notepad" : "vi");
-  const result = spawnSync10(editor, [path2], { stdio: "inherit" });
+  const result = spawnSync13(editor, [path2], { stdio: "inherit" });
   if (result.error) {
     throw new Error(
       `failed to launch editor "${editor}": ${result.error.message}`
@@ -6851,14 +7212,14 @@ function printGate(result, base_sha, head_sha) {
 }
 
 // src/commands/update.ts
-import { spawnSync as spawnSync11 } from "child_process";
+import { spawnSync as spawnSync14 } from "child_process";
 
 // src/lib/version.ts
 import { readFileSync as readFileSync14 } from "fs";
-import { dirname as dirname5, join as join13 } from "path";
+import { dirname as dirname6, join as join13 } from "path";
 import { fileURLToPath } from "url";
 function readPackageVersion() {
-  const here = dirname5(fileURLToPath(import.meta.url));
+  const here = dirname6(fileURLToPath(import.meta.url));
   for (let dir = here, i = 0; i < 6; i++) {
     try {
       const raw = readFileSync14(join13(dir, "package.json"), "utf8");
@@ -6866,7 +7227,7 @@ function readPackageVersion() {
       if (pkg.name === "@openthink/stamp" && pkg.version) return pkg.version;
     } catch {
     }
-    const parent = dirname5(dir);
+    const parent = dirname6(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -6892,7 +7253,7 @@ function runUpdate() {
 `);
   process.stdout.write(`checking npm registry for latest...
 `);
-  const viewResult = spawnSync11("npm", ["view", PKG_NAME, "version"], {
+  const viewResult = spawnSync14("npm", ["view", PKG_NAME, "version"], {
     encoding: "utf8"
   });
   if (viewResult.error || viewResult.status !== 0) {
@@ -6926,7 +7287,7 @@ function runUpdate() {
   }
   process.stdout.write(`installing ${PKG_NAME}@${latest}...
 `);
-  const installResult = spawnSync11(
+  const installResult = spawnSync14(
     "npm",
     ["install", "-g", `${PKG_NAME}@${latest}`],
     { stdio: "inherit" }
@@ -6947,9 +7308,9 @@ through that tool instead \u2014 this command only uses 'npm install -g'.`
 }
 
 // src/commands/verify.ts
-import { execFileSync as execFileSync2, spawnSync as spawnSync12 } from "child_process";
+import { execFileSync as execFileSync2, spawnSync as spawnSync15 } from "child_process";
 function loadConfigAtSha(sha, repoRoot) {
-  const result = spawnSync12(
+  const result = spawnSync15(
     "git",
     ["show", `${sha}:.stamp/config.yml`],
     { cwd: repoRoot, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }
@@ -7159,6 +7520,194 @@ function git2(args, cwd) {
   }
 }
 
+// src/commands/verifyPr.ts
+import { spawnSync as spawnSync16 } from "child_process";
+function runVerifyPr(opts) {
+  const repoRoot = opts.repoPath ?? findRepoRoot();
+  const resolved = resolveDiff(`${opts.base}..${opts.head}`, repoRoot);
+  const patch_id = patchIdForSpan(resolved.base_sha, resolved.head_sha, repoRoot);
+  const envelope = readAttestationRef(patch_id, repoRoot);
+  if (!envelope) {
+    fail2(
+      `no attestation found at refs/stamp/attestations/${patch_id} (diff ${resolved.base_sha.slice(0, 8)}..${resolved.head_sha.slice(0, 8)}). Operator must run \`stamp attest --into ${opts.into}\` and push the attestation ref to this remote.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const { payload, signature } = envelope;
+  const trustedKey = findTrustedKeyAtBase(
+    resolved.base_sha,
+    payload.signer_key_id,
+    repoRoot
+  );
+  if (!trustedKey) {
+    fail2(
+      `signer_key_id ${payload.signer_key_id} is not in .stamp/trusted-keys/ at base ${resolved.base_sha.slice(0, 8)}. The reviewer's signing key must be added to this repo's trust set via \`stamp trust grant\` and landed through the standard stamp gate before their attestations verify.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const sigOk = verifyBytes(
+    trustedKey.pem,
+    serializePayload2(payload),
+    signature
+  );
+  if (!sigOk) {
+    fail2(
+      `signature verification failed against ${trustedKey.filename} (${payload.signer_key_id}). Either the attestation has been tampered with after signing, or the trusted-keys entry doesn't match the key that signed.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (payload.target_branch !== opts.into) {
+    fail2(
+      `attestation target_branch="${payload.target_branch}" does not match verifier --into="${opts.into}". The reviewer signed an attestation for a different merge destination \u2014 re-attest with --into ${opts.into}.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  let configYaml;
+  try {
+    configYaml = showAtRef(resolved.base_sha, ".stamp/config.yml", repoRoot);
+  } catch (e) {
+    fail2(
+      `could not read .stamp/config.yml at base ${resolved.base_sha.slice(0, 8)}: ${e.message}`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const config2 = parseConfigFromYaml(configYaml);
+  const rule = findBranchRule(config2.branches, opts.into);
+  if (!rule) {
+    fail2(
+      `no branch rule for "${opts.into}" in .stamp/config.yml at base ${resolved.base_sha.slice(0, 8)}. Configured branches: ${Object.keys(config2.branches).join(", ") || "(none)"}.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  const approvalByReviewer = new Map(
+    payload.approvals.map((a) => [a.reviewer, a.verdict])
+  );
+  const missing = [];
+  for (const r of rule.required) {
+    if (approvalByReviewer.get(r) !== "approved") missing.push(r);
+  }
+  if (missing.length > 0) {
+    fail2(
+      `gate CLOSED: missing approved verdicts for: ${missing.join(", ")}. Attestation has approvals for: ${payload.approvals.map((a) => `${a.reviewer}=${a.verdict}`).join(", ")}.`,
+      patch_id,
+      resolved.base_sha,
+      resolved.head_sha
+    );
+  }
+  if (rule.strict_base) {
+    if (!payload.target_branch_tip_sha) {
+      fail2(
+        `strict_base check failed: attestation schema v${payload.schema_version} predates target_branch_tip_sha (v2+). Re-attest with stamp \u2265 1.6.0 to verify under strict_base; or relax the branch rule.`,
+        patch_id,
+        resolved.base_sha,
+        resolved.head_sha
+      );
+    }
+    const currentTip = runGit(
+      ["rev-parse", `${opts.into}^{commit}`],
+      repoRoot
+    ).trim();
+    if (payload.target_branch_tip_sha !== currentTip) {
+      fail2(
+        `strict_base check failed: attestation was signed when ${opts.into} was at ${payload.target_branch_tip_sha.slice(0, 8)}, but ${opts.into} is now at ${currentTip.slice(0, 8)}. Re-attest with the current tip.`,
+        patch_id,
+        resolved.base_sha,
+        resolved.head_sha
+      );
+    }
+  }
+  printSuccess3({
+    patch_id,
+    base_sha: resolved.base_sha,
+    head_sha: resolved.head_sha,
+    target_branch: opts.into,
+    signer_key_id: payload.signer_key_id,
+    trusted_key_filename: trustedKey.filename,
+    approvals: payload.approvals.map((a) => ({
+      reviewer: a.reviewer,
+      verdict: a.verdict
+    })),
+    strict_base: rule.strict_base ?? false
+  });
+}
+function findTrustedKeyAtBase(base_sha, signer_key_id, repoRoot) {
+  const lsTree = spawnSync16(
+    "git",
+    [
+      "ls-tree",
+      "--name-only",
+      "-r",
+      base_sha,
+      ".stamp/trusted-keys/"
+    ],
+    { cwd: repoRoot, encoding: "utf8" }
+  );
+  if (lsTree.status !== 0) {
+    return null;
+  }
+  const files = (lsTree.stdout ?? "").split("\n").map((l) => l.trim()).filter((l) => l.endsWith(".pub"));
+  for (const file of files) {
+    let pem;
+    try {
+      pem = runGit(["show", `${base_sha}:${file}`], repoRoot);
+    } catch {
+      continue;
+    }
+    let fp;
+    try {
+      fp = fingerprintFromPem(pem);
+    } catch {
+      continue;
+    }
+    if (fp === signer_key_id) {
+      return { filename: file.replace(/^\.stamp\/trusted-keys\//, ""), pem };
+    }
+  }
+  return null;
+}
+function printSuccess3(s) {
+  const bar = "\u2500".repeat(72);
+  console.log(bar);
+  console.log(
+    `target: ${s.target_branch}   base: ${s.base_sha.slice(0, 8)} \u2192 head: ${s.head_sha.slice(0, 8)}`
+  );
+  console.log(bar);
+  console.log(`  patch-id:        ${s.patch_id}`);
+  console.log(`  signer:          ${s.signer_key_id}`);
+  console.log(`  trusted-key:     .stamp/trusted-keys/${s.trusted_key_filename}`);
+  console.log(`  base mode:       ${s.strict_base ? "strict" : "loose"}`);
+  for (const a of s.approvals) {
+    const mark = a.verdict === "approved" ? "\u2713" : "\u2717";
+    console.log(`  ${mark}  ${a.reviewer.padEnd(16)} ${a.verdict}`);
+  }
+  console.log(bar);
+  console.log("result: VERIFIED");
+  console.log(bar);
+}
+function fail2(reason, patch_id, base_sha, head_sha) {
+  const bar = "\u2500".repeat(72);
+  console.error(bar);
+  console.error(`base: ${base_sha.slice(0, 8)} \u2192 head: ${head_sha.slice(0, 8)}`);
+  console.error(`patch-id: ${patch_id}`);
+  console.error(bar);
+  console.error(`error: ${reason}`);
+  console.error("result: FAILED");
+  console.error(bar);
+  process.exit(1);
+}
+
 // src/index.ts
 process.removeAllListeners("warning");
 process.on("warning", (warn) => {
@@ -7198,6 +7747,9 @@ program.command("init").description(
 ).option(
   "--no-oteam",
   "bypass the oteam-detection prompt that offers to fill stamp.host in ~/.open-team/config.json"
+).option(
+  "--no-pr-check",
+  "skip dropping .github/workflows/stamp-verify.yml (PR-check mode workflow). Default behaviour: write the workflow for forge-direct + local-only modes, skip for server-gated."
 ).action(
   (opts) => {
     try {
@@ -7219,7 +7771,12 @@ program.command("init").description(
         ghProtect: opts.ghProtect,
         mode,
         remote: opts.remote,
-        oteam: opts.oteam
+        oteam: opts.oteam,
+        // commander's --no-pr-check yields opts.prCheck === false; no
+        // flag yields true (the default-true sentinel). We only want
+        // to forward an explicit `false` to runInit so its mode-aware
+        // default fires when the operator hasn't opted out.
+        prCheck: opts.prCheck === false ? false : void 0
       });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -7473,6 +8030,21 @@ program.command("merge <branch>").description("merge <branch> into --into <targe
     handleCliError(err);
   }
 });
+program.command("attest [branch]").description(
+  "PR-check mode counterpart to `stamp merge` \u2014 sign an attestation envelope and write it to refs/stamp/attestations/<patch-id> for a GitHub Action to verify on the PR (no actual git merge happens here)"
+).requiredOption("--into <target>", "target branch whose rule the gate is checked against").option(
+  "--push [remote]",
+  "after attesting locally, push the current branch + the attestation ref to <remote> in one atomic git push (default remote: origin)"
+).action(
+  (branch, opts) => {
+    try {
+      const pushTo = opts.push === true ? "origin" : typeof opts.push === "string" ? opts.push : void 0;
+      runAttest({ branch, into: opts.into, pushTo });
+    } catch (err) {
+      handleCliError(err);
+    }
+  }
+);
 program.command("push <target>").description("push <target> to origin; surfaces stamp-verify hook stderr on rejection").option("--remote <name>", "remote to push to", "origin").action((target, opts) => {
   try {
     runPush({ target, remote: opts.remote });
@@ -7487,6 +8059,18 @@ program.command("verify <sha>").description("verify an existing merge commit's a
     handleCliError(err);
   }
 });
+program.command("verify-pr <head>").description(
+  "verify a PR attestation at refs/stamp/attestations/<patch-id> for the diff <base>..<head> against the --into branch's rule (used by stamp/verify-attestation@v1; also runnable locally for debugging)"
+).requiredOption("--base <ref>", "PR base ref (commit SHA, branch, or any rev-parse-able value)").requiredOption(
+  "--into <branch>",
+  "branch the PR is merging into; must equal the attestation's target_branch"
+).action((head, opts) => {
+  try {
+    runVerifyPr({ head, base: opts.base, into: opts.into });
+  } catch (err) {
+    handleCliError(err);
+  }
+});
 program.command("update").description(
   "upgrade stamp to the latest npm release (runs 'npm install -g @openthink/stamp@latest')"
 ).action(() => wrap(() => runUpdate()));