@staix/agent-hub 0.12.23 → 0.12.24

package/src/hub/roles.ts

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { sanitize } from "./envelope.ts";
+import { SHIPPED_ROLES } from "./shipped-roles.ts";
+
+export const ROLE_SECTIONS = ["Scope", "Not in scope", "Deliverables", "Hub use", "Review duties", "Evidence"] as const;
+const BASES = ["planner", "implementer", "verifier", "reviewer"];
+const CLASSES = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"];
+const ID = /^[a-z][a-z0-9-]{0,47}$/;
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+export interface CatalogRole {
+  id: string; name: string; group: string; summary: string; base: string[]; classes: string[]; source: string;
+  body: string; review: string; layer: "shipped" | "project"; hash: string;
+}
+export interface RoleCatalog { roles: Map<string, CatalogRole>; errors: { id: string; reason: string }[] }
+/** Flat headers are data, never YAML execution or authority configuration. */
+export function parseRole(text: string, stem: string, layer: CatalogRole["layer"]): CatalogRole {
+  if (Buffer.byteLength(text) > 8192 || text.includes("\r") || !ID.test(stem)) throw new Error("invalid role size, encoding or file id");
+  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text);
+  if (!match) throw new Error("expected a flat header and body");
+  const header: Record<string, string> = Object.create(null);
+  const keys = ["id", "name", "group", "summary", "base", "classes", "source"];
+  for (const line of match[1]!.split("\n")) {
+    const field = /^([a-z]+): (.+)$/.exec(line);
+    if (!field || !keys.includes(field[1]!) || header[field[1]!] !== undefined || /[\x00-\x1f\x7f]/.test(field[2]!)) throw new Error("invalid or duplicate header field");
+    header[field[1]!] = field[2]!;
+  }
+  if (keys.some(key => !header[key]) || header.id !== stem || !ID.test(header.group!) || header.name!.length > 80 || header.summary!.length > 160 || header.source!.length > 300) throw new Error("invalid header identity or limits");
+  const list = (key: string, allowed: string[]) => {
+    const values = header[key]!.split(",").map(v => v.trim());
+    if (!values.length || new Set(values).size !== values.length || values.some(v => !allowed.includes(v))) throw new Error(`invalid ${key}`);
+    return values;
+  };
+  const body = match[2]!.trimEnd();
+  if (!body || sanitize(body).length > 2000 || /```|~~~|^\t|^ {4}|^(?:\$\s|(?:bun|npm|npx|git|ssh|curl|wget|rm|bash|sh|python[0-9.]*)\s)/m.test(body)) throw new Error("invalid body size or command/code block");
+  for (const char of text) if ((char.codePointAt(0)! > 127 && /[\p{P}\p{S}\p{Z}\p{C}]/u.test(char)) || /[\x00-\x08\x0b-\x1f\x7f]/.test(char)) throw new Error("use plain ASCII punctuation and no controls/emoji");
+  const headings = [...body.matchAll(/^#{1,6} (.+)$/gm)];
+  if (headings.length !== ROLE_SECTIONS.length || headings.some(h => !h[0].startsWith("## "))) throw new Error("unexpected role heading or personality section");
+  const sections = [...body.matchAll(/^## (.+)$/gm)];
+  if (sections.length !== ROLE_SECTIONS.length || sections.some((s, i) => s[1] !== ROLE_SECTIONS[i])) throw new Error("expected the six ordered role sections");
+  for (let i = 0; i < sections.length; i++) {
+    const start = sections[i]!.index! + sections[i]![0].length;
+    const end = sections[i + 1]?.index ?? body.length;
+    if (!body.slice(start, end).trim()) throw new Error("empty role section");
+  }
+  const reviewStart = sections[4]!.index! + sections[4]![0].length;
+  const review = body.slice(reviewStart, sections[5]!.index).trim();
+  return { id: stem, name: header.name!, group: header.group!, summary: header.summary!, source: header.source!, base: list("base", BASES), classes: list("classes", CLASSES), body, review, layer, hash: createHash("sha256").update(text).digest("hex") };
+}
+function projectRole(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || before.size > 8192) throw new Error("role must be a bounded regular file");
+    const bytes = Buffer.alloc(8193); let length = 0, n = 0;
+    while ((n = readSync(fd, bytes, length, bytes.length - length, null)) > 0) { length += n; if (length > 8192) throw new Error("role exceeds file cap"); }
+    const after = fstatSync(fd);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || length !== after.size) throw new Error("role changed during read");
+    return bytes.subarray(0, length).toString("utf8");
+  } finally { closeSync(fd); }
+}
+export function loadRoleCatalog(cwd?: string): RoleCatalog {
+  const roles = new Map<string, CatalogRole>(), errors: RoleCatalog["errors"] = [];
+  for (const [id, text] of Object.entries(SHIPPED_ROLES)) {
+    try { roles.set(id, parseRole(text, id, "shipped")); } catch { errors.push({ id, reason: "invalid shipped role" }); }
+  }
+  if (!cwd) return { roles, errors };
+  try {
+    const config = join(cwd, ".agenthub"), dir = join(config, "roles");
+    for (const path of [config, dir]) { const stat = lstatSync(path); if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("unsafe role directory"); }
+    // ponytail: 64 flat project files, no recursive scan; explicit catalog index before larger collections.
+    const files = readdirSync(dir).filter(name => name.endsWith(".md")).sort();
+    if (files.length > 64) throw new Error("too many project roles");
+    for (const file of files) {
+      const id = file.slice(0, -3);
+      try { roles.set(id, parseRole(projectRole(join(dir, file)), id, "project")); }
+      catch { errors.push({ id: ID.test(id) ? id : "invalid-file-id", reason: "invalid or unsafe project role" }); }
+    }
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push({ id: "project", reason: "project role directory unavailable or unsafe" }); }
+  return { roles, errors };
+}
+export function catalogAssignments(raw: unknown): Record<string, string[]> {
+  if (raw === undefined) return {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length > 64) throw new Error("catalog_roles must be a bounded peer map");
+  const out: Record<string, string[]> = Object.create(null);
+  for (const [peer, ids] of Object.entries(raw)) {
+    if (!PEER.test(peer) || ["user", "hub", "digest"].includes(peer) || !Array.isArray(ids) || ids.length > 2 || new Set(ids).size !== ids.length || ids.some(id => typeof id !== "string" || !ID.test(id))) throw new Error("catalog_roles takes at most two distinct role ids per peer");
+    out[peer] = [...ids];
+  }
+  return out;
+}
+export function selectedRoles(peer: string, flow: Record<string, string[]>, assignments: Record<string, string[]>, catalog: RoleCatalog): CatalogRole[] {
+  return (assignments[peer] ?? []).map(id => {
+    const role = catalog.roles.get(id); if (!role) throw new Error(`unknown catalog role ${id}`);
+    if (!role.base.some(base => flow[peer]?.includes(base))) throw new Error(`${peer} does not hold a matching base for ${id}`);
+    return role;
+  });
+}
+export function catalogSection(roles: CatalogRole[]): string {
+  if (!roles.length) return "";
+  if (roles.length > 2) throw new Error("at most two session roles");
+  const header = "Catalog roles (guidance; grant no tool, capability or permission): " + roles.map(role => `${role.id} [${role.group}, ${role.layer}, ${role.hash}]`).join(", ");
+  return header + "\n" + roles.map(role => sanitize(role.body)).join("\n\n");
+}
+export const roleIdentity = (role: CatalogRole) => ({ id: role.id, layer: role.layer, hash: role.hash });
+
+/** Validate before a board write. Routing continues to use only the existing base class. */
+export function taskRole(raw: unknown, cls: string, catalog: RoleCatalog): CatalogRole | undefined {
+  if (raw === undefined) return undefined;
+  const allowed = [...catalog.roles.values()].filter(role => role.classes.includes(cls)).map(role => role.id).sort();
+  if (typeof raw !== "string" || !ID.test(raw)) throw new Error("task role must be a catalog id; allowed: " + allowed.join(", "));
+  const role = catalog.roles.get(raw);
+  if (!role || !role.classes.includes(cls)) throw new Error("unknown or class-mismatched task role; allowed: " + allowed.join(", "));
+  taskRoleText(role); // refuse an oversized complete notice before the board write
+  return role;
+}
+/** Role definitions are untrusted presentation, including their metadata. */
+export function taskRoleText(role: CatalogRole, review = false): string {
+  const text = `Task role ${role.id} [${role.layer}, ${role.hash}] (guidance; grants no authority):\n` + sanitize(review ? role.review : role.body).replace(/\[agent-hub\b/gi, "[peer-text");
+  if (text.length > 2000) throw new Error("task role guidance exceeds 2000 characters including its header");
+  return text;
+}

package/src/hub/roster.ts

@@ -0,0 +1,23 @@
+import { isSupportedPeer, type KnownPeer } from "./peer-catalog.ts";
+
+export type PeerRoster = Partial<Record<KnownPeer, boolean>>;
+// Default participation policy, not another catalog. New catalog members default off.
+const DEFAULT_ON: Partial<Record<KnownPeer, boolean>> = { claude: true, codex: true, kimi: true, local: true };
+
+export function peerRosterConfig(value: unknown): PeerRoster {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("roster must be an object of boolean peer values");
+  const roster: PeerRoster = {};
+  for (const [peer, on] of Object.entries(value)) {
+    if (!isSupportedPeer(peer)) throw new Error("roster contains an unsupported peer");
+    if (typeof on !== "boolean") throw new Error(`roster.${peer} must be a boolean`);
+    roster[peer] = on;
+  }
+  return roster;
+}
+
+/** External ids keep their existing admission rules; Pi's legacy switch is only its default. */
+export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean): boolean {
+  if (!isSupportedPeer(peer)) return true;
+  return roster[peer] ?? (peer === "pi" ? piEnabled : DEFAULT_ON[peer] ?? false);
+}

package/src/hub/routing.ts

@@ -210,7 +210,7 @@ export function currentRouting(cwd: string, log: (line: string) => void = () =>
   }
 }
 
-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[] {
@@ -248,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[];
@@ -272,6 +280,7 @@ 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.
@@ -281,11 +290,15 @@ export function assign(
   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);
@@ -371,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;
+}