@akagilnc/pi-workflow-roles 0.1.2193 → 0.1.2207

package/src/activation-ledger-git.ts

@@ -11,7 +11,7 @@ const GIT_DISCOVERY_ENV_KEYS = [
 ] as const;
 
 function envWithoutGitDiscovery(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = { ...base };
+  const env: NodeJS.ProcessEnv = { ...base, LC_ALL: "C" };
   for (const key of GIT_DISCOVERY_ENV_KEYS) {
     delete env[key];
   }
@@ -19,17 +19,42 @@ function envWithoutGitDiscovery(base: NodeJS.ProcessEnv = process.env): NodeJS.P
 }
 
 /**
- * Typed book-key discovery failure: a git child ran and reported non-repository status.
- * Original git cause (nonzero exit) is retained. Spawn/OS failures never become this type.
+ * #413 r2 U5 — single failure-classification owner. A git child nonzero exit is
+ * only a *confirmed* non-repository verdict when git's own diagnostic says so
+ * ("fatal: not a git repository …", forced to the C locale so the wording is
+ * deterministic). Every other diagnostic — dubious ownership exit 128,
+ * permissions, anything unknown — leaves the question open: git found or
+ * refuses to adjudicate a repository-shaped situation without certifying
+ * "non repository". Classification by diagnostic identity, not by exit code
+ * alone, because both faces share exit 128.
+ */
+const CONFIRMED_NON_REPOSITORY_STDERR = /^fatal:\s*not a git repository/i;
+
+export function isConfirmedNonRepositoryStderr(stderr: string): boolean {
+  return CONFIRMED_NON_REPOSITORY_STDERR.test(stderr);
+}
+
+/**
+ * Typed book-key discovery failure: a git child ran and exited nonzero.
+ * Original git cause (nonzero exit) is retained. Spawn/OS failures never become
+ * this type. `confirmedNonRepository` records whether git itself certified
+ * "no repository here" (true) or merely failed for an unadjudicated reason
+ * such as dubious ownership (false) — consumers may only synthesize fallback
+ * identities from the confirmed face.
  */
 export class ActivationGitRepositoryRequiredError extends Error {
   readonly code = "AK_ACTIVATION_GIT_REPOSITORY_REQUIRED" as const;
-  constructor(detail: string, options?: { cause?: unknown }) {
+  readonly confirmedNonRepository: boolean;
+  constructor(
+    detail: string,
+    options?: { cause?: unknown; confirmedNonRepository?: boolean },
+  ) {
     super(
       `Workflow role activation requires a git repository cwd (git rev-parse --git-common-dir failed): ${detail || "unknown git error"}`,
       options?.cause === undefined ? undefined : { cause: options.cause },
     );
     this.name = "ActivationGitRepositoryRequiredError";
+    this.confirmedNonRepository = options?.confirmedNonRepository ?? false;
   }
 }
 
@@ -79,7 +104,10 @@ export function resolveBookKeyFromGit(cwd: string): string {
       : typeof err.message === "string"
       ? err.message
       : "";
-    throw new ActivationGitRepositoryRequiredError(detail || "unknown git error", { cause: error });
+    throw new ActivationGitRepositoryRequiredError(detail || "unknown git error", {
+      cause: error,
+      confirmedNonRepository: isConfirmedNonRepositoryStderr(detail),
+    });
   }
   if (commonDir.length === 0) {
     throw new Error("git rev-parse --git-common-dir returned an empty path");

package/src/engine-detour.ts

@@ -136,8 +136,10 @@ export function isEngineDetourFailure(result: {
 }
 
 /**
- * Diagnostic string for shared settlement / Terminal Error Artifact.
- * Prefer engine stderr 原样; whitespace-only/empty stderr is absent → stable fallback.
+ * Diagnostic string for shared settlement / Terminal Error Artifact (#395).
+ * Prefer engine stderr 原样; whitespace-only/empty stderr with stdout body must
+ * carry the child's last result/error row verbatim (e.g. a 529 API Error row) —
+ * never swallow the cause behind an exit code. Fully-empty output → stable fallback.
  */
 export function engineDetourFailureDiagnostic(result: {
   stderr: string;
@@ -146,7 +148,15 @@ export function engineDetourFailureDiagnostic(result: {
 }): string {
   if (result.stderr.trim().length > 0) return result.stderr;
   if (result.stdout.trim() === "") return ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC;
-  return `engine detour exited with code ${result.code}`;
+  const rows = result.stdout.split("\n");
+  let lastRow = "";
+  for (let index = rows.length - 1; index >= 0; index -= 1) {
+    if (rows[index]!.trim() !== "") {
+      lastRow = rows[index]!;
+      break;
+    }
+  }
+  return `engine detour exited with code ${result.code}: ${lastRow}`;
 }
 
 /** Non-empty trimmed engine name from process.env, else undefined. */

package/src/public-cli/cli.ts

@@ -436,9 +436,10 @@ function appendUsageAndExamples(
 
 function renderHelp(): string {
   const doc = helpDocument();
-  const top = projectCommandHelp("top");
+  // "top" is a required PUBLIC_COMMAND_HELP topic — no fallback prose (#412/397-F3).
+  const top = projectCommandHelp("top")!;
   const lines: string[] = [
-    `ak-role — ${top?.summary ?? "public role CLI"}`,
+    `ak-role — ${top.summary}`,
   ];
   appendUsageAndExamples(lines, "top");
   lines.push("", PUBLIC_NAVIGATOR_HELP_NOTE);
@@ -493,11 +494,9 @@ function renderCommandHelp(command: string): string | undefined {
     lines.push(`ak-role ${match.name}`);
   }
   appendUsageAndExamples(lines, command);
-  if (command in PUBLIC_ROLE_ARGV || command === "global") {
-    const owner =
-      command === "global"
-        ? "global"
-        : (command as keyof typeof PUBLIC_ROLE_ARGV);
+  // listHelpCapabilities never yields "global"; only role owners carry OPTIONS (#412/397-F3).
+  if (command in PUBLIC_ROLE_ARGV) {
+    const owner = command as keyof typeof PUBLIC_ROLE_ARGV;
     lines.push("", "OPTIONS");
     lines.push(...renderHumanOwnerOptionLines(owner));
   }

package/src/public-cli/invocation.ts

@@ -436,9 +436,16 @@ export type ParseTaishiSweepArgv = {
 
 export type ParseTaishiCohortArgv = {
   readonly query: "cohort";
+  /** Tokens before cwd-book stamping; bare N resolves at run (#412). */
   readonly groups: readonly [
-    { readonly groupLabel: string; readonly issues: readonly number[] },
-    { readonly groupLabel: string; readonly issues: readonly number[] },
+    {
+      readonly groupLabel: string;
+      readonly issues: readonly TaishiCohortIssueToken[];
+    },
+    {
+      readonly groupLabel: string;
+      readonly issues: readonly TaishiCohortIssueToken[];
+    },
   ];
 };
 
@@ -2198,17 +2205,108 @@ export function parseTaishiTicketNumber(
   return value;
 }
 
-function parseTaishiIssueNumberList(raw: string, flag: string): number[] {
+/**
+ * One cohort issue token before cwd-book stamping.
+ * - bare N → join cwd book at run time (#412 / #399 ticket口径)
+ * - book:N → explicit cross-book join (last ":" + positive integer RHS)
+ */
+export type TaishiCohortIssueToken =
+  | { readonly kind: "bare"; readonly issueNumber: number }
+  | {
+      readonly kind: "book-qualified";
+      readonly bookKey: string;
+      readonly issueNumber: number;
+    };
+
+/**
+ * Parse one cohort issue token: bare positive integer or `book:N`.
+ * Book keys may contain ":" (e.g. synthetic `root:<path>`) — split on the last
+ * colon only when the RHS is a positive integer token.
+ */
+export function parseTaishiCohortIssueToken(
+  raw: string,
+  flag: string,
+): TaishiCohortIssueToken {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    throw new CliUsageError(
+      `${flag} requires a comma-separated list of N or book:N`,
+    );
+  }
+  const sep = trimmed.lastIndexOf(":");
+  if (sep > 0) {
+    const rhs = trimmed.slice(sep + 1);
+    if (TAISHI_TICKET_NUMBER_PATTERN.test(rhs)) {
+      const bookKey = trimmed.slice(0, sep);
+      if (bookKey.trim() === "") {
+        throw new CliUsageError(
+          `${flag} book:N requires a non-empty book key, got ${raw}`,
+        );
+      }
+      return {
+        kind: "book-qualified",
+        bookKey,
+        issueNumber: parseTaishiTicketNumber(rhs, flag),
+      };
+    }
+  }
+  return {
+    kind: "bare",
+    issueNumber: parseTaishiTicketNumber(trimmed, flag),
+  };
+}
+
+/**
+ * Sole cohort list grammar (#412): split on unescaped commas. `\,` is a literal
+ * comma and `\\` a literal backslash — both round-trip, so any directory-name
+ * book key (ADR 0048) is expressible. Any other `\x` stays literally `\x`, so
+ * pre-existing unescaped input never changes meaning. Colons remain owned by
+ * the token's lastIndexOf(':') rule.
+ */
+function splitTaishiCohortIssueListParts(raw: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let escaped = false;
+  for (const ch of raw) {
+    if (escaped) {
+      current += ch === "," || ch === "\\" ? ch : `\\${ch}`;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (ch === ",") {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  parts.push(escaped ? `${current}\\` : current);
+  return parts;
+}
+
+function parseTaishiCohortIssueTokenList(
+  raw: string,
+  flag: string,
+): TaishiCohortIssueToken[] {
   const trimmed = raw.trim();
   if (trimmed === "") {
-    throw new CliUsageError(`${flag} requires a comma-separated positive integer list`);
+    throw new CliUsageError(
+      `${flag} requires a comma-separated list of N or book:N`,
+    );
   }
-  const parts = trimmed.split(",").map((part) => part.trim());
+  const parts = splitTaishiCohortIssueListParts(trimmed).map((part) =>
+    part.trim(),
+  );
   if (parts.some((part) => part === "")) {
-    throw new CliUsageError(`${flag} requires a comma-separated positive integer list`);
+    throw new CliUsageError(
+      `${flag} requires a comma-separated list of N or book:N`,
+    );
   }
-  // Same numeric rule as --ticket; diagnostic names the actual group flag.
-  return parts.map((part) => parseTaishiTicketNumber(part, flag));
+  return parts.map((part) => parseTaishiCohortIssueToken(part, flag));
 }
 
 function requireOptionValue(
@@ -2285,7 +2383,7 @@ export function parseTaishiArgv(args: readonly string[]): ParseTaishiArgvResult
           requireOptionValue(
             taken.def.canonical,
             taken.value,
-            "a comma-separated positive integer list",
+            "a comma-separated list of N or book:N",
           ),
         );
         continue;
@@ -2340,11 +2438,17 @@ export function parseTaishiArgv(args: readonly string[]): ParseTaishiArgvResult
       groups: [
         {
           groupLabel: groupALabel,
-          issues: parseTaishiIssueNumberList(groupAIssuesRaw, "--group-a-issues"),
+          issues: parseTaishiCohortIssueTokenList(
+            groupAIssuesRaw,
+            "--group-a-issues",
+          ),
         },
         {
           groupLabel: groupBLabel,
-          issues: parseTaishiIssueNumberList(groupBIssuesRaw, "--group-b-issues"),
+          issues: parseTaishiCohortIssueTokenList(
+            groupBIssuesRaw,
+            "--group-b-issues",
+          ),
         },
       ],
     };

package/src/public-cli/option-definitions.ts

@@ -177,7 +177,7 @@ export function evaluateTaishiModeOptionContract(
       return {
         ok: false,
         message:
-          "usage: ak-role taishi --cohort --group-a-label <L> --group-a-issues <N[,N...]> --group-b-label <L> --group-b-issues <N[,N...]",
+          "usage: ak-role taishi --cohort --group-a-label <L> --group-a-issues <N|book:N[,...]> --group-b-label <L> --group-b-issues <N|book:N[,...]>",
       };
     }
     return {
@@ -643,15 +643,15 @@ const TAISHI_OPTIONS = [
     owner: "taishi",
     canonical: "--group-a-issues",
     aliases: [],
-    valueMetavar: "N[,N...]",
+    valueMetavar: "N|book:N[,...]",
     required: false,
     repeatable: false,
     form: "option",
     modes: ["cohort"],
     requiredInModes: ["cohort"],
     description: {
-      en: "Cohort group A comma-separated positive issue numbers (required in cohort mode).",
-      zh: "cohort A 组逗号分隔正整数 issue 列表（cohort 模式必填）。",
+      en: "Cohort group A issues: bare N joins cwd book; book:N selects another book; escape a literal comma/backslash in a book key as \\, / \\\\ (required in cohort mode).",
+      zh: "cohort A 组 issue：裸 N 归属 cwd 簿；book:N 显式跨簿；簿键中的逗号/反斜杠用 \\, / \\\\ 转义（cohort 模式必填）。",
     },
   },
   {
@@ -675,15 +675,15 @@ const TAISHI_OPTIONS = [
     owner: "taishi",
     canonical: "--group-b-issues",
     aliases: [],
-    valueMetavar: "N[,N...]",
+    valueMetavar: "N|book:N[,...]",
     required: false,
     repeatable: false,
     form: "option",
     modes: ["cohort"],
     requiredInModes: ["cohort"],
     description: {
-      en: "Cohort group B comma-separated positive issue numbers (required in cohort mode).",
-      zh: "cohort B 组逗号分隔正整数 issue 列表（cohort 模式必填）。",
+      en: "Cohort group B issues: bare N joins cwd book; book:N selects another book; escape a literal comma/backslash in a book key as \\, / \\\\ (required in cohort mode).",
+      zh: "cohort B 组 issue：裸 N 归属 cwd 簿；book:N 显式跨簿；簿键中的逗号/反斜杠用 \\, / \\\\ 转义（cohort 模式必填）。",
     },
   },
 ] as const satisfies readonly PublicOptionDefinition[];
@@ -1074,7 +1074,7 @@ const ROLE_COMMAND_HELP = {
     usage: [
       "ak-role taishi [--ticket <N>]",
       "ak-role taishi [sweep] --attach <path>",
-      "ak-role taishi --cohort --group-a-label <L> --group-a-issues <N[,N...]> --group-b-label <L> --group-b-issues <N[,N...]>",
+      "ak-role taishi --cohort --group-a-label <L> --group-a-issues <N|book:N[,...]> --group-b-label <L> --group-b-issues <N|book:N[,...]>",
     ],
     examples: [
       "ak-role taishi",
@@ -1163,9 +1163,10 @@ export function renderHumanOwnerOptionLines(
     }
     if (opt.aliases.length > 0) {
       // Prefer single-token aliases in the spelling hint (plan/apply, -h).
+      // #412/397-F2: inside aliases.length > 0 the empty branch is dead — join directly.
       const aliasHint = opt.aliases.join(", ");
       if (opt.form === "positional") {
-        spelling = opt.aliases.length > 0 ? opt.aliases.join("|") : spelling;
+        spelling = opt.aliases.join("|");
       } else {
         spelling = `${spelling} (${aliasHint})`;
       }

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

@@ -184,9 +184,33 @@ export async function runPublicTaishi(
     }
 
     if (parsed.query === "cohort") {
+      // #412: bare N → cwd book (same口径 as #399 --ticket); book:N stays explicit.
+      // No cross-book silent scan — callers pass book:N for another repo's issues.
+      // Cwd book resolution is lazy and resolved at most once: an all-book:N
+      // cohort never touches cwd Git, so a non-git cwd cannot reject a purely
+      // explicit cross-book query.
+      let defaultBookKey: string | undefined;
+      const resolveIssue = (
+        token: (typeof parsed.groups)[0]["issues"][number],
+      ) => {
+        if (token.kind === "book-qualified") {
+          return { bookKey: token.bookKey, issueNumber: token.issueNumber };
+        }
+        defaultBookKey ??= resolveTaishiIssueBookKeyFromCwd();
+        return { bookKey: defaultBookKey, issueNumber: token.issueNumber };
+      };
       const result = await runTaishi({
         mode: "cohort",
-        groups: parsed.groups,
+        groups: [
+          {
+            groupLabel: parsed.groups[0].groupLabel,
+            issues: parsed.groups[0].issues.map(resolveIssue),
+          },
+          {
+            groupLabel: parsed.groups[1].groupLabel,
+            issues: parsed.groups[1].issues.map(resolveIssue),
+          },
+        ],
       });
       io.stdout(`${JSON.stringify(result, null, 2)}\n`);
       return { exitCode: 0 };

package/src/taishi-book-key.ts

@@ -0,0 +1,66 @@
+/**
+ * Single true source for the Taishi projectRoot→bookKey rule (#399 / ADR 0048).
+ * Git-resolvable → git common-dir host directory name; otherwise the stable
+ * synthetic `root:<projectRoot identity>` so read/write page paths agree
+ * without a prior scan. Issue/sweep derivation and legacy library-index
+ * healing must both call this rule — never a second copy of the fallback.
+ *
+ * Failure honesty: a real existing directory that is a *confirmed* non-repository
+ * (git's own "not a git repository" verdict, plus the structurally-identical
+ * absent root / non-directory root / ENOTDIR mid-path faces — no repository can
+ * ever live there) keeps the r4-adjudicated legal `root:<identity>` fallback.
+ * Unconfirmed git failures — dubious ownership exit 128 and every other
+ * diagnostic that does not certify "non repository" — propagate loudly with
+ * their real cause (#413 r2 U5): washing them into a synthetic key would be
+ * silent identity drift. Git infrastructure failures (missing binary → ENOENT)
+ * stay loud too. The confirmed/unconfirmed classification is implemented once,
+ * in the shared resolver owner.
+ */
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import {
+  ActivationGitRepositoryRequiredError,
+  resolveBookKeyFromGit,
+} from "./activation-ledger-git.ts";
+import { errnoCode, physicalPathIdentity } from "./activation-ledger-topology.ts";
+
+export function resolveTaishiBookKey(projectRoot: string): string {
+  const identity = physicalPathIdentity(projectRoot);
+  let stats;
+  try {
+    stats = statSync(identity);
+  } catch (error) {
+    // Absent root AND plain file mid-path both mean "this path can never be a
+    // directory, hence never a Git repository" — same synthetic fallback.
+    const code = errnoCode(error);
+    if (code === "ENOENT" || code === "ENOTDIR") return `root:${identity}`;
+    throw error;
+  }
+  if (!stats.isDirectory()) return `root:${identity}`;
+  // #413 r2 U5 boundary at the Taishi seam: only git's own confirmed
+  // "not a git repository" verdict may fall back to `root:<identity>`;
+  // unconfirmed nonzero exits (dubious ownership etc.) stay loud.
+  try {
+    return resolveBookKeyFromGit(identity);
+  } catch (error) {
+    if (
+      error instanceof ActivationGitRepositoryRequiredError
+      && error.confirmedNonRepository
+    ) {
+      return `root:${identity}`;
+    }
+    throw error;
+  }
+}
+
+/**
+ * #413 r2 U3: synthetic keys are exactly `root:` + an absolute path identity
+ * (the physicalPathIdentity face). A real Git book whose basename is literally
+ * `root:foo` is NOT synthetic — its remainder is not an absolute path. The
+ * check is bidirectional: real books are never misclassified by the prefix,
+ * and existing synthetic keys keep their path-scope meaning.
+ */
+export function isSyntheticTaishiBookKey(bookKey: string): boolean {
+  return bookKey.startsWith("root:")
+    && isAbsolute(bookKey.slice("root:".length));
+}

package/src/taishi-cohort.ts

@@ -40,10 +40,16 @@ export type TaishiCohortOptionalMetric =
   | { readonly status: "present"; readonly value: number }
   | { readonly status: "absent" };
 
+/** Fully resolved cohort issue identity — book is always explicit at the library face. */
+export type TaishiCohortIssueRef = {
+  readonly bookKey: string;
+  readonly issueNumber: number;
+};
+
 export type TaishiCohortGroupInput = {
   readonly groupLabel: string;
-  /** Issue numbers (caller typed); join key into the library index. */
-  readonly issues: readonly number[];
+  /** (bookKey, issueNumber) pairs; join key into the library index (#412). */
+  readonly issues: readonly TaishiCohortIssueRef[];
 };
 
 export type TaishiCohortModeInput = {
@@ -63,6 +69,8 @@ export type TaishiCohortIssueEntry =
   | {
       readonly issueNumber: number;
       readonly status: "absent";
+      /** Requested book scope — cross-book same-number vacancies stay self-describing (#413 r2 U4). */
+      readonly bookKey: string;
     };
 
 /** Per-role contrast stats within one cohort group. */
@@ -159,16 +167,20 @@ async function aggregateGroup(
   let hasReworkSample = false;
   const legWalls: number[] = [];
 
-  for (const issueNumber of input.issues) {
-    const row = findTaishiLibraryIndexRow(index, issueNumber);
+  for (const ref of input.issues) {
+    const { issueNumber, bookKey } = ref;
+    const row = findTaishiLibraryIndexRow(index, issueNumber, bookKey);
     if (row === undefined) {
-      // Only "index has no such row" is typed vacancy.
-      issueEntries.push({ issueNumber, status: "absent" });
+      // Only "index has no such row in this book" is typed vacancy.
+      // The requested bookKey rides along so book-a:12 and book-b:12 absences
+      // are distinguishable (#413 r2 U4).
+      issueEntries.push({ issueNumber, status: "absent", bookKey });
       continue;
     }
 
     // Index hit: ensure page via sole compute-if-missing kernel (read or compute).
     // Ensure failure stays loud with issue identity — never washed to absent.
+    // row.bookKey is normalized at index read — present projection always carries it (F3).
     const page = (await ensureIssuePage({
       projectRoot: row.projectRoot,
       issueNumber,
@@ -216,7 +228,7 @@ async function aggregateGroup(
 }
 
 /**
- * Run cohort contrast: join index by issueNumber, ensure pages (#338), fold,
+ * Run cohort contrast: join index by (bookKey, issueNumber), ensure pages (#338), fold,
  * emit two side-by-side group results. Page writes happen only through the
  * injected ensurer (sole issue kernel + existing writer) — cohort itself is
  * not a second compute kernel or projection.

package/src/taishi-entry.ts

@@ -14,6 +14,7 @@ import { readFile } from "node:fs/promises";
 import { Type, type Static } from "typebox";
 
 import { physicalPathIdentity, resolveActivationLedgerHome } from "./activation-ledger-topology.ts";
+import { isSyntheticTaishiBookKey, resolveTaishiBookKey } from "./taishi-book-key.ts";
 import {
   runTaishiCohortMode,
   type TaishiCohortModeInput,
@@ -33,7 +34,6 @@ import {
   buildTaishiModelGroupsPage,
   type TaishiModelGroupsPage,
 } from "./taishi-model-groups.ts";
-import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
   assertTaishiChangedLinesInput,
   buildTaishiIssueMetricsPage,
@@ -222,19 +222,11 @@ function cachedPageMatchesRequestedScope(
   return page.issueNumber === requestedTicket;
 }
 
-function tryResolveBookKey(projectRoot: string): string | undefined {
-  try {
-    return resolveBookKeyFromGit(projectRoot);
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Resolve page/scan book identity for issue mode (#399).
  * CLI supplies bookKey from cwd git common-dir.
- * Sweep/legacy without bookKey: git common-dir when possible; else stable synthetic
- * `root:<projectRoot identity>` so read/write page paths agree without a prior scan.
+ * Sweep/legacy without bookKey falls back to the single shared
+ * projectRoot→bookKey rule (git common-dir, else `root:<identity>`).
  */
 function resolveIssueBookKey(input: {
   readonly bookKey?: string;
@@ -243,13 +235,17 @@ function resolveIssueBookKey(input: {
   if (input.bookKey !== undefined && input.bookKey.trim() !== "") {
     return input.bookKey;
   }
-  const fromGit = tryResolveBookKey(input.projectRoot);
-  if (fromGit !== undefined) return fromGit;
-  return `root:${physicalPathIdentity(input.projectRoot)}`;
+  return resolveTaishiBookKey(input.projectRoot);
 }
 
 export async function readOrComputeTaishiIssuePage(
   input: TaishiIssueModeInput,
+  /**
+   * Cohort ensure only (#412): narrow the cache-miss recompute scan to this
+   * root inside the already-selected book — a miss must never widen to a
+   * whole-book scan for one index row. Not a public CLI face.
+   */
+  options?: { readonly scanProjectRoot?: string },
 ): Promise<TaishiIssueModeResult> {
   const ledgerHome = resolveActivationLedgerHome();
   const projectRoot = physicalPathIdentity(input.projectRoot);
@@ -284,7 +280,7 @@ export async function readOrComputeTaishiIssuePage(
   }
 
   try {
-    return await runTaishiIssueMode(input);
+    return await runTaishiIssueMode(input, undefined, options?.scanProjectRoot);
   } catch (error) {
     if (error instanceof TaishiIssueComputeError) throw error;
     throw new TaishiIssueComputeError({
@@ -300,6 +296,8 @@ async function runTaishiIssueMode(
   input: TaishiIssueModeInput | TaishiMergedPullRequest,
   /** Caller-supplied scan facts — skip a second ledger walk when already scanned. */
   precomputedScan?: TaishiScopedRunScan,
+  /** Cohort ensure conjunction (#412): scan this root inside the selected book. */
+  scanProjectRoot?: string,
 ): Promise<TaishiIssueModeResult> {
   // Programmatic issue/sweep entry boundary — same finite non-negative rule as attach schema.
   assertTaishiChangedLinesInput(input.changedLines);
@@ -317,6 +315,7 @@ async function runTaishiIssueMode(
     (inputBookKey !== undefined
       ? await scanTaishiIssueRuns({
           bookKey: inputBookKey,
+          ...(scanProjectRoot === undefined ? {} : { projectRoot: scanProjectRoot }),
           ...(ticketNumber === undefined ? {} : { ticketNumber }),
         })
       : ticketNumber === undefined
@@ -467,20 +466,26 @@ export async function runTaishi(input: TaishiInput): Promise<TaishiResult> {
   if (input.mode === "cohort") {
     const ledgerHome = resolveActivationLedgerHome();
     return runTaishiCohortMode(ledgerHome, input, async ({ projectRoot, issueNumber, bookKey }) => {
-      // Real ledger book keys drive book scope. Synthetic `root:<id>` address keys
-      // (sweep/legacy path-narrow) must not be used as books/ directory names.
-      // issueNumber labels the page/index join only — not a ticketNumber scan filter
-      // (cohort fixtures historically bind by projectRoot path, not typed ticket).
+      // Real ledger book keys drive book scope. Only `root:` + an absolute path
+      // is a synthetic sweep/legacy address key; a real book basename may be
+      // literally `root:foo` and must keep its book scope (U3, non-ambiguous
+      // bidirectional check — never a bare prefix test).
       const realBookKey =
-        bookKey !== undefined && !bookKey.startsWith("root:")
+        bookKey !== undefined && !isSyntheticTaishiBookKey(bookKey)
           ? bookKey
           : undefined;
+      // T4 revised (#413 r2 U2 owner decision, per #399 book×ticket identity):
+      // cohort issueNumber IS the ticketNumber. A cache-miss recompute filters
+      // by bookKey ∧ projectRoot ∧ invocation.ticketNumber; legacy runs without
+      // a typed ticket are excluded from the recompute — never merged into the
+      // issue page by path alone.
       const ensured = await readOrComputeTaishiIssuePage({
         mode: "issue",
         projectRoot,
         issueNumber,
+        ticketNumber: issueNumber,
         ...(realBookKey === undefined ? {} : { bookKey: realBookKey }),
-      });
+      }, { scanProjectRoot: projectRoot });
       return ensured.page;
     });
   }