@staix/agent-hub 0.12.22 → 0.12.24

package/src/hub/routing.ts

@@ -1,6 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import type { Task, TaskClass } from "./board.ts";
+import { CLASSES, type Task, type TaskClass } from "./board.ts";
 import type { PeerId, PeerState } from "./envelope.ts";
 
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
@@ -36,21 +36,115 @@ export interface Routing {
   constraints: { pii: "local_only" | "off"; long_context: "skip_local" | "off"; budget_paused: "skip_peer" | "off" };
   /** `efficient_wait_ms`, opt-in (#199): how long a hub/auto request waits for a busy MLX slot before it moves to dgx/fast; absent, nothing moves for load. */
   pi: { dgx_max_context_tokens: number; mlx_max_context_tokens: number; efficient_wait_ms?: number };
+  /** The keys `.agenthub/routing.local.toml` set (#269), such as `classes.implement.peers`; every other value is routing.toml's. */
+  sources?: Record<string, "routing.local.toml">;
+}
+
+/**
+ * What `.agenthub/routing.local.toml` may hold (#269): a person's machine-local override of these keys and nothing
+ * else, so a settings write can never reach targets, routes, signals or the PII constraint.
+ */
+export interface RoutingOverlay {
+  stay_switch?: StaySwitchMode;
+  classes?: Partial<Record<TaskClass, { peers?: PeerId[]; escalate_to?: PeerId[]; route?: string; pi_backend?: "dgx" | "mlx" }>>;
+}
+export const OVERLAY_FILE = "routing.local.toml";
+const OVERLAY_PEER = /^[a-z][a-z0-9-]{0,31}$/;
+const OVERLAY_ROUTE = /^[A-Za-z0-9][A-Za-z0-9_./-]{0,63}$/;
+const OVERLAY_PEERS_MAX = 8;
+
+/** A checked copy of an overlay, in a fixed key order; throws on anything outside the keys above. */
+export function checkOverlay(raw: unknown): RoutingOverlay {
+  const bad = (what: string): never => { throw new Error(`${OVERLAY_FILE}: ${what}`); };
+  const table = (value: unknown, where: string): Record<string, unknown> => (!value || typeof value !== "object" || Array.isArray(value) ? bad(`${where} must be a table`) : value as Record<string, unknown>);
+  const peers = (value: unknown, where: string): PeerId[] => {
+    if (!Array.isArray(value) || value.length > OVERLAY_PEERS_MAX || value.some((p) => typeof p !== "string" || !OVERLAY_PEER.test(p)) || new Set(value).size !== value.length) bad(`${where} must list up to ${OVERLAY_PEERS_MAX} distinct peer ids`);
+    return [...(value as PeerId[])];
+  };
+  const top = table(raw, "the file");
+  const out: RoutingOverlay = {};
+  for (const [key, value] of Object.entries(top)) {
+    if (key === "stay_switch") {
+      if (value !== "off" && value !== "shadow" && value !== "enforce") bad('stay_switch must be "off", "shadow" or "enforce"');
+      out.stay_switch = value as StaySwitchMode;
+    } else if (key === "classes") {
+      for (const [name, policy] of Object.entries(table(value, "classes"))) {
+        if (!(CLASSES as readonly string[]).includes(name)) bad(`[classes.${name}] is not a task class`);
+        const entry: NonNullable<RoutingOverlay["classes"]>[TaskClass] = {};
+        for (const [field, v] of Object.entries(table(policy, `[classes.${name}]`))) {
+          if (field === "peers" || field === "escalate_to") entry[field] = peers(v, `[classes.${name}] ${field}`);
+          else if (field === "route") entry.route = typeof v === "string" && OVERLAY_ROUTE.test(v) ? v : bad(`[classes.${name}] route must be a route id`);
+          else if (field === "pi_backend") entry.pi_backend = v === "dgx" || v === "mlx" ? v : bad(`[classes.${name}] pi_backend must be "dgx" or "mlx"`);
+          else bad(`[classes.${name}] ${field} is not a setting this file holds; edit routing.toml`);
+        }
+        if (Object.keys(entry).length) (out.classes ??= {})[name as TaskClass] = entry;
+      }
+    } else bad(`${key} is not a setting this file holds; edit routing.toml`);
+  }
+  return out;
+}
+export const parseOverlay = (text: string): RoutingOverlay => checkOverlay(Bun.TOML.parse(text));
+
+/** The overlay as TOML. Every value is a checked id or a closed word, so a JSON string is a valid TOML basic string. */
+export function overlayToml(overlay: RoutingOverlay): string {
+  const checked = checkOverlay(overlay);
+  const lines = ["# Written by ahub settings and the dashboard (machine-local). It overrides routing.toml key by key."];
+  if (checked.stay_switch) lines.push(`stay_switch = ${JSON.stringify(checked.stay_switch)}`);
+  for (const name of CLASSES) {
+    const entry = checked.classes?.[name];
+    if (!entry) continue;
+    lines.push("", `[classes.${name}]`);
+    for (const field of ["peers", "escalate_to"] as const) if (entry[field]) lines.push(`${field} = [${entry[field]!.map((p) => JSON.stringify(p)).join(", ")}]`);
+    if (entry.route) lines.push(`route = ${JSON.stringify(entry.route)}`);
+    if (entry.pi_backend) lines.push(`pi_backend = ${JSON.stringify(entry.pi_backend)}`);
+  }
+  return `${lines.join("\n")}\n`;
 }
 
 const TEMPLATE = join(import.meta.dir, "..", "..", "templates", "routing.toml");
 export const LOCAL: PeerId = "local";
 export const PI: PeerId = "pi";
 
