@staix/agent-hub 0.12.45 → 0.13.0

package/src/hub/profiles.ts

@@ -10,6 +10,7 @@ export type ProfileName = (typeof PROFILE_NAMES)[number];
 export interface ProjectProfile {
   name: string; classes: Record<string, string>; plan_keys: string[]; role_text: Record<string, string>;
   catalog_roles: Record<string, string[]>; agents: string; example_checks: string[];
+  review_checklist?: string[];
 }
 const PROFILES: Record<ProfileName, ProjectProfile> = { dev, research, writing, general };
 export function profileName(raw: unknown): ProfileName {
@@ -34,10 +35,10 @@ export function resolveProfile(raw?: unknown, overrides?: unknown): ProjectProfi
   const original = projectProfile(raw);
   if (overrides === undefined) return original;
   if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) throw new Error("profile_overrides must be an object");
-  const data = overrides as Record<string, unknown>, allowed = new Set(["classes", "plan_keys", "role_text", "catalog_roles", "agents", "example_checks"]);
+  const data = overrides as Record<string, unknown>, allowed = new Set(["classes", "plan_keys", "role_text", "catalog_roles", "agents", "example_checks", "review_checklist"]);
   if (Object.keys(data).some(key => !allowed.has(key))) throw new Error("unknown profile override field");
   if (!Object.keys(data).length) return original;
-  const result: ProjectProfile = { ...original, classes: { ...original.classes }, plan_keys: [...original.plan_keys], role_text: { ...original.role_text }, catalog_roles: Object.fromEntries(Object.entries(original.catalog_roles).map(([peer, ids]) => [peer, [...ids]])), example_checks: [...original.example_checks] };
+  const result: ProjectProfile = { ...original, classes: { ...original.classes }, plan_keys: [...original.plan_keys], role_text: { ...original.role_text }, catalog_roles: Object.fromEntries(Object.entries(original.catalog_roles).map(([peer, ids]) => [peer, [...ids]])), example_checks: [...original.example_checks], ...(original.review_checklist ? { review_checklist: [...original.review_checklist] } : {}) };
   const text = (value: unknown, cap: number): string => { if (typeof value !== "string" || value.length > cap) throw new Error("profile text is missing or oversized"); return sanitize(value); };
   if (data.classes !== undefined) {
     if (!data.classes || typeof data.classes !== "object" || Array.isArray(data.classes) || Object.keys(data.classes).length > 32) throw new Error("profile classes must be a bounded base-class map");
@@ -63,6 +64,10 @@ export function resolveProfile(raw?: unknown, overrides?: unknown): ProjectProfi
     if (!Array.isArray(data.example_checks) || data.example_checks.length > 16) throw new Error("profile example_checks must be a bounded display list");
     result.example_checks = data.example_checks.map(value => text(value, 2000));
   }
+  if (data.review_checklist !== undefined) {
+    if (!Array.isArray(data.review_checklist) || !data.review_checklist.length || data.review_checklist.length > 16 || data.review_checklist.some(value => typeof value !== "string" || !value.trim() || value.length > 500)) throw new Error("profile review_checklist must be bounded checklist lines");
+    result.review_checklist = data.review_checklist.map(value => sanitize(value.trim()));
+  }
   return result;
 }
 

