@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2014

package/dist/reviewer-construction.js

@@ -89,10 +89,35 @@ export function reviewerAuthorityRefsMaterial(authorityRefs) {
         "These are durable authority references only. Read them as Spec grounding materials; do not invent Spec prose from caller instruction.",
     ].join("\n");
 }
+/**
+ * Spec-only material carrier for self-fetched issue bytes + source annotation (#343).
+ * Actual issue body and referenced ADR bytes are embedded for audit (fetch-then-store).
+ * Single JSON payload keeps external issue/ADR bytes inside structured field values so they
+ * cannot forge package framing markers on the same text layer (no plain-text section protocol).
+ */
+export function reviewerFetchedSpecMaterial(fetched) {
+    return [
+        "Authority-Fetched-Spec:",
+        JSON.stringify(Object.freeze({
+            source: fetched.adopted.source,
+            ticketNumber: fetched.ticketNumber,
+            issueRef: fetched.issueRef,
+            abandoned: Object.freeze([...fetched.abandoned]),
+            issueBody: fetched.issueBody,
+            adrs: Object.freeze(fetched.adrs.map((adr) => adr.status === "present"
+                ? Object.freeze({ path: adr.path, status: adr.status, body: adr.body })
+                : Object.freeze({ path: adr.path, status: adr.status }))),
+        })),
+        "These are self-fetched Spec grounding materials. Do not invent Spec prose from caller instruction.",
+    ].join("\n");
+}
 /** Deterministic compiler: fixed target/range plus discovery product in, dispatch text out. */
 export function constructReviewerDispatch(input) {
     const launchSpec = input.specAuthority.status === "available";
     const authorityRefs = Object.freeze(input.specAuthority.status === "available" ? [...input.specAuthority.refs] : []);
+    const specFetchedMaterial = input.specAuthority.status === "available" && input.specAuthority.fetched !== undefined
+        ? input.specAuthority.fetched
+        : undefined;
     const specDisposition = launchSpec ? "launched" : "skipped-missing";
     const common = [
         `Target: ${input.range.target}`,
@@ -111,8 +136,13 @@ export function constructReviewerDispatch(input) {
     const legs = axes.map((x) => {
         const parts = [common, reviewerAxisMethodAdapter(x.axis)];
         // Spec evidence-child only — never Standards or a parent replacement Spec leg.
-        if (x.axis === "spec" && authorityRefs.length > 0) {
-            parts.push(reviewerAuthorityRefsMaterial(authorityRefs));
+        if (x.axis === "spec") {
+            if (specFetchedMaterial !== undefined) {
+                parts.push(reviewerFetchedSpecMaterial(specFetchedMaterial));
+            }
+            if (authorityRefs.length > 0) {
+                parts.push(reviewerAuthorityRefsMaterial(authorityRefs));
+            }
         }
         return Object.freeze({
             axis: x.axis,
@@ -130,6 +160,7 @@ export function constructReviewerDispatch(input) {
         range: input.range,
         authorityRefs,
         specDisposition,
+        ...(specFetchedMaterial === undefined ? {} : { specFetchedMaterial }),
         legs: Object.freeze(legs),
     });
 }

package/dist/reviewer-dispatch.js

@@ -1,6 +1,6 @@
 import { sameReviewerPinnedTarget } from "./reviewer-git-snapshot.js";
-import { immutableReviewerPin } from "./reviewer-pinned-git.js";
-export { createReviewerPinnedGitReader, immutableReviewerPin } from "./reviewer-pinned-git.js";
+import { branchNamesAtPinnedHead, immutableReviewerPin } from "./reviewer-pinned-git.js";
+export { branchNamesAtPinnedHead, createReviewerPinnedGitReader, immutableReviewerPin } from "./reviewer-pinned-git.js";
 import { isReviewerPromptText, sameReviewerPromptText } from "./reviewer-prompt-identity.js";
 import { sha256Hex } from "./sha256.js";
 import { constructReviewerDispatch, } from "./reviewer-construction.js";
@@ -11,6 +11,12 @@ export { isReviewerPromptText as isReviewerPromptIdentity, sameReviewerPromptTex
 const GENERIC_FEATURE_TOKENS = new Set(["", "head", "main", "master", "trunk", "develop", "development"]);
 /** Conventional branch shells that must not hide the feature token (feat/login → login). */
 const BRANCH_SHELL_PREFIX = /^(?:feat|feature|fix|bugfix|hotfix|chore|docs|refactor)-/;
+/** Branch token ticket capture: (fix|feat|docs|audit|test)/issue-(\d+)- (#343). */
+const BRANCH_ISSUE_TOKEN = /(?:^|\/)((?:fix|feat|docs|audit|test)\/issue-(\d+)-)/;
+/** First #N in a commit subject (positive integer). */
+const COMMIT_TICKET_TOKEN = /#([1-9]\d*)/;
+/** docs/adr paths referenced inside an issue body. */
+const ADR_PATH_IN_BODY = /docs\/adr\/[A-Za-z0-9][A-Za-z0-9._/-]*\.md/g;
 function normalizeFeatureToken(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -26,22 +32,144 @@ function expandFeatureTokens(raw) {
     return Object.freeze([...tokens]);
 }
 /**
- * Unique production owner of code-review Skill step 2 Spec discovery.
- * Directly yields durable refs Spec child can read, or confirmed missing.
- * - Supplied authorityRefs ⇒ available with those refs as material.
- * - Matching pinned-target docs/specs/.scratch paths ⇒ available with those paths as material.
- * - Commit message bare #N without durable source ⇒ missing (not available).
- * Only confirmed absence yields missing; other Git/I-O failures keep true cause for preflight.
+ * Shared capture/number → positive-integer → frozen candidate conversion.
+ * Single true source for branch/commit (and typed) ticket candidate materialization.
+ */
+function ticketCandidateFromRaw(source, raw) {
+    const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : Number.NaN;
+    if (!Number.isInteger(n) || n < 1)
+        return undefined;
+    return Object.freeze({ source, ticketNumber: n });
+}
+/**
+ * Resolve ticket number with unique priority (#343):
+ * typed ticketNumber → branch token → newest commit message first #N.
+ * High-priority hit is adopted; lower sources that also yield a number are abandoned candidates.
+ */
+export function resolveReviewerTicketNumber(input) {
+    const typed = ticketCandidateFromRaw("typed-ticket-number", input.ticketNumber);
+    let branch;
+    for (const name of input.branchNames) {
+        const match = BRANCH_ISSUE_TOKEN.exec(name);
+        if (match) {
+            branch = ticketCandidateFromRaw("branch-token", match[2]);
+            if (branch !== undefined)
+                break;
+        }
+    }
+    let commit;
+    const newest = input.commitMessagesNewestFirst[0];
+    if (newest !== undefined) {
+        const match = COMMIT_TICKET_TOKEN.exec(newest);
+        if (match) {
+            commit = ticketCandidateFromRaw("commit-message", match[1]);
+        }
+    }
+    if (typed !== undefined) {
+        const abandoned = [branch, commit].filter((c) => c !== undefined);
+        return Object.freeze({ adopted: typed, abandoned: Object.freeze(abandoned) });
+    }
+    if (branch !== undefined) {
+        const abandoned = commit === undefined ? Object.freeze([]) : Object.freeze([commit]);
+        return Object.freeze({ adopted: branch, abandoned });
+    }
+    if (commit !== undefined) {
+        return Object.freeze({ adopted: commit, abandoned: Object.freeze([]) });
+    }
+    return undefined;
+}
+/** Extract unique docs/adr/*.md paths referenced by issue body text (order of first appearance). */
+export function extractReferencedAdrPaths(issueBody) {
+    const seen = new Set();
+    const paths = [];
+    for (const match of issueBody.matchAll(ADR_PATH_IN_BODY)) {
+        const path = match[0];
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        paths.push(path);
+    }
+    return Object.freeze(paths);
+}
+/** Optional AbortSignal carried on the dispatch invocation bag (same shape runDispatch already reads). */
+function optionalInvocationSignal(invocation) {
+    if (typeof invocation !== "object" || invocation === null)
+        return undefined;
+    const signal = invocation.signal;
+    return signal instanceof AbortSignal ? signal : undefined;
+}
+/**
+ * Unique production owner of code-review Skill step 2 Spec discovery (#343).
+ * Primary: self-fetch latest issue by ticket number (typed → branch token → commit #N).
+ * Degradation (unique order): self-fetch fail → supplied authorityRefs → local path match → missing.
+ * Prompt/admitted-request prose is never Spec material.
+ * Only confirmed absence yields missing; non-absence Git/I-O failures keep true cause for preflight.
  * Construction builds Standards/Spec solely from this product.
  */
 export async function discoverReviewerSpecAuthority(input) {
+    // Path-matching tokens (heads/tags/remotes) stay separate from branch-ticket provenance.
+    const featureTokens = await input.reader.featureTokens();
+    const commitMessages = input.baseCommit === undefined
+        ? Object.freeze([])
+        : await input.reader.commitMessagesNewestFirst(input.baseCommit);
+    const ticketResolution = resolveReviewerTicketNumber({
+        ...(input.ticketNumber === undefined ? {} : { ticketNumber: input.ticketNumber }),
+        // Branch ticket source: real heads/remotes at targetHead only — never tags via featureTokens.
+        branchNames: branchNamesAtPinnedHead(input.reader.pin),
+        commitMessagesNewestFirst: commitMessages,
+    });
+    // ① Primary: self-fetch latest issue + referenced docs/adr via injected capability only.
+    if (ticketResolution !== undefined) {
+        const origin = await input.reader.originRepository();
+        if (origin !== undefined && input.fetchIssue !== undefined) {
+            const issue = await input.fetchIssue({
+                owner: origin.owner,
+                repo: origin.repo,
+                ticketNumber: ticketResolution.adopted.ticketNumber,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+            if (issue !== undefined) {
+                const adrPaths = extractReferencedAdrPaths(issue.body);
+                const adrs = [];
+                for (const path of adrPaths) {
+                    const body = await input.reader.readPinnedText(path);
+                    if (body === undefined) {
+                        adrs.push(Object.freeze({ path, status: "missing" }));
+                    }
+                    else {
+                        adrs.push(Object.freeze({ path, status: "present", body }));
+                    }
+                }
+                const issueRef = `https://github.com/${origin.owner}/${origin.repo}/issues/${ticketResolution.adopted.ticketNumber}`;
+                const presentAdrRefs = adrs
+                    .filter((a) => a.status === "present")
+                    .map((a) => a.path);
+                const fetched = Object.freeze({
+                    issueRef,
+                    owner: origin.owner,
+                    repo: origin.repo,
+                    ticketNumber: ticketResolution.adopted.ticketNumber,
+                    adopted: ticketResolution.adopted,
+                    abandoned: ticketResolution.abandoned,
+                    issueBody: issue.body,
+                    adrs: Object.freeze(adrs),
+                });
+                return Object.freeze({
+                    status: "available",
+                    refs: Object.freeze([issueRef, ...presentAdrRefs]),
+                    fetched,
+                });
+            }
+        }
+    }
+    // ② Degrade: explicit --authority-ref (human intent before local heuristics).
     if (input.authorityRefs.length > 0) {
         return Object.freeze({
             status: "available",
             refs: Object.freeze([...input.authorityRefs]),
         });
     }
-    const featureTokens = await input.reader.featureTokens();
+    // ③ Degrade: matching pinned-target docs/specs/.scratch paths via branch feature tokens.
     const tokens = [
         ...new Set(featureTokens
             .flatMap((raw) => expandFeatureTokens(raw))
@@ -107,9 +235,14 @@ export function createReviewerDispatcher(d) {
                 const base = await d.reader.resolve(baseRevision);
                 const range = await d.reader.range(base);
                 const authorityRefs = Object.freeze([...(d.authorityRefs ?? [])]);
+                const signal = optionalInvocationSignal(invocation);
                 const specAuthority = await discoverReviewerSpecAuthority({
                     authorityRefs,
                     reader: d.reader,
+                    baseCommit: base,
+                    ...(d.ticketNumber === undefined ? {} : { ticketNumber: d.ticketNumber }),
+                    ...(d.fetchIssue === undefined ? {} : { fetchIssue: d.fetchIssue }),
+                    ...(signal === undefined ? {} : { signal }),
                 });
                 dispatch = constructReviewerDispatch({
                     identity,

package/dist/reviewer-execution-ledger.js

@@ -6,7 +6,11 @@ export function projectAcceptedDispatch(dispatch) {
         source: "reviewer-dispatch", type: "accepted", identity: dispatch.identity,
         recipe: dispatch.recipe, input: dispatch.input, target: dispatch.targetSnapshot,
         range: dispatch.range, authorityRefs: dispatch.authorityRefs,
-        specDisposition: dispatch.specDisposition, legs: dispatch.legs,
+        specDisposition: dispatch.specDisposition,
+        ...(dispatch.specFetchedMaterial === undefined
+            ? {}
+            : { specFetchedMaterial: dispatch.specFetchedMaterial }),
+        legs: dispatch.legs,
     };
 }
 export function projectReviewerDispatchOutcome(ledger, dispatch, result) {

package/dist/reviewer-pinned-git.js

@@ -6,8 +6,12 @@ import { sha256Hex } from "./sha256.js";
 import { ReviewerCorrectablePreflightError } from "./reviewer-preflight-error.js";
 const execFileAsync = promisify(execFile);
 async function execGit(args, options) {
+    // Pin C locale at the sole Git exec seam so English diagnostic classifiers stay honest under translated gettext installs.
     try {
-        return await execFileAsync("git", args, options);
+        return await execFileAsync("git", args, {
+            ...options,
+            env: { ...process.env, LC_ALL: "C" },
+        });
     }
     catch (error) {
         const source = error;
@@ -17,6 +21,23 @@ async function execGit(args, options) {
     }
 }
 function exitCode(error) { const code = typeof error === "object" && error !== null ? error.code : undefined; return typeof code === "number" ? code : undefined; }
+function gitStderr(error) {
+    if (typeof error !== "object" || error === null)
+        return "";
+    const stderr = error.stderr;
+    return typeof stderr === "string" ? stderr : "";
+}
+/** Confirmed `origin` remote absence only (`git remote get-url origin`). */
+function isConfirmedMissingOriginRemote(error) {
+    return /No such remote ['"]origin['"]/.test(gitStderr(error));
+}
+/** Confirmed path-at-pinned-tree absence only — exit 128 alone is not enough. */
+function isConfirmedPinnedPathAbsent(error, path) {
+    const stderr = gitStderr(error);
+    const quoted = `'${path}'`;
+    return (stderr.includes(`path ${quoted} does not exist in `) ||
+        stderr.includes(`path ${quoted} exists on disk, but not in `));
+}
 async function repositoryIsAvailable(root) { try {
     await access(`${root}/.git`);
     return { available: true };
@@ -27,6 +48,35 @@ catch (cause) {
 export const immutableReviewerPin = (pin) => Object.freeze({
     repositoryRoot: pin.repositoryRoot, objectFormat: pin.objectFormat, targetHead: pin.targetHead, refs: immutableReviewerRefs(pin.refs),
 });
+/** Short name from a full ref, stripping heads/tags/remotes namespaces (and remote remote-name). */
+function shortNameFromPinnedRef(refName) {
+    const short = refName.startsWith("refs/heads/")
+        ? refName.slice("refs/heads/".length)
+        : refName.startsWith("refs/tags/")
+            ? refName.slice("refs/tags/".length)
+            : refName.startsWith("refs/remotes/")
+                ? refName.slice("refs/remotes/".length).replace(/^[^/]+\//, "")
+                : refName;
+    const trimmed = short.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * Branch-only short names at pinned targetHead for ticket-number provenance (#343).
+ * Heads and remotes only — tags never supply branch-token ticket candidates.
+ */
+export function branchNamesAtPinnedHead(pin) {
+    const names = new Set();
+    for (const [refName, entry] of Object.entries(pin.refs)) {
+        if (entry.peeledCommitId !== pin.targetHead)
+            continue;
+        if (!refName.startsWith("refs/heads/") && !refName.startsWith("refs/remotes/"))
+            continue;
+        const short = shortNameFromPinnedRef(refName);
+        if (short !== undefined)
+            names.add(short);
+    }
+    return Object.freeze([...names]);
+}
 async function gitText(root, args) {
     const { stdout } = await execGit(["-C", root, ...args], { encoding: "utf8" });
     return stdout.trim();
@@ -145,19 +195,14 @@ export async function createReviewerPinnedGitReader(root = process.cwd()) {
         async featureTokens() {
             // Pinned ref snapshot is the target-tree fact — no live branch/symbolic-ref walk,
             // no catch-to-empty. Detached/remote-only tips surface via refs/remotes/* entries.
+            // Includes tags for local Spec-path matching only; ticket branch source is separate.
             const names = new Set();
             for (const [refName, entry] of Object.entries(pin.refs)) {
                 if (entry.peeledCommitId !== targetHead)
                     continue;
-                const short = refName.startsWith("refs/heads/")
-                    ? refName.slice("refs/heads/".length)
-                    : refName.startsWith("refs/tags/")
-                        ? refName.slice("refs/tags/".length)
-                        : refName.startsWith("refs/remotes/")
-                            ? refName.slice("refs/remotes/".length).replace(/^[^/]+\//, "")
-                            : refName;
-                if (short.trim() !== "")
-                    names.add(short.trim());
+                const short = shortNameFromPinnedRef(refName);
+                if (short !== undefined)
+                    names.add(short);
             }
             return Object.freeze([...names]);
         },
@@ -175,5 +220,89 @@ export async function createReviewerPinnedGitReader(root = process.cwd()) {
             ]);
             return Object.freeze(text === "" ? [] : text.split("\n").filter((line) => line.length > 0));
         },
+        async originRepository() {
+            let remoteUrl;
+            try {
+                remoteUrl = await gitText(repositoryRoot, ["remote", "get-url", "origin"]);
+            }
+            catch (error) {
+                // Only confirmed origin absence softens to unavailable; other Git failures keep true cause.
+                if (isConfirmedMissingOriginRemote(error))
+                    return undefined;
+                throw error;
+            }
+            // Non-github / unparseable remote URL = self-fetch unavailable (soft degrade).
+            return parseGitHubOriginRemote(remoteUrl);
+        },
+        async commitMessagesNewestFirst(base) {
+            const text = await gitText(repositoryRoot, [
+                "log",
+                "--format=%s",
+                `${base}..${targetHead}`,
+            ]);
+            return Object.freeze(text === "" ? [] : text.split("\n"));
+        },
+        async readPinnedText(path) {
+            // Reject path traversal / absolute paths — Spec material is relative tree paths only.
+            if (path.length === 0 ||
+                path.startsWith("/") ||
+                path.includes("\0") ||
+                path.split("/").some((part) => part === ".." || part === "")) {
+                return undefined;
+            }
+            try {
+                const { stdout } = await execGit(["-C", repositoryRoot, "show", `${targetHead}:${path}`], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+                return stdout;
+            }
+            catch (error) {
+                // Only confirmed path-at-pinned-tree absence softens to missing; exit 128 is not a blanket.
+                if (isConfirmedPinnedPathAbsent(error, path))
+                    return undefined;
+                throw error;
+            }
+        },
     });
 }
+/**
+ * Parse github.com owner/repo from a git remote URL.
+ * Supports scp-like SSH, ssh://, https://, and git:// shapes. Soft: undefined when not github.
+ */
+export function parseGitHubOriginRemote(remoteUrl) {
+    const trimmed = remoteUrl.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const scp = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i.exec(trimmed);
+    if (scp)
+        return normalizeOrigin(scp[1], scp[2]);
+    const ssh = /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(trimmed);
+    if (ssh)
+        return normalizeOrigin(ssh[1], ssh[2]);
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (!/^github\.com$/i.test(parsed.hostname))
+        return undefined;
+    if (parsed.search !== "" || parsed.hash !== "")
+        return undefined;
+    const parts = parsed.pathname.split("/").filter((p) => p.length > 0);
+    if (parts.length !== 2)
+        return undefined;
+    return normalizeOrigin(parts[0], parts[1]);
+}
+function normalizeOrigin(ownerRaw, repoRaw) {
+    const owner = ownerRaw.trim();
+    const repo = stripGitSuffix(repoRaw.trim());
+    if (owner.length === 0 || repo.length === 0)
+        return undefined;
+    // Conservative identity: no path separators or URL material inside segments.
+    if (/[/?#@\\]/.test(owner) || /[/?#@\\]/.test(repo))
+        return undefined;
+    return Object.freeze({ owner, repo });
+}
+function stripGitSuffix(name) {
+    return name.toLowerCase().endsWith(".git") ? name.slice(0, -4) : name;
+}

package/extensions/role-runtime.ts

@@ -14,7 +14,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import type { Message } from "@earendil-works/pi-ai";
 
-import { createGhCollectorGitHubTransport } from "../src/collector-github.ts";
+import { createGhCollectorGitHubTransport, createGhIssueSoftFetcher } from "../src/collector-github.ts";
 import { createReviewerAgentRunner } from "../src/reviewer-agent.ts";
 import { createReviewerPinnedGitReader } from "../src/reviewer-dispatch.ts";
 import { createPiReviewerAuditor } from "../src/reviewer-auditor.ts";
@@ -252,6 +252,7 @@ export default function roleRuntime(pi: ExtensionAPI): void {
     loadCoderTask: (path) => readFile(path, "utf8"),
     loadReviewerSoul: () => readFile(reviewerSoulPath, "utf8"),
     createReviewerPinnedGitReader: () => createReviewerPinnedGitReader(),
+    createReviewerIssueFetcher: () => createGhIssueSoftFetcher(),
     loadCollectorSoul: () => readFile(collectorSoulPath, "utf8"),
     createCollectorTransport: () => createGhCollectorGitHubTransport(),
     collectorPackageExtensionPath: extensionPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.1941",
+  "version": "0.1.2014",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/atomic-write.ts

@@ -0,0 +1,26 @@
+/**
+ * Same-directory temp + rename atomic file replace.
+ * Shared primitive for ledger-adjacent typed pages (taishi metrics, etc.).
+ * Does not open/truncate an existing destination inode, so hard-linked twins
+ * keep prior bytes until the directory entry is swapped.
+ * Parent directory must already exist — callers that write under the package
+ * ledger home own confinement via ensureRealDirectoryTree (ADR 0038).
+ */
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export async function writeFileAtomically(
+  destination: string,
+  contents: string | Uint8Array,
+): Promise<void> {
+  const parent = dirname(destination);
+  const temporary = join(parent, `.atomic-write-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, contents);
+    await rename(temporary, destination);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}

package/src/collector-github.ts

@@ -434,6 +434,100 @@ export function createGhApiRunner(
   };
 }
 
+export type GhIssueSoftFetchResult = Readonly<{ body: string }>;
+/**
+ * Soft single-issue fetch over the shared gh api runner.
+ * undefined = confirmed tracker unreachable / issue not found / gh tool unavailable:
+ *   - HTTP non-2xx, or
+ *   - runner-tagged ambiguousGhFailure (gh ran but no parseable HTTP — auth/network/transport), or
+ *   - gh process could not start (ENOENT / spawn syscall failure).
+ * After gh starts successfully: response JSON/shape/implementation errors propagate with true cause.
+ */
+export type GhIssueSoftFetcher = (input: {
+  owner: string;
+  repo: string;
+  ticketNumber: number;
+  /** Optional cancellation signal forwarded to the shared GhApiRunner. */
+  signal?: AbortSignal;
+}) => Promise<GhIssueSoftFetchResult | undefined>;
+
+function isAmbiguousGhFailure(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { ambiguousGhFailure?: unknown }).ambiguousGhFailure === true
+  );
+}
+
+/** gh binary missing or otherwise unable to launch — ticket-authorized soft unavailable. */
+function isGhProcessStartFailure(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code === "ENOENT") return true;
+  const syscall = (error as NodeJS.ErrnoException).syscall;
+  return typeof syscall === "string" && (syscall === "spawn" || syscall.startsWith("spawn "));
+}
+
+/**
+ * Production issue-fetch capability owned by the shared gh execution seam.
+ * Reuses createGhApiRunner lifecycle. Softens only ticket-authorized unavailable results
+ * (tracker unreachable / issue not found / gh cannot start); does not catch-all wash
+ * post-start parse or implementation failures into unavailable.
+ */
+export function createGhIssueSoftFetcher(
+  runner: GhApiRunner = createGhApiRunner(),
+): GhIssueSoftFetcher {
+  return async (input) => {
+    const path = `repos/${input.owner}/${input.repo}/issues/${input.ticketNumber}`;
+    let response: GhApiResponse;
+    try {
+      // Forward invocation AbortSignal into the shared GhApiRunner lifecycle (no local timeout).
+      response = await runner(
+        [
+          "api",
+          "--hostname",
+          "github.com",
+          "--include",
+          "-X",
+          "GET",
+          path,
+        ],
+        input.signal === undefined ? {} : { signal: input.signal },
+      );
+    } catch (error) {
+      // Ticket-authorized soft unavailable: tagged transport ambiguity, or gh never started.
+      // Cancellation / other post-start failures keep true cause (not washed into degrade).
+      if (isAmbiguousGhFailure(error) || isGhProcessStartFailure(error)) return undefined;
+      throw error;
+    }
+    // Ticket-authorized degrade: issue not found / tracker non-success via HTTP status.
+    if (response.status < 200 || response.status >= 300) return undefined;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(response.bodyText);
+    } catch (error) {
+      throw new Error("GitHub issue payload is not JSON", { cause: error });
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error("GitHub issue payload must be a JSON object");
+    }
+    // Issues endpoint also returns PRs. Own-key presence of the standard pull_request marker
+    // means this is a PR payload — soft-unavailable so Spec does not adopt PR description as issue body.
+    // Key presence only; no marker-content parse, PR schema, or linked-issue chase.
+    if (Object.hasOwn(parsed, "pull_request")) {
+      return undefined;
+    }
+    // Match former gh --jq `(.body // "")`: null/missing body projects to empty string.
+    // Title is not ticket-authorized audited material — do not parse or validate it.
+    const bodyRaw = (parsed as { body?: unknown }).body;
+    if (bodyRaw !== undefined && bodyRaw !== null && typeof bodyRaw !== "string") {
+      throw new Error("GitHub issue payload body must be string or null");
+    }
+    const body = typeof bodyRaw === "string" ? bodyRaw : "";
+    return Object.freeze({ body });
+  };
+}
+
 export function createGhCollectorGitHubTransport(
   runner: GhApiRunner = createGhApiRunner(),
 ): CollectorGitHubTransport {