@staix/agent-hub 0.12.44 → 0.13.0

package/src/hub/review-findings.ts

@@ -0,0 +1,104 @@
+import { types } from "node:util";
+import { sanitize } from "./envelope.ts";
+
+export interface ReviewFinding {
+  id: string;
+  pass: "bugs" | "security" | "compliance";
+  severity: "important" | "nit";
+  path?: string;
+  disposition: "open" | "fixed" | "false_positive" | "accepted";
+  rationale?: string;
+}
+export interface ReviewFindingSet { head?: string; items: ReviewFinding[] }
+export interface ReviewFindingTally { important: number; nit: number; openImportant: number; openNit: number; fixed: number; falsePositive: number; accepted: number }
+export const DEFAULT_MAX_NITS = 5;
+const MAX_ITEMS = 64, MAX_BYTES = 64 * 1024;
+const fail = (reason: string): never => { throw new Error("review findings: " + reason); };
+function fields(raw: unknown): Record<string, PropertyDescriptor> {
+  if (!raw || typeof raw !== "object" || types.isProxy(raw) || Array.isArray(raw)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(raw)) || Object.getOwnPropertySymbols(raw).length) return fail("plain own-data finding required");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.values(descriptors).some(field => !Object.hasOwn(field, "value") || !field.enumerable)) return fail("accessors and hidden fields refused");
+  if (Object.keys(descriptors).some(key => !["id", "pass", "severity", "path", "disposition", "rationale"].includes(key))) return fail("unknown finding field");
+  return descriptors;
+}
+function text(raw: unknown, max: number, path: boolean): string {
+  if (typeof raw !== "string" || !raw.trim() || Buffer.byteLength(raw) > max
+    || path && /[\p{Cc}\p{Cf}]/u.test(raw)) return fail("invalid bounded finding text");
+  const clean = sanitize(raw.trim());
+  if (Buffer.byteLength(clean) > max) return fail("sanitized finding text exceeds its bound");
+  return clean;
+}
+/** Supplied findings are validated independently of lifecycle mode, before any board effect. */
+export function parseReviewFindings(raw: unknown, options: { person: boolean; maxNits: number }): ReviewFinding[] {
+  if (typeof options.person !== "boolean" || !Number.isSafeInteger(options.maxNits) || options.maxNits < 0 || options.maxNits > MAX_ITEMS) return fail("invalid finding authority or nit limit");
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw) || types.isProxy(raw) || Object.getPrototypeOf(raw) !== Array.prototype
+    || Object.getOwnPropertySymbols(raw).length || raw.length > MAX_ITEMS) return fail("at most 64 own-data findings required");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.keys(descriptors).length !== raw.length + 1) return fail("dense finding array required");
+  const ids = new Set<string>();
+  const result = Array.from({ length: raw.length }, (_, index): ReviewFinding => {
+    const entry = descriptors[String(index)];
+    if (!entry || !Object.hasOwn(entry, "value") || !entry.enumerable) return fail("finding array accessors refused");
+    const item = fields(entry.value), id: unknown = item.id?.value, pass: unknown = item.pass?.value;
+    const severity: unknown = item.severity?.value, disposition: unknown = item.disposition?.value;
+    if (typeof id !== "string" || !/^[A-Za-z0-9._:-]+$/.test(id) || Buffer.byteLength(id) > 96 || ids.has(id)) return fail("invalid or duplicate finding id");
+    ids.add(id);
+    if (pass !== "bugs" && pass !== "security" && pass !== "compliance") return fail("invalid finding pass");
+    if (severity !== "important" && severity !== "nit") return fail("invalid finding severity");
+    if (disposition !== "open" && disposition !== "fixed" && disposition !== "false_positive" && disposition !== "accepted") return fail("invalid finding disposition");
+    const path = item.path ? text(item.path.value, 512, true) : undefined;
+    const rationale = item.rationale ? text(item.rationale.value, 2048, false) : undefined;
+    if (disposition === "accepted" && (!options.person || !rationale)) return fail("accepted findings require a person and rationale");
+    return { id, pass, severity, disposition, ...(path !== undefined ? { path } : {}), ...(rationale !== undefined ? { rationale } : {}) };
+  });
+  if (result.filter(item => item.severity === "nit").length > options.maxNits) return fail("nit limit exceeded");
+  if (Buffer.byteLength(JSON.stringify(result)) > MAX_BYTES) return fail("finding report exceeds 64 KiB");
+  return result;
+}
+
+/** Prefer live artifact identity, skipping malformed historical candidates rather than hiding a valid fallback. */
+export function findingHead(receipt?: { head?: string; reviewedHead?: string; localHead?: string }, evidence?: { head: string }, commit?: string): string | undefined {
+  return [evidence?.head, receipt?.head, receipt?.reviewedHead, receipt?.localHead, commit]
+    .find((head): head is string => typeof head === "string" && /^[a-f0-9]{40}$/.test(head));
+}
+
+/**
+ * Nits belong only to their head bucket, including the explicit undefined bucket.
+ * Open Important is an obligation across heads until an explicit disposition resolves its ID globally.
+ */
+export function findingsForHead(sets: readonly ReviewFindingSet[], head?: string): ReviewFinding[] {
+  interface Entry { item: ReviewFinding; order: number }
+  const current = new Map<string, Entry>(), important = new Map<string, Entry>();
+  let order = 0;
+  for (const set of sets) for (const item of set.items) {
+    const key = item.id, position = order++;
+    if (set.head === head) current.set(key, { item: { ...current.get(key)?.item, ...item }, order: position });
+    const prior = important.get(key);
+    if (item.severity === "important") {
+      important.set(key, { item: { ...prior?.item, ...item }, order: position });
+    } else if (prior && (prior.item.disposition === "open" || item.disposition !== "open")) {
+      // A nit/open reclassification cannot discharge Important. An explicit disposition can.
+      important.set(key, { item: { ...prior.item, ...item, severity: "important" }, order: position });
+    }
+  }
+  for (const [key, entry] of important) {
+    if (entry.item.disposition === "open") current.set(key, entry);
+    else {
+      const seen = current.get(key);
+      // Settling on B also settles older A when A is queried again. A later new nit/open remains a head-local nit.
+      if (seen?.item.disposition === "open" && seen.order <= entry.order) current.delete(key);
+    }
+  }
+  return [...current.values()].map(entry => ({ ...entry.item }));
+}
+export function findingTally(items: readonly ReviewFinding[]): ReviewFindingTally {
+  const tally: ReviewFindingTally = { important: 0, nit: 0, openImportant: 0, openNit: 0, fixed: 0, falsePositive: 0, accepted: 0 };
+  for (const item of items) {
+    tally[item.severity]++;
+    if (item.disposition === "open") tally[item.severity === "important" ? "openImportant" : "openNit"]++;
+    else tally[item.disposition === "false_positive" ? "falsePositive" : item.disposition]++;
+  }
+  return tally;
+}