package/src/hub/release-worktree.ts

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import type { ReleaseGit } from "./sdlc-release.ts";
+
+/** Filter-free tracked checkout comparison. Unknown or transformed content refuses. */
+// ponytail: 4096 entries, 4 MiB/file, 32 MiB total and 250 ms; larger/gitlink/transformed checkouts require a future bounded artifact attestation.
+export function releaseTrackedClean(root: string, git: ReleaseGit): boolean {
+  const start = performance.now(), deadline = () => performance.now() - start <= 250;
+  const run = (args: string[]) => {
+    if (!deadline()) return;
+    const result = git(args);
+    return deadline() && result.code === 0 && Buffer.byteLength(result.stdout) <= 2 * 1024 * 1024 ? result.stdout : undefined;
+  };
+  try {
+    const base = resolve(root);
+    if (!lstatSync(base).isDirectory() || lstatSync(base).isSymbolicLink()) return false;
+    if (run(["diff-index", "--cached", "--quiet", "--no-ext-diff", "--no-textconv", "HEAD", "--"]) === undefined) return false;
+    const inventory = run(["ls-files", "--stage", "-z"]);
+    if (inventory === undefined || inventory && !inventory.endsWith("\0")) return false;
+    const entries = inventory ? inventory.slice(0, -1).split("\0") : [];
+    if (entries.length > 4096) return false;
+    let total = 0;
+    for (const entry of entries) {
+      if (!deadline()) return false;
+      const match = /^([0-7]{6}) ([0-9a-f]{40}) ([0-3])\t([\s\S]+)$/.exec(entry);
+      if (!match) return false;
+      const [, mode, oid, stage, name] = match;
+      if (stage !== "0" || !["100644", "100755", "120000"].includes(mode!)) return false;
+      if (!name || name.length > 4096 || name.startsWith("/") || name.includes("\\") || name.split("/").some(part => !part || part === "." || part === "..") || /[\p{Cc}]/u.test(name)) return false;
+      const file = resolve(base, name), within = relative(base, file);
+      if (!within || within === ".." || within.startsWith("../")) return false;
+      for (let parent = dirname(file); parent !== base; parent = dirname(parent)) {
+        if (!deadline()) return false;
+        const info = lstatSync(parent);
+        if (!info.isDirectory() || info.isSymbolicLink()) return false;
+      }
+      const before = lstatSync(file);
+      if (before.size > 4 * 1024 * 1024 || total + before.size > 32 * 1024 * 1024) return false;
+      let bytes: Buffer;
+      if (mode === "120000") {
+        if (!before.isSymbolicLink()) return false;
+        bytes = readlinkSync(file, { encoding: "buffer" });
+      } else {
+        if (!before.isFile() || before.isSymbolicLink() || !!(before.mode & 0o111) !== (mode === "100755")) return false;
+        bytes = readFileSync(file);
+      }
+      total += bytes.length;
+      if (bytes.length > 4 * 1024 * 1024 || total > 32 * 1024 * 1024 || !deadline()) return false;
+      const after = lstatSync(file);
+      if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) return false;
+      if (createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex") !== oid) return false;
+    }
+    return deadline();
+  } catch { return false; }
+}

package/src/hub/review-brief.ts

@@ -1,5 +1,7 @@
+import type { CodeFactResult, CodeSymbol } from "./code-facts.ts";
 import { childEnv } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
+import { symbolsOverlap } from "./symbol-normalizer.ts";
 
 /**
  * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same
@@ -10,6 +12,7 @@ import { hubGitSync } from "./git.ts";
 export interface BriefFile { path: string; status: string; oldPath?: string; insertions?: number; deletions?: number }
 export interface BriefExcluded { path: string; status: string; oldPath?: string; reason: string }
 export interface ReviewBrief {
+  symbols?: { state: "known" | "unknown"; complete?: boolean; files: {path:string; symbols:CodeSymbol[]}[]; planned: string[]; unplanned: string[]; unseen: string[] };
   head: string;
   /** The default branch the head is compared with: origin/HEAD, origin/main or origin/master. */
   base: string;
@@ -149,6 +152,38 @@ function attributes(cwd: string, source: string, paths: string[]): Map<string, {
   return out;
 }
 