-/** `.agenthub/routing.toml`, or the shipped default when the project has none. Throws on a file that does not parse or lacks a fixed model. */
+/**
+ * `.agenthub/routing.toml`, or the shipped default when the project has none, with `.agenthub/routing.local.toml`
+ * merged over it key by key (#269). Throws on a file that does not parse or lacks a fixed model.
+ */
 export function loadRouting(cwd: string): Routing {
-  let text: string;
+  const text = routingText(cwd);
+  let overlay: string | undefined;
   try {
-    text = readFileSync(join(cwd, ".agenthub", "routing.toml"), "utf8");
+    overlay = readFileSync(join(cwd, ".agenthub", OVERLAY_FILE), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  return parseRouting(text, overlay === undefined ? undefined : parseOverlay(overlay));
+}
+
+/** The project's routing.toml as text, or the shipped default when it has none. */
+export function routingText(cwd: string): string {
+  try {
+    return readFileSync(join(cwd, ".agenthub", "routing.toml"), "utf8");
   } catch {
-    text = readFileSync(TEMPLATE, "utf8");
+    return readFileSync(TEMPLATE, "utf8");
   }
+}
+
+/** The policy of a routing.toml text with an overlay merged over it: what `loadRouting` reads, without the disk. */
+export function parseRouting(text: string, overlay?: RoutingOverlay): Routing {
   const raw = Bun.TOML.parse(text) as Partial<Routing>;
+  const sources: NonNullable<Routing["sources"]> = {};
+  if (overlay) {
+    const checked = checkOverlay(overlay);
+    if (checked.stay_switch) { (raw as Record<string, unknown>).stay_switch = checked.stay_switch; sources.stay_switch = OVERLAY_FILE; }
+    const known = new Set([...Object.keys(raw.routes ?? {}), ...Object.keys(raw.hub_routes ?? {})]);
+    for (const [name, entry] of Object.entries(checked.classes ?? {})) {
+      if (entry.route && !known.has(entry.route)) throw new Error(`${OVERLAY_FILE}: [classes.${name}] route ${entry.route} names no route in routing.toml`);
+      const classes = (raw.classes ??= {}) as Record<string, ClassPolicy>;
+      // A class the shared file does not have starts from an empty peer list: the overlay may add its own.
+      classes[name] = { ...(classes[name] ?? { peers: [] }), ...entry };
+      for (const field of Object.keys(entry)) sources[`classes.${name}.${field}`] = OVERLAY_FILE;
+    }
+  }
   if (!raw.local?.fixed_model) throw new Error("routing.toml: [local] fixed_model is required (the path that works without Switchyard)");
   const signals = { pii_patterns: [], long_context_tokens: 120_000, pii_screen: "off" as const, ...raw.signals };
   for (const p of signals.pii_patterns) new RegExp(p); // a bad pattern fails here, at load, not in the middle of an assignment
@@ -82,22 +176,26 @@ export function loadRouting(cwd: string): Routing {
     signals,
     constraints: { pii: "local_only", long_context: "skip_local", budget_paused: "skip_peer", ...raw.constraints },
     pi,
+    ...(Object.keys(sources).length ? { sources } : {}),
   };
 }
 
-const cache = new Map<string, { mtime: number; routing: Routing }>();
+const cache = new Map<string, { mtime: string; routing: Routing }>();
 
 /**
  * loadRouting behind an mtime check. routing.toml is edited while the hub runs and read on every task operation;
  * a half-saved file must not abort an operation midway, so the last good parse stays in force until the file parses again.
  */
 export function currentRouting(cwd: string, log: (line: string) => void = () => {}): Routing {
-  let mtime = 0;
-  try {
-    mtime = statSync(join(cwd, ".agenthub", "routing.toml")).mtimeMs;
-  } catch {
-    // no project file: the shipped template
-  }
+  // Both files count: a settings write changes only the overlay.
+  const mtime = ["routing.toml", OVERLAY_FILE].map((name) => {
+    try {
+      const stat = statSync(join(cwd, ".agenthub", name));
+      return `${stat.mtimeMs}/${stat.size}`;
+    } catch {
+      return 0; // no project file: the shipped template, or no overlay
+    }
+  }).join(":");
   const hit = cache.get(cwd);
   if (hit && hit.mtime === mtime) return hit.routing;
   try {
@@ -106,13 +204,13 @@ export function currentRouting(cwd: string, log: (line: string) => void = () =>
     return routing;
   } catch (e) {
     if (!hit) throw e;
-    log(`routing.toml does not load, keeping the previous policy: ${(e as Error).message}`);
+    log(`routing does not load, keeping the previous policy: ${(e as Error).message}`);
     cache.set(cwd, { mtime, routing: hit.routing });
     return hit.routing;
   }
 }
 
-export type Signal = "pii" | "long_context" | "urgent";
+export type Signal = "pii" | "pii_path" | "long_context" | "urgent";
 
 /** What the policy can see in a task. Context length is estimated from the referenced files, 3 characters per token as elsewhere. */
 export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, routing: Routing, cwd: string): Signal[] {
@@ -150,11 +248,19 @@ export interface Assignment {
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
  */
 export function assign(
-  task: Pick<Task, "class" | "signals" | "reserved">,
+  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state">>,
   states: Record<PeerId, PeerState>,
   routing: Routing,
   opts: {
     exclude?: PeerId[];
+    /** Owner admission limits do not remove otherwise eligible reviewers. */
+    excludeOwners?: PeerId[];
+    /** Live membership supplied as data; routing never reads the roster store. */
+    offRoster?: PeerId[];
+    /** Watched peers take work only on an explicit nomination, never a routing singleton. */
+    pullOnly?: PeerId[];
+    namedOwner?: PeerId;
+    namedReviewer?: PeerId;
     candidates?: PeerId[];
     notReviewer?: PeerId;
     waitsFor?: number[];
@@ -174,17 +280,25 @@ export function assign(
     roles?: Record<string, string[]>;
   } = {},
 ): Assignment {
+  if (task.state === "backlog") return { trace: ["backlog: not routed; pull into To Do first"] };
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];
+  // Which file each of this class's values comes from (#269), only when the machine-local overlay sets one.
+  const local = Object.keys(routing.sources ?? {}).filter((key) => key.startsWith(`classes.${task.class}.`)).map((key) => key.slice(`classes.${task.class}.`.length));
+  if (local.length) trace.push(`policy source: ${local.join(", ")} from ${OVERLAY_FILE}; the rest from routing.toml`);
   // A reserved owner (issue #207) is offered the task first. Named candidates (an assign, an escalation, a relay) replace it.
   const reserved = opts.candidates ? undefined : task.reserved ?? undefined;
   // Readiness is an input like peer states (issue #34): a task that waits for others goes to nobody yet.
   if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`, ...(reserved ? [`reserved owner ${reserved}: offered first once it is ready`] : [])] };
-  const pii = task.signals.includes("pii") && routing.constraints.pii === "local_only";
+  const pii = task.signals.includes("pii_path") || (task.signals.includes("pii") && routing.constraints.pii === "local_only");
 
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
+    if (opts.offRoster?.includes(peer)) return "off roster";
+    const named = role === "owner" ? opts.namedOwner ?? reserved : opts.namedReviewer;
+    if (opts.pullOnly?.includes(peer) && named !== peer) return "pull-only: takes work when named or when it claims it";
     if (!Object.hasOwn(states, peer)) return "not attached";
     if (opts.exclude?.includes(peer)) return "excluded (declined or replaced)";
+    if (role === "owner" && opts.excludeOwners?.includes(peer)) return "owner admission: WIP or delivery hold";
     if (states[peer] === "offline") return "offline";
     if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return "paused";
     const failing = peerEntry(opts.failing, peer);
@@ -270,8 +384,8 @@ export function assign(
       // Reviewer candidates (issue #92): the review class's peers first, then peers holding the reviewer role, deduped.
       const classPeers = routing.classes.review?.peers ?? [];
       const rolePeers = Object.keys(opts.roles ?? {}).filter((p) => opts.roles![p]!.includes("reviewer"));
-      trace.push(`  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}`);
-      reviewer = pick([...new Set([...classPeers, ...rolePeers])], "reviewer", owner ?? opts.notReviewer);
+      trace.push(opts.namedReviewer === undefined ? `  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}` : `  reviewer candidate explicitly named: ${opts.namedReviewer}`);
+      reviewer = pick(opts.namedReviewer === undefined ? [...new Set([...classPeers, ...rolePeers])] : [opts.namedReviewer], "reviewer", owner ?? opts.notReviewer);
       trace.push(reviewer ? `reviewer: ${reviewer}` : "reviewer: none, done will approve directly");
       const reviewerHold = reviewer ? peerEntry(opts.held, reviewer) : undefined;
       if (reviewerHold) trace.push(`  hold: ${reviewer}'s queue is held: ${reviewerHold} (it receives the review once the hold is resolved)`);

package/src/hub/sdlc-queue.ts

@@ -0,0 +1,112 @@
+import type { PhaseView } from "./workflow.ts";
+import { parsePrEvidence, readSdlcPr, sdlcGh, sdlcStatus, type PrEvidence, type SdlcConfig, type SdlcGh, type SdlcReceipt } from "./sdlc.ts";
+export interface DeliveryTask { id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: PhaseView; }
+export interface MergeQueueRow { pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
+export interface MergeConflict { left: number; right: number; files: number; order: "dependency" | "person_required"; }
+export interface MergeQueue { repo: string; rows: MergeQueueRow[]; order: number[]; unordered?: number[]; conflicts: MergeConflict[]; complete: boolean; truncated: boolean; }
+const validRepo = (value: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
+const validId = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+const parseSnapshot = (reply: { code: number; stdout: string }): { number: number; head: string; base: string; baseHead: string }[] | undefined => {
+  try { const data = JSON.parse(reply.stdout); if (reply.code !== 0 || !Array.isArray(data) || data.length > 17 || data.some(p => !validId(p?.number) || typeof p.headRefOid !== "string" || !/^[0-9a-f]{40}$/.test(p.headRefOid) || typeof p.baseRefName !== "string" || !p.baseRefName || p.baseRefName.length > 200 || /[\x00-\x1f\x7f]/.test(p.baseRefName) || typeof p.baseRefOid !== "string" || !/^[0-9a-f]{40}$/.test(p.baseRefOid)) || new Set(data.map(p => p.number)).size !== data.length) return; return data.map(p => ({ number: p.number, head: p.headRefOid, base: p.baseRefName, baseHead: p.baseRefOid })).sort((a, b) => a.number - b.number); }
+  catch { return; }
+};
+const gateIdentity = (p: PrEvidence) => JSON.stringify({ head: p.head, state: p.state, checks: [...p.checks].sort((a, b) => a.name.localeCompare(b.name) || a.state.localeCompare(b.state)), review: p.review, pending: p.pendingReviews, unresolved: p.unresolved, draft: p.draft, base: p.base, baseHead: p.baseHead, pathsComplete: p.pathsComplete });
+/** The last remote read gathers both open identities and mutable gates in one bounded request. */
+async function finalSnapshot(repo: string, evidence: Map<number, PrEvidence>, run: SdlcGh): Promise<{ gatesStable: boolean; prs?: ReturnType<typeof parseSnapshot> }> {
+  const [owner, name] = repo.split("/");
+  const fields = "headRefOid state isDraft baseRefName baseRefOid changedFiles reviewDecision reviewRequests(first:100){nodes{requestedReviewer{__typename}} pageInfo{hasNextPage}} reviewThreads(first:100){nodes{isResolved} pageInfo{hasNextPage}} statusCheckRollup{contexts(first:100){nodes{... on CheckRun{name conclusion status} ... on StatusContext{context state}} pageInfo{hasNextPage}}}";
+  const entries = [...evidence.entries()];
+  const query = `query($owner:String!,$name:String!){repository(owner:$owner,name:$name){pullRequests(first:17,states:OPEN){nodes{number headRefOid baseRefName baseRefOid} pageInfo{hasNextPage}} ${entries.map(([id]) => `queue_p${id}:pullRequest(number:${id}){${fields}}`).join(" ")}}}`;
+  try {
+    const reply = await run(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`]);
+    if (reply.code !== 0) return { gatesStable: false };
+    const data = JSON.parse(reply.stdout);
+    if (data.errors || !data.data?.repository) return { gatesStable: false };
+    const open = data.data.repository.pullRequests;
+    const prs = parseSnapshot({ code: 0, stdout: JSON.stringify(open?.nodes) });
+    if (!prs || open?.pageInfo?.hasNextPage !== false) return { gatesStable: false, prs };
+    for (const [id, before] of entries) {
+      const p = data.data.repository[`queue_p${id}`];
+      const threads = p?.reviewThreads, reviews = p?.reviewRequests, checks = p?.statusCheckRollup === null ? { nodes: [], pageInfo: { hasNextPage: false } } : p?.statusCheckRollup?.contexts;
+      if (threads?.pageInfo?.hasNextPage !== false || reviews?.pageInfo?.hasNextPage !== false || checks?.pageInfo?.hasNextPage !== false || !Array.isArray(threads.nodes) || threads.nodes.length > 100 || threads.nodes.some((n: { isResolved?: unknown }) => typeof n?.isResolved !== "boolean") || !Array.isArray(reviews.nodes) || !Array.isArray(checks.nodes) || checks.nodes.length > 100) return { gatesStable: false, prs };
+      const after = parsePrEvidence({ ...p, files: before.paths.map(path => ({ path })), statusCheckRollup: checks.nodes, reviewRequests: reviews.nodes, unresolvedThreads: threads.nodes.filter((n: { isResolved: boolean }) => !n.isResolved).length });
+      if (gateIdentity(before) !== gateIdentity(after)) return { gatesStable: false, prs };
+    }
+    return { gatesStable: true, prs };
+  } catch { return { gatesStable: false }; }
+}
+/** Fixed metadata-only reads; local claims and unknown dependency evidence never become merge approval. */
+export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: DeliveryTask[], run: SdlcGh = sdlcGh): Promise<MergeQueue> {
+  if (!validRepo(repo)) throw new Error("merge queue requires owner/repository");
+  const result: MergeQueue = { repo, rows: [], order: [], conflicts: [], complete: false, truncated: false };
+  const deadline = performance.now() + 20_000;
+  const bounded: SdlcGh = args => { const remaining = deadline - performance.now(); return remaining > 0 ? run(args, Math.min(10_000, remaining)) : Promise.resolve({ code: 1, stdout: "" }); };
+  const listArgs = ["pr", "list", "--repo", repo, "--state", "open", "--limit", "17", "--json", "number,headRefOid,baseRefName,baseRefOid"];
+  const initialPrs = parseSnapshot(await bounded(listArgs)); if (!initialPrs) return result;
+  result.truncated = initialPrs.length > 16; const ids = initialPrs.slice(0, 16).map(pr => pr.number);
+  const sameRepo = (value: unknown) => typeof value === "string" && value.toLowerCase() === repo.toLowerCase();
+  const evidence = new Map<number, PrEvidence>(), links = new Map<number, DeliveryTask[]>();
+  for (const pr of ids) {
+    const holders = tasks.filter(t => sameRepo(t.receipt?.repo) && t.receipt?.pr === pr); links.set(pr, holders);
+    const row: MergeQueueRow = { pr, tasks: holders.some(t => t.private) ? [] : holders.map(t => t.id), ready: false, blockers: [], after: [] }; result.rows.push(row);
+    if (holders.some(t => t.private)) { row.private = true; row.blockers.push("private lifecycle evidence unavailable"); continue; }
+    const read = await readSdlcPr(holders[0]?.receipt ?? { stage: config.stages[0] ?? "spec", repo, pr }, bounded);
+    if (!read || read.state !== "OPEN") { row.blockers.push("current PR evidence unknown or no longer open"); continue; }
+    evidence.set(pr, read); row.head = read.head;
+    if (!read.pathsComplete) row.blockers.push("PR file coverage is incomplete or unknown");
+    if (read.draft !== false) row.blockers.push("PR is draft or draft status is unknown");
+    if (!read.base) row.blockers.push("PR target branch is unknown");
+    const linked = holders.length ? holders : [undefined];
+    for (const holder of linked) row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+  }
+  const dependencyEvidence = new Map<number, PrEvidence | undefined>(); let dependencyReads = 0;
+  for (const row of result.rows) {
+    if (row.private) continue;
+    for (const holder of links.get(row.pr) ?? []) for (const id of holder.after) {
+      const dependency = tasks.find(t => t.id === id);
+      if (!dependency || dependency.private || !dependency.receipt || !sameRepo(dependency.receipt.repo) || !validId(dependency.receipt.pr)) { row.blockers.push("dependency merge evidence unknown or private"); continue; }
+      const pr = dependency.receipt.pr;
+      if (pr === row.pr) continue; // task dependency within this same artifact
+      if (ids.includes(pr)) { row.after.push(pr); row.blockers.push("dependency PR is still open"); continue; }
+      if (!dependencyEvidence.has(pr) && dependencyReads < 8) { dependencyReads++; dependencyEvidence.set(pr, await readSdlcPr(dependency.receipt, bounded)); }
+      const read = dependencyEvidence.get(pr);
+      if (!read || read.state !== "MERGED" || !read.mergeCommit) row.blockers.push("dependency PR merge is not verified");
+    }
+    row.after = [...new Set(row.after)].sort((a, b) => a - b);
+  }
+  const reaches = (from: number, target: number, seen = new Set<number>()): boolean => {
+    if (seen.has(from)) return false; seen.add(from);
+    return (result.rows.find(r => r.pr === from)?.after ?? []).some(before => before === target || reaches(before, target, seen));
+  };
+  for (let i = 0; i < result.rows.length; i++) for (const right of result.rows.slice(i + 1)) {
+    const left = result.rows[i]!, a = evidence.get(left.pr), b = evidence.get(right.pr); if (!a || !b || !a.base || a.base !== b.base) continue;
+    const files = new Set(a.paths.filter(path => b.paths.includes(path))).size; if (!files) continue;
+    const ordered = reaches(left.pr, right.pr) || reaches(right.pr, left.pr);
+    result.conflicts.push({ left: left.pr, right: right.pr, files, order: ordered ? "dependency" : "person_required" });
+    if (!ordered) { left.blockers.push("touching PRs require a person order"); right.blockers.push("touching PRs require a person order"); }
+  }
+  const remaining = new Set(ids);
+  while (remaining.size) {
+    const next = result.rows.filter(r => remaining.has(r.pr) && r.after.every(pr => !remaining.has(pr))).map(r => r.pr).sort((a, b) => a - b);
+    if (!next.length) { for (const row of result.rows.filter(r => remaining.has(r.pr))) row.blockers.push("artifact dependency cycle requires a person"); break; }
+    for (const pr of next) { remaining.delete(pr); result.order.push(pr); }
+  }
+  const touchingCoverageUnknown = result.rows.some(row => evidence.get(row.pr)?.pathsComplete !== true || !evidence.get(row.pr)?.base);
+  const personOrder = new Set(result.conflicts.filter(conflict => conflict.order === "person_required").flatMap(conflict => [conflict.left, conflict.right]));
+  const unresolvedOrder = new Set([...remaining, ...personOrder]);
+  for (const row of result.rows) if (result.truncated || touchingCoverageUnknown || [...personOrder].some(pr => reaches(row.pr, pr))) unresolvedOrder.add(row.pr);
+  if (unresolvedOrder.size) { result.unordered = ids.filter(pr => unresolvedOrder.has(pr)); result.order = result.order.filter(pr => !unresolvedOrder.has(pr)); }
+  for (const row of result.rows) { if (result.truncated) row.blockers.push("open PR coverage truncated; touching order unknown"); if (touchingCoverageUnknown) row.blockers.push("open PR file coverage incomplete; touching order unknown"); row.blockers = [...new Set(row.blockers)]; row.ready = !row.private && !row.blockers.length; }
+  result.complete = !result.truncated && !remaining.size && !touchingCoverageUnknown && !personOrder.size;
+  // Empty/private-only snapshots have no intervening remote reads and offer no private PR evidence.
+  if (evidence.size) {
+    const finalRead = await finalSnapshot(repo, evidence, bounded);
+    const gatesStable = finalRead.gatesStable;
+    const finalPrs = finalRead.prs;
+    if (!gatesStable || !finalPrs || JSON.stringify(finalPrs) !== JSON.stringify(initialPrs) || finalPrs.some(pr => evidence.has(pr.number) && (evidence.get(pr.number)?.head !== pr.head || evidence.get(pr.number)?.base !== pr.base || evidence.get(pr.number)?.baseHead !== pr.baseHead))) {
+      result.complete = false; result.order = []; result.unordered = ids;
+      for (const row of result.rows) { row.ready = false; row.blockers.push("open PR set changed or could not be reverified"); }
+    }
+  }
+  return result;
+}

package/src/hub/sdlc-release.ts

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { childEnv, stopOwnedProcess } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
+import { sdlcGh, type SdlcGh } from "./sdlc.ts";
+export interface DocEvidence { schemaVersion: 1; head?: string; version?: string; documents: { path?: string; state: "fresh" | "stale" | "nonancestor" | "unknown"; verifiedAgainst?: string; commits?: number; dirty?: boolean }[]; errors: number; fresh: boolean; }
+export interface ReleaseReadiness { repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
+export type ReleaseGit = (args: string[]) => { code: number; stdout: string };
+export interface ReleaseReaders { gh?: SdlcGh; git?: ReleaseGit; docs?: (root: string, timeoutMs: number) => Promise<DocEvidence | undefined>; }
+const SHA = /^[0-9a-f]{40}$/;
+const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** One identity floor for initial and final remote tag observations. */
+function tagMatches(target: unknown, commit: string): boolean {
+  const parsed = target as { oid?: unknown; target?: { oid?: unknown } } | null | undefined;
+  const oid = parsed?.oid ?? parsed?.target?.oid;
+  return typeof oid === "string" && SHA.test(oid) && oid === commit;
+}
+/** Package-owned checker only; no caller-supplied program or document text is executed. */
+export function readDocEvidence(root: string, timeoutMs = 10_000): Promise<DocEvidence | undefined> {
+  return new Promise(resolve => {
+    const child = spawn(process.execPath, [fileURLToPath(new URL("../../scripts/check-docs.mjs", import.meta.url)), root, "--json", "--committed"], { cwd: root, env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
+    let output = "", invalid = false;
+    const stop = () => { invalid = true; void stopOwnedProcess(child, { group: true }).catch(() => {}); };
+    const timer = setTimeout(stop, Math.max(1, Math.min(10_000, timeoutMs)));
+    child.stdout?.setEncoding("utf8"); child.stdout?.on("data", chunk => { output += chunk; if (Buffer.byteLength(output) > 256 * 1024) { output = ""; stop(); } });
+    child.once("error", () => { invalid = true; clearTimeout(timer); resolve(undefined); });
+    child.once("close", (code, signal) => {
+      clearTimeout(timer); if (invalid || signal || (code !== 0 && code !== 1)) return resolve(undefined);
+      try {
+        const data = JSON.parse(output);
+        if (data.schemaVersion !== 1 || !Array.isArray(data.documents) || data.documents.length > 128 || !Number.isSafeInteger(data.errors) || data.errors < 0 || typeof data.fresh !== "boolean" || (data.head !== undefined && !SHA.test(data.head)) || (data.version !== undefined && !VERSION.test(data.version)) || data.documents.some((d: {state?:string}) => !["fresh","stale","nonancestor","unknown"].includes(d.state ?? ""))) return resolve(undefined);
+        resolve(data);
+      } catch { resolve(undefined); }
+    });
+  });
+}
+/** Read-only checklist. Native acceptance remains an explicit human/operational gate. */
+export async function readReleaseReadiness(root: string, repo: string, liveIssues: number[], readers: ReleaseReaders = {}): Promise<ReleaseReadiness> {
+  if (!REPO.test(repo) || repo.startsWith("-") || liveIssues.length > 32 || liveIssues.some(id => !Number.isSafeInteger(id) || id <= 0) || new Set(liveIssues).size !== liveIssues.length) throw new Error("release evidence requires owner/repository and bounded issue ids");
+  const report: ReleaseReadiness = { repo, commits: [], mergedPrs: [], liveIssues: [], blockers: [], sourceReady: false, native: "unverified", ready: false };
+  const deadline = performance.now() + 20_000;
+  const gh: SdlcGh = args => { const left = deadline - performance.now(); return left > 0 ? (readers.gh ?? sdlcGh)(args, Math.min(left,10_000)) : Promise.resolve({code:1,stdout:""}); };
+  const git: ReleaseGit = readers.git ?? (args => { const r = hubGitSync(args, { cwd: root, encoding: "utf8", timeout: Math.max(1, Math.min(1000, deadline - performance.now())), maxBuffer: 256 * 1024 }); return { code: r.status ?? 1, stdout: r.stdout ?? "" }; });
+  const first = git(["rev-parse","--verify","HEAD"]); const head = first.stdout.trim();
+  if (first.code !== 0 || !SHA.test(head)) { report.blockers.push("local HEAD unknown"); return report; } report.head = head;
+  try { const r = git(["show",`${head}:package.json`]), pkg = JSON.parse(r.stdout); if (r.code === 0 && typeof pkg.version === "string" && VERSION.test(pkg.version)) report.version = pkg.version; else report.blockers.push("package version unknown"); } catch { report.blockers.push("package version unknown"); }
+  const published = await gh(["release","list","--repo",repo,"--exclude-drafts","--order","desc","--limit","1","--json","tagName,isDraft,isPrerelease"]);
+  let tag: string | undefined;
+  try { const rows = JSON.parse(published.stdout), p = Array.isArray(rows) && rows.length === 1 ? rows[0] : undefined; if (published.code === 0 && p && typeof p.tagName === "string" && p.tagName.startsWith("v") && VERSION.test(p.tagName.slice(1)) && p.isDraft === false && typeof p.isPrerelease === "boolean") tag = p.tagName; } catch { /* unknown metadata */ }
+  if (!tag) report.blockers.push("published release identity unknown");
+  else {
+    report.tag = tag; const local = git(["rev-parse","--verify",`refs/tags/${tag}^{commit}`]);
+    const [owner,name] = repo.split("/");
+    const ref = await gh(["api","graphql","-f","query=query($owner:String!,$name:String!,$ref:String!){repository(owner:$owner,name:$name){ref(qualifiedName:$ref){target{... on Commit{oid} ... on Tag{target{... on Commit{oid}}}}}}}","-f",`owner=${owner}`,"-f",`name=${name}`,"-f",`ref=refs/tags/${tag}`]);
+    const commit = local.stdout.trim();
+    let remoteMatches = false; try { remoteMatches = tagMatches(JSON.parse(ref.stdout)?.data?.repository?.ref?.target, commit); } catch { /* unknown */ }
+    if (local.code !== 0 || ref.code !== 0 || !SHA.test(commit) || !remoteMatches) report.blockers.push("local and remote release tag identity differ or are unknown");
+    else if (git(["merge-base","--is-ancestor",commit,head]).code !== 0) report.blockers.push("published release is not a verified ancestor");
+    else {
+      report.tagCommit = commit;
+      const work = git(["rev-list","--first-parent","--max-count=1001",`${commit}..${head}`]); const commits = work.stdout.trim().split("\n").filter(Boolean);
+      if (work.code !== 0 || commits.length > 1000 || commits.some(c => !SHA.test(c))) report.blockers.push("merged work coverage unknown or truncated"); else report.commits = commits;
+      let advanced = false;
+      try { advanced = !!report.version && Bun.semver.order(report.version, tag.slice(1)) > 0; } catch { /* invalid version remains blocked */ }
+      if (!advanced) report.blockers.push("package version has not advanced past published release");
+    }
+  }
+  if (report.tagCommit) {
+    // Resolve only commits since the verified tag, never the repository's lifetime PR list.
+    const [owner, name] = repo.split("/");
+    for (let start = 0; start < report.commits.length; start += 100) {
+      const batch = report.commits.slice(start, start + 100);
+      const objects = batch.map((commit, i) => `c${i}:object(oid:"${commit}"){... on Commit{oid associatedPullRequests(first:10){nodes{number state mergeCommit{oid}} pageInfo{hasNextPage}}}}`).join(" ");
+      const pulls = await gh(["api", "graphql", "-f", `query=query($owner:String!,$name:String!){repository(owner:$owner,name:$name){${objects}}}`, "-f", `owner=${owner}`, "-f", `name=${name}`]);
+      try {
+        const data = JSON.parse(pulls.stdout)?.data?.repository;
+        if (pulls.code !== 0 || !data) throw new Error("unavailable");
+        for (const [i, commit] of batch.entries()) {
+          const object = data[`c${i}`], connection = object?.associatedPullRequests, rows = connection?.nodes;
+          if (object?.oid !== commit || connection?.pageInfo?.hasNextPage !== false || !Array.isArray(rows) || rows.length > 10 || rows.some(p => !Number.isSafeInteger(p?.number) || p.number <= 0 || !["OPEN", "CLOSED", "MERGED"].includes(p.state) || (p.state === "MERGED" && !SHA.test(p.mergeCommit?.oid)))) throw new Error("incomplete");
+          for (const p of rows) if (p.state === "MERGED" && p.mergeCommit.oid === commit && !report.mergedPrs.some(r => r.pr === p.number)) report.mergedPrs.push({ pr: p.number, commit });
+        }
+      } catch { report.blockers.push("merged PR coverage unknown or truncated"); break; }
+    }
+  }
+  const left = deadline - performance.now(); report.documents = left > 0 ? await (readers.docs ?? readDocEvidence)(root,Math.min(10_000,left)) : undefined;
+  if (!report.documents || report.documents.head !== head || !report.documents.fresh || report.documents.errors || report.documents.documents.some(d => d.state !== "fresh")) report.blockers.push("documentation freshness or ancestry is unknown or stale");
+  if (!liveIssues.length) report.blockers.push("native verification ledger unspecified");
+  for (const id of liveIssues) {
+    const reply = await gh(["issue","view",String(id),"--repo",repo,"--json","number,state"]); let state: "open"|"closed"|"unknown" = "unknown";
+    try { const p = JSON.parse(reply.stdout); if (reply.code === 0 && p.number === id && ["OPEN","CLOSED"].includes(p.state)) state = p.state.toLowerCase(); } catch { /* unknown */ }
+    report.liveIssues.push({id,state}); if (state !== "closed") report.blockers.push("native verification ledger open or unknown");
+  }
+  // The predecessor and tag can change while documents/issues are read. Recheck both in the last remote snapshot.
+  if (report.tag && report.tagCommit) {
+    const [owner, name] = repo.split("/");
+    const ledgers = liveIssues.map(id => `ledger_${id}:issue(number:${id}){number state}`).join(" ");
+    const query = `query($owner:String!,$name:String!,$ref:String!){repository(owner:$owner,name:$name){releases(first:100,orderBy:{field:CREATED_AT,direction:DESC}){nodes{tagName isDraft} pageInfo{hasNextPage}} ref(qualifiedName:$ref){target{... on Commit{oid} ... on Tag{target{... on Commit{oid}}}}} ${ledgers}}}`;
+    const snapshot = await gh(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-f", `ref=refs/tags/${report.tag}`]);
+    let stable = false, issuesStable = false;
+    let finalIssues: ReleaseReadiness["liveIssues"] = report.liveIssues.map(issue => ({ id: issue.id, state: "unknown" }));
+    try {
+      const data = JSON.parse(snapshot.stdout), repository = data.data?.repository, rows = repository?.releases?.nodes;
+      if (snapshot.code === 0 && !data.errors && Array.isArray(rows) && rows.length <= 100 && typeof repository.releases.pageInfo?.hasNextPage === "boolean" && rows.every(p => typeof p?.tagName === "string" && typeof p.isDraft === "boolean")) {
+        finalIssues = report.liveIssues.map(issue => {
+          const value = repository[`ledger_${issue.id}`];
+          const state: "open" | "closed" | "unknown" = value?.number === issue.id && ["OPEN", "CLOSED"].includes(value.state) ? value.state.toLowerCase() : "unknown";
+          return { id: issue.id, state };
+        });
+        issuesStable = finalIssues.every((issue, index) => issue.state === "closed" && issue.state === report.liveIssues[index]?.state);
+        const newest = rows.find(p => !p.isDraft), target = repository.ref?.target;
+        stable = newest?.tagName === report.tag && tagMatches(target, report.tagCommit);
+      }
+    } catch { /* unavailable predecessor remains blocked */ }
+    if (!stable) report.blockers.push("published release or remote tag changed or could not be reverified");
+    report.liveIssues = finalIssues;
+    if (!issuesStable) report.blockers.push("live issue states changed or could not be reverified");
+  }
+  const last = git(["rev-parse","--verify","HEAD"]); if (last.code !== 0 || last.stdout.trim() !== head) report.blockers.push("local HEAD changed during release readback");
+  report.blockers = [...new Set(report.blockers)]; report.sourceReady = report.blockers.length === 0;
+  // Closed issue metadata is not a native receipt or permission to publish.
+  report.blockers.push("native acceptance and person release decision unverified");
+  return report;
+}