@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2014

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;
+}

package/src/reviewer-role.ts

@@ -9,7 +9,7 @@ import type { ComplianceDecision } from "./compliance-transport.ts";
 import { appendActiveSessionCustomEntry } from "./compliance-transport.ts";
 import { REVIEWER_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.ts";
 import { type ReviewerSpecDisposition } from "./reviewer-construction.ts";
-import { createReviewerDispatcher, type AcceptedReviewerDispatch, type AcceptedReviewerExecution, type ReviewerPinnedGitReader } from "./reviewer-dispatch.ts";
+import { createReviewerDispatcher, type AcceptedReviewerDispatch, type AcceptedReviewerExecution, type ReviewerIssueFetcher, type ReviewerPinnedGitReader } from "./reviewer-dispatch.ts";
 import { ReviewerDispatchExecutionError, type ReviewerDispatchRunResult } from "./reviewer-agent.ts";
 import { createReviewerExecutionLedger, projectAcceptedDispatch, projectReviewerDispatchOutcome, type ReviewerExecutionRecord } from "./reviewer-execution-ledger.ts";
 import { assembleRuntimeReviewerReceipt } from "./reviewer-settlement.ts";
@@ -24,6 +24,8 @@ export type ReviewerAdmittedInputs = Readonly<{
   baseRevision: string;
   reviewScopeKeys?: readonly string[];
   authorityRefs?: readonly string[];
+  /** Typed #176 ticketNumber from admitted invocation (Spec self-fetch primary). */
+  ticketNumber?: number;
 }>;
 
 const reviewerOutputVariants = Type.Union([
@@ -35,6 +37,8 @@ export type ReviewerRoleDependencies = {
   loadSoul(): Promise<string>;
   loadCanonicalSkillBinding(name: "code-review"): Promise<AnyCanonicalSkillBinding>;
   createPinnedGitReader(): Promise<ReviewerPinnedGitReader>;
+  /** Injected issue-fetch capability; shared seam owns gh lifecycle. */
+  fetchIssue?: ReviewerIssueFetcher;
   runDispatch(execution: AcceptedReviewerExecution, options: { context: ExtensionContext; signal?: AbortSignal }): Promise<ReviewerDispatchRunResult>;
   shutdownAgent?(): Promise<void>;
   auditCompliance(options: { context: ExtensionContext; signal?: AbortSignal }): Promise<ComplianceDecision>;
@@ -86,6 +90,7 @@ export function createReviewerRoleRuntime(
       fixedBaseRevision = admitted.baseRevision;
       const reviewScopeKeys = admitted.reviewScopeKeys;
       const authorityRefs = admitted.authorityRefs;
+      const ticketNumber = admitted.ticketNumber;
       const loaded = await dependencies.loadCanonicalSkillBinding("code-review");
       if (loaded.name !== "code-review") throw new Error("Canonical Skill binding loader returned tdd for code-review");
       binding = loaded;
@@ -115,6 +120,8 @@ export function createReviewerRoleRuntime(
         reader,
         ...(reviewScopeKeys === undefined ? {} : { reviewScopeKeys }),
         ...(authorityRefs === undefined ? {} : { authorityRefs }),
+        ...(ticketNumber === undefined ? {} : { ticketNumber }),
+        ...(dependencies.fetchIssue === undefined ? {} : { fetchIssue: dependencies.fetchIssue }),
         decisionEvidence(decision) {
           try {
             if (decision.disposition === "accepted") {

package/src/reviewer-settlement.ts

@@ -56,6 +56,10 @@ export function assembleRuntimeReviewerReceipt(input: {
       ...(accepted.specDisposition === undefined
         ? {}
         : { specDisposition: accepted.specDisposition }),
+      // Self-fetch bytes + source annotation retained for audit (#343 fetch-then-store).
+      ...(accepted.specFetchedMaterial === undefined
+        ? {}
+        : { specFetchedMaterial: accepted.specFetchedMaterial }),
     }),
     reports,
     outcomes,

package/src/role-runtime.ts

@@ -61,7 +61,7 @@ import {
   type ReviewerActivation,
   type ReviewerAdmittedInputs,
 } from "./reviewer-role.ts";
-import type { AcceptedReviewerExecution, ReviewerPinnedGitReader } from "./reviewer-dispatch.ts";
+import type { AcceptedReviewerExecution, ReviewerIssueFetcher, ReviewerPinnedGitReader } from "./reviewer-dispatch.ts";
 import type { ReviewerDispatchRunResult } from "./reviewer-agent.ts";
 import {
   REVIEWER_VERIFICATION_BOUNDARY,
@@ -94,6 +94,13 @@ const REVIEWER_TRANSPORT_FLAGS = Object.freeze([
       type: "string" as const,
     }),
   }),
+  Object.freeze({
+    name: "ak-review-ticket-number",
+    definition: Object.freeze({
+      description: "Typed ticketNumber for Spec self-fetch primary path",
+      type: "string" as const,
+    }),
+  }),
 ] as const);
 
 /**
@@ -134,6 +141,13 @@ function decodeReviewerAdmittedInputs(getFlag: (name: string) => unknown): Revie
     authorityRefs = Object.freeze(parsed as string[]);
   }
 
+  let ticketNumber: number | undefined;
+  const rawTicketNumber = getFlag("ak-review-ticket-number");
+  // Shape-invalid flag values do not abort: omit typed candidate; branch→commit→degrade continues.
+  if (typeof rawTicketNumber === "string" && /^[1-9]\d*$/.test(rawTicketNumber)) {
+    ticketNumber = Number(rawTicketNumber);
+  }
+
   const baseRevision = getFlag("ak-review-base");
   if (typeof baseRevision !== "string" || !baseRevision.trim()) {
     throw new Error("Reviewer role requires --ak-review-base");
@@ -142,6 +156,7 @@ function decodeReviewerAdmittedInputs(getFlag: (name: string) => unknown): Revie
     baseRevision,
     ...(reviewScopeKeys === undefined ? {} : { reviewScopeKeys }),
     ...(authorityRefs === undefined ? {} : { authorityRefs }),
+    ...(ticketNumber === undefined ? {} : { ticketNumber }),
   });
 }
 
@@ -454,6 +469,8 @@ export type RoleRuntimeDependencies = {
   loadCoderTask?(path: string): Promise<string>;
   loadReviewerSoul?(): Promise<string>;
   createReviewerPinnedGitReader?(): Promise<ReviewerPinnedGitReader>;
+  /** Shared-seam issue-fetch capability for Reviewer Spec self-fetch (#343). */
+  createReviewerIssueFetcher?(): ReviewerIssueFetcher;
   loadCollectorSoul?(): Promise<string>;
   createCollectorTransport?(): CollectorGitHubTransport;
   loadDoctorSoul?(): Promise<string>;
@@ -892,6 +909,9 @@ export function createRoleRuntimeExtension(
           }
           return dependencies.loadCanonicalSkillBinding(name);
         },
+        ...(dependencies.createReviewerIssueFetcher === undefined
+          ? {}
+          : { fetchIssue: dependencies.createReviewerIssueFetcher() }),
         async runDispatch(dispatch, options) {
           if (dependencies.runReviewerDispatch === undefined) throw new Error("Reviewer runtime dependencies are not configured");
           return dependencies.runReviewerDispatch(dispatch, options);