+/** One plan name against one changed name: a qualified pair must be equal, otherwise the last segments are. Shared with the console's task detail (#684 2b). */
+export const planSymbolMatches = (left: string, right: string): boolean => symbolsOverlap(left, right);
+/** Project derived names through the host metadata screen before comparing or rendering them. */
+export function withCodeSymbols(brief:ReviewBrief,result:CodeFactResult<CodeSymbol[]>,plan:readonly string[]|undefined,publicMetadataText:(text:string)=>boolean):ReviewBrief {
+  const unknown={...brief,symbols:{state:"unknown" as const,files:[],planned:[],unplanned:[],unseen:[]}};
+  if(result.state!=="known")return unknown;
+  try {
+    const paths=new Set(brief.reviewable.map(file=>file.path));
+    const changed=result.value.filter(s=>!s.ambiguous && paths.has(s.path) && publicMetadataText(s.path) && publicMetadataText(s.name) && publicMetadataText(s.kind));
+    const planned=(plan??[]).filter(name=>publicMetadataText(name));
+    const matches=planSymbolMatches;
+    const names=[...new Set(changed.map(s=>s.name))];
+    return {...brief,symbols:{state:"known",complete:changed.length===result.value.length && brief.withheld===0,files:[...paths].map(path=>({path,symbols:changed.filter(s=>s.path===path)})),
+      planned:names.filter(name=>planned.some(p=>matches(p,name))),unplanned:names.filter(name=>!planned.some(p=>matches(p,name))),unseen:planned.filter(p=>!names.some(name=>matches(p,name)))}};
+  } catch { return unknown; }
+}
+
+function renderCodeSymbols(brief:ReviewBrief):string[] {
+  const symbols=brief.symbols;
+  if(!symbols)return [];
+  if(symbols.state === "unknown")return ["Changed symbols: unknown (optional code facts unavailable)."];
+  const lines=[
+    "Changed symbols (advisory; change: unknown):",
+    ...symbols.files.flatMap(file=>file.symbols.length ? file.symbols.map(symbol=>`- ${file.path}: ${symbol.name} (${symbol.kind}, lines ${symbol.line}${symbol.endLine === undefined ? "..unknown" : `..${symbol.endLine}`}; change: unknown)`) : [`- ${file.path}: no changed symbol observed`]),
+    `Changed and planned: ${symbols.planned.join(", ") || "none observed"}`,
+    `Changed, not planned: ${symbols.unplanned.join(", ") || "none observed"}`,
+    `Planned, not seen as changed: ${symbols.unseen.join(", ") || "none observed"}`,
+    "Ceiling: ripwire 0.6.7 does not report deleted symbols; these lists never establish plan conformance.",
+  ];
+  return Buffer.byteLength(lines.join("\n"))<=16000 ? lines : ["Changed symbols: unknown (advice exceeds 16000 bytes)."];
+}
+
 /** The brief as review text: what every reviewer reads and how it accounts for its coverage. */
 export function renderReviewBrief(brief: ReviewBrief): string {
   const file = (f: BriefFile) => `- ${f.oldPath ? `${f.oldPath} -> ` : ""}${f.path} (${f.status}${f.insertions !== undefined ? `, +${f.insertions} -${f.deletions}` : ""})`;
@@ -156,6 +191,7 @@ export function renderReviewBrief(brief: ReviewBrief): string {
     `Review brief: head ${brief.head} against ${brief.base} (merge base ${brief.mergeBase.slice(0, 12)}); ${brief.reviewable.length} reviewable, ${brief.excluded.length} excluded${brief.withheld ? `, ${brief.withheld} withheld by the privacy policy` : ""}.`,
     ...(brief.reviewable.length ? ["Reviewable:", ...brief.reviewable.map(file)] : ["Reviewable: none (record why in the note)."]),
     ...(brief.excluded.length ? ["Excluded (still read their diff when it matters):", ...brief.excluded.map(e => `- ${e.oldPath ? `${e.oldPath} -> ` : ""}${e.path} (${e.status}): ${e.reason}`)] : []),
+    ...renderCodeSymbols(brief),
     ...(brief.unlisted.length ? ["Not in the brief's list, read directly:", ...brief.unlisted.map(path => `- ${path}`)] : []),
     ...brief.ruleGroups.filter(g => g.sources.length).map(g => `Rules ${g.sources.join(" + ")} apply to: ${brief.ruleGroups.length === 1 ? "every reviewable file" : g.paths.join(", ")}`),
     ...(brief.rulesMissing.length ? ["Configured rules not loaded (read them in the repository):", ...brief.rulesMissing.map(m => `- ${m.source}: ${m.reason}`)] : []),

package/src/hub/sdlc-queue.ts

@@ -1,9 +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 { 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 { 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 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("-");
@@ -12,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 };
@@ -32,27 +40,34 @@ 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; 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);
+    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) {
@@ -70,8 +85,15 @@ export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: De
     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));
