@akagilnc/pi-workflow-roles 0.1.1918 → 0.1.1941

package/dist/evidence-child-executor.js

@@ -9,9 +9,19 @@ import { join } from "node:path";
 import { createAssistantMessageEventStream, InMemoryCredentialStore, } from "@earendil-works/pi-ai";
 import { AUDITOR_COMPLIANCE_FAILURE_ENTRY_TYPE, AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE, prepareComplianceDispatch, } from "./compliance-transport.js";
 import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.js";
-import { createStreamIdleGuard, isStreamIdleTimeoutError } from "./stream-idle-guard.js";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.js";
+import { REVIEWER_VERIFICATION_BOUNDARY } from "./reviewer-construction.js";
+import { createStreamIdleGuard, isStreamIdleTimeoutError } from "./stream-idle-guard.js";
 import { hasUpstreamErrorTestimony, isNonSuccessHttpStatus, projectConfirmedRemotePayload, } from "./upstream-error-testimony.js";
+/** Package-owned system prompt for Reviewer Standards/Spec evidence children (private carrier). */
+function buildEvidenceChildSystemPrompt() {
+    return [
+        "Work only in the supplied workspace.",
+        "Use the available evidence tools to investigate. Do not commit, push, or mutate remotes.",
+        REVIEWER_VERIFICATION_BOUNDARY,
+        "Return one substantive non-blank report.",
+    ].join("\n");
+}
 // ── shared constants / types ──────────────────────────────────────────────
 export const AUDITOR_TURN_LIMIT = 32;
 export const DEFAULT_COMPLIANCE_IDLE_MAX_RETRIES = 2;
@@ -450,11 +460,7 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
             model: inherited.model,
             thinkingLevel: context.thinkingLevel ?? "off",
             modelRuntime: inherited.runtime,
-            systemPrompt: [
-                "Work only in the supplied workspace.",
-                "Use the available evidence tools to investigate. Do not commit, push, or mutate remotes.",
-                "Return one substantive non-blank report.",
-            ].join("\n"),
+            systemPrompt: buildEvidenceChildSystemPrompt(),
             sessionManager: createRecordSession({
                 cwd: workspace,
                 kind: "evidence-children",

package/dist/package-contracts/reviewer-output.js

@@ -68,6 +68,22 @@ export function validateRuntimeReviewerReceipt(output) {
             if (status === "failed" && report !== undefined)
                 throw new Error("Failed Reviewer outcome cannot bind a report");
         }
+        // One read inside the existing accepted-leg consistency cycle — not a second validator.
+        // launched ⇔ Standards+Spec; skipped-missing ⇔ Standards only.
+        const specDisposition = read(output, "specDisposition");
+        if (specDisposition === "launched") {
+            if (expectedAxes.length !== 2 || expectedAxes[0] !== "standards" || expectedAxes[1] !== "spec") {
+                throw new Error("Reviewer specDisposition launched requires Standards+Spec accepted legs");
+            }
+        }
+        else if (specDisposition === "skipped-missing") {
+            if (expectedAxes.length !== 1 || expectedAxes[0] !== "standards") {
+                throw new Error("Reviewer specDisposition skipped-missing requires Standards-only accepted legs");
+            }
+        }
+        else if (specDisposition !== undefined) {
+            throw new Error("Invalid Reviewer specDisposition");
+        }
     }
     return output;
 }

package/dist/public-cli/main.js

@@ -147,6 +147,18 @@ function validateRuntimeReviewerReceipt(output) {
         throw new Error("Successful Reviewer outcome lacks report");
       if (status === "failed" && report !== void 0) throw new Error("Failed Reviewer outcome cannot bind a report");
     }
+    const specDisposition = read(output, "specDisposition");
+    if (specDisposition === "launched") {
+      if (expectedAxes.length !== 2 || expectedAxes[0] !== "standards" || expectedAxes[1] !== "spec") {
+        throw new Error("Reviewer specDisposition launched requires Standards+Spec accepted legs");
+      }
+    } else if (specDisposition === "skipped-missing") {
+      if (expectedAxes.length !== 1 || expectedAxes[0] !== "standards") {
+        throw new Error("Reviewer specDisposition skipped-missing requires Standards-only accepted legs");
+      }
+    } else if (specDisposition !== void 0) {
+      throw new Error("Invalid Reviewer specDisposition");
+    }
   }
   return output;
 }
