@akagilnc/pi-workflow-roles 0.1.2193 → 0.1.2203

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

package/src/taishi-index.ts

@@ -8,8 +8,11 @@
  * #399 D9: retained solely for cohort (and sweep producers that feed it).
  * Ticket CLI query path must not read this index (no bootstrap prerequisite).
  * Row address includes book identity so cross-book same ticket numbers do not merge (D5).
- * C2 joins cohort groups by issueNumber → page reference. Missing row =
+ * C2 joins cohort groups by (bookKey, issueNumber) → page reference. Missing row =
  * typed vacancy entry — never silent skip, never live recompute.
+ * #412: bare cohort issue numbers resolve inside one book; no cross-book silent find.
+ * Legacy rows lacking bookKey heal via the single shared projectRoot→bookKey rule
+ * (git common-dir when resolvable, else `root:<identity>`) on read/ingest (F1/F3).
  *
  * Multi-process issue/sweep writers coordinate the whole read→upsert→write
  * on one exclusive lock next to the index (atomic rename still prevents torn
@@ -22,7 +25,9 @@ import { writeFileAtomically } from "./atomic-write.ts";
 import {
   assertLedgerFileInsideHome,
   ensureRealDirectoryTree,
+  physicalPathIdentity,
 } from "./activation-ledger-topology.ts";
+import { resolveTaishiBookKey } from "./taishi-book-key.ts";
 import type {
   TaishiIssueMetricsPage,
   TaishiOptionalMetricNumber,
@@ -128,10 +133,27 @@ export function rowFromIssueMetricsPage(
   };
 }
 
+/**
+ * #412 F1/F3: pre-#399 library-index rows omit bookKey. Heal with the single
+ * shared projectRoot→bookKey rule (#399 / ADR 0048) — the same rule the
+ * issue/sweep path uses, never a second resolver.
+ */
+export function normalizeTaishiLibraryIndexRow(
+  row: TaishiLibraryIndexRow,
+): TaishiLibraryIndexRow {
+  const rawBook = (row as { readonly bookKey?: unknown }).bookKey;
+  if (typeof rawBook === "string" && rawBook !== "") {
+    if (rawBook === row.bookKey) return row;
+    return { ...row, bookKey: rawBook };
+  }
+  const projectRoot = physicalPathIdentity(row.projectRoot);
+  return { ...row, projectRoot, bookKey: resolveTaishiBookKey(projectRoot) };
+}
+
 function sortRows(
   rows: readonly TaishiLibraryIndexRow[],
 ): TaishiLibraryIndexRow[] {
-  // Stable book → projectRoot sort (C1 listing). Cohort join is by issueNumber find,
+  // Stable book → projectRoot sort (C1 listing). Cohort join is by (book, issue) find,
   // not row order — issueNumber secondary keeps C2 rows deterministic too.
   return [...rows].sort((a, b) => {
     const byBook = a.bookKey.localeCompare(b.bookKey);
@@ -153,20 +175,24 @@ export function buildTaishiLibraryIndexPage(
 ): TaishiLibraryIndexPage {
   return {
     kind: "taishi-library-index",
-    rows: sortRows(rows),
+    rows: sortRows(rows.map(normalizeTaishiLibraryIndexRow)),
   };
 }
 
 /**
- * Look up the first index row for an issue number.
+ * Look up the index row for (bookKey, issueNumber).
+ * #412: no cross-book silent scan — caller supplies the book (cwd book or book:N).
  * Absence is a lawful cohort vacancy signal — not an error.
  */
 export function findTaishiLibraryIndexRow(
   index: TaishiLibraryIndexPage | undefined,
   issueNumber: number,
+  bookKey: string,
 ): TaishiLibraryIndexRow | undefined {
   if (index === undefined) return undefined;
-  return index.rows.find((row) => row.issueNumber === issueNumber);
+  return index.rows.find(
+    (row) => row.issueNumber === issueNumber && row.bookKey === bookKey,
+  );
 }
 
 /** Row map key: book + root keeps cross-book same-ticket rows distinct (D5). */
@@ -193,6 +219,7 @@ export function upsertTaishiLibraryIndexRows(
   const keyByIssue = new Map<string, string>();
 
   const ingest = (row: TaishiLibraryIndexRow): void => {
+    row = normalizeTaishiLibraryIndexRow(row);
     const key = indexRowKey(row);
     // C2 uniqueness within book: one row per issueNumber — drop prior if number moved.
     if (row.issueNumber !== undefined) {
@@ -230,8 +257,10 @@ export function upsertTaishiLibraryIndexRows(
 
 /**
  * Read existing library index, or undefined when absent.
- * Single typed producer writes this file — JSON.parse failure is loud;
- * no bespoke shape validator on the self-read path.
+ * Single typed producer writes this file — JSON.parse failure is loud; a
+ * syntactically valid but malformed shape (null / non-object / rows not an
+ * array) is rejected at this sole read boundary with the file path and real
+ * shape, so no type assertion lets garbage reach consumers (#413 r2 U1).
  */
 export async function readTaishiLibraryIndexPage(
   ledgerHome: string,
@@ -250,7 +279,23 @@ export async function readTaishiLibraryIndexPage(
     }
     throw error;
   }
-  return JSON.parse(raw) as TaishiLibraryIndexPage;
+  const parsed: unknown = JSON.parse(raw);
+  if (
+    parsed === null
+    || typeof parsed !== "object"
+    || !Array.isArray((parsed as { readonly rows?: unknown }).rows)
+  ) {
+    const shape = parsed === null
+      ? "null"
+      : typeof parsed !== "object"
+      ? typeof parsed
+      : `object with non-array rows (${typeof (parsed as { rows?: unknown }).rows})`;
+    throw new Error(
+      `taishi library-index at ${path} is malformed (${shape}; expected an index page with a rows array) — rejected at the read boundary`,
+    );
+  }
+  // Heal legacy rows at the read boundary so every consumer sees defined bookKey.
+  return buildTaishiLibraryIndexPage((parsed as TaishiLibraryIndexPage).rows);
 }
 
 /**