package/src/hub/roster.ts

@@ -1,15 +1,41 @@
 import { definitionOf as builtinDefinitionOf, type ProjectAdapterCatalog, type KindMap } from "../adapters/registry.ts";
-import { defaultRosterEnabled as builtinDefaultRosterEnabled } from "../adapters/registry.ts";
+import { validateInstances } from "./instances.ts";
+import { defaultRosterEnabled as builtinDefaultRosterEnabled, createProjectAdapterCatalog as builtinCatalog } from "../adapters/registry.ts";
 
 export type PeerRoster = Partial<Record<string, boolean>>;
 
-export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog): PeerRoster {
+/**
+ * A roster key of an instance that was declared, put on the roster and later undeclared (#225). It has the shape a declaration
+ * could have had (`<builtin kind>-<name>`, the rule validateInstances applies to an id) and no definition now, so it grants and
+ * refuses nothing: the config still loads and `ahub roster remove` can delete it. Anything else stays an unsupported peer.
+ */
+export function staleInstanceKey(peer: string, catalog: ProjectAdapterCatalog | undefined): boolean {
+  const definitionOf = catalog?.definitionOf ?? builtinDefinitionOf;
+  if (!/^[a-z][a-z0-9-]{0,31}$/.test(peer) || definitionOf(peer)) return false; // a reserved id (user, hub, digest) never starts with a kind and a dash
+  if (!catalog) return false;
+  return catalog.definitions.some(kind => peer.startsWith(`${kind.kind}-`) && /^[a-z0-9][a-z0-9-]*$/.test(peer.slice(kind.kind.length + 1)) && canDeclareInstance(peer, kind.kind, catalog) && !catalog.externalDefinitions.some(item => item.kind === kind.kind));
+}
+
+/** The declarations a person can write for an extra instance of a kind: validateInstances decides which of them its definition takes. */
+const DECLARATION_SHAPES: readonly Record<string, unknown>[] = [
+  { roles: ["implementer"], start_mode: "headless" }, { roles: ["reviewer"], start_mode: "headless" }, { roles: ["reviewer"] }, { roles: ["planner"] },
+];
+
+/** Whether validateInstances would take `<kind>-<name>` for this kind under any declaration, so the answer cannot drift from its policy. */
+function canDeclareInstance(id: string, kind: string, catalog: ProjectAdapterCatalog): boolean {
+  return DECLARATION_SHAPES.some(shape => { try { validateInstances({ [id]: { kind, ...shape } }, catalog); return true; } catch { return false; } });
+}
+
+export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog, inertUnknown = false): PeerRoster {
   const definitionOf = catalog?.definitionOf ?? builtinDefinitionOf;
   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 = {};
+  const requireKnownPeer = (peer: string) => {
+    if (!definitionOf(peer, instances) && !staleInstanceKey(peer, catalog ?? builtinCatalog())) throw new Error("roster contains an unsupported peer");
+  };
   for (const [peer, on] of Object.entries(value)) {
-    if (!definitionOf(peer, instances)) throw new Error("roster contains an unsupported peer");
+    if (!inertUnknown || !/^[a-z][a-z0-9-]{0,31}$/.test(peer)) requireKnownPeer(peer);
     if (typeof on !== "boolean") throw new Error(`roster.${peer} must be a boolean`);
     roster[peer] = on;
   }
@@ -17,10 +43,10 @@ export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?:
 }
 
 /** External ids keep their existing admission rules; Pi's legacy switch is only its default. */