@@ -15464,6 +15476,17 @@ function requireOptionPath(flag, value) {
   }
   return value;
 }
+function requireAuthorityRef(value) {
+  if (value === void 0 || value.trim() === "") {
+    throw new CliUsageError("--authority-ref requires a nonempty durable reference");
+  }
+  if (/\s/.test(value)) {
+    throw new CliUsageError(
+      "--authority-ref requires a durable reference, not inline Spec prose"
+    );
+  }
+  return value;
+}
 function parseJudgeArgv(args) {
   const attachmentPaths = [];
   let project;
@@ -16426,6 +16449,7 @@ function buildDoctorTransportPrompt(admitted) {
 }
 function parseReviewerArgv(args) {
   const attachmentPaths = [];
+  const authorityRefs = [];
   let project;
   let baseRevision;
   const positional = [];
@@ -16452,6 +16476,14 @@ function parseReviewerArgv(args) {
       baseRevision = requireOptionPath("--base", token.slice("--base=".length));
       continue;
     }
+    if (token === "--authority-ref") {
+      authorityRefs.push(requireAuthorityRef(tokens.shift()));
+      continue;
+    }
+    if (token.startsWith("--authority-ref=")) {
+      authorityRefs.push(requireAuthorityRef(token.slice("--authority-ref=".length)));
+      continue;
+    }
     if (token.startsWith("-") && token !== "-") {
       throw new CliUsageError(`unknown reviewer option: ${token}`);
     }
@@ -16464,6 +16496,7 @@ function parseReviewerArgv(args) {
     instruction: positional.join(" "),
     attachmentPaths,
     baseRevision,
+    authorityRefs,
     ...project === void 0 ? {} : { project }
   };
 }
@@ -16474,6 +16507,9 @@ async function admitReviewerInvocation(options) {
   if (options.baseRevision.trim() === "") {
     throw new CliUsageError("--base requires a nonempty revision");
   }
+  const authorityRefs = Object.freeze(
+    (options.authorityRefs ?? []).map((ref) => requireAuthorityRef(ref))
+  );
   const projectRoot = resolve4(options.project ?? options.cwd);
   const runId = (options.createRunId ?? uuidv7)();
   const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } = roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "reviewer", home: options.home });
