@akagilnc/pi-workflow-roles 0.1.1893 → 0.1.1941

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

@@ -308,8 +308,9 @@ async function dispatchAdmittedMerger(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
-    if (env.correlationId !== undefined && env.correlationId.trim() !== "") {
-      childEnv.AK_CORRELATION_ID = env.correlationId;
+    const correlationId = admitted.correlationId ?? env.correlationId;
+    if (correlationId !== undefined && correlationId.trim() !== "") {
+      childEnv.AK_CORRELATION_ID = correlationId;
     }
 
     let result: ExplicitInternalPiResult;
@@ -589,7 +590,10 @@ export async function runPublicMerger(
 
   return await dispatchAdmittedMerger({
     admitted,
-    env,
+    env: {
+      ...env,
+      ...(admitted.correlationId === undefined ? {} : { correlationId: admitted.correlationId }),
+    },
     io,
     extraArgs,
     lease,
@@ -676,7 +680,10 @@ export async function runPublicMergerResume(
 
   return await dispatchAdmittedMerger({
     admitted,
-    env,
+    env: {
+      ...env,
+      ...(admitted.correlationId === undefined ? {} : { correlationId: admitted.correlationId }),
+    },
     io,
     extraArgs,
     lease,

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

@@ -118,6 +118,10 @@ export function buildReviewerActivationExtraArgs(
     options.packageRoot,
     "code-review",
   );
+  const authorityRefArgs =
+    admitted.authorityRefs.length === 0
+      ? []
+      : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
   return [
     "--no-skills",
     "--skill",
@@ -134,6 +138,7 @@ export function buildReviewerActivationExtraArgs(
     "reviewer",
     "--ak-review-base",
     admitted.baseRevision,
+    ...authorityRefArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),
@@ -157,6 +162,10 @@ export function buildReviewerResumeActivationExtraArgs(
     options.packageRoot,
     "code-review",
   );
+  const authorityRefArgs =
+    admitted.authorityRefs.length === 0
+      ? []
+      : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
   return [
     "--no-skills",
     "--skill",
@@ -173,6 +182,7 @@ export function buildReviewerResumeActivationExtraArgs(
     "reviewer",
     "--ak-review-base",
     admitted.baseRevision,
+    ...authorityRefArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),
@@ -293,8 +303,9 @@ async function dispatchAdmittedReviewer(input: {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory,
     };
-    if (env.correlationId !== undefined && env.correlationId.trim() !== "") {
-      childEnv.AK_CORRELATION_ID = env.correlationId;
+    const correlationId = admitted.correlationId ?? env.correlationId;
+    if (correlationId !== undefined && correlationId.trim() !== "") {
+      childEnv.AK_CORRELATION_ID = correlationId;
     }
 
     let result: ExplicitInternalPiResult;
@@ -419,6 +430,7 @@ export async function runPublicReviewer(
     instruction: string;
     attachmentPaths: string[];
     baseRevision: string;
+    authorityRefs: string[];
     project?: string;
   },
 ): Promise<{
@@ -435,6 +447,7 @@ export async function runPublicReviewer(
       instruction: parsed.instruction,
       attachmentPaths: parsed.attachmentPaths,
       baseRevision: parsed.baseRevision,
+      authorityRefs: parsed.authorityRefs,
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
     });
@@ -484,7 +497,10 @@ export async function runPublicReviewer(
 
   return await dispatchAdmittedReviewer({
     admitted,
-    env,
+    env: {
+      ...env,
+      ...(admitted.correlationId === undefined ? {} : { correlationId: admitted.correlationId }),
+    },
     io,
     extraArgs,
     lease,
@@ -570,7 +586,10 @@ export async function runPublicReviewerResume(
 
   return await dispatchAdmittedReviewer({
     admitted,
-    env,
+    env: {
+      ...env,
+      ...(admitted.correlationId === undefined ? {} : { correlationId: admitted.correlationId }),
+    },
     io,
     extraArgs,
     lease,

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

@@ -24,6 +24,7 @@ export {
 import type { FixerPhase } from "../package-contracts/fixer-output.ts";
 import type { FixerPrerequisite } from "../package-contracts/fixer-packet.ts";
 import {
+  requireAuthorityRef,
   type AdmittedCoderInvocation,
   type AdmittedFixerInvocation,
   type AdmittedJudgeInvocation,
@@ -389,10 +390,43 @@ type LoadedAdmittedRequestFields = {
   readonly prerequisitesPath?: string;
   readonly prerequisites?: readonly FixerPrerequisite[];
   readonly baseRevision?: string;
+  readonly authorityRefs?: readonly string[];
   readonly mergerInputPath?: string;
   readonly derived?: DerivedMergerEnvelope;
+  readonly correlationId?: string;
+  readonly ticketNumber?: number;
 };
 
+/** Restore optional correlation + typed ticketNumber from a durable admitted page. */
+function parsePersistedTicketIdentity(
+  record: Record<string, unknown>,
+): { correlationId?: string; ticketNumber?: number } {
+  const correlationId =
+    typeof record.correlationId === "string" && record.correlationId.trim() !== ""
+      ? record.correlationId
+      : undefined;
+  const ticketNumber =
+    typeof record.ticketNumber === "number" &&
+    Number.isInteger(record.ticketNumber) &&
+    record.ticketNumber >= 1
+      ? record.ticketNumber
+      : undefined;
+  return {
+    ...(correlationId === undefined ? {} : { correlationId }),
+    ...(ticketNumber === undefined ? {} : { ticketNumber }),
+  };
+}
+
+function restoredTicketFields(fields: LoadedAdmittedRequestFields): {
+  correlationId?: string;
+  ticketNumber?: number;
+} {
+  return {
+    ...(fields.correlationId === undefined ? {} : { correlationId: fields.correlationId }),
+    ...(fields.ticketNumber === undefined ? {} : { ticketNumber: fields.ticketNumber }),
+  };
+}
+
 async function loadResumableRunRecord(
   home: string,
   runId: string,
@@ -431,8 +465,11 @@ async function loadResumableRunRecord(
   let prerequisitesPath: string | undefined;
   let prerequisites: readonly FixerPrerequisite[] | undefined;
   let baseRevision: string | undefined;
+  let authorityRefs: readonly string[] | undefined;
   let mergerInputPath: string | undefined;
   let derived: DerivedMergerEnvelope | undefined;
+  let correlationId: string | undefined;
+  let ticketNumber: number | undefined;
   try {
     const raw: unknown = JSON.parse(
       await readFile(run.admittedRequestPath, "utf8"),
@@ -472,6 +509,19 @@ async function loadResumableRunRecord(
       ) {
         baseRevision = record.baseRevision;
       }
+      if (Array.isArray(record.authorityRefs)) {
+        // Reuse unique --authority-ref grammar; blank/inline prose must not resume as authority.
+        authorityRefs = Object.freeze(
+          record.authorityRefs.map((ref) => {
+            if (typeof ref !== "string") {
+              throw new CliUsageError(
+                "role run admitted authority refs must be durable reference strings",
+              );
+            }
+            return requireAuthorityRef(ref);
+          }),
+        );
+      }
       if (
         typeof record.mergerInputPath === "string" &&
         record.mergerInputPath.trim() !== ""
@@ -502,12 +552,49 @@ async function loadResumableRunRecord(
           };
         }
       }
+      const fromAdmitted = parsePersistedTicketIdentity(record);
+      correlationId = fromAdmitted.correlationId;
+      ticketNumber = fromAdmitted.ticketNumber;
     }
-  } catch {
+  } catch (error) {
+    // Preserve unique --authority-ref grammar failures; do not collapse to unreadable.
+    if (error instanceof CliUsageError) throw error;
     throw new CliUsageError(
       `role run admitted request is unreadable: ${runId}`,
+      { cause: error },
     );
   }
+  if (correlationId === undefined || ticketNumber === undefined) {
+    try {
+      const invocationRaw: unknown = JSON.parse(
+        await readFile(join(run.runDirectory, "invocation.json"), "utf8"),
+      );
+      if (
+        invocationRaw !== null &&
+        typeof invocationRaw === "object" &&
+        !Array.isArray(invocationRaw)
+      ) {
+        const fromInvocation = parsePersistedTicketIdentity(
+          invocationRaw as Record<string, unknown>,
+        );
+        if (correlationId === undefined) correlationId = fromInvocation.correlationId;
+        if (ticketNumber === undefined) ticketNumber = fromInvocation.ticketNumber;
+      }
+    } catch (error) {
+      if (
+        !(
+          error instanceof Error &&
+          "code" in error &&
+          (error as { code?: unknown }).code === "ENOENT"
+        )
+      ) {
+        throw new CliUsageError(
+          `role run invocation identity is unreadable: ${runId}`,
+          { cause: error },
+        );
+      }
+    }
+  }
   return {
     run,
     observation: run.resumable,
@@ -521,8 +608,11 @@ async function loadResumableRunRecord(
       ...(prerequisitesPath === undefined ? {} : { prerequisitesPath }),
       ...(prerequisites === undefined ? {} : { prerequisites }),
       ...(baseRevision === undefined ? {} : { baseRevision }),
+      ...(authorityRefs === undefined ? {} : { authorityRefs }),
       ...(mergerInputPath === undefined ? {} : { mergerInputPath }),
       ...(derived === undefined ? {} : { derived }),
+      ...(correlationId === undefined ? {} : { correlationId }),
+      ...(ticketNumber === undefined ? {} : { ticketNumber }),
     },
   };
 }
@@ -577,6 +667,7 @@ export async function loadResumableJudgeRun(
     sessionDirectory: loaded.run.sessionDirectory,
     sessionFile: loaded.run.sessionFile,
     admittedRequestPath: loaded.run.admittedRequestPath,
+    ...restoredTicketFields(loaded.admittedFields),
   };
   return {
     admitted,
@@ -630,6 +721,7 @@ export async function loadResumableCoderRun(
     sessionFile: loaded.run.sessionFile,
     admittedRequestPath: loaded.run.admittedRequestPath,
     taskPath,
+    ...restoredTicketFields(loaded.admittedFields),
   };
   return {
     admitted,
@@ -688,6 +780,7 @@ export async function loadResumableFixerRun(
       ? {}
       : { prerequisitesPath: loaded.admittedFields.prerequisitesPath }),
     prerequisites,
+    ...restoredTicketFields(loaded.admittedFields),
   };
   return {
     admitted,
@@ -733,6 +826,8 @@ export async function loadResumableReviewerRun(
     sessionFile: loaded.run.sessionFile,
     admittedRequestPath: loaded.run.admittedRequestPath,
     baseRevision,
+    authorityRefs: Object.freeze([...(loaded.admittedFields.authorityRefs ?? [])]),
+    ...restoredTicketFields(loaded.admittedFields),
   };
   return {
     admitted,
@@ -792,6 +887,7 @@ export async function loadResumableMergerRun(
     admittedRequestPath: loaded.run.admittedRequestPath,
     mergerInputPath,
     derived,
+    ...restoredTicketFields(loaded.admittedFields),
   };
   return {
     admitted,

package/src/public-cli/settlement.ts

@@ -1255,6 +1255,7 @@ function reviewerDecisiveFacts(
   const axes = reviewerAxes(outcomes.readable ? outcomes.value : undefined);
   const reportAxes = reviewerAxes(reports.readable ? reports.value : undefined);
   const acceptedBatch = safelyRead(candidate, "acceptedBatch");
+  const specDisposition = safelyRead(candidate, "specDisposition");
   const facts: Record<string, unknown> = {
     axes,
     reportAxes,
@@ -1262,6 +1263,12 @@ function reviewerDecisiveFacts(
     ...auditNoReceiptDecisiveFact(candidate),
   };
   if (status.readable && typeof status.value === "string") facts.reviewerStatus = status.value;
+  if (
+    specDisposition.readable &&
+    (specDisposition.value === "launched" || specDisposition.value === "skipped-missing")
+  ) {
+    facts.specDisposition = specDisposition.value;
+  }
   const diagnostic = safelyRead(candidate, "diagnostic");
   if (status.readable && status.value === "refused" && diagnostic.readable) {
     facts.diagnosticPresent = typeof diagnostic.value === "string" && diagnostic.value.trim().length > 0;
@@ -3165,6 +3172,7 @@ export async function publishReviewerArtifacts(
         sessionFile: admitted.sessionFile,
         admittedRequestPath: admitted.admittedRequestPath,
         baseRevision: admitted.baseRevision,
+        authorityRefs: [...admitted.authorityRefs],
         ...(admitted.instructionEmpty
           ? {}
           : { callerProvenance: admitted.instruction }),

package/src/reviewer-construction.ts

@@ -18,6 +18,22 @@ export const REVIEWER_AXIS_OUTPUT_ADAPTER = Object.freeze({
   implementationSha256: sha256Hex("reviewer-axis-output:v1:single-axis-verbatim-report+standards-three-priorities"),
 });
 
+/**
+ * Package-owned #1185 review verification cadence.
+ * Single true source consumed by two real actor carriers: parent Reviewer system-prompt injection
+ * and evidence-child system prompt. Not part of axis-adapter identity or axis leg prompts.
+ * Graded guidance only: focused tests allowed; full suite not forbidden but avoid frequent every-round reruns.
+ * Does not narrow ADR 0064 tools and adds no command ban, allowlist, or runtime block.
+ */
+export const REVIEWER_VERIFICATION_BOUNDARY = [
+  "Verification-Boundary: you may run focused product tests during this review turn when independent verification needs them.",
+  "A full repository test suite is not forbidden, but do not re-run it every review round;",
+  "prefer once at family wrap-up unless this review specifically requires a broader run.",
+  "Slice and review work should not trigger frequent full-suite reruns.",
+  "Independently discover test facts (including existing coder/fixer receipts and any tests you run);",
+  "do not treat caller prose as the source of those facts.",
+].join(" ");
+
 /** Typed Standards conclusion keys owned by reviewer construction (presentation labels are not the contract). */
 export const REVIEWER_STANDARDS_CONCLUSION_KEYS = Object.freeze([
   "constitutionality",
@@ -85,6 +101,15 @@ export function reviewerAxisMethodAdapter(axis: ReviewerAxis): string {
 }
 
 export type ConstructedReviewerLeg = Readonly<{ axis: "standards" | "spec"; prompt: ReviewerPromptText }>;
+/**
+ * Unique discovery product for Skill step 2: durable refs Spec child can read, or confirmed missing.
+ * Construction builds Standards/Spec solely from this product — no secondary launch decision.
+ */
+export type ReviewerSpecAuthorityDiscovery =
+  | Readonly<{ status: "available"; refs: readonly string[] }>
+  | Readonly<{ status: "missing" }>;
+/** Spec-child cardinality decision recorded on the accepted dispatch. */
+export type ReviewerSpecDisposition = "launched" | "skipped-missing";
 export type ConstructedReviewerDispatch = Readonly<{
   identity: string;
   recipe: "reviewer-common-bundle-v1";
@@ -94,17 +119,40 @@ export type ConstructedReviewerDispatch = Readonly<{
   }>;
   targetSnapshot: ReviewerPinnedTarget;
   range: ReviewerRange;
+  /** Frozen durable authority references carried into Spec evidence-child material only. */
+  authorityRefs: readonly string[];
+  /** Honest Spec-child disposition: launched, or skipped after confirmed missing Spec. */
+  specDisposition: ReviewerSpecDisposition;
   legs: readonly ConstructedReviewerLeg[];
 }>;
 
-/** Deterministic compiler: fixed target/range plus packaged Skill in, dispatch text out. */
+/**
+ * Spec-only evidence-child material carrier for durable authority references.
+ * Exact values preserved; no prose extraction and no Standards/parent injection.
+ */
+export function reviewerAuthorityRefsMaterial(authorityRefs: readonly string[]): string {
+  return [
+    "Authority-Refs:",
+    JSON.stringify(Object.freeze([...authorityRefs])),
+    "These are durable authority references only. Read them as 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;
   canonicalSkill: string;
   target: ReviewerPinnedTarget;
   range: ReviewerRange;
   reviewScopeKeys?: readonly string[];
+  /** Unique discovery product (available+refs material, or missing). */
+  specAuthority: ReviewerSpecAuthorityDiscovery;
 }): ConstructedReviewerDispatch {
+  const launchSpec = input.specAuthority.status === "available";
+  const authorityRefs = Object.freeze(
+    input.specAuthority.status === "available" ? [...input.specAuthority.refs] : [],
+  );
+  const specDisposition: ReviewerSpecDisposition = launchSpec ? "launched" : "skipped-missing";
   const common = [
     `Target: ${input.range.target}`,
     `Base: ${input.range.base}`,
@@ -116,13 +164,20 @@ export function constructReviewerDispatch(input: {
     "Fixed-Range:",
     JSON.stringify(input.range, null, 2),
   ].join("\n");
-  const axes = [{ axis: "standards" as const }, { axis: "spec" as const }];
-  const legs = axes.map((x) =>
-    Object.freeze({
+  const axes: readonly { axis: "standards" | "spec" }[] = launchSpec
+    ? [{ axis: "standards" }, { axis: "spec" }]
+    : [{ axis: "standards" }];
+  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));
+    }
+    return Object.freeze({
       axis: x.axis,
-      prompt: `${common}\n${reviewerAxisMethodAdapter(x.axis)}\n`,
-    }),
-  );
+      prompt: `${parts.join("\n")}\n`,
+    });
+  });
   return Object.freeze({
     identity: input.identity,
     recipe: "reviewer-common-bundle-v1",
@@ -132,6 +187,8 @@ export function constructReviewerDispatch(input: {
     }),
     targetSnapshot: input.target,
     range: input.range,
+    authorityRefs,
+    specDisposition,
     legs: Object.freeze(legs),
   });
 }

package/src/reviewer-dispatch.ts

@@ -1,13 +1,84 @@
 import { sameReviewerPinnedTarget } from "./reviewer-git-snapshot.ts";
-import { immutableReviewerPin, type ReviewerPinnedGitReader, type ReviewerPinnedTarget } from "./reviewer-pinned-git.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 { isReviewerPromptText, sameReviewerPromptText, type ReviewerPromptText } from "./reviewer-prompt-identity.ts";
 import { sha256Hex } from "./sha256.ts";
-import { constructReviewerDispatch, type ConstructedReviewerDispatch } from "./reviewer-construction.ts";
+import {
+  constructReviewerDispatch,
+  type ConstructedReviewerDispatch,
+  type ReviewerSpecAuthorityDiscovery,
+} from "./reviewer-construction.ts";
+export {
+  type ReviewerSpecAuthorityDiscovery,
+  type ReviewerSpecDisposition,
+} from "./reviewer-construction.ts";
 import { ReviewerCorrectablePreflightError } from "./reviewer-preflight-error.ts";
 export { sha256Hex } from "./sha256.ts";
 export { isReviewerPromptText as isReviewerPromptIdentity, sameReviewerPromptText as sameReviewerPromptIdentity, type ReviewerPromptText as ReviewerPromptIdentity } from "./reviewer-prompt-identity.ts";
 
+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)-/;
+
+function normalizeFeatureToken(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+/** Expand one branch/ref name into matchable tokens, stripping conventional shells. */
+function expandFeatureTokens(raw: string): readonly string[] {
+  const normalized = normalizeFeatureToken(raw);
+  if (normalized.length === 0) return Object.freeze([]);
+  const tokens = new Set<string>([normalized]);
+  const stripped = normalized.replace(BRANCH_SHELL_PREFIX, "");
+  if (stripped.length > 0 && stripped !== normalized) tokens.add(stripped);
+  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.
+ * Construction builds Standards/Spec solely from this product.
+ */
+export async function discoverReviewerSpecAuthority(input: {
+  authorityRefs: readonly string[];
+  reader: ReviewerPinnedGitReader;
+}): Promise<ReviewerSpecAuthorityDiscovery> {
+  if (input.authorityRefs.length > 0) {
+    return Object.freeze({
+      status: "available" as const,
+      refs: Object.freeze([...input.authorityRefs]),
+    });
+  }
+  const featureTokens = await input.reader.featureTokens();
+  const tokens = [
+    ...new Set(
+      featureTokens
+        .flatMap((raw) => expandFeatureTokens(raw))
+        .filter((token) => token.length >= 3 && !GENERIC_FEATURE_TOKENS.has(token)),
+    ),
+  ];
+  if (tokens.length === 0) {
+    return Object.freeze({ status: "missing" as const });
+  }
+  // Pinned target tree only — Spec child cannot read live-worktree or gitignored paths.
+  const candidates = await input.reader.listSpecCandidatePaths();
+  const matched = candidates.filter((relativePath) => {
+    const normalizedPath = normalizeFeatureToken(relativePath);
+    return tokens.some((token) => normalizedPath.includes(token));
+  });
+  if (matched.length === 0) {
+    return Object.freeze({ status: "missing" as const });
+  }
+  return Object.freeze({
+    status: "available" as const,
+    refs: Object.freeze(matched),
+  });
+}
+
 export type AcceptedReviewerLeg = ConstructedReviewerDispatch["legs"][number];
 export type AcceptedReviewerDispatch = ConstructedReviewerDispatch;
 export type AcceptedReviewerExecution = Readonly<{
@@ -28,6 +99,8 @@ type DispatcherDependencies = Readonly<{
   canonicalSkill: string;
   reader: ReviewerPinnedGitReader;
   reviewScopeKeys?: readonly string[];
+  /** Durable authority references preserved unchanged into Spec-leg construction only. */
+  authorityRefs?: readonly string[];
   run(execution: AcceptedReviewerExecution, invocation: unknown): Promise<unknown>;
   decisionEvidence?(decision: ReviewerDecisionEvidence): void;
 }>;
@@ -66,12 +139,18 @@ export function createReviewerDispatcher(d: DispatcherDependencies) {
       try {
         const base = await d.reader.resolve(baseRevision);
         const range = await d.reader.range(base);
+        const authorityRefs = Object.freeze([...(d.authorityRefs ?? [])]);
+        const specAuthority = await discoverReviewerSpecAuthority({
+          authorityRefs,
+          reader: d.reader,
+        });
         dispatch = constructReviewerDispatch({
           identity,
           canonicalSkill: d.canonicalSkill,
           target,
           range,
           ...(d.reviewScopeKeys === undefined ? {} : { reviewScopeKeys: d.reviewScopeKeys }),
+          specAuthority,
         });
         if (!sameReviewerPinnedTarget(await d.reader.snapshot(), target)) {
           throw new ReviewerPreflightError("target-drift", "pinned target snapshot changed before child execution");

package/src/reviewer-execution-ledger.ts

@@ -27,7 +27,8 @@ export function projectAcceptedDispatch(dispatch: AcceptedReviewerDispatch): Rev
   return {
     source: "reviewer-dispatch", type: "accepted", identity: dispatch.identity,
     recipe: dispatch.recipe, input: dispatch.input, target: dispatch.targetSnapshot,
-    range: dispatch.range, legs: dispatch.legs,
+    range: dispatch.range, authorityRefs: dispatch.authorityRefs,
+    specDisposition: dispatch.specDisposition, legs: dispatch.legs,
   };
 }
 

package/src/reviewer-pinned-git.ts

@@ -25,6 +25,18 @@ export type ReviewerPinnedGitReader = {
   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.
+   * 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.
+   */
+  featureTokens(): Promise<readonly string[]>;
+  /**
+   * Durable Spec-candidate paths present in the pinned target tree under docs/specs/.scratch.
+   * Spec child clones this target — live working tree is not a source of material facts.
+   * Empty list is confirmed absence; other Git/I-O failures propagate with true cause.
+   */
+  listSpecCandidatePaths(): Promise<readonly string[]>;
 };
 
 const execFileAsync = promisify(execFile);
@@ -139,6 +151,37 @@ export async function createReviewerPinnedGitReader(root = process.cwd()): Promi
       if (diff.length === 0) invalid("range-invalid", "review range must contain a non-empty diff between base and pinned target");
       return Object.freeze({ base: mergeBase, target: targetHead, diffCommand, diffSha256: sha256Hex(Uint8Array.from(diff)), commits: Object.freeze(commitsText ? commitsText.split("\n") : []) });
     },
+    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.
+      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());
+      }
+      return Object.freeze([...names]);
+    },
+    async listSpecCandidatePaths() {
+      const roots = ["docs", "specs", ".scratch"] as const;
+      // git ls-tree exits 0 with empty stdout when none of the roots exist at targetHead.
+      // Other Git/I-O failures keep their true cause for the dispatch preflight path.
+      const text = await gitText(repositoryRoot, [
+        "ls-tree",
+        "-r",
+        "--name-only",
+        targetHead,
+        "--",
+        ...roots,
+      ]);
+      return Object.freeze(text === "" ? [] : text.split("\n").filter((line) => line.length > 0));
+    },
 
   });
 }