@staix/agent-hub 0.12.35 → 0.12.36

package/src/hub/hub-tools.ts

@@ -17,6 +17,10 @@ const refs = {
   additionalProperties: false,
 } as const;
 const list = (description: string) => ({ type: "array", items: str, description }) as const;
+const costPlanProperties = {
+  review: { type: "object", properties: { scope: { type: "string", enum: ["none", "delta", "full"] }, reviewers: { type: "integer", minimum: 0, maximum: 8 } }, required: ["scope", "reviewers"], additionalProperties: false },
+  ci: { type: "string", enum: ["focused", "full", "reuse"] },
+} as const;
 const plan = {
   type: "object",
   description: "what you will change, before you start. Owners of open tasks on the same files or symbols see it, and get a notice when your task is done.",
@@ -66,7 +70,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
-  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
+  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
   tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
@@ -75,6 +79,13 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
 ];
 
+export const PLANNER_REVIEW_TOOLS: HubTool[] = [
+  tool("hub_planner_groom", "Read a bounded planner grooming digest of dependencies, repository-scoped overlaps, WIP and blockers. No board change; unavailable evidence stays unknown.", {}),
+  tool("hub_plan_review", "Record a planner review against the task planning revision and host-read issue edit time. Configured planner or person only; never accepts caller issue timestamps.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 }, ...costPlanProperties }, ["id", "revision", "reason"]),
+  tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes. S7 owns automatic band proposals.", { repo: str }),
+  tool("hub_backlog_return_untouched", "Return accepted but untouched work to the backlog with its history and planning retained. Refuses execution/branch/commit evidence; planner or person only.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 } }, ["id", "revision", "reason"]),
+];
+TASK_TOOLS.push(...PLANNER_REVIEW_TOOLS);
 export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 
 /** Separately published: serving a schema grants no authority, only the daemon's explicit role does. */
@@ -134,6 +145,14 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       const selectedPlan = { ...plan, properties: Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
     }
+    if (criteria && properties.plan) {
+      const current = properties.plan as { properties: Record<string, unknown> };
+      properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties } };
+    }
+    if (criteria && tool.name === "hub_backlog_split") {
+      const parts = properties.parts as { items: { properties: { plan: { properties: Record<string, unknown> } } } };
+      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties } } } } };
+    }
     return { ...tool, ...(customProfile && tool.name === "hub_task_propose" ? { description: tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.` } : {}), inputSchema: { ...tool.inputSchema, properties } };
   });
 }

package/src/hub/instances.ts

@@ -54,7 +54,20 @@ export function validateInstances(raw: unknown): InstancesConfig {
     const definition = definitionOf(kind), prefix = `${kind}-`;
     if (!definition) return fail(`${path}.kind`, "unknown native kind");
     if (!id.startsWith(prefix) || !/^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length))) return fail(path, "id must be <kind>-<name>");
-    if (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp)) return fail(`${path}.kind`, "unsupported in I2; a headless factory with env or ACP-session identity is required, not channel-only or project-file identity");
+    // #450 I3: a channel-plugin kind (Claude) runs only in the person's terminal, so it reviews or plans and never owns writes.
+    const channel = definition.identity.mcp === "channel-plugin";
+    if (!channel && (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp))) return fail(`${path}.kind`, "unsupported; a headless factory with env or ACP-session identity, or a channel-plugin kind, is required, not project-file identity");
+    if (channel) {
+      const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
+      // #223: a headless one is the kind's reviewer variant, one fresh hub-run session per review request.
+      if (entry.start_mode && definition.reviewerVariant) {
+        if (entry.worktree) return fail(path, "a headless reviewer reads the project checkout: worktree is not supported");
+        if (declared.length !== 1 || declared[0] !== "reviewer") return fail(`${path}.roles`, "a headless channel-kind instance is a reviewer: roles must be exactly [\"reviewer\"]");
+      } else {
+        if (entry.start_mode || entry.worktree) return fail(path, "a channel instance starts only from the person's terminal (ahub <kind> --as <id>): start_mode and worktree are not supported; a headless reviewer declares roles [\"reviewer\"] and start_mode \"headless\"");
+        if (!declared.length || declared.some(role => role !== "reviewer" && role !== "planner")) return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
+      }
+    }
     const value: InstanceConfig = { kind };
     if (entry.roles) { value.roles = roles(entry.roles.value, `${path}.roles`); Object.freeze(value.roles); }
     if (entry.start_mode) {
@@ -80,13 +93,14 @@ export function instanceCatalog(declarations?: InstancesConfig): readonly Instan
   const instances = validateInstances(declarations);
   return Object.freeze([
     ...ADAPTERS.map(definition => Object.freeze({ id: definition.kind, kind: definition.kind, definition })),
-    ...Object.entries(instances).map(([id, config]) => Object.freeze({ id, kind: config.kind, definition: definitionOf(config.kind)!, config })),
+    ...Object.entries(instances).map(([id, config]) => Object.freeze({ id, kind: config.kind, definition: definitionOf(id, instances)!, config })),
   ]);
 }
 export function instancePeerIds(declarations?: InstancesConfig): string[] { return instanceCatalog(declarations).map(entry => entry.id); }
 export function instanceDefaultRoles(declarations?: InstancesConfig, includeOptional = true): Record<string, string[]> {
   const result = defaultPeerRoles(includeOptional);
-  for (const [id, config] of Object.entries(validateInstances(declarations))) result[id] = [...(config.roles ?? definitionOf(config.kind)!.roles)];
+  const instances = validateInstances(declarations);
+  for (const [id, config] of Object.entries(instances)) result[id] = [...(config.roles ?? definitionOf(id, instances)!.roles)];
   return result;
 }
 

package/src/hub/review-brief.ts

@@ -0,0 +1,175 @@
+import { childEnv } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
+
+/**
+ * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same
+ * one: the changed files of the head against its merge base with the checkout's HEAD, the files left out and why, the
+ * review rules that apply to each file, and the files the plain name list shows that the brief does not. Only git is
+ * read, bounded; nothing here touches the board.
+ */
+export interface BriefFile { path: string; status: string; oldPath?: string; insertions?: number; deletions?: number }
+export interface BriefExcluded { path: string; status: string; oldPath?: string; reason: string }
+export interface ReviewBrief {
+  head: string;
+  /** The default branch the head is compared with: origin/HEAD, origin/main or origin/master. */
+  base: string;
+  mergeBase: string;
+  reviewable: BriefFile[];
+  excluded: BriefExcluded[];
+  /** Changes left out by the privacy policy, both sides of a move included; counted, never named. */
+  withheld: number;
+  /** Rule files by name (REVIEW.md, then `ahub-review-rules` attribute values) with their text at the merge base. */
+  rules: { source: string; text: string }[];
+  /** Configured rule files the brief could not load, with why: the reviewer reads them in the repository. */
+  rulesMissing: { source: string; reason: string }[];
+  /** Reviewable paths grouped by the rule sources that apply to them. */
+  ruleGroups: { sources: string[]; paths: string[] }[];
+  /** Paths in the plain name list of the range that the brief does not list: read them directly. */
+  unlisted: string[];
+}
+export interface BriefPolicy { privatePath(path: string): boolean; nameable(text: string): boolean }
+
+const MAX_FILES = 500, RULE_BYTES = 32_000, MAX_RULE_FILES = 8;
+const LOCKFILES = new Set(["bun.lock", "bun.lockb", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "Cargo.lock", "poetry.lock", "uv.lock", "go.sum", "composer.lock", "Gemfile.lock"]);
+const HEX = /^[0-9a-f]{7,40}$/i;
+
+/** Every diff of the brief reads attributes from the trusted tree, never the checkout (a head's `* -diff` cannot mark its own files binary). */
+const attrFrom = (source?: string) => source ? [`--attr-source=${source}`] : [];
+const git = (cwd: string, args: string[]) => hubGitSync(["-C", cwd, ...args], { encoding: "utf8", env: childEnv(process.env), maxBuffer: 16 * 1024 * 1024, timeout: 15_000 });
+
+/**
+ * The changes of `HEAD...head` as groups: one path, or both sides of a rename or copy. A caller that must not show a
+ * private file withholds a whole group when any side is private, so content never shows up under a public name.
+ * ponytail: git's 50% similarity decides what counts as a move.
+ */
+export function changedPathGroups(cwd: string, head: string, base = "HEAD", attrSource?: string): { status: string; paths: string[] }[] | undefined {
+  const r = git(cwd, [...attrFrom(attrSource), "diff", "--no-ext-diff", "--no-textconv", "--relative", "-M", "-C", "--find-copies-harder", "--name-status", "-z", `${base}...${head}`, "--"]);
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  const fields = r.stdout.split("\0"), groups: { status: string; paths: string[] }[] = [];
+  for (let i = 0; i < fields.length - 1;) {
+    const status = fields[i++]!, sides = /^[RC]/.test(status) ? 2 : 1;
+    groups.push({ status, paths: fields.slice(i, i + sides) }); i += sides;
+  }
+  return groups;
+}
+
+export function buildReviewBrief(cwd: string, head: unknown, policy: BriefPolicy): ReviewBrief | { unavailable: string } {
+  if (typeof head !== "string" || !HEX.test(head)) return { unavailable: "the task names no commit" };
+  const full = git(cwd, ["rev-parse", "--verify", "-q", `${head}^{commit}`]);
+  if (full.status !== 0 || typeof full.stdout !== "string") return { unavailable: `commit ${head} is not in this checkout` };
+  const commit = full.stdout.trim();
+  // A reliable base only: the remote's default branch. The checkout's HEAD may be the head itself (an empty inventory)
+  // or another session's branch.
+  const from = ["origin/HEAD", "origin/main", "origin/master"].find(ref => git(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).status === 0);
+  if (!from) return { unavailable: "no default branch (origin/HEAD, origin/main or origin/master) to compare with" };
+  const base = git(cwd, ["merge-base", from, commit]);
+  if (base.status !== 0 || typeof base.stdout !== "string") return { unavailable: `commit ${head} shares no history with ${from}` };
+  const mergeBase = base.stdout.trim();
+  const groups = changedPathGroups(cwd, commit, from, mergeBase);
+  if (!groups) return { unavailable: `the changes of ${head} could not be read` };
+  if (!groups.length) return { unavailable: `commit ${head} has no changes against ${from}` };
+  const shown = groups.filter(g => !g.paths.some(path => policy.privatePath(path) || !policy.nameable(path)));
+  if (shown.length > MAX_FILES) return { unavailable: `${shown.length} changed files, over the brief's ${MAX_FILES}` };
+  const withheld = groups.length - shown.length;
+  const counts = numstat(cwd, commit, from, mergeBase);
+  // Attributes and rules come from the merge base: a change cannot lift its own review obligations (a head that marks
+  // everything generated, or edits REVIEW.md, is still reviewed under the rules it is merging into).
+  // Both sides of a move: renaming a reviewed file to a generated or unscoped name must not shed its obligations.
+  const attrs = attributes(cwd, mergeBase, [...new Set(shown.flatMap(g => g.paths))]);
+  if (!counts || !attrs) return { unavailable: `the file details of ${head} could not be read` };
+  const reviewable: BriefFile[] = [], excluded: BriefExcluded[] = [];
+  for (const g of shown) {
+    const path = g.paths.at(-1)!, count = counts.get(path);
+    const sides = { status: g.status[0]!, ...(g.paths.length === 2 ? { oldPath: g.paths[0]! } : {}) };
+    // Excluded only when every side is: a move keeps the source's obligation.
+    const sideReason = (p: string) => attrs.get(p)?.generated ? "generated (linguist-generated)" : LOCKFILES.has(p.split("/").at(-1)!) ? "lockfile" : undefined;
+    const reasons = g.paths.map(sideReason);
+    const reason = count?.binary ? "binary" : reasons.every(Boolean) ? reasons.at(-1) : undefined;
+    if (reason) { excluded.push({ path, ...sides, reason }); continue; }
+    reviewable.push({ path, ...sides, ...(count && !count.binary ? { insertions: count.insertions, deletions: count.deletions } : {}) });
+  }
+  const ruleText = new Map<string, string>(), rulesMissing = new Map<string, string>();
+  const readRule = (source: string): boolean => {
+    if (ruleText.has(source)) return true;
+    if (rulesMissing.has(source)) return false;
+    // A private or non-nameable rule path is not named either: it is left out silently.
+    if (policy.privatePath(source) || !policy.nameable(source)) return false;
+    if (ruleText.size >= MAX_RULE_FILES) { rulesMissing.set(source, `over the brief's ${MAX_RULE_FILES} rule files`); return false; }
+    const r = git(cwd, ["show", `${mergeBase}:${source}`]);
+    if (r.status !== 0 || typeof r.stdout !== "string") { rulesMissing.set(source, "not found at the merge base"); return false; }
+    // Screened whole, before any cut: a rule file that matches a private-data pattern is named but not shown.
+    if (!policy.nameable(r.stdout)) { ruleText.set(source, "(withheld: it matches a private-data pattern; read it in the repository)"); return true; }
+    const bytes = Buffer.from(r.stdout, "utf8");
+    ruleText.set(source, bytes.length > RULE_BYTES ? `${bytes.subarray(0, RULE_BYTES).toString("utf8")}\n[cut at ${RULE_BYTES} bytes]` : r.stdout);
+    return true;
+  };
+  const root = readRule("REVIEW.md");
+  const byKey = new Map<string, { sources: string[]; paths: string[] }>();
+  for (const file of reviewable) {
+    // The rules of every side apply, so a move out of a scoped directory keeps its rule file.
+    const scoped = [...new Set([file.oldPath, file.path].flatMap(p => { const r = p ? attrs.get(p)?.rules : undefined; return r ? [r] : []; }))];
+    const sources = [...(root ? ["REVIEW.md"] : []), ...scoped.filter(readRule)];
+    const key = sources.join("\0");
+    (byKey.get(key) ?? byKey.set(key, { sources, paths: [] }).get(key)!).paths.push(file.path);
+  }
+  // Cross-check with the plain name list (no rename detection), as OCR's list is checked against the PR's.
+  const plain = git(cwd, [...attrFrom(mergeBase), "diff", "--relative", "--no-renames", "--name-only", "-z", `${from}...${commit}`, "--"]);
+  if (plain.status !== 0 || typeof plain.stdout !== "string") return { unavailable: `the name list of ${head} could not be read` };
+  const listed = new Set(shown.flatMap(g => g.paths)), hidden = new Set(groups.filter(g => !shown.includes(g)).flatMap(g => g.paths));
+  const unlisted = plain.stdout.split("\0").filter(path => path && !listed.has(path) && !hidden.has(path));
+  return { head: commit, base: from, mergeBase, reviewable, excluded, withheld, rules: [...ruleText].map(([source, text]) => ({ source, text })), rulesMissing: [...rulesMissing].map(([source, reason]) => ({ source, reason })), ruleGroups: [...byKey.values()], unlisted };
+}
+
+function numstat(cwd: string, head: string, base: string, attrSource: string): Map<string, { insertions: number; deletions: number; binary: boolean }> | undefined {
+  const out = new Map<string, { insertions: number; deletions: number; binary: boolean }>();
+  const r = git(cwd, [...attrFrom(attrSource), "diff", "--no-ext-diff", "--no-textconv", "--relative", "-M", "-C", "--find-copies-harder", "--numstat", "-z", `${base}...${head}`, "--"]);
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  // -z: "ins\tdel\tpath\0", or for a move "ins\tdel\t\0old\0new\0"; a binary file has "-" counts.
+  const fields = r.stdout.split("\0");
+  for (let i = 0; i < fields.length - 1;) {
+    const [ins = "", del = "", path = ""] = fields[i++]!.split("\t");
+    const target = path || (i++, fields[i++] ?? "");
+    out.set(target, { insertions: Number(ins) || 0, deletions: Number(del) || 0, binary: ins === "-" });
+  }
+  return out;
+}
+
+function attributes(cwd: string, source: string, paths: string[]): Map<string, { generated?: boolean; rules?: string }> | undefined {
+  const out = new Map<string, { generated?: boolean; rules?: string }>();
+  if (!paths.length) return out;
+  const r = hubGitSync(["-C", cwd, "check-attr", "-z", "--stdin", `--source=${source}`, "linguist-generated", "ahub-review-rules"], { input: paths.join("\0") + "\0", encoding: "utf8", env: childEnv(process.env), maxBuffer: 4 * 1024 * 1024, timeout: 15_000 });
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  const f = r.stdout.split("\0");
+  for (let i = 0; i + 2 < f.length; i += 3) {
+    const [path, attr, value] = [f[i]!, f[i + 1]!, f[i + 2]!], entry = out.get(path) ?? {};
+    if (attr === "linguist-generated" && (value === "set" || value === "true")) entry.generated = true;
+    if (attr === "ahub-review-rules" && value !== "unspecified" && value !== "unset" && value !== "set" && !value.startsWith("/") && !value.split("/").includes("..")) entry.rules = value;
+    out.set(path, entry);
+  }
+  return out;
+}
+
+/** The brief as review text: what every reviewer reads and how it accounts for its coverage. */
+export function renderReviewBrief(brief: ReviewBrief): string {
+  const file = (f: BriefFile) => `- ${f.oldPath ? `${f.oldPath} -> ` : ""}${f.path} (${f.status}${f.insertions !== undefined ? `, +${f.insertions} -${f.deletions}` : ""})`;
+  return [
+    `Review brief: head ${brief.head} against ${brief.base} (merge base ${brief.mergeBase.slice(0, 12)}); ${brief.reviewable.length} reviewable, ${brief.excluded.length} excluded${brief.withheld ? `, ${brief.withheld} withheld by the privacy policy` : ""}.`,
+    ...(brief.reviewable.length ? ["Reviewable:", ...brief.reviewable.map(file)] : ["Reviewable: none (record why in the note)."]),
+    ...(brief.excluded.length ? ["Excluded (still read their diff when it matters):", ...brief.excluded.map(e => `- ${e.oldPath ? `${e.oldPath} -> ` : ""}${e.path} (${e.status}): ${e.reason}`)] : []),
+    ...(brief.unlisted.length ? ["Not in the brief's list, read directly:", ...brief.unlisted.map(path => `- ${path}`)] : []),
+    ...brief.ruleGroups.filter(g => g.sources.length).map(g => `Rules ${g.sources.join(" + ")} apply to: ${brief.ruleGroups.length === 1 ? "every reviewable file" : g.paths.join(", ")}`),
+    ...(brief.rulesMissing.length ? ["Configured rules not loaded (read them in the repository):", ...brief.rulesMissing.map(m => `- ${m.source}: ${m.reason}`)] : []),
+    ...brief.rules.map(r => `--- ${r.source} ---\n${r.text.trimEnd()}`),
+    `Coverage: pass hub_review coverage {reviewed: [paths], skipped: [{path, reason}]} naming every reviewable path above.`,
+  ].join("\n");
+}
+
+/** The reviewable paths a verdict's coverage does not account for: reviewed, or skipped with a reason. */
+export function coverageGap(brief: ReviewBrief, coverage: unknown): string[] {
+  const c = coverage && typeof coverage === "object" && !Array.isArray(coverage) ? coverage as { reviewed?: unknown; skipped?: unknown } : {};
+  const accounted = new Set<string>([
+    ...(Array.isArray(c.reviewed) ? c.reviewed.filter((p): p is string => typeof p === "string") : []),
+    ...(Array.isArray(c.skipped) ? c.skipped.flatMap(s => s && typeof s === "object" && typeof (s as { path?: unknown }).path === "string" && typeof (s as { reason?: unknown }).reason === "string" && (s as { reason: string }).reason.trim() ? [(s as { path: string }).path] : []) : []),
+  ]);
+  return brief.reviewable.map(f => f.path).filter(path => !accounted.has(path));
+}

package/src/hub/routing.ts

@@ -290,6 +290,8 @@ export interface RoutingRefusal { peer: PeerId; role: "owner" | "reviewer"; code
 export interface Assignment {
   /** A same-family reviewer was chosen only because no other family was eligible. */
   sameFamilyFallback?: true;
+  /** #223 R5: the planner reviews because the declared reviewer-only instance was not eligible. */
+  plannerFallback?: true;
   refusals?: RoutingRefusal[];
   owner?: PeerId;
   reviewer?: PeerId;
@@ -374,6 +376,7 @@ export function assign(
     if (opts.exclude?.includes(peer)) return deny("excluded", "excluded (declined or replaced)");
     if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
     const adapter = definitionOf(peer, opts.instances);
+    if (role === "owner" && adapter?.routing?.reviewOnly) return deny("owner-admission", "owner admission: a review-only instance owns no task");
     if (role === "owner" && needsTests && adapter && adapter.kind !== peer) {
       if (!peerEntry(opts.roles, peer)?.includes("implementer")) return deny("owner-admission", "owner admission: declared write owner requires the current implementer role");
       if (peerEntry(opts.ownerIsolation, peer) !== true) return deny("owner-admission", "owner admission: declared write owner requires a verified isolated execution root");
@@ -458,6 +461,7 @@ export function assign(
 
   let reviewer: PeerId | undefined;
   let sameFamilyFallback = false;
+  let plannerFallback = false;
   if (task.class !== "review") {
     if (pii) trace.push("reviewer: user (pii: no second on-prem peer; ahub review <id> <verdict>)");
     else {
@@ -475,7 +479,18 @@ export function assign(
         const reason = `same family as ${reviewOwner}; eligible other-family reviewer available`;
         refusals.set(`reviewer:${named}`, { peer: named, role: "reviewer", code: "family", reason });
         trace.push(`  reviewer candidate ${named}: skipped, ${reason}`);
-      } else reviewer = pick(named === undefined ? independent.length ? independent : automatic : [named], "reviewer", reviewOwner, named === undefined);
+      } else {
+        // #223 R1: a declared instance that reviews and does not plan goes first, busy or not.
+        const holds = (peer: PeerId, role: string) => opts.roles?.[peer]?.includes(role) === true;
+        const dedicated = (peer: PeerId) => !!opts.instances && Object.hasOwn(opts.instances, peer) && holds(peer, "reviewer") && !holds(peer, "planner");
+        const pool = independent.length ? independent : automatic;
+        const ready = named === undefined ? pool.filter(peer => dedicated(peer) && peer !== reviewOwner && !blocked(peer, "reviewer")) : [];
+        reviewer = pick(named === undefined ? ready.length ? ready : pool : [named], "reviewer", reviewOwner, named === undefined);
+        if (named === undefined && !ready.length && reviewer && holds(reviewer, "planner") && Object.keys(opts.roles ?? {}).some(dedicated)) {
+          plannerFallback = true;
+          trace.push(`  planner fallback: no declared reviewer-only instance is eligible; ${reviewer} reviews`);
+        }
+      }
       if (reviewer && sameFamily(reviewer)) {
         sameFamilyFallback = true;
         trace.push(`  same-family fallback: ${reviewer} and ${reviewOwner} share ${ownerFamily}; no eligible other family`);
@@ -490,7 +505,7 @@ export function assign(
   const piBackend = policy?.pi_backend;
   if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
   if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "backend") trace.push(`${definitionOf(owner, opts.instances)!.routing!.backendLabel} decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
-  return { ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
+  return { ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(plannerFallback ? { plannerFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }
 
 /**

package/src/hub/sdlc.ts

@@ -1,3 +1,4 @@
+import type { CostPlan } from "./cost-governance.ts";
 import { criteriaReceipt, type CriteriaReceipt, type CriteriaView, type LegacyPhaseReceipt } from "./workflow.ts";
 import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
@@ -29,11 +30,21 @@ export interface StageDefinition { base: SdlcBaseStage; actor: string; entry_gat
 export type SdlcMode = "off" | "advise" | "enforce";
 /** `workflow: "gsd-lite"` marks the retired setting during its window (#481 S8): every task then needs a criteria checklist. */
 export interface SdlcConfig { workflow?: "gsd-lite"; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+export interface PlanReviewReceipt {
+  planner: string;
+  planningRevision: number;
+  recordedAt: number;
+  scope?: CostPlan;
+  issue?: PlanIssueMetadata;
+}
 export interface SdlcReceipt {
   stage: SdlcStage;
+  planReview?: PlanReviewReceipt;
   criteria?: CriteriaReceipt;
   /** Stored before #481 S8 and read as `criteria`; never written again. */
   phase?: LegacyPhaseReceipt;
+  /** The person's spec acceptance (#481 S1): set only by Tasks.acceptSpec, never by hub_sdlc_record. */
+  acceptance?: SpecAcceptance;
   repo?: string;
   issue?: number;
   pr?: number;
@@ -181,6 +192,8 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
     if (!["passed", "failed", "unknown"].includes(String(raw.localResult))) throw new Error("sdlc receipt.localResult: expected passed, failed or unknown");
     next.localResult = raw.localResult as SdlcReceipt["localResult"];
   }
+  // An acceptance names one spec issue; relinking the receipt to another drops it (#481 S1).
+  if (next.repo !== previous.repo || next.issue !== previous.issue) delete next.acceptance;
   // A new artifact cannot inherit another PR's review or local gate.
   if (next.repo !== previous.repo || next.pr !== previous.pr) {
     delete next.head; delete next.observed;
@@ -199,7 +212,7 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     const name = c.name ?? c.context;
     if (typeof name !== "string" || !name || name.length > 120) throw new Error("PR readback: invalid check identity");
     const native = c.conclusion ?? c.state;
-    const state = native === "SUCCESS" ? "passed" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(String(native)) ? "failed" : ["PENDING", "QUEUED", "IN_PROGRESS"].includes(String(c.status ?? native)) ? "pending" : "unknown";
+    const state = ["PENDING", "QUEUED", "IN_PROGRESS"].includes(String(c.status ?? native)) ? "pending" : native === "SUCCESS" ? "passed" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(String(native)) ? "failed" : "unknown";
     return { name, state } as PrEvidence["checks"][number];
   });
   const paths = p.files.map((f: Record<string, unknown>) => { if (typeof f.path !== "string" || !f.path || f.path.length > 1000) throw new Error("PR readback: invalid file identity"); return f.path; });
@@ -210,10 +223,26 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     ...(sha(p.mergeCommit?.oid) ? { mergeCommit: p.mergeCommit.oid } : {}) };
 }
 
-export interface SdlcStatus { playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
+/** Issue identity and edit times only; no body is fetched or stored. `lastEditedAt` moves on a body edit, not on comments. */
+export interface SpecEdit { lastEditedAt: string | null; updatedAt: string }
+export interface SpecAcceptance extends SpecEdit { repo: string; issue: number; acceptedAt: number }
+export type SpecState = "missing" | "current" | "changed" | "unknown";
+/** Whether the receipt's spec issue is accepted at its current body. `edit` undefined means the readback failed. */
+export function specState(receipt: SdlcReceipt | undefined, edit: SpecEdit | undefined): SpecState {
+  const accepted = receipt?.acceptance;
+  if (!accepted || accepted.repo !== receipt?.repo || accepted.issue !== receipt?.issue) return "missing";
+  if (!edit) return "unknown";
+  return edit.lastEditedAt === accepted.lastEditedAt ? "current" : "changed";
+}
+export const SPEC_STATE_TEXT: Record<Exclude<SpecState, "current">, string> = {
+  missing: "spec acceptance missing: the person runs ahub sdlc accept <task> --issue <n>",
+  changed: "spec changed after acceptance: the person re-accepts with ahub sdlc accept <task> --issue <n>",
+  unknown: "spec edit time unknown: the issue could not be read",
+};
+export interface SdlcStatus { spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
 /** The acceptance-criteria checklist (#481 S8, Compliance pass) counts once recorded, and on every task under the retired gsd-lite setting. Off keeps #257's output. */
 export const criteriaRequired = (config: SdlcConfig, receipt: SdlcReceipt | undefined): boolean => config.workflow === "gsd-lite" || (config.mode !== "off" && !!checklistOf(receipt));
-export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView): SdlcStatus {
+export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit): SdlcStatus {
   const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
   const definition = stageDefinition(config, stage);
   if (!definition) blockers.push("lifecycle stage definition unknown");
@@ -239,7 +268,9 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
   const custom = config.definitions && definition ? stageGates(definition, blockers, [...viewBlockers, ...staleHead]) : undefined;
   if (custom) for (const blocker of [...custom.entry, ...custom.exit]) if (!blockers.includes(blocker)) blockers.push(blocker);
   const shown = criteria && (criteriaRequired(config, receipt) || definition && [...definition.entry_gates, ...definition.exit_gates].includes("criteria"));
-  return { ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
+  // Shown, not counted as a readiness blocker: the spec gate is build entry (#481 S1).
+  const spec = config.mode !== "off" && receipt?.issue ? { spec: { issue: receipt.issue, state: specState(receipt, specEdit) } } : {};
+  return { ...spec, ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
     actor: !definition ? "person" : shown && criteria.blockers.length ? "reviewer/person" : config.definitions ? definition.actor : baseActor(definition.base),
     next: blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
 }
@@ -279,6 +310,20 @@ export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 2
   child.once("close", code => { clearTimeout(timer); resolve({ code: failed ? 1 : code ?? 1, stdout: failed ? "" : stdout }); });
 });
 
+/** Read-only, fixed argv: the issue's edit times, never its body. */
+export async function readSpecEdit(repoName: string, issue: number, run: SdlcGh = sdlcGh): Promise<SpecEdit | undefined> {
+  if (!repo(repoName) || !id(issue)) return undefined;
+  const [owner, name] = repoName.split("/");
+  try {
+    const out = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){number lastEditedAt updatedAt}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${issue}`]);
+    if (out.code !== 0) return undefined;
+    const found = JSON.parse(out.stdout)?.data?.repository?.issue;
+    const stamp = (v: unknown) => typeof v === "string" && v.length <= 40 && !Number.isNaN(Date.parse(v));
+    if (found?.number !== issue || !stamp(found.updatedAt) || (found.lastEditedAt !== null && !stamp(found.lastEditedAt))) return undefined;
+    return { lastEditedAt: found.lastEditedAt, updatedAt: found.updatedAt };
+  } catch { return undefined; }
+}
+
 export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Promise<PrEvidence | undefined> {
   if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
   try {
@@ -298,3 +343,159 @@ export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Pr
     return parsePrEvidence(p);
   } catch { return undefined; }
 }
+
+export interface PlanIssueMetadata {
+  repo: string;
+  issue: number;
+  state: "OPEN" | "CLOSED";
+  /** Body edit time; comment activity must never invalidate a plan review. */
+  editedAt: string;
+  /** Nullable GitHub body edit field, retained to compare independent S1 acceptance evidence. */
+  lastEditedAt?: string | null;
+}
+
+/** Metadata only: never request issue bodies or comments for a planning receipt. */
+export async function readPlanIssueMetadata(repository: string, number: number, run: SdlcGh = sdlcGh): Promise<PlanIssueMetadata | undefined> {
+  if (!repo(repository) || !id(number)) return undefined;
+  const [owner, name] = repository.split("/");
+  try {
+    const result = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){number state createdAt lastEditedAt}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${number}`], 10_000, undefined, 8 * 1024);
+    if (result.code !== 0 || Buffer.byteLength(result.stdout) > 8 * 1024) return undefined;
+    const response = JSON.parse(result.stdout);
+    if (response.errors !== undefined) return undefined;
+    const issue = response.data?.repository?.issue;
+    if (!issue || issue.number !== number || !["OPEN", "CLOSED"].includes(issue.state)) return undefined;
+    const editedAt = issue.lastEditedAt === null ? issue.createdAt : issue.lastEditedAt;
+    if (typeof editedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(editedAt) || !Number.isFinite(Date.parse(editedAt))) return undefined;
+    return { repo: repository, issue: number, state: issue.state, editedAt, lastEditedAt: issue.lastEditedAt };
+  } catch { return undefined; }
+}
+
+/** A complete resolved-thread snapshot already proves there is no pending unanswered bot thread. */
+export function reviewReadinessFromEvidence(evidence: PrEvidence | undefined, expected: string | undefined, required: readonly string[]): ReviewReadiness | undefined {
+  if (!evidence || evidence.unresolved !== 0) return undefined;
+  const checks = required.length ? [...required] : ["check (ubuntu-latest)", "check (macos-latest)", "seeded guards"];
+  if (!checks.every(name => evidence.checks.some(check => check.name === name)) || evidence.checks.some(check => check.state === "unknown")) return undefined;
+  const blockers: string[] = [];
+  if (!expected || !sha(expected)) blockers.push("review head missing");
+  else if (evidence.head !== expected) blockers.push("review head changed");
+  if (evidence.state !== "OPEN") blockers.push("review PR is not open");
+  if (!checks.every(name => { const matched = evidence.checks.filter(check => check.name === name); return matched.length === 1 && matched[0]?.state === "passed"; })) blockers.push("exact-head full CI is not green");
+  return { head: evidence.head, ready: blockers.length === 0, blockers };
+}
+
+export interface ReviewReadiness { head?: string; ready: boolean; blockers: string[]; reusedRun?: number }
+/** Metadata-only pre-review admission; no remote body or comment text is requested. */
+export async function readReviewReadiness(receipt: SdlcReceipt, expected: string | undefined, run: SdlcGh = sdlcGh, requiredChecks: readonly string[] = []): Promise<ReviewReadiness> {
+  const unknown = (): ReviewReadiness => ({ ready: false, blockers: ["review readiness unavailable"] });
+  if (!repo(receipt.repo) || !id(receipt.pr)) return unknown();
+  const [owner, name] = receipt.repo.split("/");
+  const query = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid state commits(last:1){nodes{commit{oid tree{oid} statusCheckRollup{contexts(first:100){nodes{... on CheckRun{name status conclusion} ... on StatusContext{context state}} pageInfo{hasNextPage}}}}}} reviewThreads(first:100){nodes{isResolved comments(first:100){nodes{author{__typename} createdAt} pageInfo{hasNextPage}}} pageInfo{hasNextPage}}}}}";
+  try {
+    const deadline = performance.now() + 20_000;
+    const bounded: SdlcGh = (args, timeout, cwd, cap) => performance.now() < deadline
+      ? run(args, Math.max(1, Math.min(timeout ?? 10_000, deadline - performance.now())), cwd, cap)
+      : Promise.resolve({ code: 1, stdout: "" });
+    const args = ["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${receipt.pr}`];
+    const response = await bounded(args, 10_000, undefined, 512 * 1024);
+    if (response.code !== 0 || Buffer.byteLength(response.stdout) > 512 * 1024) return unknown();
+    const parsed = JSON.parse(response.stdout), pr = parsed.data?.repository?.pullRequest;
+    if (parsed.errors || !pr || !sha(pr.headRefOid)) return unknown();
+    const blockers: string[] = [];
+    if (!expected || !sha(expected)) blockers.push("review head missing");
+    else if (pr.headRefOid !== expected) blockers.push("review head changed");
+    if (pr.state !== "OPEN") blockers.push("review PR is not open");
+    const commit = pr.commits?.nodes?.[0]?.commit;
+    if (!commit || commit.oid !== pr.headRefOid) blockers.push("review head changed");
+    const contexts = commit?.statusCheckRollup?.contexts;
+    const nodes: unknown[] | undefined = contexts?.nodes;
+    const full = requiredChecks.length ? [...requiredChecks] : ["check (ubuntu-latest)", "check (macos-latest)", "seeded guards"];
+    let reusedRun: number | undefined;
+    if (contexts?.pageInfo?.hasNextPage !== false || !Array.isArray(nodes) || nodes.length > 100
+      || !full.every(name => {
+        const matches = (nodes as { name?: string; context?: string; status?: string; conclusion?: string; state?: string }[]).filter(node => (node?.name ?? node?.context) === name);
+        return matches.length === 1 && (matches[0]?.name ? matches[0].status === "COMPLETED" && matches[0].conclusion === "SUCCESS" : matches[0]?.state === "SUCCESS");
+      })) blockers.push("exact-head full CI is not green");
+    if (blockers.includes("exact-head full CI is not green") && contexts?.pageInfo?.hasNextPage === false && Array.isArray(nodes)
+      && full.every(name => { const matches = (nodes as { name?: string; conclusion?: string }[]).filter(node => node?.name === name); return matches.length === 1 && matches[0]?.conclusion === "SKIPPED"; }) && sha(commit?.tree?.oid)) {
+      reusedRun = await identicalTreeGate(receipt.repo, commit.tree.oid, bounded, full);
+      if (reusedRun !== undefined) {
+        // Proof reads can await several API calls: recheck the complete head/check/thread snapshot before admission.
+        const after = await bounded(args, 10_000, undefined, 512 * 1024);
+        try { if (after.code !== 0 || JSON.stringify(JSON.parse(after.stdout)?.data?.repository?.pullRequest) !== JSON.stringify(pr)) reusedRun = undefined; }
+        catch { reusedRun = undefined; }
+        if (reusedRun !== undefined) blockers.splice(blockers.indexOf("exact-head full CI is not green"), 1);
+      }
+    }
+    const threads = pr.reviewThreads;
+    if (threads?.pageInfo?.hasNextPage !== false || !Array.isArray(threads.nodes) || threads.nodes.length > 100) blockers.push("bot review thread evidence unavailable");
+    else for (const thread of threads.nodes) {
+      if (thread?.isResolved === true) continue;
+      if (thread?.isResolved !== false) { blockers.push("bot review thread evidence unavailable"); continue; }
+      const comments = thread?.comments;
+      if (comments?.pageInfo?.hasNextPage !== false || !Array.isArray(comments.nodes) || comments.nodes.length > 100
+        || comments.nodes.some((comment: { author?: { __typename?: string }; createdAt?: string }) => !["Bot", "User"].includes(comment?.author?.__typename ?? "") || !Number.isFinite(Date.parse(comment.createdAt ?? "")))) {
+        blockers.push("bot review thread evidence unavailable"); continue;
+      }
+      let unanswered = false;
+      for (const comment of comments.nodes) {
+        if (comment.author.__typename === "Bot") unanswered = true;
+        else if (comment.author.__typename === "User") unanswered = false;
+      }
+      if (unanswered) blockers.push("bot review threads unanswered");
+    }
+    return { head: pr.headRefOid, ready: blockers.length === 0, blockers: [...new Set(blockers)], ...(reusedRun !== undefined ? { reusedRun } : {}) };
+  } catch { return unknown(); }
+}
+
+/** Same proof floor as scripts/ci-gates.mjs: the identical tree includes the workflow itself. No skipped proof. */
+async function identicalTreeGate(repository: string, tree: string, run: SdlcGh, required: readonly string[]): Promise<number | undefined> {
+  try {
+    const list = await run(["api", `repos/${repository}/actions/workflows/check.yml/runs?status=success&per_page=20`, "--jq", "{total_count,workflow_runs:[.workflow_runs[]|{id,event,conclusion,head_sha}]}"], 10_000, undefined, 64 * 1024);
+    if (list.code !== 0) return;
+    const runs = JSON.parse(list.stdout)?.workflow_runs;
+    if (!Array.isArray(runs) || runs.length > 20) return;
+    for (const candidate of runs) {
+      if (!id(candidate?.id) || candidate.conclusion !== "success" || !["pull_request", "push"].includes(candidate.event) || !sha(candidate.head_sha)) continue;
+      const commit = await run(["api", `repos/${repository}/git/commits/${candidate.head_sha}`, "--jq", "{tree:{sha:.tree.sha}}"], 10_000, undefined, 4096);
+      if (commit.code !== 0 || JSON.parse(commit.stdout)?.tree?.sha !== tree) continue;
+      const jobs = await run(["api", `repos/${repository}/actions/runs/${candidate.id}/jobs?per_page=100`, "--jq", '{total_count,jobs:[.jobs[]|{name,conclusion,reused:any(.steps[]?; .name=="Reuse verified identical-tree full gate" and .conclusion=="success")}]}'], 10_000, undefined, 32 * 1024);
+      if (jobs.code !== 0) continue;
+      const proof = JSON.parse(jobs.stdout);
+      if (!Array.isArray(proof.jobs) || proof.jobs.length > 100 || proof.total_count !== proof.jobs.length) continue;
+      if (required.every(name => {
+        const found = proof.jobs.filter((job: { name?: string }) => job?.name === name); return found.length === 1 && found[0]?.conclusion === "success" && found[0]?.reused !== true;
+      })) return candidate.id;
+    }
+  } catch { return; }
+}
+
+/** PR cost evidence excludes titles, bodies and comment text; unknown/truncated coverage never becomes zero. */
+export async function readPrCostHistory(repository: string, number: number, run: SdlcGh = sdlcGh): Promise<import("./cost-governance.ts").CostPr | undefined> {
+  if (!repo(repository) || !id(number)) return;
+  const [owner, name] = repository.split("/");
+  try {
+    const query = "query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){number state headRefOid mergedAt commits(first:100){nodes{commit{oid}} pageInfo{hasNextPage}} reviews(first:100){nodes{databaseId commit{oid}} pageInfo{hasNextPage}}}}}";
+    const reply = await run(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${number}`], 10_000, undefined, 128 * 1024);
+    if (reply.code !== 0) return;
+    const parsed = JSON.parse(reply.stdout), pr = parsed.data?.repository?.pullRequest;
+    if (parsed.errors || pr?.number !== number || !["OPEN", "CLOSED", "MERGED"].includes(pr.state)) return;
+    const result: import("./cost-governance.ts").CostPr = { repo: repository, pr: number, state: pr.state, complete: false,
+      ...(typeof pr.mergedAt === "string" && Number.isFinite(Date.parse(pr.mergedAt)) ? { mergedAt: Date.parse(pr.mergedAt) } : {}) };
+    if (pr.state !== "MERGED") return result; // Cost metrics count merged PRs, not an active work queue.
+    const reviews = pr.reviews, commits = pr.commits;
+    const reviewComplete = reviews?.pageInfo?.hasNextPage === false && Array.isArray(reviews.nodes) && reviews.nodes.length <= 100 && reviews.nodes.every((node: { databaseId?: number }) => id(node?.databaseId));
+    const commitComplete = commits?.pageInfo?.hasNextPage === false && Array.isArray(commits.nodes) && commits.nodes.length <= 100 && sha(pr.headRefOid) && commits.nodes.every((node: { commit?: { oid?: string } }) => sha(node?.commit?.oid));
+    if (reviewComplete) result.reviews = new Set(reviews.nodes.map((review: { databaseId?: unknown }) => review.databaseId).filter((id: unknown) => Number.isSafeInteger(id))).size;
+    const heads = new Set<string>([pr.headRefOid, ...(commits?.nodes ?? []).map((node: { commit?: { oid?: string } }) => node?.commit?.oid), ...(reviews?.nodes ?? []).map((node: { commit?: { oid?: string } }) => node?.commit?.oid)].filter(sha));
+    const checks = await run(["api", `repos/${repository}/actions/workflows/check.yml/runs?per_page=100`, "--jq", "{total_count,workflow_runs:[.workflow_runs[]|{id,run_attempt,head_sha,pull_requests:[.pull_requests[].number]}]}"], 10_000, undefined, 128 * 1024);
+    if (checks.code !== 0) return result;
+    const runs = JSON.parse(checks.stdout);
+    if (!Array.isArray(runs.workflow_runs) || runs.workflow_runs.length > 100 || !Number.isSafeInteger(runs.total_count) || runs.total_count < runs.workflow_runs.length) return result;
+    const linked = runs.workflow_runs.filter((row: { head_sha?: string; pull_requests?: number[] }) => heads.has(row.head_sha ?? "") || Array.isArray(row.pull_requests) && row.pull_requests.includes(number));
+    if (linked.some((row: { id?: number; run_attempt?: number }) => !id(row.id) || !id(row.run_attempt))) return result;
+    result.ciRuns = linked.map((row: { id: number; run_attempt: number }) => ({ id: row.id, attempt: row.run_attempt }));
+    result.complete = reviewComplete && commitComplete && runs.total_count === runs.workflow_runs.length;
+    return result;
+  } catch { return; }
+}