+      if (config.mode === "enforce") row.blockers.push(...planConformanceBlockers(conformance), ...testIntegrityBlockers(integrity));
     }
   }
   const dependencyEvidence = new Map<number, PrEvidence | undefined>(); let dependencyReads = 0;
@@ -115,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.ts

@@ -1,3 +1,4 @@
+import { parseIssueLabels, parseRedFirst, testIntegrityBlockers, type RedFirstReceipt, type TestIntegrity } from "./test-integrity.ts";
 import { planConformanceBlockers, type PlanConformance } from "./plan-conformance.ts";
 import { DEFAULT_MAX_NITS, findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CostPlan } from "./cost-governance.ts";
@@ -55,6 +56,7 @@ export interface SdlcReceipt {
   localHead?: string;
   localResult?: "passed" | "failed" | "unknown";
   observed?: number;
+  redFirst?: RedFirstReceipt;
 }
 export interface PrEvidence {
   head: string;
@@ -64,6 +66,8 @@ export interface PrEvidence {
   unresolved: number | null;
   pendingReviews: number | null;
   paths: string[];
+  fileChanges?: { path: string; change: string }[];
+  issueLabels?: { issue: number; labels: string[] | null };
   pathsComplete?: boolean;
   /** All affected path identities are represented; rename/copy destinations alone cannot certify S2. */
   typesComplete?: boolean;
@@ -178,7 +182,7 @@ export function loadSdlc(cwd: string, version?: string): SdlcConfig {
 export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined = undefined, config: SdlcConfig = sdlcConfig(undefined), version?: string): SdlcReceipt {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc receipt: expected an object");
   const raw = value as Record<string, unknown>;
-  for (const key of Object.keys(raw)) if (!["stage", "repo", "issue", "pr", "reviewedHead", "localHead", "localResult", "criteria", "phase"].includes(key)) throw new Error(`sdlc receipt.${key}: unsupported or externally observed field`);
+  for (const key of Object.keys(raw)) if (!["stage", "repo", "issue", "pr", "reviewedHead", "localHead", "localResult", "criteria", "phase", ...(config.mode !== "off" ? ["redFirst"] : [])].includes(key)) throw new Error(`sdlc receipt.${key}: unsupported or externally observed field`);
   if (raw.criteria !== undefined && raw.phase !== undefined) throw new Error("sdlc receipt: give criteria only; phase is its retired name");
   if (raw.phase !== undefined && version !== undefined && !olderThan(version, RETIRED_WORKFLOW_FROM)) throw new Error(`sdlc receipt.phase: retired in ${RETIRED_WORKFLOW_FROM} (#481); use criteria`);
   previous ??= { stage: config.stages[0] ?? "spec" };
@@ -199,6 +203,9 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
     if (!["passed", "failed", "unknown"].includes(String(raw.localResult))) throw new Error("sdlc receipt.localResult: expected passed, failed or unknown");
     next.localResult = raw.localResult as SdlcReceipt["localResult"];
   }
+  if (raw.redFirst !== undefined) next.redFirst = parseRedFirst(raw.redFirst);
+  // A test receipt never carries across a different linked issue or artifact.
+  if (raw.redFirst === undefined && (next.repo !== previous.repo || next.issue !== previous.issue || next.pr !== previous.pr)) delete next.redFirst;
   // An acceptance names one spec issue; relinking the receipt to another drops it (#481 S1).
   if (next.repo !== previous.repo || next.issue !== previous.issue) delete next.acceptance;
   // A new artifact cannot inherit another PR's review or local gate.
@@ -225,7 +232,7 @@ export function parsePrEvidence(value: unknown): PrEvidence {
   const paths = p.files.map((f: Record<string, unknown>) => { if (typeof f.path !== "string" || !f.path || f.path.length > 1000) throw new Error("PR readback: invalid file identity"); return f.path; });
   const completeTypes = p.files.every((file: Record<string, unknown>) => typeof file.changeType === "string" && ["ADDED", "DELETED", "MODIFIED", "CHANGED"].includes(file.changeType));
   // Rename/copy metadata exposes only its destination, never a complete inventory of affected identities.
-  return { head: p.headRefOid, state: p.state, checks, paths, pathsComplete: Number.isSafeInteger(p.changedFiles) && p.changedFiles >= 0 && p.changedFiles === paths.length, typesComplete: completeTypes, ...(typeof p.isDraft === "boolean" ? { draft: p.isDraft } : {}), ...(typeof p.baseRefName === "string" && p.baseRefName && p.baseRefName.length <= 200 && !/[\x00-\x1f\x7f]/.test(p.baseRefName) ? { base: p.baseRefName } : {}), ...(sha(p.baseRefOid) ? { baseHead: p.baseRefOid } : {}),
+  return { head: p.headRefOid, state: p.state, checks, paths, fileChanges: p.files.map((file: Record<string, unknown>) => ({ path: file.path as string, change: typeof file.changeType === "string" ? file.changeType : "UNKNOWN" })), pathsComplete: Number.isSafeInteger(p.changedFiles) && p.changedFiles >= 0 && p.changedFiles === paths.length, typesComplete: completeTypes, ...(typeof p.isDraft === "boolean" ? { draft: p.isDraft } : {}), ...(typeof p.baseRefName === "string" && p.baseRefName && p.baseRefName.length <= 200 && !/[\x00-\x1f\x7f]/.test(p.baseRefName) ? { base: p.baseRefName } : {}), ...(sha(p.baseRefOid) ? { baseHead: p.baseRefOid } : {}),
     review: p.reviewDecision === "APPROVED" ? "approved" : p.reviewDecision === "CHANGES_REQUESTED" ? "changes_requested" : "unknown",
     pendingReviews: Array.isArray(p.reviewRequests) && p.reviewRequests.length <= 100 && p.reviewRequests.every((r: unknown) => !!r && typeof r === "object") ? p.reviewRequests.length : null,
     unresolved: Number.isSafeInteger(p.unresolvedThreads) && p.unresolvedThreads >= 0 ? p.unresolvedThreads : null,
@@ -248,16 +255,16 @@ export const SPEC_STATE_TEXT: Record<Exclude<SpecState, "current">, string> = {
   changed: "spec changed after acceptance: the person re-accepts with ahub sdlc accept <task> --issue <n>",
   unknown: "spec edit time unknown: the issue could not be read",
 };
-export interface SdlcStatus { planConformance?: PlanConformance & { accepted?: boolean; earlierPushes?: "unknown"; revisionsAfterFirstObservedPush?: number }; findings?: ReviewFindingTally; spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
+export interface SdlcStatus { testIntegrity?: TestIntegrity; planConformance?: PlanConformance & { accepted?: boolean; earlierPushes?: "unknown"; revisionsAfterFirstObservedPush?: number }; findings?: ReviewFindingTally; spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
 /** The acceptance-criteria checklist (#481 S8, Compliance pass) counts once recorded, and on every task under the retired gsd-lite setting. Off keeps #257's output. */
 export const criteriaRequired = (config: SdlcConfig, receipt: SdlcReceipt | undefined): boolean => config.workflow === "gsd-lite" || (config.mode !== "off" && !!checklistOf(receipt));
-export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit, sets: readonly ReviewFindingSet[] = [], commit?: string, plan?: SdlcStatus["planConformance"]): SdlcStatus {
+export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit, sets: readonly ReviewFindingSet[] = [], commit?: string, plan?: SdlcStatus["planConformance"], integrity?: TestIntegrity): SdlcStatus {
   const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
   const definition = stageDefinition(config, stage);
   const items = findingsForHead(sets, findingHead(receipt, evidence, commit));
   const findings = items.length ? findingTally(items) : undefined;
   if (config.mode === "enforce" && findings?.openImportant) blockers.push("open important review findings: " + findings.openImportant);
-  if (config.mode === "enforce") blockers.push(...planConformanceBlockers(plan));
+  if (config.mode === "enforce") blockers.push(...planConformanceBlockers(plan), ...testIntegrityBlockers(integrity));
   if (!definition) blockers.push("lifecycle stage definition unknown");
   if (!receipt?.repo || !receipt.issue) blockers.push("issue identity missing");
   if (!receipt?.pr) blockers.push("PR identity missing");
@@ -283,9 +290,10 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
   const shown = criteria && (criteriaRequired(config, receipt) || definition && [...definition.entry_gates, ...definition.exit_gates].includes("criteria"));
   // Shown, not counted as a readiness blocker: the spec gate is build entry (#481 S1).
   const spec = config.mode !== "off" && receipt?.issue ? { spec: { issue: receipt.issue, state: specState(receipt, specEdit) } } : {};
-  return { ...spec, ...(config.mode !== "off" && plan ? { planConformance: plan } : {}), ...(findings ? { findings } : {}), ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
+  return { ...spec, ...(config.mode !== "off" && integrity ? { testIntegrity: integrity } : {}), ...(config.mode !== "off" && plan ? { planConformance: plan } : {}), ...(findings ? { findings } : {}), ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
     actor: !definition ? "person" : shown && criteria.blockers.length ? "reviewer/person" : config.definitions ? definition.actor : baseActor(definition.base),
-    next: blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
+    // #694: the identity blocker keeps its exact text for gate matching; the next step says how to supply it.
+    next: blockers[0] === "issue identity missing" ? "issue identity missing: name one issue (title #N, refs or hub_sdlc_record)" : blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
 }
 
 function stageGates(def: StageDefinition, blockers: string[], checklist: string[]): { entry: string[]; exit: string[] } {
@@ -337,23 +345,53 @@ export async function readSpecEdit(repoName: string, issue: number, run: SdlcGh
   } catch { return undefined; }
 }
 
-export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Promise<PrEvidence | undefined> {
+/**
+ * #694: the one open PR whose head is `commit`, or, with no commit, whose branch is `branch`. Zero or several matches, a
+ * failed read or malformed output give undefined: the hub links only what it verified, never text an agent wrote.
+ */
+export async function openPrFor(repository: string, head: { commit?: string; branch?: string }, run: SdlcGh = sdlcGh): Promise<number | undefined> {
+  if (!repo(repository) || head.commit !== undefined && !sha(head.commit) || !head.commit && !head.branch) return undefined;
+  try {
+    const listed = await run(["pr", "list", "--repo", repository, "--state", "open", "--limit", "100", "--json", "number,headRefOid,headRefName"], 10_000, undefined, 256 * 1024);
+    if (listed.code !== 0) return undefined;
+    const rows: unknown = JSON.parse(listed.stdout);
+    // A full page may be truncated: uniqueness is unknown, so nothing is linked. Every row must be well formed.
+    if (!Array.isArray(rows) || rows.length >= 100) return undefined;
+    if (!rows.every((row: { number?: unknown; headRefOid?: unknown; headRefName?: unknown }) => id(row?.number) && sha(row.headRefOid) && typeof row.headRefName === "string")) return undefined;
+    const hits = rows.filter((row: { headRefOid: string; headRefName: string }) => head.commit ? row.headRefOid === head.commit : row.headRefName === head.branch);
+    return hits.length === 1 ? (hits[0] as { number: number }).number : undefined;
+  } catch { return undefined; }
+}
+/** #694: the first link of an issue or PR is not a relink: it keeps everything the receipt already holds. */
+export function linkedReceipt(previous: SdlcReceipt | undefined, link: { repo: string; issue?: number; pr?: number }, config: SdlcConfig): SdlcReceipt | undefined {
+  if (!repo(link.repo) || link.issue !== undefined && !id(link.issue) || link.pr !== undefined && !id(link.pr)) return undefined;
+  if (previous?.repo && previous.repo.toLowerCase() !== link.repo.toLowerCase()) return undefined;
+  if (link.issue !== undefined && previous?.issue !== undefined || link.pr !== undefined && previous?.pr !== undefined) return undefined;
+  return { ...(previous ?? { stage: config.stages[0] ?? "spec" }), repo: previous?.repo ?? link.repo, ...(link.issue !== undefined ? { issue: link.issue } : {}), ...(link.pr !== undefined ? { pr: link.pr } : {}) };
+}
+
+export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh, withIntegrity = false): Promise<PrEvidence | undefined> {
   if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
   try {
     const view = await run(["pr", "view", String(receipt.pr), "--repo", receipt.repo, "--json", "headRefOid,state,statusCheckRollup,reviewDecision,reviewRequests,files,changedFiles,mergeCommit,isDraft,baseRefName,baseRefOid"]);
     if (view.code !== 0) return undefined;
     const [owner, name] = receipt.repo.split("/");
-    const threads = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid reviewThreads(first:100){nodes{isResolved} pageInfo{hasNextPage}}}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${receipt.pr}`]);
+    // The enabled S4 label read shares the existing thread snapshot, never a second readback for a known non-bug.
+    const labels = withIntegrity && id(receipt.issue) ? { issue: receipt.issue, labels: null as string[] | null } : undefined;
+    const query = `query($owner:String!,$name:String!,$number:Int!${labels ? ",$issue:Int!" : ""}){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid reviewThreads(first:100){nodes{isResolved} pageInfo{hasNextPage}}}${labels ? " issue(number:$issue){number labels(first:100){nodes{name} pageInfo{hasNextPage}}}" : ""}}}`;
+    const threads = await run(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, ...(labels ? ["-F", `issue=${labels.issue}`] : []), "-F", `number=${receipt.pr}`]);
     const p = JSON.parse(view.stdout);
     delete p.unresolvedThreads; // only the complete thread query can establish this fact
     if (threads.code === 0) {
-      const current = JSON.parse(threads.stdout)?.data?.repository?.pullRequest;
+      const response = JSON.parse(threads.stdout);
+      const current = response?.data?.repository?.pullRequest;
+      if (labels && response.errors === undefined) labels.labels = parseIssueLabels(response?.data?.repository?.issue, labels.issue) ?? null;
       const nodes = current?.reviewThreads?.nodes;
       // Paginated or malformed thread data is unknown, never a clean review.
       if (current?.headRefOid === p.headRefOid && current?.reviewThreads?.pageInfo?.hasNextPage === false && Array.isArray(nodes) && nodes.every(n => typeof n?.isResolved === "boolean")) p.unresolvedThreads = nodes.filter(n => !n.isResolved).length;
       else if (current?.headRefOid && current.headRefOid !== p.headRefOid) return undefined;
     }
-    return parsePrEvidence(p);
+    return { ...parsePrEvidence(p), ...(labels ? { issueLabels: labels } : {}) };
   } catch { return undefined; }
 }