@@ -16499,6 +16535,7 @@ async function admitReviewerInvocation(options) {
     instruction,
     instructionEmpty,
     baseRevision: options.baseRevision,
+    authorityRefs: [...authorityRefs],
     attachments: attachments.map((a) => ({
       provenancePath: a.provenancePath,
       frozenPath: a.frozenPath,
@@ -16528,6 +16565,7 @@ async function admitReviewerInvocation(options) {
     sessionFile,
     admittedRequestPath,
     baseRevision: options.baseRevision,
+    authorityRefs,
     ...ticketFields
   };
 }
@@ -16804,7 +16842,7 @@ var init_reviewer_scope_prompt = __esm({
 });
 
 // src/reviewer-construction.ts
-var REVIEWER_CONSTRUCTION_RECIPE, REVIEWER_AXIS_OUTPUT_ADAPTER, REVIEWER_STANDARDS_CONCLUSION_KEYS, REVIEWER_STANDARDS_CONCLUSION_LABELS;
+var REVIEWER_CONSTRUCTION_RECIPE, REVIEWER_AXIS_OUTPUT_ADAPTER, REVIEWER_VERIFICATION_BOUNDARY, REVIEWER_STANDARDS_CONCLUSION_KEYS, REVIEWER_STANDARDS_CONCLUSION_LABELS;
 var init_reviewer_construction = __esm({
   "src/reviewer-construction.ts"() {
     "use strict";
@@ -16821,6 +16859,14 @@ var init_reviewer_construction = __esm({
       version: 1,
       implementationSha256: sha256Hex("reviewer-axis-output:v1:single-axis-verbatim-report+standards-three-priorities")
     });
+    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(" ");
     REVIEWER_STANDARDS_CONCLUSION_KEYS = Object.freeze([
       "constitutionality",
       "minimum-necessary-test-cost",
@@ -16845,6 +16891,7 @@ var init_reviewer_dispatch = __esm({
     init_reviewer_prompt_identity();
     init_sha256();
     init_reviewer_construction();
+    init_reviewer_construction();
     init_reviewer_preflight_error();
     init_sha256();
     init_reviewer_prompt_identity();
@@ -17640,6 +17687,7 @@ async function loadResumableRunRecord(home, runId) {
   let prerequisitesPath;
   let prerequisites;
   let baseRevision;
+  let authorityRefs;
   let mergerInputPath;
   let derived;
   let correlationId;
@@ -17677,6 +17725,18 @@ async function loadResumableRunRecord(home, runId) {
       if (typeof record4.baseRevision === "string" && record4.baseRevision.trim() !== "") {
         baseRevision = record4.baseRevision;
       }
+      if (Array.isArray(record4.authorityRefs)) {
+        authorityRefs = Object.freeze(
+          record4.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 record4.mergerInputPath === "string" && record4.mergerInputPath.trim() !== "") {
         mergerInputPath = record4.mergerInputPath;
       }
@@ -17696,9 +17756,11 @@ async function loadResumableRunRecord(home, runId) {
       correlationId = fromAdmitted.correlationId;
       ticketNumber = fromAdmitted.ticketNumber;
     }
-  } catch {
+  } catch (error) {
+    if (error instanceof CliUsageError) throw error;
     throw new CliUsageError(
-      `role run admitted request is unreadable: ${runId}`
+      `role run admitted request is unreadable: ${runId}`,
+      { cause: error }
     );
   }
   if (correlationId === void 0 || ticketNumber === void 0) {
@@ -17735,6 +17797,7 @@ async function loadResumableRunRecord(home, runId) {
       ...prerequisitesPath === void 0 ? {} : { prerequisitesPath },
       ...prerequisites === void 0 ? {} : { prerequisites },
       ...baseRevision === void 0 ? {} : { baseRevision },
+      ...authorityRefs === void 0 ? {} : { authorityRefs },
       ...mergerInputPath === void 0 ? {} : { mergerInputPath },
       ...derived === void 0 ? {} : { derived },
       ...correlationId === void 0 ? {} : { correlationId },
@@ -17890,6 +17953,7 @@ async function loadResumableReviewerRun(home, runId) {
     sessionFile: loaded.run.sessionFile,
     admittedRequestPath: loaded.run.admittedRequestPath,
     baseRevision,
+    authorityRefs: Object.freeze([...loaded.admittedFields.authorityRefs ?? []]),
     ...restoredTicketFields(loaded.admittedFields)
   };
   return {
@@ -18093,8 +18157,9 @@ var init_evidence_child_executor = __esm({
     "use strict";
     init_compliance_transport();
     init_package_owned_tool_idle();
-    init_stream_idle_guard();
     init_receipt_delivery_policy();
+    init_reviewer_construction();
+    init_stream_idle_guard();
     init_upstream_error_testimony();
   }
 });
@@ -19352,6 +19417,7 @@ function reviewerDecisiveFacts(output) {
   const axes = reviewerAxes(outcomes.readable ? outcomes.value : void 0);
   const reportAxes = reviewerAxes(reports.readable ? reports.value : void 0);
   const acceptedBatch = safelyRead(candidate, "acceptedBatch");
+  const specDisposition = safelyRead(candidate, "specDisposition");
   const facts = {
     axes,
     reportAxes,
@@ -19359,6 +19425,9 @@ function reviewerDecisiveFacts(output) {
     ...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;
@@ -20649,6 +20718,7 @@ async function publishReviewerArtifacts(admitted, roleOutcome, sessionDirectory,
         sessionFile: admitted.sessionFile,
         admittedRequestPath: admitted.admittedRequestPath,
         baseRevision: admitted.baseRevision,
+        authorityRefs: [...admitted.authorityRefs],
         ...admitted.instructionEmpty ? {} : { callerProvenance: admitted.instruction },
         attachments: admitted.attachments.map((a) => ({
           provenancePath: a.provenancePath,
@@ -23335,6 +23405,7 @@ function buildReviewerActivationExtraArgs(admitted, options) {
     options.packageRoot,
     "code-review"
   );
+  const authorityRefArgs = admitted.authorityRefs.length === 0 ? [] : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
   return [
     "--no-skills",
     "--skill",
@@ -23351,6 +23422,7 @@ function buildReviewerActivationExtraArgs(admitted, options) {
     "reviewer",
     "--ak-review-base",
     admitted.baseRevision,
+    ...authorityRefArgs,
     "--mode",
     "json",
     ...buildModelArgs7(options.model),
@@ -23362,6 +23434,7 @@ function buildReviewerResumeActivationExtraArgs(admitted, options) {
     options.packageRoot,
     "code-review"
   );
+  const authorityRefArgs = admitted.authorityRefs.length === 0 ? [] : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
   return [
     "--no-skills",
     "--skill",
@@ -23378,6 +23451,7 @@ function buildReviewerResumeActivationExtraArgs(admitted, options) {
     "reviewer",
     "--ak-review-base",
     admitted.baseRevision,
+    ...authorityRefArgs,
     "--mode",
     "json",
     ...buildModelArgs7(options.model),
@@ -23571,6 +23645,7 @@ async function runPublicReviewer(argv, env, io, parseReviewerArgv2) {
       instruction: parsed.instruction,
       attachmentPaths: parsed.attachmentPaths,
       baseRevision: parsed.baseRevision,
+      authorityRefs: parsed.authorityRefs,
       ...parsed.project === void 0 ? {} : { project: parsed.project },
       ...env.createRunId === void 0 ? {} : { createRunId: env.createRunId }
     });

package/dist/reviewer-construction.js

@@ -11,6 +11,21 @@ export const REVIEWER_AXIS_OUTPUT_ADAPTER = Object.freeze({
     version: 1,
     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",
@@ -63,8 +78,22 @@ export function reviewerAxisMethodAdapter(axis) {
         "The returned report is the complete output envelope and its UTF-8 bytes are preserved verbatim; no heading parser, sanitizer, section splitter, rewrite, aggregation, or replacement leg follows.",
     ].join("\n");
 }
-/** 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) {
+    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) {
+    const launchSpec = input.specAuthority.status === "available";
+    const authorityRefs = Object.freeze(input.specAuthority.status === "available" ? [...input.specAuthority.refs] : []);
+    const specDisposition = launchSpec ? "launched" : "skipped-missing";
     const common = [
         `Target: ${input.range.target}`,
         `Base: ${input.range.base}`,
@@ -76,11 +105,20 @@ export function constructReviewerDispatch(input) {
         "Fixed-Range:",
         JSON.stringify(input.range, null, 2),
     ].join("\n");
-    const axes = [{ axis: "standards" }, { axis: "spec" }];
-    const legs = axes.map((x) => Object.freeze({
-        axis: x.axis,
-        prompt: `${common}\n${reviewerAxisMethodAdapter(x.axis)}\n`,
-    }));
+    const axes = 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: `${parts.join("\n")}\n`,
+        });
+    });
     return Object.freeze({
         identity: input.identity,
         recipe: "reviewer-common-bundle-v1",
@@ -90,6 +128,8 @@ export function constructReviewerDispatch(input) {
         }),
         targetSnapshot: input.target,
         range: input.range,
+        authorityRefs,
+        specDisposition,
         legs: Object.freeze(legs),
     });
 }

package/dist/reviewer-dispatch.js

@@ -3,10 +3,67 @@ import { immutableReviewerPin } from "./reviewer-pinned-git.js";
 export { 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";
+import { constructReviewerDispatch, } from "./reviewer-construction.js";
+export {} from "./reviewer-construction.js";
 import { ReviewerCorrectablePreflightError } from "./reviewer-preflight-error.js";
 export { sha256Hex } from "./sha256.js";
 export { isReviewerPromptText as isReviewerPromptIdentity, sameReviewerPromptText as sameReviewerPromptIdentity } from "./reviewer-prompt-identity.js";
+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) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/** Expand one branch/ref name into matchable tokens, stripping conventional shells. */
+function expandFeatureTokens(raw) {
+    const normalized = normalizeFeatureToken(raw);
+    if (normalized.length === 0)
+        return Object.freeze([]);
+    const tokens = new Set([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) {
+    if (input.authorityRefs.length > 0) {
+        return Object.freeze({
+            status: "available",
+            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" });
+    }
+    // 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" });
+    }
+    return Object.freeze({
+        status: "available",
+        refs: Object.freeze(matched),
+    });
+}
 export const REVIEWER_PREFLIGHT_VIOLATIONS = ["base-invalid", "range-invalid", "prompt-identity-invalid", "target-drift"];
 export class ReviewerPreflightError extends Error {
     code;
@@ -49,12 +106,18 @@ export function createReviewerDispatcher(d) {
             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/dist/reviewer-execution-ledger.js

@@ -5,7 +5,8 @@ export function projectAcceptedDispatch(dispatch) {
     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,
     };
 }
 export function projectReviewerDispatchOutcome(ledger, dispatch, result) {

package/dist/reviewer-pinned-git.js

@@ -142,5 +142,38 @@ export async function createReviewerPinnedGitReader(root = process.cwd()) {
                 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();
+            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"];
+            // 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));
+        },
     });
 }

package/package.json

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

package/src/evidence-child-executor.ts

@@ -30,15 +30,26 @@ import {
   type AuditorParentAttemptBinding,
 } from "./compliance-transport.ts";
 import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.ts";
+import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT, type NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
+import { REVIEWER_VERIFICATION_BOUNDARY } from "./reviewer-construction.ts";
 import type { ReviewerPromptText } from "./reviewer-prompt-identity.ts";
 import { createStreamIdleGuard, isStreamIdleTimeoutError } from "./stream-idle-guard.ts";
-import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT, type NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import {
   hasUpstreamErrorTestimony,
   isNonSuccessHttpStatus,
   projectConfirmedRemotePayload,
 } from "./upstream-error-testimony.ts";
 
+/** Package-owned system prompt for Reviewer Standards/Spec evidence children (private carrier). */
+function buildEvidenceChildSystemPrompt(): string {
+  return [
+    "Work only in the supplied workspace.",
+    "Use the available evidence tools to investigate. Do not commit, push, or mutate remotes.",
+    REVIEWER_VERIFICATION_BOUNDARY,
+    "Return one substantive non-blank report.",
+  ].join("\n");
+}
+
 // ── shared constants / types ──────────────────────────────────────────────
 
 export const AUDITOR_TURN_LIMIT = 32;
@@ -561,11 +572,7 @@ export async function executeEvidenceChild(
         model: inherited.model,
         thinkingLevel: context.thinkingLevel ?? "off",
         modelRuntime: inherited.runtime,
-        systemPrompt: [
-          "Work only in the supplied workspace.",
-          "Use the available evidence tools to investigate. Do not commit, push, or mutate remotes.",
-          "Return one substantive non-blank report.",
-        ].join("\n"),
+        systemPrompt: buildEvidenceChildSystemPrompt(),
         sessionManager: createRecordSession({
           cwd: workspace,
           kind: "evidence-children",

package/src/package-contracts/reviewer-output.ts

@@ -26,11 +26,15 @@ export type RuntimeReviewerAcceptedBatch = Readonly<{
   identity: string;
   legs: readonly Readonly<{ axis: "standards" | "spec"; prompt: ReviewerReceiptPrompt }>[];
 }>;
+/** Honest Spec-child disposition on the receipt face. */
+export type RuntimeReviewerSpecDisposition = "launched" | "skipped-missing";
 export type RuntimeReviewerReceiptV2 = Readonly<{
   version: 2;
   status: "completed" | "refused";
   diagnostic?: string;
   acceptedBatch?: RuntimeReviewerAcceptedBatch;
+  /** Present on accepted batches: launched Spec child, or skipped after confirmed missing Spec. */
+  specDisposition?: RuntimeReviewerSpecDisposition;
   reports: Readonly<Partial<Record<"standards" | "spec", VerbatimChildReport>>>;
   outcomes: Readonly<Partial<Record<"standards" | "spec", RuntimeReviewerOutcome>>>;
   identities: Readonly<{
@@ -100,6 +104,21 @@ export function validateRuntimeReviewerReceipt(output: unknown): RuntimeReviewer
         throw new Error("Successful Reviewer outcome lacks report");
       if (status === "failed" && report !== undefined) throw new Error("Failed Reviewer outcome cannot bind a report");
     }
+
+    // One read inside the existing accepted-leg consistency cycle — not a second validator.
+    // launched ⇔ Standards+Spec; skipped-missing ⇔ Standards only.
+    const specDisposition = read(output, "specDisposition");
+    if (specDisposition === "launched") {
+      if (expectedAxes.length !== 2 || expectedAxes[0] !== "standards" || expectedAxes[1] !== "spec") {
+        throw new Error("Reviewer specDisposition launched requires Standards+Spec accepted legs");
+      }
+    } else if (specDisposition === "skipped-missing") {
+      if (expectedAxes.length !== 1 || expectedAxes[0] !== "standards") {
+        throw new Error("Reviewer specDisposition skipped-missing requires Standards-only accepted legs");
+      }
+    } else if (specDisposition !== undefined) {
+      throw new Error("Invalid Reviewer specDisposition");
+    }
   }
   return output as RuntimeReviewerReceiptV2;
 }