@akagilnc/pi-workflow-roles 0.1.2004 → 0.1.2014

package/src/public-cli/reviewer-run.ts

@@ -100,6 +100,15 @@ function buildModelArgs(model: SeatModelConfig | undefined): string[] {
   ];
 }
 
+/** Encode admitted ticketNumber as CLI argv for activation/resume (no defaults). */
+function buildReviewerTicketNumberArgs(
+  ticketNumber: number | undefined,
+): string[] {
+  return ticketNumber === undefined
+    ? []
+    : ["--ak-review-ticket-number", String(ticketNumber)];
+}
+
 /**
  * Build Internal activation extra-args for an admitted Reviewer run.
  * Package code-review Skill is forced via --skill; ambient home skills stay off.
@@ -122,6 +131,7 @@ export function buildReviewerActivationExtraArgs(
     admitted.authorityRefs.length === 0
       ? []
       : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
+  const ticketNumberArgs = buildReviewerTicketNumberArgs(admitted.ticketNumber);
   return [
     "--no-skills",
     "--skill",
@@ -139,6 +149,7 @@ export function buildReviewerActivationExtraArgs(
     "--ak-review-base",
     admitted.baseRevision,
     ...authorityRefArgs,
+    ...ticketNumberArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),
@@ -166,6 +177,7 @@ export function buildReviewerResumeActivationExtraArgs(
     admitted.authorityRefs.length === 0
       ? []
       : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
+  const ticketNumberArgs = buildReviewerTicketNumberArgs(admitted.ticketNumber);
   return [
     "--no-skills",
     "--skill",
@@ -183,6 +195,7 @@ export function buildReviewerResumeActivationExtraArgs(
     "--ak-review-base",
     admitted.baseRevision,
     ...authorityRefArgs,
+    ...ticketNumberArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),

package/src/public-cli/settlement.ts

@@ -3185,6 +3185,10 @@ export async function publishReviewerArtifacts(
         ...(admitted.instructionEmpty
           ? {}
           : { callerProvenance: admitted.instruction }),
+        // Self-fetch Spec bytes + source annotation when primary path produced material (#343).
+        ...(options.reviewerReceipt?.specFetchedMaterial === undefined
+          ? {}
+          : { specFetchedMaterial: options.reviewerReceipt.specFetchedMaterial }),
         attachments: admitted.attachments.map((a) => ({
           provenancePath: a.provenancePath,
           frozenPath: a.frozenPath,

package/src/reviewer-construction.ts

@@ -101,12 +101,49 @@ export function reviewerAxisMethodAdapter(axis: ReviewerAxis): string {
 }
 
 export type ConstructedReviewerLeg = Readonly<{ axis: "standards" | "spec"; prompt: ReviewerPromptText }>;
+
+/** Ticket-number provenance for Spec self-fetch (#343). High-priority source wins. */
+export type ReviewerTicketNumberSource =
+  | "typed-ticket-number"
+  | "branch-token"
+  | "commit-message";
+
+export type ReviewerTicketNumberCandidate = Readonly<{
+  source: ReviewerTicketNumberSource;
+  ticketNumber: number;
+}>;
+
+/** One docs/adr path referenced by the fetched issue body. */
+export type ReviewerFetchedAdr =
+  | Readonly<{ path: string; status: "present"; body: string }>
+  | Readonly<{ path: string; status: "missing" }>;
+
+/**
+ * Actual Spec bytes pulled on the self-fetch primary path (fetch-then-store).
+ * Carried into Spec-child material and retained on the accepted dispatch for audit.
+ */
+export type ReviewerSpecFetchedMaterial = Readonly<{
+  issueRef: string;
+  owner: string;
+  repo: string;
+  ticketNumber: number;
+  adopted: ReviewerTicketNumberCandidate;
+  abandoned: readonly ReviewerTicketNumberCandidate[];
+  issueBody: string;
+  adrs: readonly ReviewerFetchedAdr[];
+}>;
+
 /**
  * Unique discovery product for Skill step 2: durable refs Spec child can read, or confirmed missing.
+ * Optional `fetched` is present only when the self-fetch primary path produced issue bytes.
  * Construction builds Standards/Spec solely from this product — no secondary launch decision.
  */
 export type ReviewerSpecAuthorityDiscovery =
