@akagilnc/pi-workflow-roles 0.1.1918 → 0.1.2004

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.2004",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/atomic-write.ts

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

package/src/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/ledger-session-read.ts

@@ -0,0 +1,260 @@
+/**
+ * Canonical ledger session JSONL read primitives (shared owner).
+ * Consumers (ticket-trajectory, taishi, …) must import here — no second parse kernel.
+ */
+import { readFile } from "node:fs/promises";
+
+export type LedgerSessionRow = Record<string, unknown>;
+
+/**
+ * Loud JSONL failure that still retains rows parsed before the bad line.
+ * Callers that only need the throw keep catching Error; owners that must
+ * surface partial typed facts (e.g. first-frame timestamp) read prefixRows.
+ */
+export class LedgerSessionJsonlError extends Error {
+  readonly path: string;
+  readonly line: number;
+  readonly prefixRows: readonly LedgerSessionRow[];
+
+  constructor(
+    message: string,
+    init: {
+      readonly path: string;
+      readonly line: number;
+      readonly prefixRows: readonly LedgerSessionRow[];
+    },
+  ) {
+    super(message);
+    this.name = "LedgerSessionJsonlError";
+    this.path = init.path;
+    this.line = init.line;
+    this.prefixRows = init.prefixRows;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read session JSONL with honest live-tail semantics:
+ * a malformed line is tolerated only when it is an unfinished final
+ * fragment at EOF (no record terminator after it). Any malformed line
+ * completed by a line terminator must fail loudly with file and 1-based
+ * line context — even when no non-empty record follows — never silently
+ * under-count.
+ *
+ * Loud failures throw LedgerSessionJsonlError carrying prefixRows so the
+ * single parse kernel can still expose facts obtained before the bad line.
+ */
+export async function readLedgerSessionJsonl(path: string): Promise<LedgerSessionRow[]> {
+  const text = await readFile(path, "utf8");
+  // split keeps a trailing empty segment iff text ends with "\n", so
+  // index < lines.length - 1 means this segment was terminated.
+  const lines = text.split("\n");
+  const rows: LedgerSessionRow[] = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    if (!line.trim()) continue;
+    let row: unknown;
+    try {
+      row = JSON.parse(line);
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      const completedByTerminator = index < lines.length - 1;
+      if (completedByTerminator) {
+        throw new LedgerSessionJsonlError(
+          `malformed JSONL record in ${path} at line ${index + 1}: ${error.message}`,
+          { path, line: index + 1, prefixRows: rows },
+        );
+      }
+      // unfinished fragment at EOF — keep prior complete rows
+      break;
+    }
+    // Syntactically complete line: must be a session object. Silent omission
+    // would under-count ledger evidence (failure honesty).
+    if (!isRecord(row)) {
+      const kind = row === null ? "null" : Array.isArray(row) ? "array" : typeof row;
+      throw new LedgerSessionJsonlError(
+        `complete non-object JSONL record in ${path} at line ${index + 1}: expected object, got ${kind}`,
+        { path, line: index + 1, prefixRows: rows },
+      );
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+/** First and last record timestamps in encounter order. */
+export function extractSessionTimestampSpan(
+  rows: readonly LedgerSessionRow[],
+): { startedAt?: string; endedAt?: string } {
+  let startedAt: string | undefined;
+  let endedAt: string | undefined;
+  for (const row of rows) {
+    if (typeof row.timestamp !== "string" || !row.timestamp) continue;
+    if (startedAt === undefined) startedAt = row.timestamp;
+    endedAt = row.timestamp;
+  }
+  return {
+    ...(startedAt !== undefined ? { startedAt } : {}),
+    ...(endedAt !== undefined ? { endedAt } : {}),
+  };
+}
+
+/**
+ * Ordered-unique model ids from session frames (first-seen order).
+ * Sources (same faces ticket-trajectory already reads — single parse kernel):
+ * - `model_change.modelId`
+ * - assistant `message.model`
+ * Blank / non-string values are skipped. Does not invent a default model.
+ */
+export function extractSessionModelSequence(
+  rows: readonly LedgerSessionRow[],
+): string[] {
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  const push = (raw: string): void => {
+    const model = raw.trim();
+    if (model === "" || seen.has(model)) return;
+    seen.add(model);
+    ordered.push(model);
+  };
+  for (const row of rows) {
+    if (row.type === "model_change" && typeof row.modelId === "string") {
+      push(row.modelId);
+    }
+    const message = isRecord(row.message) ? row.message : undefined;
+    if (message?.role === "assistant" && typeof message.model === "string") {
+      push(message.model);
+    }
+  }
+  return ordered;
+}
+
+/** First line of a bash `command` argument (sole owner of this summary). */
+export function bashCommandFirstLine(command: string): string {
+  const match = /^[^\r\n]*/.exec(command);
+  return match?.[0] ?? "";
+}
+
+export type SessionToolInterval = {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly startedAt: string;
+  readonly endedAt?: string;
+  /**
+   * Bash-only first-line command summary from `arguments.command`.
+   * Omitted for non-bash tools and when the argument is absent/non-string.
+   * Full multi-line bodies are never retained on this typed fact face.
+   */
+  readonly command?: string;
+};
+
+/**
+ * Pair toolCall frames → toolResult frames by toolCallId.
+ * Throws when a tool-bearing frame is structurally unreadable for association
+ * (toolCall missing string id, toolResult missing string toolCallId).
+ * Unpaired open calls remain without endedAt — that is incomplete, not unreadable.
+ */
+export function extractSessionToolIntervals(
+  rows: readonly LedgerSessionRow[],
+): SessionToolInterval[] {
+  type Open = {
+    toolCallId: string;
+    toolName: string;
+    startedAt: string;
+    endedAt?: string;
+    command?: string;
+  };
+  const order: Open[] = [];
+  const openById = new Map<string, Open>();
+
+  for (const row of rows) {
+    const rowTimestamp = typeof row.timestamp === "string" ? row.timestamp : undefined;
+    const message = isRecord(row.message) ? row.message : undefined;
+
+    if (message?.role === "assistant" && Array.isArray(message.content)) {
+      const callTimestamp =
+        typeof message.timestamp === "string" && message.timestamp
+          ? message.timestamp
+          : rowTimestamp;
+      for (const part of message.content) {
+        if (!isRecord(part) || part.type !== "toolCall") continue;
+        if (typeof part.id !== "string" || part.id.length === 0) {
+          throw new Error("toolCall frame missing string id");
+        }
+        if (typeof part.name !== "string" || part.name.length === 0) {
+          throw new Error(`toolCall ${part.id} missing string name`);
+        }
+        if (callTimestamp === undefined || callTimestamp.length === 0) {
+          throw new Error(`toolCall ${part.id} missing timestamp`);
+        }
+        if (openById.has(part.id)) {
+          throw new Error(`duplicate toolCall id ${part.id}`);
+        }
+        const args = isRecord(part.arguments) ? part.arguments : undefined;
+        // Ticket surface: only bash first-line summary is authorized here.
+        const command =
+          part.name === "bash" &&
+          args !== undefined &&
+          typeof args.command === "string"
+            ? bashCommandFirstLine(args.command)
+            : undefined;
+        const interval: Open = {
+          toolCallId: part.id,
+          toolName: part.name,
+          startedAt: callTimestamp,
+          ...(command !== undefined ? { command } : {}),
+        };
+        order.push(interval);
+        openById.set(part.id, interval);
+      }
+    }
+
+    if (message?.role === "toolResult") {
+      if (typeof message.toolCallId !== "string" || message.toolCallId.length === 0) {
+        throw new Error("toolResult frame missing string toolCallId");
+      }
+      const resultTimestamp =
+        typeof message.timestamp === "string" && message.timestamp
+          ? message.timestamp
+          : rowTimestamp;
+      if (resultTimestamp === undefined || resultTimestamp.length === 0) {
+        throw new Error(`toolResult ${message.toolCallId} missing timestamp`);
+      }
+      const open = openById.get(message.toolCallId);
+      if (open === undefined) {
+        // Result without a prior call is still associable as a closed interval
+        // once a name is known; keep structural readability without inventing a call.
+        const toolName =
+          typeof message.toolName === "string" && message.toolName.length > 0
+            ? message.toolName
+            : "unknown";
+        order.push({
+          toolCallId: message.toolCallId,
+          toolName,
+          startedAt: resultTimestamp,
+          endedAt: resultTimestamp,
+        });
+        continue;
+      }
+      if (open.endedAt !== undefined) {
+        throw new Error(`duplicate toolResult for toolCallId ${message.toolCallId}`);
+      }
+      open.endedAt = resultTimestamp;
+    }
+  }
+
+  return order.map((interval) => {
+    const base = {
+      toolCallId: interval.toolCallId,
+      toolName: interval.toolName,
+      startedAt: interval.startedAt,
+      ...(interval.command !== undefined ? { command: interval.command } : {}),
+    };
+    return interval.endedAt === undefined
+      ? base
+      : { ...base, endedAt: interval.endedAt };
+  });
+}

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

package/src/public-cli/cli.ts

@@ -32,6 +32,7 @@ import {
   parseJudgeArgv,
   parseMergerArgv,
   parseReviewerArgv,
+  parseTaishiArgv,
 } from "./invocation.ts";
 import { runPublicCoder, runPublicCoderResume } from "./coder-run.ts";
 import { runPublicCollector } from "./collector-run.ts";
@@ -40,6 +41,7 @@ import { runPublicFixer, runPublicFixerResume } from "./fixer-run.ts";
 import { runPublicJudge, runPublicResume } from "./judge-run.ts";
 import { runPublicMerger, runPublicMergerResume } from "./merger-run.ts";
 import { runPublicReviewer, runPublicReviewerResume } from "./reviewer-run.ts";
+import { runPublicTaishi } from "./taishi-run.ts";
 import { peekRoleRunRole } from "./run-lifecycle.ts";
 import {
   INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
@@ -73,6 +75,8 @@ export const PUBLIC_ROLE_ARGV = {
   doctor: { parse: parseDoctorArgv },
   merger: { parse: parseMergerArgv },
   reviewer: { parse: parseReviewerArgv },
+  /** Deterministic analysis seat (#336) — argv parse only; no LLM admission. */
+  taishi: { parse: parseTaishiArgv },
 } as const;
 
 type TakenPublicGlobalFlag =
@@ -314,6 +318,12 @@ function renderHelp(): string {
       lines.push(`  ${cap.name} — ${phaseText}`);
     }
   }
+  lines.push("", "Deterministic commands:");
+  for (const cap of doc.capabilities) {
+    if (cap.kind === "deterministic") {
+      lines.push(`  ${cap.name}`);
+    }
+  }
   lines.push(
     "",
     "Global options: --model provider/model --thinking level",
@@ -430,6 +440,8 @@ export async function runAkRole(
         }
         if (match.kind === "support") {
           io.stdout(`command\t${match.name}\tkind\tsupport\n`);
+        } else if (match.kind === "deterministic") {
+          io.stdout(`command\t${match.name}\tkind\tdeterministic\n`);
         } else {
           io.stdout(
             `command\t${match.name}\tkind\trole\tphases\t${match.phases
@@ -949,6 +961,18 @@ export async function runAkRole(
       };
     }
 
+    // Taishi public run path: deterministic analysis seat (#336 issue / #337 sweep).
+    // Not an LLM PUBLIC_CALLABLE_ROLE — registered only on PUBLIC_ROLE_ARGV (#176).
+    if (parsed.command === "taishi") {
+      const result = await runPublicTaishi(
+        parsed.args,
+        { home },
+        io,
+        PUBLIC_ROLE_ARGV.taishi.parse,
+      );
+      return { exitCode: result.exitCode };
+    }
+
     // #115: every PUBLIC_CALLABLE_ROLE has a completed handler above. Unknown
     // tokens (including misspelled role names) are structural rejects.
     throw new CliUsageError(`unknown command: ${parsed.command}`);