@maycombhq/atticus 2.0.0-beta.21 → 2.0.0-beta.23

package/dist/{chunk-HSZMPH5T.js → chunk-WZYM5M4U.js}

@@ -6,24 +6,26 @@ var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
 import {
   STORE_MARKER,
   addStoreReference,
+  archiveRefuses,
+  blockingIssues,
   readStoreMarker,
   readStoreVia
-} from "./chunk-D2WSW4GU.js";
+} from "./chunk-NC755EKE.js";
 import {
   AdapterError,
   mergeBlockers,
   requireApproval
-} from "./chunk-4KNOJC6J.js";
+} from "./chunk-FL344WQD.js";
 import {
   outsideProfileSystems,
   readCatalog
-} from "./chunk-4SLBCEPD.js";
+} from "./chunk-IKAW2KJU.js";
 import {
   baseClonePath,
   createGit,
   readChangeRepos,
   writeChangeRepos
-} from "./chunk-XOL3GFW2.js";
+} from "./chunk-3EWKO457.js";
 import {
   ChangeArtifact,
   ChangeLifecycle,
@@ -40,23 +42,28 @@ import {
   external_exports,
   fastGateOf,
   fastPathOf,
+  handleKey,
   handoffBranch,
   isAssistantResolution,
   listQuestions,
   loadOpenSpecSettings,
   loadOrgPack,
+  nextOwnersOf,
   openspecDirOf,
   orgPackDirOf,
   questionsRelOf,
   readFlow,
   readQuestion,
-  require_dist,
   specFlowFiles,
+  taskBranch,
   toCanonicalYaml
-} from "./chunk-PAINMSID.js";
+} from "./chunk-FPBUTZI5.js";
 import {
   writeFileAtomic
-} from "./chunk-ODMBPDDV.js";
+} from "./chunk-B4AEL3RF.js";
+import {
+  require_dist
+} from "./chunk-BQGDB6ZL.js";
 import {
   __toESM
 } from "./chunk-TV45EUGM.js";
@@ -628,22 +635,33 @@ function changeStore(root) {
       await writeFileAtomic(path, serializeChange(value));
       return path;
     },
+    listWithProblems,
     async list() {
-      let names;
+      return (await listWithProblems()).changes;
+    }
+  };
+  async function listWithProblems() {
+    let names;
+    try {
+      names = (await readdir2(changesDirOf(root), { withFileTypes: true })).filter((d) => d.isDirectory() && d.name !== "archive" && RecordId.safeParse(d.name).success).map((d) => d.name).sort();
+    } catch {
+      return { changes: [], problems: [] };
+    }
+    const changes = [];
+    const problems = [];
+    for (const n of names) {
       try {
-        names = (await readdir2(changesDirOf(root), { withFileTypes: true })).filter((d) => d.isDirectory() && d.name !== "archive" && RecordId.safeParse(d.name).success).map((d) => d.name).sort();
-      } catch {
-        return [];
-      }
-      const out = [];
-      for (const n of names) {
         const c = await tryRead(n);
         if (c)
-          out.push(c);
+          changes.push(c);
+      } catch (e) {
+        if (!(e instanceof ChangeFileError))
+          throw e;
+        problems.push({ file: e.path, message: e.message });
       }
-      return out;
     }
-  };
+    return { changes, problems };
+  }
 }
 
 // packages/changes/dist/codeowners.js