-  | Readonly<{ status: "available"; refs: readonly string[] }>
+  | Readonly<{
+      status: "available";
+      refs: readonly string[];
+      fetched?: ReviewerSpecFetchedMaterial;
+    }>
   | Readonly<{ status: "missing" }>;
 /** Spec-child cardinality decision recorded on the accepted dispatch. */
 export type ReviewerSpecDisposition = "launched" | "skipped-missing";
@@ -123,6 +160,8 @@ export type ConstructedReviewerDispatch = Readonly<{
   authorityRefs: readonly string[];
   /** Honest Spec-child disposition: launched, or skipped after confirmed missing Spec. */
   specDisposition: ReviewerSpecDisposition;
+  /** Self-fetch bytes + source annotation when primary path produced material. */
+  specFetchedMaterial?: ReviewerSpecFetchedMaterial;
   legs: readonly ConstructedReviewerLeg[];
 }>;
 
@@ -138,6 +177,35 @@ export function reviewerAuthorityRefsMaterial(authorityRefs: readonly string[]):
   ].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: ReviewerSpecFetchedMaterial): string {
+  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: {
   identity: string;
@@ -152,6 +220,10 @@ export function constructReviewerDispatch(input: {
   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: ReviewerSpecDisposition = launchSpec ? "launched" : "skipped-missing";
   const common = [
     `Target: ${input.range.target}`,
@@ -170,8 +242,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,
@@ -189,6 +266,7 @@ export function constructReviewerDispatch(input: {
     range: input.range,
     authorityRefs,
     specDisposition,
+    ...(specFetchedMaterial === undefined ? {} : { specFetchedMaterial }),
     legs: Object.freeze(legs),
   });
 }

package/src/reviewer-dispatch.ts

@@ -1,16 +1,22 @@
 import { sameReviewerPinnedTarget } from "./reviewer-git-snapshot.ts";
-import { immutableReviewerPin, type ReviewerPinnedGitReader, type ReviewerPinnedTarget, type ReviewerRange } from "./reviewer-pinned-git.ts";
-export { createReviewerPinnedGitReader, immutableReviewerPin, type ReviewerPinnedGitReader, type ReviewerPinnedTarget, type ReviewerRange } from "./reviewer-pinned-git.ts";
+import { branchNamesAtPinnedHead, immutableReviewerPin, type ReviewerPinnedGitReader, type ReviewerPinnedTarget, type ReviewerRange } from "./reviewer-pinned-git.ts";
+export { branchNamesAtPinnedHead, createReviewerPinnedGitReader, immutableReviewerPin, type ReviewerPinnedGitReader, type ReviewerPinnedTarget, type ReviewerRange } from "./reviewer-pinned-git.ts";
 import { isReviewerPromptText, sameReviewerPromptText, type ReviewerPromptText } from "./reviewer-prompt-identity.ts";
 import { sha256Hex } from "./sha256.ts";
 import {
   constructReviewerDispatch,
   type ConstructedReviewerDispatch,
   type ReviewerSpecAuthorityDiscovery,
+  type ReviewerSpecFetchedMaterial,
+  type ReviewerTicketNumberCandidate,
+  type ReviewerTicketNumberSource,
 } from "./reviewer-construction.ts";
 export {
   type ReviewerSpecAuthorityDiscovery,
   type ReviewerSpecDisposition,
+  type ReviewerSpecFetchedMaterial,
+  type ReviewerTicketNumberCandidate,
+  type ReviewerTicketNumberSource,
 } from "./reviewer-construction.ts";
 import { ReviewerCorrectablePreflightError } from "./reviewer-preflight-error.ts";
 export { sha256Hex } from "./sha256.ts";
@@ -19,6 +25,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: string): string {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -35,25 +47,184 @@ function expandFeatureTokens(raw: string): readonly string[] {
 }
 
 /**
- * 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: ReviewerTicketNumberSource,
+  raw: unknown,
+): ReviewerTicketNumberCandidate | undefined {
+  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: {
+  ticketNumber?: number;
+  branchNames: readonly string[];
+  commitMessagesNewestFirst: readonly string[];
+}): Readonly<{ adopted: ReviewerTicketNumberCandidate; abandoned: readonly ReviewerTicketNumberCandidate[] }> | undefined {
+  const typed = ticketCandidateFromRaw("typed-ticket-number", input.ticketNumber);
+
+  let branch: ReviewerTicketNumberCandidate | undefined;
+  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: ReviewerTicketNumberCandidate | undefined;
+  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 is ReviewerTicketNumberCandidate => 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: string): readonly string[] {
+  const seen = new Set<string>();
+  const paths: string[] = [];
+  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);
+}
+
+export type ReviewerIssueFetchResult = Readonly<{ body: string }>;
+/**
+ * Soft issue fetch capability: undefined means confirmed tracker unreachable / issue not found.
+ * Unrecognized runner failures and parse/implementation errors propagate with true cause (not washed into degrade).
+ * Optional signal rides the shared GhApiRunner cancellation chain; role modules never own gh lifecycle.
+ */
+export type ReviewerIssueFetcher = (input: {
+  owner: string;
+  repo: string;
+  ticketNumber: number;
+  signal?: AbortSignal;
+}) => Promise<ReviewerIssueFetchResult | undefined>;
+
+/** Optional AbortSignal carried on the dispatch invocation bag (same shape runDispatch already reads). */
+function optionalInvocationSignal(invocation: unknown): AbortSignal | undefined {
+  if (typeof invocation !== "object" || invocation === null) return undefined;
+  const signal = (invocation as { signal?: unknown }).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: {
   authorityRefs: readonly string[];
   reader: ReviewerPinnedGitReader;
+  /** Typed #176 ticketNumber from admitted invocation, when present. */
+  ticketNumber?: number;
+  /** base..HEAD commit scan base (resolved oid). Required for commit-message ticket source. */
+  baseCommit?: string;
+  /**
+   * Injected issue-fetch capability from the shared execution seam.
+   * Absent capability = self-fetch unavailable (degrade); role module never owns gh lifecycle.
+   */
+  fetchIssue?: ReviewerIssueFetcher;
+  /** Optional cancellation signal for the soft-fetch gh subprocess (invocation AbortSignal). */
+  signal?: AbortSignal;
 }): Promise<ReviewerSpecAuthorityDiscovery> {
+  // 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" as const }));
+          } else {
+            adrs.push(Object.freeze({ path, status: "present" as const, 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: ReviewerSpecFetchedMaterial = 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" as const,
+          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" as const,
       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
@@ -101,6 +272,10 @@ type DispatcherDependencies = Readonly<{
   reviewScopeKeys?: readonly string[];
   /** Durable authority references preserved unchanged into Spec-leg construction only. */
   authorityRefs?: readonly string[];
+  /** Typed #176 ticketNumber from admitted invocation (Spec self-fetch primary). */
+  ticketNumber?: number;
+  /** Injected issue-fetch capability from shared execution seam (production/tests). */
+  fetchIssue?: ReviewerIssueFetcher;
   run(execution: AcceptedReviewerExecution, invocation: unknown): Promise<unknown>;
   decisionEvidence?(decision: ReviewerDecisionEvidence): void;
 }>;
@@ -140,9 +315,14 @@ export function createReviewerDispatcher(d: DispatcherDependencies) {
         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/src/reviewer-execution-ledger.ts

@@ -28,7 +28,11 @@ export function projectAcceptedDispatch(dispatch: AcceptedReviewerDispatch): Rev
     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,
   };
 }
 

package/src/reviewer-pinned-git.ts

@@ -20,15 +20,18 @@ export type ReviewerRange = Readonly<{
   diffSha256: string;
   commits: readonly string[];
 }>;
+export type ReviewerOriginRepository = Readonly<{ owner: string; repo: string }>;
+
 export type ReviewerPinnedGitReader = {
   pin: ReviewerPinnedTarget;
   snapshot(): Promise<ReviewerPinnedTarget>;
   resolve(base: string): Promise<string>;
   range(base: string): Promise<ReviewerRange>;
   /**
-   * Branch/feature name tokens at the pinned target for Spec path matching.
+   * Branch/feature name tokens at the pinned target for Spec *path* matching only.
    * Derived from the pinned ref snapshot (heads/tags/remotes pointing at targetHead);
    * does not depend on current symbolic HEAD, so detached/remote-only tips stay honest.
+   * Ticket-number branch provenance must not use this set — see branchNamesAtPinnedHead.
    */
   featureTokens(): Promise<readonly string[]>;
   /**
@@ -37,13 +40,33 @@ export type ReviewerPinnedGitReader = {
    * Empty list is confirmed absence; other Git/I-O failures propagate with true cause.
    */
   listSpecCandidatePaths(): Promise<readonly string[]>;
+  /**
+   * github.com owner/repo from `origin` remote at the pinned repository root.
+   * undefined = no remote / non-github / unparseable — self-fetch unavailable (degrade).
+   */
+  originRepository(): Promise<ReviewerOriginRepository | undefined>;
+  /**
+   * Commit subjects for base..targetHead, newest first (for #N ticket extraction).
+   * Empty when the range has no commits; other Git failures propagate with true cause.
+   */
+  commitMessagesNewestFirst(base: string): Promise<readonly string[]>;
+  /**
+   * Read one path from the pinned target tree as UTF-8 text.
+   * undefined = path absent at targetHead; other Git failures propagate with true cause.
+   */
+  readPinnedText(path: string): Promise<string | undefined>;
 };
 
 const execFileAsync = promisify(execFile);
 type GitProcessError = Error & Readonly<{ code: number | string | null; signal: NodeJS.Signals | null; timedOut: boolean; aborted: boolean; stderr: string; stdout: string }>;
 async function execGit<T extends "utf8" | "buffer">(args: readonly string[], options: { encoding: T; maxBuffer?: number }): Promise<{ stdout: T extends "buffer" ? Buffer : string; stderr: string }> {
-  try { return await execFileAsync("git", args, options) as unknown as { stdout: T extends "buffer" ? Buffer : string; stderr: string }; }
-  catch (error) {
+  // 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,
+      env: { ...process.env, LC_ALL: "C" },
+    }) as unknown as { stdout: T extends "buffer" ? Buffer : string; stderr: string };
+  } catch (error) {
     const source = error as Partial<GitProcessError>;
     const wrapped = new Error("git process failed", { cause: error }) as GitProcessError;
     Object.assign(wrapped, { code: source.code ?? null, signal: source.signal ?? null, timedOut: (source as { killed?: unknown }).killed === true && source.signal === "SIGTERM", aborted: source.name === "AbortError", stderr: String(source.stderr ?? ""), stdout: String(source.stdout ?? "") });
@@ -51,10 +74,56 @@ async function execGit<T extends "utf8" | "buffer">(args: readonly string[], opt
   }
 }
 function exitCode(error: unknown): number | undefined { const code = typeof error === "object" && error !== null ? (error as { code?: unknown }).code : undefined; return typeof code === "number" ? code : undefined; }
+function gitStderr(error: unknown): string {
+  if (typeof error !== "object" || error === null) return "";
+  const stderr = (error as { stderr?: unknown }).stderr;
+  return typeof stderr === "string" ? stderr : "";
+}
+/** Confirmed `origin` remote absence only (`git remote get-url origin`). */
+function isConfirmedMissingOriginRemote(error: unknown): boolean {
+  return /No such remote ['"]origin['"]/.test(gitStderr(error));
+}
+/** Confirmed path-at-pinned-tree absence only — exit 128 alone is not enough. */
+function isConfirmedPinnedPathAbsent(error: unknown, path: string): boolean {
+  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: string): Promise<{ available: boolean; cause?: unknown }> { try { await access(`${root}/.git`); return { available: true }; } catch (cause) { return { available: false, cause }; } }
 export const immutableReviewerPin = (pin: ReviewerPinnedTarget): ReviewerPinnedTarget => 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: string): string | undefined {
+  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: ReviewerPinnedTarget): readonly string[] {
+  const names = new Set<string>();
+  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: string, args: readonly string[]): Promise<string> {
   const { stdout } = await execGit(["-C", root, ...args], { encoding: "utf8" });
   return stdout.trim();
@@ -154,17 +223,12 @@ export async function createReviewerPinnedGitReader(root = process.cwd()): Promi
     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<string>();
       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]);
     },
@@ -182,6 +246,85 @@ export async function createReviewerPinnedGitReader(root = process.cwd()): Promi
       ]);
       return Object.freeze(text === "" ? [] : text.split("\n").filter((line) => line.length > 0));
     },
+    async originRepository() {
+      let remoteUrl: string;
+      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: string) {
+      const text = await gitText(repositoryRoot, [
+        "log",
+        "--format=%s",
+        `${base}..${targetHead}`,
+      ]);
+      return Object.freeze(text === "" ? [] : text.split("\n"));
+    },
+    async readPinnedText(path: string) {
+      // 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: string): ReviewerOriginRepository | undefined {
+  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: URL;
+  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: string, repoRaw: string): ReviewerOriginRepository | undefined {
+  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: string): string {
+  return name.toLowerCase().endsWith(".git") ? name.slice(0, -4) : name;
+}