-export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances: KindMap | undefined, catalog: ProjectAdapterCatalog): boolean {
+export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances: KindMap | undefined, catalog: ProjectAdapterCatalog, inertUnknown = false): boolean {
   const definitionOf = catalog.definitionOf;
   const defaultRosterEnabled = (id: string, enabled: boolean) => !builtinDefinitionOf(id) ? catalog.definitionOf(id)?.defaultOnRoster ?? false : builtinDefaultRosterEnabled(id, enabled);
   const definition = definitionOf(peer, instances);
-  if (!definition) return true; // External clients do not acquire a native kind from a project declaration.
+  if (!definition) return !inertUnknown || !Object.hasOwn(roster, peer); // Only a captured module scope makes unresolved rows inert; legacy external clients keep their admission rules.
   return roster[peer] ?? (definition.kind === peer ? defaultRosterEnabled(peer, piEnabled) : true);
 }

package/src/hub/sdlc-queue.ts

@@ -1,7 +1,10 @@
+import { publicTestIntegrity, parseIssueLabels, readTestIntegrity, testIntegrityBlockers, type TestIntegrity } from "./test-integrity.ts";
+import { planConformance, planConformanceBlockers } from "./plan-conformance.ts";
+import { findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CriteriaView } 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?: CriteriaView; }
-export interface MergeQueueRow { pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
+export interface DeliveryTask { plan?: { paths?: string[]; revision: number; fingerprint: string; accepted: { repo: string; pr: number; head: string; revision: number; fingerprint: string; paths: string[] }[] }; findings?: readonly ReviewFindingSet[]; id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
+export interface MergeQueueRow { testIntegrity?: (TestIntegrity & { task?: number })[]; planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; 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("-");
@@ -10,13 +13,20 @@ const parseSnapshot = (reply: { code: number; stdout: string }): { number: numbe
   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 });
+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, ...(p.issueLabels ? { issue: p.issueLabels.issue, bug: p.issueLabels.labels?.some(name => name.toLowerCase() === "bug") ?? "unknown" } : {}) });
 /** 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> }> {
+async function finalSnapshot(repo: string, evidence: Map<number, PrEvidence>, run: SdlcGh, issues: Map<number, TestIntegrity["applicability"]>): Promise<{ gatesStable: boolean; prs?: ReturnType<typeof parseSnapshot> }> {
+  // ponytail: one snapshot verifies at most 32 linked issues; paginate within the same deadline if queues grow.
+  if (issues.size > 32) return { gatesStable: false };
   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(" ")}}}`;
+  const issueAlias = (issue: number) => {
+    const primary = entries.find(([, value]) => value.issueLabels?.issue === issue);
+    return primary ? `queue_i${primary[0]}` : `queue_issue${issue}`;
+  };
+  const extraIssues = [...issues.keys()].filter(issue => !entries.some(([, value]) => value.issueLabels?.issue === issue));
+  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, before]) => `queue_p${id}:pullRequest(number:${id}){${fields}}${before.issueLabels ? ` queue_i${id}:issue(number:${before.issueLabels.issue}){number labels(first:100){nodes{name} pageInfo{hasNextPage}}}` : ""}`).join(" ")} ${extraIssues.map(issue => `${issueAlias(issue)}:issue(number:${issue}){number labels(first:100){nodes{name} pageInfo{hasNextPage}}}`).join(" ")}}}`;
   try {
     const reply = await run(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`]);
     if (reply.code !== 0) return { gatesStable: false };
@@ -30,34 +40,61 @@ async function finalSnapshot(repo: string, evidence: Map<number, PrEvidence>, ru
       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 (before.issueLabels) after.issueLabels = { issue: before.issueLabels.issue, labels: parseIssueLabels(data.data.repository[`queue_i${id}`], before.issueLabels.issue) ?? null };
       if (gateIdentity(before) !== gateIdentity(after)) return { gatesStable: false, prs };
     }
+    for (const [issue, expected] of issues) {
+      const labels = parseIssueLabels(data.data.repository[issueAlias(issue)], issue);
+      const current = labels === undefined ? "unknown" : labels.some(name => name.toLowerCase() === "bug") ? "bug" : "not_bug";
+      if (current !== expected) 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> {
+export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: DeliveryTask[], run: SdlcGh = sdlcGh, readableMetadata?: (path: string) => boolean): 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 bounded: SdlcGh = (args, timeout, cwd, cap) => { const remaining = deadline - performance.now(); return remaining > 0 ? run(args, Math.min(timeout ?? 10_000, remaining), cwd, cap) : 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[]>();
+  const issueApplicability = new Map<number, TestIntegrity["applicability"]>();
   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 (holders.some(t => t.private)) { row.private = true; if (config.mode !== "off") row.planConformance = [{ state: "unknown", outside: 0, untouched: 0, accepted: false }]; row.blockers.push("private lifecycle evidence unavailable"); continue; }
+    const read = await readSdlcPr(holders[0]?.receipt ?? { stage: config.stages[0] ?? "spec", repo, pr }, bounded, config.mode !== "off");
     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;
+    for (const holder of holders) {
+      const items = findingsForHead(holder.findings ?? [], findingHead(holder.receipt, read));
+      if (!items.length) continue;
+      const tally = findingTally(items);
+      row.findings ??= findingTally([]);
+      for (const key of Object.keys(tally) as (keyof ReviewFindingTally)[]) row.findings[key] += tally[key];
+    }
     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);
+    if (config.mode === "enforce" && row.findings?.openImportant) row.blockers.push("open important review findings: " + row.findings.openImportant);
+    for (const holder of linked) {
+      const conformance = holder?.plan ? { ...planConformance(holder.plan.paths, read), accepted: holder.plan.accepted.some(item => item.repo === holder.receipt?.repo && item.pr === holder.receipt?.pr && item.head === read.head && item.revision === holder.plan!.revision && item.fingerprint === holder.plan!.fingerprint && JSON.stringify([...item.paths].sort()) === JSON.stringify([...read.paths].sort())) } : undefined;
+      if (holder && conformance && config.mode !== "off") (row.planConformance ??= []).push({ task: holder.id, state: conformance.state, outside: conformance.outside.length, untouched: conformance.untouched.length, accepted: conformance.accepted });
+      const rawIntegrity = config.mode !== "off" && holder?.receipt ? await readTestIntegrity(holder.receipt, read, bounded) : undefined;
+      if (rawIntegrity && holder?.receipt?.issue) {
+        const issue = holder.receipt.issue, before = issueApplicability.get(issue);
+        issueApplicability.set(issue, before !== undefined && before !== rawIntegrity.applicability ? "unknown" : rawIntegrity.applicability);
+      }
+      const integrity = rawIntegrity ? publicTestIntegrity(rawIntegrity, readableMetadata) : undefined;
+      if (integrity) (row.testIntegrity ??= []).push({ task: holder!.id, ...integrity });
+      row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+      if (config.mode === "enforce") row.blockers.push(...planConformanceBlockers(conformance), ...testIntegrityBlockers(integrity));
+    }
   }
   const dependencyEvidence = new Map<number, PrEvidence | undefined>(); let dependencyReads = 0;
   for (const row of result.rows) {
@@ -100,7 +137,7 @@ export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: De
   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 finalRead = await finalSnapshot(repo, evidence, bounded, issueApplicability);
     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))) {

package/src/hub/sdlc-release-authorization.ts

@@ -0,0 +1,173 @@
+import { releaseTrackedClean } from "./release-worktree.ts";
+import { createHash, randomUUID } from "node:crypto";
+import { USER } from "./envelope.ts";
+import { hubGitEnv, hubGitSync } from "./git.ts";
+import { readDocEvidence, type DocEvidence, type ReleaseGit, type ReleaseReadiness } from "./sdlc-release.ts";
+import type { SdlcGh } from "./sdlc.ts";
+import type { ReleaseGuardRequest, ReleasePushUpdate } from "../cli/sdlc-release-guard.ts";
+
+class ReleaseAuthorizationError extends Error {}
+export const releaseAuthorizationError = (error: unknown): string => error instanceof ReleaseAuthorizationError ? error.message : "release authorization evidence unavailable";
+
+const SHA = /^[0-9a-f]{40}$/;
+const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export const validReleaseVersion = (value: unknown): value is string => typeof value === "string" && value.length <= 128 && VERSION.test(value);
+export interface ReleaseDocsVerdict { fresh: true; errors: 0; documents: number; digest: string }
+export interface ReleaseAuthorization { schemaVersion: 1; id: string; by: typeof USER; commit: string; version: string; at: number; docs: ReleaseDocsVerdict }
+export interface ReleaseAuthorizationPorts {
+  git?: ReleaseGit;
+  docs?: (root: string) => Promise<DocEvidence | undefined>;
+  gh?: SdlcGh;
+  now?: () => number;
+  current?: () => boolean;
+  record: (receipt: ReleaseAuthorization) => boolean;
+}
+export type ReleaseGuardVerdict = { ok: true; receipts: ReleaseAuthorization[] } | { ok: false; error: string };
+interface Origin { hash: string; urls: string[]; repo?: string }
+interface Entry { receipt: ReleaseAuthorization; origin: Origin }
+const digest = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function docsVerdict(value: DocEvidence | undefined, commit: string, version: string): ReleaseDocsVerdict | undefined {
+  if (!value || value.schemaVersion !== 1 || value.head !== commit || value.version !== version || value.fresh !== true || value.errors !== 0
+    || !Array.isArray(value.documents) || value.documents.length > 128 || value.documents.some(row => row.state !== "fresh" || row.dirty === true)) return;
+  // Paths may be withheld in a public release report; the commit binds their identities, not this projection.
+  const rows = value.documents.map(({ state, verifiedAgainst, commits, dirty }) => ({ state, verifiedAgainst, commits, dirty })).map(row => JSON.stringify(row)).sort();
+  return { fresh: true, errors: 0, documents: rows.length, digest: digest({ commit, version, rows }) };
+}
+function githubRepo(url: string): string | undefined {
+  const match = url.match(/^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?\/?$/);
+  return match?.[1];
+}
+
+/** Host-owned consent, never imported from a task receipt or an agent-writable file. Restart revokes it. */
+export class ReleaseAuthorizations {
+  private readonly entries = new Map<string, Entry>();
+  private latest?: Entry;
+  constructor(private readonly root: string, private readonly ports: ReleaseAuthorizationPorts) {}
+  private current(): void { if (this.ports.current?.() === false) throw new ReleaseAuthorizationError("release authorization unavailable during lifecycle transition"); }
+  private git(): ReleaseGit {
+    let remaining = 5000;
+    return args => {
+      if (remaining <= 0) return { code: 1, stdout: "" };
+      const start = performance.now();
+      try {
+        if (this.ports.git) return this.ports.git(args);
+        const result = hubGitSync(args, { cwd: this.root, env: hubGitEnv(process.env, { repositoryIsolation: true }), encoding: "utf8", timeout: Math.max(1, Math.min(1000, remaining)), maxBuffer: 256 * 1024 });
+        return { code: result.status ?? 1, stdout: result.stdout ?? "" };
+      } finally { remaining -= performance.now() - start; }
+    };
+  }
+  private read(git: ReleaseGit, args: string[]): string {
+    const result = git(args);
+    if (result.code !== 0 || Buffer.byteLength(result.stdout) > 256 * 1024) throw new ReleaseAuthorizationError("release target evidence unavailable");
+    return result.stdout.trim();
+  }
+  private origin(git: ReleaseGit, remote = "origin"): Origin {
+    if (!/^[A-Za-z0-9_.-]{1,128}$/.test(remote) || remote.startsWith("-")) throw new ReleaseAuthorizationError("release guard requires a configured named remote");
+    const urls = this.read(git, ["remote", "get-url", "--push", "--all", remote]).split("\n");
+    if (!urls.length || urls.length > 8 || urls.some(url => !url || url.length > 4096 || /[\p{Cc}]/u.test(url))) throw new ReleaseAuthorizationError("release remote identity unavailable");
+    const sorted = [...new Set(urls)].sort();
+    const fetch = this.read(git, ["remote", "get-url", "--all", remote]).split("\n");
+    if (!fetch.length || fetch.length > 8 || fetch.some(url => !url || url.length > 4096 || /[\p{Cc}]/u.test(url))) throw new ReleaseAuthorizationError("release remote identity unavailable");
+    const repos = [...sorted, ...fetch].map(githubRepo);
+    return { hash: digest({ push: sorted, fetch: [...new Set(fetch)].sort() }), urls: sorted, ...(repos[0] && repos.every(repo => repo === repos[0]) ? { repo: repos[0] } : {}) };
+  }
+  private commit(git: ReleaseGit, ref: string): string {
+    if (!ref || ref.length > 256 || ref.startsWith("-") || /[\s\p{Cc}]/u.test(ref)) throw new ReleaseAuthorizationError("invalid release source ref");
+    const commit = this.read(git, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]);
+    if (!SHA.test(commit)) throw new ReleaseAuthorizationError("release commit unavailable");
+    return commit;
+  }
+  private version(git: ReleaseGit, commit: string): string {
+    if (!SHA.test(commit)) throw new ReleaseAuthorizationError("invalid release commit");
+    let value: unknown;
+    try { value = JSON.parse(this.read(git, ["show", `${commit}:package.json`])).version; } catch { throw new ReleaseAuthorizationError("committed package version unavailable"); }
+    if (!validReleaseVersion(value)) throw new ReleaseAuthorizationError("committed package version unavailable");
+    return value;
+  }
+  async authorize(by: string, version: unknown, expectedCommit: unknown): Promise<ReleaseAuthorization> {
+    if (by !== USER) throw new ReleaseAuthorizationError("only the person may authorize a release");
+    if (!validReleaseVersion(version) || typeof expectedCommit !== "string" || !SHA.test(expectedCommit)) throw new ReleaseAuthorizationError("authorization needs an exact version and candidate commit");
+    this.current();
+    const git = this.git(), commit = this.commit(git, "HEAD"), origin = this.origin(git);
+    if (commit !== expectedCommit || this.version(git, commit) !== version) throw new ReleaseAuthorizationError("candidate commit or version differs from the person's request");
+    const docs = docsVerdict(await (this.ports.docs ?? readDocEvidence)(this.root), commit, version);
+    if (!docs) throw new ReleaseAuthorizationError("release authorization requires fresh committed documentation evidence");
+    this.current();
+    if (this.commit(git, "HEAD") !== commit || this.version(git, commit) !== version || this.origin(git).hash !== origin.hash) throw new ReleaseAuthorizationError("release candidate changed during authorization");
+    const receipt: ReleaseAuthorization = { schemaVersion: 1, id: randomUUID(), by: USER, commit, version, at: (this.ports.now ?? Date.now)(), docs };
+    if (!this.ports.record(structuredClone(receipt))) throw new ReleaseAuthorizationError("release approval audit could not be recorded");
+    const entry = { receipt, origin };
+    this.entries.set(`${version}:${commit}`, entry); this.latest = entry;
+    // ponytail: retain at most 64 approvals in this daemon generation; older candidates need a new person approval.
+    if (this.entries.size > 64) this.entries.delete(this.entries.keys().next().value!);
+    return structuredClone(receipt);
+  }
+  private matched(git: ReleaseGit, version: string, commit: string, remote?: string, url?: string): ReleaseAuthorization {
+    this.current();
+    const entry = this.entries.get(`${version}:${commit}`);
+    if (!entry || this.version(git, commit) !== version) throw new ReleaseAuthorizationError("no matching person release authorization; ask the person to authorize this commit and version");
+    const origin = this.origin(git);
+    if (origin.hash !== entry.origin.hash || remote && this.origin(git, remote).hash !== origin.hash || url !== undefined && !origin.urls.includes(url)) throw new ReleaseAuthorizationError("release remote differs from the authorized project");
+    return structuredClone(entry.receipt);
+  }
+  async guardRequest(request: ReleaseGuardRequest): Promise<ReleaseGuardVerdict> {
+    try {
+      this.current(); const git = this.git();
+      if (request.kind === "tag-push") {
+        const commit = this.commit(git, request.sourceRef);
+        return { ok: true, receipts: [this.matched(git, request.version, commit, request.remote)] };
+      }
+      if (request.kind === "npm-publish") {
+        if (!releaseTrackedClean(this.root, git)) throw new ReleaseAuthorizationError("npm publish requires a clean tracked worktree");
+        const commit = this.commit(git, "HEAD"), version = this.version(git, commit);
+        const receipt = this.matched(git, version, commit);
+        const docs = docsVerdict(await (this.ports.docs ?? readDocEvidence)(this.root), commit, version);
+        this.current();
+        if (!docs || docs.digest !== receipt.docs.digest || this.commit(git, "HEAD") !== commit || !releaseTrackedClean(this.root, git)) throw new ReleaseAuthorizationError("publish checkout or documentation evidence changed");
+        return { ok: true, receipts: [this.matched(git, version, commit)] };
+      }
+      const origin = this.origin(git), repo = origin.repo;
+      if (!repo || !this.ports.gh) throw new ReleaseAuthorizationError("GitHub release target evidence unavailable");
+      const [owner, name] = repo.split("/");
+      const 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}}}}}}}";
+      const result = await this.ports.gh(["api", "graphql", "--hostname", "github.com", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-f", `ref=refs/tags/${request.tag}`], 10000);
+      let commit: string;
+      try {
+        const body = JSON.parse(result.stdout), repository = body?.data?.repository;
+        if (result.code !== 0 || body.errors || !repository || !Object.hasOwn(repository, "ref")) throw new ReleaseAuthorizationError();
+        if (repository.ref === null) {
+          if (!request.target || !SHA.test(request.target)) throw new ReleaseAuthorizationError();
+          commit = this.commit(git, request.target);
+        } else {
+          commit = repository.ref.target?.oid ?? repository.ref.target?.target?.oid;
+          if (!SHA.test(commit)) throw new ReleaseAuthorizationError();
+        }
+      } catch { throw new ReleaseAuthorizationError("GitHub tag unknown, or a new release lacks an explicit full commit target"); }
+      this.current();
+      if (this.origin(git).hash !== origin.hash) throw new ReleaseAuthorizationError("release remote changed during readback");
+      return { ok: true, receipts: [this.matched(git, request.version, commit)] };
+    } catch (error) { return { ok: false, error: releaseAuthorizationError(error) }; }
+  }
+  guardPush(remoteName: string, remoteUrl: string, updates: readonly ReleasePushUpdate[]): ReleaseGuardVerdict {
+    try {
+      this.current(); const git = this.git(), receipts: ReleaseAuthorization[] = [];
+      if (updates.length > 128) throw new ReleaseAuthorizationError("release push inventory exceeds the guard bound");
+      for (const update of updates) {
+        if (!validReleaseVersion(update.version) || update.remoteRef !== `refs/tags/v${update.version}` || !SHA.test(update.localOid) || /^0+$/.test(update.localOid)) throw new ReleaseAuthorizationError("release push target is invalid or deleted");
+        if (this.read(git, ["rev-parse", "--verify", "--end-of-options", update.localRef]) !== update.localOid) throw new ReleaseAuthorizationError("release tag changed after Git captured the push");
+        const commit = this.commit(git, update.localOid);
+        receipts.push(this.matched(git, update.version, commit, remoteName, remoteUrl));
+      }
+      return { ok: true, receipts };
+    } catch (error) { return { ok: false, error: releaseAuthorizationError(error) }; }
+  }
+  report<T extends ReleaseReadiness>(report: T): T & { authorization?: { state: "matched" | "stale"; receipt: ReleaseAuthorization } } {
+    if (!this.latest) return report;
+    const entry = this.entries.get(`${report.version}:${report.head}`), verdict = report.head && report.version ? docsVerdict(report.documents, report.head, report.version) : undefined;
+    let matched = !!entry && !!entry.origin.repo && entry.origin.repo.toLowerCase() === report.repo.toLowerCase() && !!verdict && verdict.digest === entry.receipt.docs.digest;
+    try { matched &&= this.origin(this.git()).hash === entry!.origin.hash; } catch { matched = false; }
+    const receipt = structuredClone((matched ? entry! : this.latest).receipt);
+    const blockers = matched ? report.blockers.map(item => item === "native acceptance and person release decision unverified" ? "native acceptance unverified" : item) : report.blockers;
+    return { ...report, blockers, authorization: { state: matched ? "matched" : "stale", receipt } };
+  }
+}

package/src/hub/sdlc-release.ts

@@ -4,7 +4,22 @@ 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";
+import type { SdlcGh } from "./sdlc.ts";
+// Standalone document evidence does not need lifecycle/review code; load the default remote reader only when used.
+let importDiagnosticShown = false;
+const sdlcGh: SdlcGh = async (...args) => {
+  let reader: typeof import("./sdlc.ts");
+  try { reader = await import("./sdlc.ts"); }
+  catch {
+    if (!importDiagnosticShown) {
+      importDiagnosticShown = true;
+      try { console.warn("sdlc: release evidence reader unavailable (lifecycle import failed)"); } catch { /* a diagnostic cannot turn unknown evidence into an exception */ }
+    }
+    return { code: 1, stdout: "" };
+  }
+  try { return await reader.sdlcGh(...args); }
+  catch { return { code: 1, stdout: "" }; }
+};
 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 };