@@ -1650,8 +1668,19 @@ async function checkFindings(root, change, gates) {
       continue;
     const round2 = Math.max(...rounds);
     const dir = join7(base, String(round2));
+    const files = (await readdir4(dir)).filter((f) => /\.ya?ml$/.test(f)).sort();
+    const unfinished = {
+      code: "round-unfinished",
+      message: `Critic round ${round2} on the ${gate} gate didn't finish: run atticus critic ${change.id} --gate ${gate} again.`
+    };
+    let hasMeta = false;
     try {
       const meta = (0, import_yaml5.parse)(await readFile6(join7(dir, "meta", "round.yaml"), "utf8"));
+      hasMeta = true;
+      if (meta?.state === "in-progress") {
+        reasons.push(unfinished);
+        continue;
+      }
       for (const l of meta?.lenses ?? [])
         if (l.state === "waiting")
           reasons.push({
@@ -1665,7 +1694,10 @@ async function checkFindings(root, change, gates) {
           });
     } catch {
     }
-    const files = (await readdir4(dir)).filter((f) => /\.ya?ml$/.test(f)).sort();
+    if (!hasMeta && files.length === 0) {
+      reasons.push(unfinished);
+      continue;
+    }
     for (const f of files) {
       const rel = `review/${gate}/${round2}/${f}`;
       let data;
@@ -1813,14 +1845,195 @@ function prApprovers(handoff2, approvers) {
 }
 
 // packages/changes/dist/assess.js
-import { readFile as readFile9 } from "node:fs/promises";
-import { join as join10 } from "node:path";
+import { readFile as readFile10 } from "node:fs/promises";
+import { join as join11 } from "node:path";
 
 // packages/changes/dist/release-prs.js
+var import_yaml8 = __toESM(require_dist(), 1);
+import { readFile as readFile9, writeFile } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join10 } from "node:path";
+
+// packages/changes/dist/task-branches.js
 var import_yaml7 = __toESM(require_dist(), 1);
-import { readFile as readFile8, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { readdir as readdir5, readFile as readFile8 } from "node:fs/promises";
 import { join as join9 } from "node:path";
+var TASK_DECISION_FILE = "decision.yaml";
+var TaskDecision = external_exports.strictObject({
+  schemaVersion: external_exports.literal(1),
+  task: external_exports.string().min(1),
+  branch: external_exports.string().min(1),
+  /** The task branch's commit the person decided over. */
+  commit: external_exports.string().regex(/^[0-9a-f]{7,64}$/),
+  by: external_exports.string().min(1),
+  at: external_exports.string().min(1),
+  reason: external_exports.string().min(1)
+});
+async function taskRefs(root, id) {
+  const dir = join9(changeFolder(root, id), "tasks");
+  const out = [];
+  for (const d of await readdir5(dir, { withFileTypes: true }).catch(() => [])) {
+    if (!d.isDirectory())
+      continue;
+    const text = await readFile8(join9(dir, d.name, "task-run.yaml"), "utf8").catch(() => void 0);
+    let y;
+    try {
+      y = text ? (0, import_yaml7.parse)(text) : void 0;
+    } catch {
+      y = void 0;
+    }
+    const task = String(y?.task ?? d.name);
+    let branch;
+    try {
+      branch = typeof y?.branch === "string" ? y.branch : taskBranch(id, task);
+    } catch {
+      continue;
+    }
+    const pr = y?.pr;
+    out.push({
+      task,
+      ...typeof y?.repo === "string" ? { repo: y.repo } : {},
+      branch,
+      ...typeof y?.state === "string" ? { state: y.state } : {},
+      ...pr && typeof pr.number === "number" && typeof pr.url === "string" ? { pr: { number: pr.number, url: pr.url } } : {},
+      ...y?.ticked ? { ticked: true } : {},
+      ...typeof y?.commit === "string" && /^[0-9a-f]{7,64}$/.test(y.commit) ? { commit: y.commit } : {}
+    });
+  }
+  return out;
+}
+function repoDir(root, r) {
+  const dirs = [join9(root, r.worktree)];
+  try {
+    dirs.push(baseClonePath(root, r.id));
+  } catch {
+  }
+  return dirs.find((d) => existsSync(d));
+}
+async function readTaskDecision(root, id, task) {
+  const text = await readFile8(join9(changeFolder(root, id), "tasks", task, TASK_DECISION_FILE), "utf8").catch(() => void 0);
+  if (text === void 0)
+    return void 0;
+  try {
+    const r = TaskDecision.safeParse((0, import_yaml7.parse)(text));
+    return r.success ? r.data : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function unmergedTaskBranches(root, id, o = {}) {
+  const cr = await readChangeRepos(root, id).catch(() => void 0);
+  if (!cr?.repos.length)
+    return [];
+  const git = o.git ?? createGit({ timeoutMs: 3e4 });
+  const remote = o.remote ?? "origin";
+  const from = changeBranch(id);
+  const records = await taskRefs(root, id);
+  const out = [];
+  const sha = (dir, ref) => git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], dir).then((x) => x.stdout.trim() || void 0, () => void 0);
+  for (const r of cr.repos) {
+    const dir = repoDir(root, r);
+    if (!dir)
+      continue;
+    const listed = await git(["for-each-ref", "--format=%(refname)", `refs/heads/task/${id}/`], dir).then((x) => x.stdout.split(/\r?\n/).map((l) => l.trim().replace(/^refs\/heads\//, "")).filter(Boolean), () => []);
+    const branches = /* @__PURE__ */ new Map();
+    for (const b of listed) {
+      const mine = records.find((x) => x.branch === b && (!x.repo || x.repo === r.id));
+      const other = records.find((x) => x.branch === b);
+      branches.set(b, mine ?? { task: other?.task ?? b.split("/").at(-1), branch: b });
+    }
+    for (const x of records)
+      if (x.repo === r.id && !branches.has(x.branch))
+        branches.set(x.branch, x);
+    const refs = [...branches.values()].filter((x) => (!x.repo || x.repo === r.id) && (!o.task || x.task === o.task));
+    if (!refs.length)
+      continue;
+    const not = [];
+    if (await sha(dir, `refs/heads/${from}`))
+      not.push(`refs/heads/${from}`);
+    if (!o.offline) {
+      const onHost = await git(["ls-remote", "--heads", remote, `refs/heads/${from}`], dir).then((x) => x.stdout.trim().split(/\s+/)[0] || void 0, () => void 0);
+      if (onHost && !await sha(dir, onHost))
+        await git(["fetch", "-q", remote, `+refs/heads/${from}:refs/remotes/${remote}/${from}`], dir).catch(() => void 0);
+      if (onHost && await sha(dir, onHost))
+        not.push(onHost);
+    } else if (await sha(dir, `refs/remotes/${remote}/${from}`))
+      not.push(`refs/remotes/${remote}/${from}`);
+    for (const x of refs) {
+      const tip = await sha(dir, `refs/heads/${x.branch}`);
+      if (!tip)
+        continue;
+      const merged = x.ticked && x.commit ? await sha(dir, x.commit) : void 0;
+      if (x.ticked && !merged)
+        continue;
+      const decided = await readTaskDecision(root, id, x.task);
+      if (decided && decided.branch === x.branch && sameSha(decided.commit, tip))
+        continue;
+      const commits = await git([
+        "rev-list",
+        "--count",
+        `refs/heads/${x.branch}`,
+        ...not.length || merged ? ["--not", ...not, ...merged ? [merged] : []] : []
+      ], dir).then((y) => Number(y.stdout.trim()) || 0, () => 0);
+      if (commits > 0)
+        out.push({
+          task: x.task,
+          repo: r.id,
+          branch: x.branch,
+          commits,
+          ...x.state ? { state: x.state } : {},
+          ...x.pr ? { pr: x.pr } : {}
+        });
+    }
+  }
+  return out.sort((a, b) => a.task < b.task ? -1 : a.task > b.task ? 1 : 0);
+}
+var sameSha = (a, b) => a.startsWith(b) || b.startsWith(a);
+function unmergedTaskWords(id, u) {
+  const from = changeBranch(id);
+  const n = `${u.commits} commit${u.commits === 1 ? "" : "s"}`;
+  const what = u.state === "pr-open" && u.pr ? `its PR #${u.pr.number} isn't merged yet: a person merges it on the Git host (${u.pr.url}), then Sync records it` : u.state === "unverified" || u.state === "needs-person" || u.state === "failed" ? `it was never built and raised: Build and raise PR on the Task board (or Run again), then merge its PR into ${from}` : `raise its PR (Raise the task's PR on the Task board) and merge it into ${from}`;
+  return `Task ${u.task}'s branch ${u.branch} in ${u.repo} has ${n} not in ${from}, so its code isn't in the change: ${what}. If its work isn't needed, mark the task done with a reason.`;
+}
+async function taskBranchReasons(root, id, o = {}) {
+  return (await unmergedTaskBranches(root, id, o)).map((u) => ({
+    code: "task-not-merged",
+    message: unmergedTaskWords(id, u)
+  }));
+}
+async function recordTaskDecision(root, id, task, o) {
+  const reason = o.reason.trim();
+  if (!reason)
+    throw new ChangeError("invalid", `Say why task ${task}'s work isn't needed in ${id}: a reason is recorded with the decision.`);
+  const branch = taskBranch(id, task);
+  const git = o.git ?? createGit({ timeoutMs: 3e4 });
+  const cr = await readChangeRepos(root, id).catch(() => void 0);
+  let commit;
+  for (const r of cr?.repos ?? []) {
+    const dir = repoDir(root, r);
+    if (!dir)
+      continue;
+    commit = await git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}^{commit}`], dir).then((x) => x.stdout.trim() || void 0, () => void 0);
+    if (commit)
+      break;
+  }
+  if (!commit)
+    throw new ChangeError("refused", `Task ${task} has no branch ${branch} here, so there is nothing to decide: mark it done.`);
+  const d = TaskDecision.parse({
+    schemaVersion: 1,
+    task,
+    branch,
+    commit,
+    by: o.by.trim(),
+    at: o.at,
+    reason
+  });
+  await writeFileAtomic(join9(changeFolder(root, id), "tasks", task, TASK_DECISION_FILE), toCanonicalYaml(d, ["schemaVersion", "task", "branch", "commit"]));
+  return d;
+}
+
+// packages/changes/dist/release-prs.js
 var RELEASE_PR_STATES = [
   "qa",
   "release-ready",
@@ -1837,18 +2050,87 @@ var NothingFile = external_exports.strictObject({
     commit: external_exports.string().regex(/^[0-9a-f]{7,64}$/).optional(),
     at: external_exports.string().min(1),
     by: external_exports.string().min(1)
-  }))
+  })),
+  /**
+   * Review round 48: the change branch's commit when Sync first read each release PR merged, so
+   * a merged PR stands only while the branch is there (work landed since needs a PR of its own).
+   */
+  merged: external_exports.array(external_exports.strictObject({
+    repo: external_exports.string().min(1),
+    number: external_exports.number().int().positive(),
+    commit: external_exports.string().regex(/^[0-9a-f]{7,64}$/),
+    at: external_exports.string().min(1)
+  })).optional()
 });
-async function readNothing(root, id) {
-  const text = await readFile8(join9(changeFolder(root, id), RELEASE_PRS_FILE), "utf8").catch(() => void 0);
+async function readReleaseFile(root, id) {
+  const empty = { schemaVersion: 1, nothingToRelease: [] };
+  const text = await readFile9(join10(changeFolder(root, id), RELEASE_PRS_FILE), "utf8").catch(() => void 0);
   if (text === void 0)
-    return [];
+    return empty;
   try {
-    const r = NothingFile.safeParse((0, import_yaml7.parse)(text));
-    return r.success ? r.data.nothingToRelease : [];
+    const r = NothingFile.safeParse((0, import_yaml8.parse)(text));
+    return r.success ? r.data : empty;
   } catch {
-    return [];
+    return empty;
+  }
+}
+async function readNothing(root, id) {
+  return (await readReleaseFile(root, id)).nothingToRelease;
+}
+async function writeReleaseFile(root, id, nothing, merged) {
+  const byRepo = (xs) => [...xs].sort((a, b) => a.repo < b.repo ? -1 : a.repo > b.repo ? 1 : 0);
+  await writeFile(join10(changeFolder(root, id), RELEASE_PRS_FILE), toCanonicalYaml(NothingFile.parse({
+    schemaVersion: 1,
+    nothingToRelease: byRepo(nothing),
+    ...merged.length ? { merged: byRepo(merged) } : {}
+  })), "utf8");
+}
+function repoDir2(root, r) {
+  const dirs = [join10(root, r.worktree)];
+  try {
+    dirs.push(baseClonePath(root, r.id));
+  } catch {
+  }
+  return dirs.find((d) => existsSync2(d));
+}
+async function staleReleasePrs(root, id, o = {}) {
+  const out = /* @__PURE__ */ new Set();
+  const cr = await readChangeRepos(root, id).catch(() => void 0);
+  const merged = (await readReleaseFile(root, id)).merged ?? [];
+  if (!cr || !merged.length)
+    return out;
+  const git = o.git ?? createGit({ timeoutMs: 3e4 });
+  const remote = o.remote ?? "origin";
+  for (const r of cr.repos) {
+    if (r.pr?.state !== "merged")
+      continue;
+    const entry = merged.find((x) => x.repo === r.id && x.number === r.pr.number);
+    if (!entry)
+      continue;
+    const dir = repoDir2(root, r);
+    if (!dir)
+      continue;
+    if (await movedPast(git, dir, remote, r.branch, entry.commit, o.offline))
+      out.add(r.id);
   }
+  return out;
+}
+var lastFetched = (git, dir, remote, branch) => git(["rev-parse", "--verify", "--quiet", `refs/remotes/${remote}/${branch}^{commit}`], dir).then((x) => x.stdout.trim() || void 0, () => void 0);
+async function movedPast(git, dir, remote, branch, commit, offline) {
+  const ref = `refs/heads/${branch}`;
+  const known = (sha) => git(["cat-file", "-e", `${sha}^{commit}`], dir).then(() => true, () => false);
+  const here = await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], dir).then((x) => x.stdout.trim() || void 0, () => void 0);
+  const onHost = offline ? await lastFetched(git, dir, remote, branch) : await git(["ls-remote", "--heads", remote, ref], dir).then((x) => x.stdout.trim().split(/\s+/)[0] || void 0, () => void 0);
+  if (!offline && onHost && !sameSha2(onHost, commit) && !await known(onHost))
+    await git(["fetch", "-q", remote, `+${ref}:refs/remotes/${remote}/${branch}`], dir).catch(() => void 0);
+  const ahead = async (sha) => {
+    if (!sha || sameSha2(sha, commit))
+      return false;
+    if (!await known(sha) || !await known(commit))
+      return true;
+    return git(["merge-base", "--is-ancestor", sha, commit], dir).then(() => false, () => true);
+  };
+  return await ahead(here) || await ahead(onHost);
 }
 async function nothingToRelease(root, id, o = {}) {
   const entries = await readNothing(root, id);
@@ -1866,22 +2148,19 @@ async function nothingToRelease(root, id, o = {}) {
   }
   return out;
   async function moved(r, commit) {
-    const dirs = [join9(root, r.worktree)];
-    try {
-      dirs.push(baseClonePath(root, r.id));
-    } catch {
-    }
-    const dir = dirs.find((d) => existsSync(d));
+    const dir = repoDir2(root, r);
     if (!dir)
       return false;
     const ref = `refs/heads/${r.branch}`;
     const here = await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], dir).then((x) => x.stdout.trim() || void 0, () => void 0);
-    const onHost = await git(["ls-remote", "--heads", remote, ref], dir).then((x) => x.stdout.trim().split(/\s+/)[0] || void 0, () => void 0);
-    const at = (sha) => sha !== void 0 && (commit === void 0 || !sameSha(sha, commit));
+    const fetched = o.offline ? await lastFetched(git, dir, remote, r.branch) : void 0;
+    const behind = !!fetched && !!commit && await git(["merge-base", "--is-ancestor", fetched, commit], dir).then(() => true, () => false);
+    const onHost = o.offline ? behind ? void 0 : fetched : await git(["ls-remote", "--heads", remote, ref], dir).then((x) => x.stdout.trim().split(/\s+/)[0] || void 0, () => void 0);
+    const at = (sha) => sha !== void 0 && (commit === void 0 || !sameSha2(sha, commit));
     return at(here) || at(onHost);
   }
 }
-var sameSha = (a, b) => a.startsWith(b) || b.startsWith(a);
+var sameSha2 = (a, b) => a.startsWith(b) || b.startsWith(a);
 var firstLine = (e) => (e instanceof Error ? e.message : String(e)).split("\n")[0].replace(/\.$/, "");
 var prOf = (pr, now) => ({
   url: pr.url,
@@ -1912,12 +2191,16 @@ async function raiseReleasePrs(root, id, o) {
   const rows = [];
   let changed2 = false;
   const repos = cr.repos.map((r) => ({ ...r }));
-  const before = await readNothing(root, id);
+  const file = await readReleaseFile(root, id);
+  const before = file.nothingToRelease;
   const nothing = new Map(before.map((x) => [x.repo, x]));
+  const stale = await staleReleasePrs(root, id, { git, remote });
+  const unmerged = await unmergedTaskBranches(root, id, { git, remote });
   for (const r of repos) {
-    if (!live(r.pr))
+    const movedOn = r.pr?.state === "merged" && stale.has(r.id) ? `Release PR #${r.pr.number} merged before ${r.branch} moved on; this one carries what landed since.` : void 0;
+    if (!live(r.pr) || movedOn)
       nothing.delete(r.id);
-    if (live(r.pr)) {
+    if (live(r.pr) && !movedOn) {
       rows.push({
         repo: r.id,
         outcome: "kept",
@@ -1926,6 +2209,15 @@ async function raiseReleasePrs(root, id, o) {
       });
       continue;
     }
+    const held = unmerged.filter((u) => u.repo === r.id);
+    if (held.length) {
+      rows.push({
+        repo: r.id,
+        outcome: "refused",
+        message: `${r.id}: no release PR, since ${r.branch} lacks the code of ${held.length === 1 ? `task ${held[0].task}` : `tasks ${held.map((u) => u.task).join(", ")}`}. ${held.map((u) => unmergedTaskWords(id, u)).join(" ")}`
+      });
+      continue;
+    }
     if (r.branch !== expected) {
       rows.push({
         repo: r.id,
@@ -1964,9 +2256,9 @@ async function raiseReleasePrs(root, id, o) {
       });
       continue;
     }
-    const notes = [];
-    const dir = join9(root, r.worktree);
-    if (existsSync(dir)) {
+    const notes = movedOn ? [movedOn] : [];
+    const dir = join10(root, r.worktree);
+    if (existsSync2(dir)) {
       const onHost = await git(["ls-remote", "--heads", remote, `refs/heads/${r.branch}`], dir).then((x) => x.stdout.trim() ? "yes" : "no").catch((e) => {
         notes.push(`Atticus couldn't reach ${remote} (${firstLine(e)}): push ${r.branch} yourself if the host lacks it.`);
         return "unknown";
@@ -2048,8 +2340,10 @@ async function raiseReleasePrs(root, id, o) {
   if (changed2)
     await writeChangeRepos(root, { ...cr, repos });
   const after = [...nothing.values()].sort((a, b) => a.repo < b.repo ? -1 : 1);
-  if (JSON.stringify(after) !== JSON.stringify(before))
-    await writeFile(join9(changeFolder(root, id), RELEASE_PRS_FILE), toCanonicalYaml(NothingFile.parse({ schemaVersion: 1, nothingToRelease: after })), "utf8");
+  const mergedBefore = file.merged ?? [];
+  const mergedAfter = mergedBefore.filter((x) => repos.some((r) => r.id === x.repo && r.pr?.number === x.number && r.pr.state === "merged"));
+  if (JSON.stringify(after) !== JSON.stringify(before) || mergedAfter.length !== mergedBefore.length)
+    await writeReleaseFile(root, id, after, mergedAfter);
   return { change: id, rows };
 }
 async function syncReleasePrs(root, id, o) {
@@ -2060,6 +2354,9 @@ async function syncReleasePrs(root, id, o) {
   const now = o.now ?? nowIso();
   let changed2 = false;
   const repos = cr.repos.map((r) => ({ ...r }));
+  const file = await readReleaseFile(root, id);
+  const merged = [...file.merged ?? []];
+  let mergedChanged = false;
   for (const r of repos) {
     if (!r.pr)
       continue;
@@ -2100,6 +2397,16 @@ async function syncReleasePrs(root, id, o) {
       r.build = { ...r.build, status: build, at: now };
       changed2 = true;
     }
+    if (pr.state === "merged" && !merged.some((x) => x.repo === r.id && x.number === pr.number)) {
+      const commit = await branchTip(root, r, o.git, o.remote ?? "origin");
+      if (commit) {
+        for (let i = merged.length - 1; i >= 0; i--)
+          if (merged[i].repo === r.id)
+            merged.splice(i, 1);
+        merged.push({ repo: r.id, number: pr.number, commit, at: now });
+        mergedChanged = true;
+      }
+    }
     rows.push({
       repo: r.id,
       outcome: "kept",
@@ -2109,8 +2416,25 @@ async function syncReleasePrs(root, id, o) {
   }
   if (changed2)
     await writeChangeRepos(root, { ...cr, repos });
+  if (mergedChanged)
+    await writeReleaseFile(root, id, file.nothingToRelease, merged);
   return { change: id, rows };
 }
+async function branchTip(root, r, g, remote) {
+  const dir = repoDir2(root, r);
+  if (!dir)
+    return void 0;
+  const git = g ?? createGit({ timeoutMs: 3e4 });
+  const ref = `refs/heads/${r.branch}`;
+  const onHost = await git(["ls-remote", "--heads", remote, ref], dir).then((x) => x.stdout.trim().split(/\s+/)[0] || void 0, () => void 0);
+  if (onHost) {
+    await git(["fetch", "-q", remote, `+${ref}:refs/remotes/${remote}/${r.branch}`], dir).catch(() => void 0);
+    if (/^[0-9a-f]{7,64}$/.test(onHost))
+      return onHost;
+  }
+  const here = await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], dir).then((x) => x.stdout.trim(), () => "");
+  return /^[0-9a-f]{7,64}$/.test(here) ? here : void 0;
+}
 function buildOf(pr) {
   if (!pr.checks.length)
     return void 0;
@@ -2121,11 +2445,11 @@ function buildOf(pr) {
   return "passed";
 }
 async function requireMergedPrs(root) {
-  const text = await readFile8(join9(orgPackDirOf(root), "process", "ci.yaml"), "utf8").catch(() => void 0);
+  const text = await readFile9(join10(orgPackDirOf(root), "process", "ci.yaml"), "utf8").catch(() => void 0);
   if (text === void 0)
     return true;
   try {
-    const v = (0, import_yaml7.parse)(text)?.archive?.requireMergedPrs;
+    const v = (0, import_yaml8.parse)(text)?.archive?.requireMergedPrs;
     return v !== false;
   } catch {
     return true;
@@ -2137,10 +2461,18 @@ async function releasePrReasons(root, id, o = {}) {
     return [];
   const merged = await requireMergedPrs(root);
   const nothing = await nothingToRelease(root, id, o);
-  const out = [];
+  const stale = await staleReleasePrs(root, id, o);
+  const out = await taskBranchReasons(root, id, o);
   for (const r of cr.repos) {
     if (!r.pr && nothing.has(r.id))
       continue;
+    if (r.pr?.state === "merged" && stale.has(r.id)) {
+      out.push({
+        code: "release-pr-stale",
+        message: `${r.id}: ${r.branch} has commits since release PR #${r.pr.number} merged, so they haven't reached its default branch: raise the release PRs again (Release \u203A Raise the release PRs, or atticus change release-prs ${id} --approve).`
+      });
+      continue;
+    }
     if (!r.pr || r.pr.state === "closed")
       out.push({
         code: "release-pr-missing",
@@ -2202,7 +2534,11 @@ async function assess(ctx, change) {
     ...stageReasons.length ? [] : await checkMandatoryRounds(ctx.root, change, phaseGates(ctx, phase).filter((g) => mandatoryGates(ctx).includes(g))),
     // ADR 0184: go/no-go is decided over the release PRs, each repo's change branch into its
     // default branch, merged (unless the org pack's ci.yaml says archive.requireMergedPrs: false).
-    ...phase === "release" ? await releasePrReasons(ctx.root, change.id) : []
+    // Both read refs here only (the host's branches as last fetched): an assessment runs on every
+    // page load (Home's cockpit), which never reaches the Git host; Sync and the release steps do.
+    ...phase === "release" ? await releasePrReasons(ctx.root, change.id, { offline: true }) : [],
+    // App-only audit: Build ready waits for every task's work to be in the change branch.
+    ...phase === "build" ? await taskBranchReasons(ctx.root, change.id, { offline: true }) : []
   ];
   const next = change.state === "returned" ? phaseState(phase) : nextState(type, phase);
   const live2 = change.state === "returned" ? void 0 : liveHandoff(change);
@@ -2245,7 +2581,7 @@ async function changeReport(root, id) {
   return { ...a, nextStep: nextStep(a, tasks), problems: ctx.problems };
 }
 async function taskTicks(root, id) {
-  const text = await readFile9(join10(changeFolder(root, id), "tasks.md"), "utf8").catch(() => "");
+  const text = await readFile10(join11(changeFolder(root, id), "tasks.md"), "utf8").catch(() => "");
   const boxes = [...text.matchAll(/^\s*[-*]\s+\[([ xX])\]/gm)].map((m) => m[1] !== " ");
   return boxes.length ? { done: boxes.filter(Boolean).length, total: boxes.length } : void 0;
 }
@@ -2276,9 +2612,9 @@ function nextStep(a, tasks) {
 }
 
 // packages/changes/dist/new-change.js
-var import_yaml8 = __toESM(require_dist(), 1);
-import { mkdir, readFile as readFile10, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join11 } from "node:path";
+var import_yaml9 = __toESM(require_dist(), 1);
+import { mkdir, readFile as readFile11, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join12 } from "node:path";
 var nowIso2 = () => (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 var strip2 = (h) => h.startsWith("@") ? h.slice(1) : h;
 function windowsUnsafeName(id) {
@@ -2290,7 +2626,7 @@ function slugify(title) {
 }
 async function exists(path) {
   try {
-    await readFile10(path);
+    await readFile11(path);
     return true;
   } catch {
     return false;
@@ -2298,7 +2634,7 @@ async function exists(path) {
 }
 async function defaultSchema(root) {
   try {
-    const cfg = (0, import_yaml8.parse)(await readFile10(join11(openspecDirOf(root), "config.yaml"), "utf8"));
+    const cfg = (0, import_yaml9.parse)(await readFile11(join12(openspecDirOf(root), "config.yaml"), "utf8"));
     if (cfg && typeof cfg.schema === "string")
       return cfg.schema;
   } catch {
@@ -2322,17 +2658,17 @@ async function newChange(root, opts) {
   const now = opts.now ?? nowIso2();
   const by = strip2(opts.by);
   const dir = changeFolder(root, id);
-  if (opts.openspec && !await exists(join11(dir, ".openspec.yaml"))) {
+  if (opts.openspec && !await exists(join12(dir, ".openspec.yaml"))) {
     await opts.openspec.newChange(id, { description: opts.title });
   } else {
     await mkdir(dir, { recursive: true });
-    if (!await exists(join11(dir, ".openspec.yaml")))
-      await writeFile2(join11(dir, ".openspec.yaml"), `schema: ${await defaultSchema(root)}
+    if (!await exists(join12(dir, ".openspec.yaml")))
+      await writeFile2(join12(dir, ".openspec.yaml"), `schema: ${await defaultSchema(root)}
 created: ${now.slice(0, 10)}
 `, "utf8");
   }
-  if (!await exists(join11(dir, "brief.md")))
-    await writeFileAtomic(join11(dir, "brief.md"), renderTemplate(template, {
+  if (!await exists(join12(dir, "brief.md")))
+    await writeFileAtomic(join12(dir, "brief.md"), renderTemplate(template, {
       title: opts.title,
       id,
       type: type.id,
@@ -2372,7 +2708,7 @@ created: ${now.slice(0, 10)}
 // packages/changes/dist/publish.js
 import { rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join as join12, resolve } from "node:path";
+import { join as join13, resolve } from "node:path";
 function gitHandoffPublisher(opts = {}) {
   const remote = opts.remote ?? "origin";
   const env = opts.env ?? process.env;
@@ -2394,18 +2730,19 @@ function gitHandoffPublisher(opts = {}) {
       const gitDir = await out(["rev-parse", "--absolute-git-dir"]);
       await tryOut(["fetch", "--quiet", remote, base]);
       await tryOut(["fetch", "--quiet", remote, branch]);
-      const start = await tryOut([
+      const onRemote = await tryOut([
         "rev-parse",
         "--verify",
         "--quiet",
         `refs/remotes/${remote}/${branch}^{commit}`
-      ]) ?? await tryOut([
+      ]);
+      const start = onRemote ?? await tryOut([
         "rev-parse",
         "--verify",
         "--quiet",
         `refs/remotes/${remote}/${base}^{commit}`
       ]) ?? await out(["rev-parse", "--verify", `refs/heads/${base}^{commit}`]);
-      const index = join12(gitDir, `atticus-handoff-index-${process.pid}-${randomUUID()}`);
+      const index = join13(gitDir, `atticus-handoff-index-${process.pid}-${randomUUID()}`);
       const staged = createGit({ env: { ...env, GIT_INDEX_FILE: index } });
       try {
         await staged(["read-tree", start], root);
@@ -2414,9 +2751,9 @@ function gitHandoffPublisher(opts = {}) {
         const tree = (await staged(["write-tree"], root)).stdout.trim();
         const startTree = await out(["rev-parse", `${start}^{tree}`]);
         const commit = tree === startTree ? start : await out(["commit-tree", tree, "-p", start, "-m", message]);
-        await out(["update-ref", `refs/heads/${branch}`, commit]);
+        await keepLocalBranch(out, tryOut, branch, start, commit);
         await out(["push", "--quiet", remote, `${commit}:refs/heads/${branch}`]);
-        return { commit };
+        return { commit, changed: commit !== onRemote };
       } finally {
         await rm(index, { force: true });
       }
@@ -2424,15 +2761,49 @@ function gitHandoffPublisher(opts = {}) {
   }
 }
 var queue = /* @__PURE__ */ new Map();
+async function handoffBranchPushed(root, branch, o = {}) {
+  const git = createGit({ env: o.env ?? process.env });
+  const sha = (ref) => git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], root).then((x) => x.stdout.trim() || void 0, () => void 0);
+  const here = await sha(`refs/heads/${branch}`);
+  if (!here)
+    return true;
+  return await sha(`refs/remotes/${o.remote ?? "origin"}/${branch}`) === here;
+}
+async function pushHandoffBranch(root, branch, o) {
+  requireApproval("git", o.approval);
+  if (!/^handoff\//.test(branch))
+    throw new Error(`${branch} isn't a hand-off branch`);
+  const git = createGit({ env: o.env ?? process.env });
+  const commit = (await git(["rev-parse", "--verify", `refs/heads/${branch}^{commit}`], root)).stdout.trim();
+  await git(["push", "--quiet", o.remote ?? "origin", `refs/heads/${branch}:refs/heads/${branch}`], root);
+  return { branch, commit };
+}
+async function keepLocalBranch(out, tryOut, branch, start, commit) {
+  const ref = `refs/heads/${branch}`;
+  const local = await tryOut(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  if (local === commit)
+    return;
+  const list = await tryOut(["worktree", "list", "--porcelain"]) ?? "";
+  if (list.split(/\r?\n/).includes(`branch ${ref}`))
+    return;
+  if (!local) {
+    await tryOut(["update-ref", ref, commit, ""]);
+    return;
+  }
+  const own = await tryOut(["rev-list", "--count", `${start}..${local}`]);
+  if (own === void 0 || own !== "0")
+    return;
+  await out(["update-ref", ref, commit, local]).catch(() => void 0);
+}
 
 // packages/changes/dist/handoff.js
-import { readdir as readdir6, readFile as readFile12 } from "node:fs/promises";
-import { join as join14 } from "node:path";
+import { readdir as readdir7, readFile as readFile13 } from "node:fs/promises";
+import { join as join15 } from "node:path";
 
 // packages/changes/dist/drafted.js
-var import_yaml9 = __toESM(require_dist(), 1);
-import { mkdir as mkdir2, readdir as readdir5, readFile as readFile11, rm as rm2 } from "node:fs/promises";
-import { dirname, join as join13, relative, sep } from "node:path";
+var import_yaml10 = __toESM(require_dist(), 1);
+import { mkdir as mkdir2, readdir as readdir6, readFile as readFile12, rm as rm2 } from "node:fs/promises";
+import { dirname, join as join14, relative, sep } from "node:path";
 var CAPTURE_SCHEMA_VERSION = 1;
 var DraftCapture = external_exports.object({
   schemaVersion: external_exports.literal(CAPTURE_SCHEMA_VERSION),
@@ -2507,7 +2878,7 @@ var sameText = (text, recorded) => sha256(text) === recorded || sha256(text.repl
 async function walk2(dir, rel = "") {
   let entries;
   try {
-    entries = await readdir5(join13(dir, rel), { withFileTypes: true });
+    entries = await readdir6(join14(dir, rel), { withFileTypes: true });
   } catch {
     return [];
   }
@@ -2652,7 +3023,7 @@ async function captureHandoff(input) {
   } else {
     const texts = await Promise.all(recorded.map(async (r) => [
       r,
-      await readFile11(join13(folder, ...r.path.split("/")), "utf8").catch(() => void 0)
+      await readFile12(join14(folder, ...r.path.split("/")), "utf8").catch(() => void 0)
     ]));
     if (texts.every(([r, t]) => t !== void 0 && sameText(t, r.sha256))) {
       from = "working-tree";
@@ -2716,10 +3087,10 @@ async function captureHandoff(input) {
     } : {}
   };
   const p = capturePaths(name);
-  await rm2(join13(folder, ...p.drafted.split("/")), { recursive: true, force: true });
-  await rm2(join13(folder, ...p.merged.split("/")), { recursive: true, force: true });
+  await rm2(join14(folder, ...p.drafted.split("/")), { recursive: true, force: true });
+  await rm2(join14(folder, ...p.merged.split("/")), { recursive: true, force: true });
   const put = async (base, rel, text) => {
-    const f = join13(folder, ...base.split("/"), ...rel.split("/"));
+    const f = join14(folder, ...base.split("/"), ...rel.split("/"));
     await mkdir2(dirname(f), { recursive: true });
     await writeFileAtomic(f, text);
   };
@@ -2728,37 +3099,37 @@ async function captureHandoff(input) {
   if (state === "captured")
     for (const [rel, t] of mergedFiles)
       await put(p.merged, rel, t);
-  await mkdir2(join13(folder, "stage"), { recursive: true });
-  await writeFileAtomic(join13(folder, ...p.capture.split("/")), HEADER + (0, import_yaml9.stringify)(capture, { lineWidth: 0 }));
+  await mkdir2(join14(folder, "stage"), { recursive: true });
+  await writeFileAtomic(join14(folder, ...p.capture.split("/")), HEADER + (0, import_yaml10.stringify)(capture, { lineWidth: 0 }));
   return { capture, file: p.capture };
 }
 async function readFolderFiles(dir) {
   const out = /* @__PURE__ */ new Map();
   for (const f of await walk2(dir))
-    out.set(f, (await readFile11(join13(dir, ...f.split("/")), "utf8")).replace(/\r\n/g, "\n"));
+    out.set(f, (await readFile12(join14(dir, ...f.split("/")), "utf8")).replace(/\r\n/g, "\n"));
   return out;
 }
 async function changeFolders(root) {
-  const base = join13(root, ...changesRelOf(root).split("/"));
+  const base = join14(root, ...changesRelOf(root).split("/"));
   const out = [];
-  const list = async (dir) => (await readdir5(dir, { withFileTypes: true }).catch(() => [])).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  const list = async (dir) => (await readdir6(dir, { withFileTypes: true }).catch(() => [])).filter((e) => e.isDirectory()).map((e) => e.name).sort();
   for (const name of await list(base)) {
     if (name === "archive")
-      for (const a of await list(join13(base, "archive")))
-        out.push(join13(base, "archive", a));
+      for (const a of await list(join14(base, "archive")))
+        out.push(join14(base, "archive", a));
     else
-      out.push(join13(base, name));
+      out.push(join14(base, name));
   }
   return out;
 }
 async function readDraftPairs(root) {
   const out = [];
   for (const folder of await changeFolders(root)) {
-    const names = (await readdir5(join13(folder, "stage")).catch(() => [])).filter((f) => f.endsWith(".capture.yaml")).sort();
+    const names = (await readdir6(join14(folder, "stage")).catch(() => [])).filter((f) => f.endsWith(".capture.yaml")).sort();
     for (const f of names) {
       let capture;
       try {
-        capture = DraftCapture.parse((0, import_yaml9.parse)(await readFile11(join13(folder, "stage", f), "utf8")));
+        capture = DraftCapture.parse((0, import_yaml10.parse)(await readFile12(join14(folder, "stage", f), "utf8")));
       } catch {
         continue;
       }
@@ -2766,8 +3137,8 @@ async function readDraftPairs(root) {
       out.push({
         capture,
         folder: relative(root, folder).split(sep).join("/"),
-        drafted: await readFolderFiles(join13(folder, ...p.drafted.split("/"))),
-        merged: await readFolderFiles(join13(folder, ...p.merged.split("/")))
+        drafted: await readFolderFiles(join14(folder, ...p.drafted.split("/"))),
+        merged: await readFolderFiles(join14(folder, ...p.merged.split("/")))
       });
     }
   }
@@ -2787,8 +3158,8 @@ async function completeCaptures(root, ctx, o) {
       continue;
     for (const h of change.handoffs.filter((x) => x.state === "merged")) {
       const { name } = await captureStageOf(ctx, change, h.phase);
-      const file = join13(changeFolder(root, change.id), ...capturePaths(name).capture.split("/"));
-      const prior = await readFile11(file, "utf8").then((t) => DraftCapture.safeParse((0, import_yaml9.parse)(t)), () => void 0);
+      const file = join14(changeFolder(root, change.id), ...capturePaths(name).capture.split("/"));
+      const prior = await readFile12(file, "utf8").then((t) => DraftCapture.safeParse((0, import_yaml10.parse)(t)), () => void 0);
       if (prior?.success && prior.data.pr.number === h.pr.number && prior.data.state !== "waiting-for-merge")
         continue;
       const base = prior?.success ? prior.data.base : o.defaultBase ?? "main";
@@ -2812,6 +3183,7 @@ async function completeCaptures(root, ctx, o) {
 // packages/changes/dist/handoff.js
 var nowIso3 = () => (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 var strip3 = (h) => h.startsWith("@") ? h.slice(1) : h;
+var sameHandle = (a, b) => handleKey(a) === handleKey(b);
 function metarepo(ctx, repo) {
   const fromRuntime = ctx.orgPack.runtime.adapters.gitHost?.settings.metarepo;
   const r = repo ?? (typeof fromRuntime === "string" ? fromRuntime : void 0);
@@ -2828,16 +3200,16 @@ async function load(root, id) {
 }
 async function walkReview(dir, gate) {
   const out = [];
-  const base = join14(dir, "review", gate);
+  const base = join15(dir, "review", gate);
   let rounds;
   try {
-    rounds = (await readdir6(base)).filter((r) => /^\d+$/.test(r)).sort((a, b) => Number(a) - Number(b));
+    rounds = (await readdir7(base)).filter((r) => /^\d+$/.test(r)).sort((a, b) => Number(a) - Number(b));
   } catch {
     return [];
   }
   for (const r of rounds) {
     try {
-      for (const f of (await readdir6(join14(base, r))).filter((x) => /\.ya?ml$/.test(x)).sort())
+      for (const f of (await readdir7(join15(base, r))).filter((x) => /\.ya?ml$/.test(x)).sort())
         out.push(`review/${gate}/${r}/${f}`);
     } catch {
     }
@@ -2848,12 +3220,12 @@ async function keptPairFiles(dir) {
   const out = [];
   let entries;
   try {
-    entries = await readdir6(join14(dir, "stage"), { withFileTypes: true });
+    entries = await readdir7(join15(dir, "stage"), { withFileTypes: true });
   } catch {
     return out;
   }
   const walk3 = async (rel) => {
-    for (const e of await readdir6(join14(dir, ...rel.split("/")), { withFileTypes: true }).catch(() => [])) {
+    for (const e of await readdir7(join15(dir, ...rel.split("/")), { withFileTypes: true }).catch(() => [])) {
       const p = `${rel}/${e.name}`;
       if (e.isDirectory())
         await walk3(p);
@@ -2887,15 +3259,20 @@ async function handoffFiles(ctx, a, phase) {
       for (const f of await stageFiles(dir, step))
         files.add(f);
   }
-  const present = async (f) => readFile12(join14(dir, ...f.split("/"))).then(() => true, () => false);
-  for (const own of ["stage/corrections.yaml", "stage/drafted.yaml"])
+  const present = async (f) => readFile13(join15(dir, ...f.split("/"))).then(() => true, () => false);
+  for (const own of [
+    "stage/corrections.yaml",
+    "stage/drafted.yaml",
+    "stage/stories-numbers.yaml",
+    "stage/stories-shape.yaml"
+  ])
     if (await present(own))
       files.add(own);
   if (phase === "build") {
     for (const extra of ["tasks.md", "repos.yaml"])
       if (await present(extra))
         files.add(extra);
-    for (const t of await readdir6(join14(dir, "tasks"), { withFileTypes: true }).catch(() => []))
+    for (const t of await readdir7(join15(dir, "tasks"), { withFileTypes: true }).catch(() => []))
       if (t.isDirectory() && await present(`tasks/${t.name}/report.md`))
         files.add(`tasks/${t.name}/report.md`);
   }
@@ -2918,6 +3295,11 @@ async function changeQuestionFiles(root, id) {
   const rel = questionsRelOf(root);
   return questions.filter((q) => namesChange(q.askedBy.command, id) || namesChange(q.rerun, id)).map((q) => `${rel}/${q.id}.yaml`).sort();
 }
+function nextRoleOf(c, phase, person) {
+  const n = nextOwnersOf(phase, c.owners);
+  return n?.people.includes(person) ? ` (${n.role.replace(/-/g, " ")})` : "";
+}
+var nextRoleName = (phase) => (nextOwnersOf(phase, {})?.role ?? "reviewer").replace(/-/g, " ");
 function prBody(a, phase, next, paths, reviewers, review) {
   const c = a.change;
   const lines2 = [
@@ -2933,7 +3315,7 @@ function prBody(a, phase, next, paths, reviewers, review) {
     "",
     "### Reviewers",
     "",
-    ...reviewers.length ? reviewers.map((r) => `- @${r}`) : ["- None"],
+    ...reviewers.length ? reviewers.map((r) => `- @${r}${nextRoleOf(c, phase, r)}`) : [`- None: name the ${nextRoleName(phase)} under the change's owners`],
     "",
     "### Risk",
     "",
@@ -2964,7 +3346,7 @@ async function handoff(root, id, opts) {
     await requireValid(opts.openspec, id);
   const { files, artifacts } = await handoffFiles(ctx, a, phase);
   const dir = changeFolder(root, id);
-  const hashed = await Promise.all(files.map(async (path) => ({ path, sha256: sha256(await readFile12(join14(dir, path))) })));
+  const hashed = await Promise.all(files.map(async (path) => ({ path, sha256: sha256(await readFile13(join15(dir, path))) })));
   const authors = { ...change.authors };
   for (const art of artifacts) {
     const people = (opts.authors?.[art] ?? [by]).map(strip3);
@@ -2979,13 +3361,16 @@ async function handoff(root, id, opts) {
     ...questionFiles
   ];
   const reviewers = [
-    ...new Set(files.flatMap((f) => ownersFor(ctx.codeowners, `${rel}/${id}/${f}`)))
-  ].filter((p) => p !== by).sort();
+    .../* @__PURE__ */ new Set([
+      ...files.flatMap((f) => ownersFor(ctx.codeowners, `${rel}/${id}/${f}`)),
+      ...nextOwnersOf(phase, change.owners)?.people ?? []
+    ])
+  ].filter((p) => sameHandle(p, by) === false).sort();
   const live2 = change.state === "returned" ? void 0 : liveHandoff(change);
   if (live2 && live2.phase === phase) {
     const pr2 = await handoffPr(opts.gitHost, repo, id, live2);
     if (pr2.state === "open" || pr2.state === "draft") {
-      await opts.publisher?.publish({
+      const published = await opts.publisher?.publish({
         root,
         branch,
         base: pr2.base,
@@ -2993,7 +3378,9 @@ async function handoff(root, id, opts) {
         message: `${handoffName(a.type, phase)}: update`,
         approval: opts.approval
       });
-      await opts.gitHost.comment(repo, pr2.number, `${by} updated the hand-off for another review.`, opts.approval);
+      const unchanged = published ? published.changed === false : sameArtifacts(hashed, live2.artifacts);
+      if (!unchanged)
+        await opts.gitHost.comment(repo, pr2.number, `${by} updated the hand-off for another review.`, opts.approval);
       const updated = {
         ...live2,
         state: "open",
@@ -3014,6 +3401,13 @@ async function handoff(root, id, opts) {
     live2.state = "closed";
     live2.updatedAt = now;
   }
+  if (change.state === "returned") {
+    const open = (await opts.gitHost.listPullRequests(repo, { head: branch })).find((p) => p.state === "open" || p.state === "draft");
+    if (open) {
+      const message = `PR #${open.number} from ${branch} is still open on the Git host (${open.url}): close it there first (the return asked for that), then resubmit the change.`;
+      throw new ChangeError("refused", message, [{ code: "host-refused", message }]);
+    }
+  }
   const base = opts.base ?? (await opts.gitHost.getRepo(repo)).defaultBranch;
   const next = a.next;
   await opts.publisher?.publish({
@@ -3024,13 +3418,23 @@ async function handoff(root, id, opts) {
     message: `${handoffName(a.type, phase)}: ${change.title}`,
     approval: opts.approval
   });
-  const pr = await opts.gitHost.createPullRequest({
-    repo,
-    head: branch,
-    base,
-    title: `${change.title}: ${handoffName(a.type, phase)}`,
-    body: prBody(a, phase, change.state === "returned" ? nextAfterResubmit(a, phase) : next, [...files.map((f) => `${rel}/${id}/${f}`), ...questionFiles], reviewers, opts.review)
-  }, opts.approval);
+  let pr;
+  try {
+    pr = await opts.gitHost.createPullRequest({
+      repo,
+      head: branch,
+      base,
+      title: `${change.title}: ${handoffName(a.type, phase)}`,
+      body: prBody(a, phase, change.state === "returned" ? nextAfterResubmit(a, phase) : next, [...files.map((f) => `${rel}/${id}/${f}`), ...questionFiles], reviewers, opts.review)
+    }, opts.approval);
+  } catch (e) {
+    if (!(e instanceof AdapterError) || e.code !== "conflict")
+      throw e;
+    const open = (await opts.gitHost.listPullRequests(repo, { head: branch }).catch(() => [])).filter((p) => p.base === base && (p.state === "open" || p.state === "draft")).at(0);
+    if (!open)
+      throw e;
+    pr = open;
+  }
   const h = {
     phase,
     branch,
@@ -3057,6 +3461,10 @@ async function handoff(root, id, opts) {
   });
   return h;
 }
+function sameArtifacts(a, b) {
+  const key = (xs) => JSON.stringify([...xs].map((x) => `${x.path} ${x.sha256}`).sort());
+  return key(a) === key(b);
+}
 function nextAfterResubmit(a, phase) {
   const next = a.type.phases[a.type.phases.indexOf(phase) + 1];
   return next ? phaseState(next) : "released";
@@ -3255,10 +3663,15 @@ async function returnToPo(root, id, opts) {
 async function requireValid(openspec, id) {
   const r = await openspec.validate({ item: id, type: "change", strict: true });
   const item = r.items[0];
-  if (!item || item.valid)
+  const issues = item ? blockingIssues(item.issues) : [];
+  if (!item || item.valid && issues.length === 0)
     return;
-  throw new ChangeError("refused", `${id} doesn't pass openspec validate --strict.`, item.issues.filter((i) => i.level !== "INFO").map((i) => ({ code: "openspec-invalid", message: `${i.path}: ${i.message}` })));
+  throw new ChangeError("refused", `${id} doesn't pass openspec validate --strict.`, issues.map((i) => ({
+    code: "openspec-invalid",
+    message: `${i.path}: ${i.message}${archiveRefuses(i) ? ` ${ADDED_ONLY}` : ""}`
+  })));
 }
+var ADDED_ONLY = `A spec that openspec/specs doesn't have yet takes "## ADDED Requirements" only: change the delta's MODIFIED (or RENAMED, REMOVED) heading to ADDED, or run the stage that wrote it again.`;
 async function archiveChange(root, id, opts) {
   const { ctx, change } = await load(root, id);
   const a = await assess(ctx, change);
@@ -3279,14 +3692,25 @@ async function archiveChange(root, id, opts) {
   };
   await changeStore(root).write(updated);
   if (opts.openspec)
-    await opts.openspec.archive(id);
+    try {
+      await opts.openspec.archive(id);
+    } catch (e) {
+      await changeStore(root).write(change);
+      const words = (e instanceof Error ? e.message : String(e)).trim();
+      throw new ChangeError("refused", `OpenSpec refused to archive ${id}, so nothing was archived.`, [
+        {
+          code: "openspec-invalid",
+          message: `${words.replace(/\.?$/, ".")}${/target spec does not exist|only ADDED/i.test(words) ? ` ${ADDED_ONLY}` : " Fix what it says, then archive again (atticus openspec validate " + id + " --strict says more)."}`
+        }
+      ]);
+    }
   return updated;
 }
 
 // packages/changes/dist/learn.js
-var import_yaml10 = __toESM(require_dist(), 1);
-import { readFile as readFile13 } from "node:fs/promises";
-import { join as join15 } from "node:path";
+var import_yaml11 = __toESM(require_dist(), 1);
+import { readFile as readFile14 } from "node:fs/promises";
+import { join as join16 } from "node:path";
 var LEARN_SCHEMA_VERSION = 1;
 var MAX_CELLS = 4e6;
 var lines = (text) => {
@@ -3633,7 +4057,7 @@ async function pairTouches(root, p) {
   let entry;
   const yaml = (t) => {
     try {
-      const v = (0, import_yaml10.parse)(t);
+      const v = (0, import_yaml11.parse)(t);
       return v && typeof v === "object" ? v : void 0;
     } catch {
       return void 0;
@@ -3675,7 +4099,7 @@ async function pairTouches(root, p) {
         flows.push(m[1]);
     }
   }
-  const change = yaml(await readFile13(join15(root, ...p.folder.split("/"), "change.yaml"), "utf8").catch(() => ""));
+  const change = yaml(await readFile14(join16(root, ...p.folder.split("/"), "change.yaml"), "utf8").catch(() => ""));
   const touches = change?.touches ?? {};
   for (const r of Array.isArray(touches.repos) ? touches.repos : [])
     if (typeof r === "string")
@@ -3768,8 +4192,8 @@ async function detectConflicts(root) {
 }
 
 // packages/changes/dist/size.js
-import { readFile as readFile14 } from "node:fs/promises";
-import { join as join16 } from "node:path";
+import { readFile as readFile15 } from "node:fs/promises";
+import { join as join17 } from "node:path";
 async function changeSize(ctx, change) {
   const type = ctx.orgPack.changeTypes.types.find((t) => t.id === change.type);
   if (!type)
@@ -3778,7 +4202,7 @@ async function changeSize(ctx, change) {
       why: "standard",
       words: `${change.type} isn't a change type in change-types.yaml, so ${change.id} takes the full path.`
     };
-  const brief = await readFile14(join16(changeFolder(ctx.root, change.id), "brief.md"), "utf8").catch(() => "");
+  const brief = await readFile15(join17(changeFolder(ctx.root, change.id), "brief.md"), "utf8").catch(() => "");
   const f = fastPathOf(type, brief);
   const gate = f.fast ? fastGateOf(type, ctx.orgPack.gates) : void 0;
   const words = {
@@ -3792,13 +4216,13 @@ async function changeSize(ctx, change) {
 }
 
 // packages/changes/dist/openspec-stores.js
-import { existsSync as existsSync2 } from "node:fs";
-import { readFile as readFile15, writeFile as writeFile3 } from "node:fs/promises";
+import { existsSync as existsSync3 } from "node:fs";
+import { readFile as readFile16, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, isAbsolute, join as join17, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
+import { basename, isAbsolute, join as join18, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
 function storeDirOf(root, path) {
   if (path === "~" || path.startsWith("~/") || path.startsWith("~\\"))
-    return join17(homedir(), path.slice(2));
+    return join18(homedir(), path.slice(2));
   return isAbsolute(path) ? resolve2(path) : resolve2(root, path);
 }
 function packRel(root) {
@@ -3828,7 +4252,7 @@ async function storeSpecLookup(root, capability) {
 var REMOTE = /^[a-z][a-z0-9+.-]*:\/\//i;
 var SCP = /^[^/\\]+@[^:/\\]+:/;
 async function metarepoOrigin(root, git = createGit()) {
-  if (!existsSync2(join17(root, ".git")))
+  if (!existsSync3(join18(root, ".git")))
     return void 0;
   try {
     const url = (await git(["remote", "get-url", "origin"], root)).stdout.trim();
@@ -3839,7 +4263,7 @@ async function metarepoOrigin(root, git = createGit()) {
     return void 0;
   }
 }
-async function referenceMetarepoIn(root, repoDir, o = {}) {
+async function referenceMetarepoIn(root, repoDir3, o = {}) {
   const { settings } = await loadOpenSpecSettings(orgPackDirOf(root));
   if (!settings.referenceInRepos)
     return { action: "off" };
@@ -3851,8 +4275,8 @@ async function referenceMetarepoIn(root, repoDir, o = {}) {
       file,
       why: marker.missing ? `this metarepo isn't an OpenSpec store yet (no ${STORE_MARKER}): run atticus upgrade --openspec-store, commit the file, then hand down again` : `this metarepo's ${STORE_MARKER} can't be read (${marker.notes.join("; ")})`
     };
-  const path = join17(repoDir, "openspec", "config.yaml");
-  const text = await readFile15(path, "utf8").catch(() => void 0);
+  const path = join18(repoDir3, "openspec", "config.yaml");
+  const text = await readFile16(path, "utf8").catch(() => void 0);
   if (text === void 0)
     return {
       action: "skipped",
@@ -3869,7 +4293,7 @@ async function referenceMetarepoIn(root, repoDir, o = {}) {
 }
 
 // packages/changes/dist/merge-record.js
-var import_yaml11 = __toESM(require_dist(), 1);
+var import_yaml12 = __toESM(require_dist(), 1);
 import { isDeepStrictEqual } from "node:util";
 var HANDOFF_RANK = {
   open: 0,
@@ -3987,7 +4411,7 @@ function mergeChangeRecords(base, ours, theirs) {
 }
 function readRecord(text) {
   try {
-    const r = ChangeLifecycle.safeParse((0, import_yaml11.parse)(text));
+    const r = ChangeLifecycle.safeParse((0, import_yaml12.parse)(text));
     return r.success ? r.data : void 0;
   } catch {
     return void 0;
@@ -4038,6 +4462,29 @@ async function setChangeOwners(root, id, owners) {
   return r.data;
 }
 
+// packages/changes/dist/edit-hash.js
+import { createHash as createHash2 } from "node:crypto";
+function editText(file, text) {
+  const lf = text.replace(/\r\n?/g, "\n");
+  return isTasks(file) ? lf.replace(/^(\s*[-*]\s+\[)[ xX]?(\])/gm, "$1 $2") : lf;
+}
+function editSha(file, text) {
+  const h = createHash2("sha256");
+  if (typeof text !== "string" && !text.includes(13) && !isTasks(file))
+    return h.update(text).digest("hex");
+  const t = typeof text === "string" ? text : text.toString("utf8");
+  return h.update(editText(file, t), "utf8").digest("hex");
+}
+function wroteThis(file, text, hash) {
+  if (hash === void 0)
+    return false;
+  if (editSha(file, text) === hash)
+    return true;
+  const t = typeof text === "string" ? text : text.toString("utf8");
+  return createHash2("sha256").update(t.replace(/\r\n?/g, "\n"), "utf8").digest("hex") === hash;
+}
+var isTasks = (file) => file.split(/[\\/]/).at(-1) === "tasks.md";
+
 export {
   ChangeError,
   readTables,
@@ -4104,8 +4551,15 @@ export {
   workProgress,
   privacyImpact,
   prApprovers,
+  TASK_DECISION_FILE,
+  readTaskDecision,
+  unmergedTaskBranches,
+  unmergedTaskWords,
+  taskBranchReasons,
+  recordTaskDecision,
   RELEASE_PR_STATES,
   RELEASE_PRS_FILE,
+  staleReleasePrs,
   nothingToRelease,
   raiseReleasePrs,
   syncReleasePrs,
@@ -4121,6 +4575,8 @@ export {
   slugify,
   newChange,
   gitHandoffPublisher,
+  handoffBranchPushed,
+  pushHandoffBranch,
   CAPTURE_SCHEMA_VERSION,
   DraftCapture,
   capturePaths,
@@ -4160,5 +4616,8 @@ export {
   mergeChangeText,
   OWNER_ROLE_KEYS,
   ChangeOwnersError,
-  setChangeOwners
+  setChangeOwners,
+  editText,
+  editSha,
+  wroteThis
 };