@akagilnc/pi-workflow-roles 0.1.2120 → 0.1.2124

package/src/taishi-entry.ts

@@ -33,6 +33,7 @@ import {
   buildTaishiModelGroupsPage,
   type TaishiModelGroupsPage,
 } from "./taishi-model-groups.ts";
+import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
   assertTaishiChangedLinesInput,
   buildTaishiIssueMetricsPage,
@@ -45,10 +46,12 @@ import {
 /** #338 compute-if-missing failure — issue identity + real cause (CLI → ControlledFailure). */
 export class TaishiIssueComputeError extends Error {
   readonly code = "taishi-issue-compute-failed" as const;
+  readonly bookKey: string;
   readonly projectRoot: string;
   readonly issueNumber?: number;
 
   constructor(input: {
+    readonly bookKey: string;
     readonly projectRoot: string;
     readonly issueNumber?: number;
     readonly cause: unknown;
@@ -60,12 +63,13 @@ export class TaishiIssueComputeError extends Error {
         : String(input.cause);
     const issueFace =
       input.issueNumber === undefined
-        ? `projectRoot ${root}`
-        : `issue ${input.issueNumber} (projectRoot ${root})`;
+        ? `book ${input.bookKey} (projectRoot ${root})`
+        : `issue ${input.issueNumber} book ${input.bookKey} (projectRoot ${root})`;
     super(`taishi compute failed for ${issueFace}: ${causeText}`, {
       cause: input.cause,
     });
     this.name = "TaishiIssueComputeError";
+    this.bookKey = input.bookKey;
     this.projectRoot = root;
     if (input.issueNumber !== undefined) {
       this.issueNumber = input.issueNumber;
@@ -81,22 +85,24 @@ function isMissingPathError(error: unknown): boolean {
   );
 }
 
-/** Issue-mode typed input — single-issue scope via projectRoot mechanical key. */
+/** Issue-mode typed input — book × ticket scope (#399). */
 export type TaishiIssueModeInput = {
   readonly mode: "issue";
-  readonly projectRoot: string;
   /**
-   * C4: caller typed ticket face (#176). When set, issue 圈定 prefers matching
-   * invocation.ticketNumber; runs without ticketNumber fall back to projectRoot.
+   * Ledger book identity (git common-dir key). Required for CLI issue query.
+   * When omitted, sweep/legacy may supply projectRoot alone (path-narrow / git resolve).
    */
-  readonly ticketNumber?: number;
+  readonly bookKey?: string;
   /**
-   * Losing caller projectRoot when typed ticket/index root already won
-   * (public CLI dual-param: --ticket index hit over concurrent --project-root).
-   * When set and identity-distinct from projectRoot, page records the C4
-   * typed-ticketNumber-over-projectRoot fact for this call — no ledger alien run required.
+   * Recording/display face and sweep/legacy path-narrow pointer.
+   * Not the CLI issue-query mechanical key after #399 (ADR 0068 revised).
    */
-  readonly conflictingProjectRoot?: string;
+  readonly projectRoot: string;
+  /**
+   * C4/#399: caller typed ticket face (#176). When set, issue 圈定 admits only
+   * matching invocation.ticketNumber — no silent projectRoot fallback.
+   */
+  readonly ticketNumber?: number;
   /**
    * 排除后改动行数 — optional caller typed input.
    * Omit or 0 → page retains typed 空缺 for LOC and 耗时/千行.
@@ -104,8 +110,8 @@ export type TaishiIssueModeInput = {
   readonly changedLines?: number;
   /**
    * Caller typed issue number — retained on the metrics page for cohort index join.
-   * Page addressing remains projectRoot (ADR 0068); issueNumber is not the key.
-   * When present, issue mode also maintains the unique issueNumber→projectRoot index row.
+   * Page address = book + ticket when present (#399); not a global bare number key.
+   * When present, issue mode also maintains the library-index row (cohort consumer).
    */
   readonly issueNumber?: number;
 };
@@ -199,16 +205,16 @@ export type TaishiResult =
  * whole-compute failure. Sweep / explicit recompute still use runTaishiIssueMode.
  */
 /**
- * Cached page may be reused only under bidirectional ticket-scope equality.
- * - requested ticket present: page.issueNumber must equal it
+ * Cached page may be reused only under bidirectional book×ticket scope equality.
+ * - requested ticket present: page.issueNumber must equal it and bookKey matches
  * - requested ticket absent: only reuse a page that also lacks issueNumber
- *   (a narrower ticket page must not stand in for the full root page)
- * projectRoot path alone is not scope identity either direction.
+ *   (a narrower ticket page must not stand in for the full book page)
  */
 function cachedPageMatchesRequestedScope(
   page: TaishiIssueMetricsPage,
-  input: TaishiIssueModeInput,
+  input: { readonly bookKey: string; readonly issueNumber?: number; readonly ticketNumber?: number },
 ): boolean {
+  if (page.bookKey !== input.bookKey) return false;
   const requestedTicket = input.ticketNumber ?? input.issueNumber;
   if (requestedTicket === undefined) {
     return page.issueNumber === undefined;
@@ -216,17 +222,52 @@ 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.
+ */
+function resolveIssueBookKey(input: {
+  readonly bookKey?: string;
+  readonly projectRoot: string;
+}): string {
+  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)}`;
+}
+
 export async function readOrComputeTaishiIssuePage(
   input: TaishiIssueModeInput,
 ): Promise<TaishiIssueModeResult> {
   const ledgerHome = resolveActivationLedgerHome();
   const projectRoot = physicalPathIdentity(input.projectRoot);
-  const pagePath = taishiIssuePagePath(ledgerHome, projectRoot);
+  const bookKey = resolveIssueBookKey(input);
+  const issueNumber = input.ticketNumber ?? input.issueNumber;
+  const pagePath = taishiIssuePagePath(ledgerHome, {
+    bookKey,
+    ...(issueNumber === undefined ? {} : { issueNumber }),
+    // Sweep/legacy path-narrow pages (no ticket, no explicit CLI book-only scope).
+    ...(issueNumber === undefined && input.bookKey === undefined
+      ? { scopeRootIdentity: projectRoot }
+      : {}),
+  });
 
   try {
     const raw = await readFile(pagePath, "utf8");
     const page = JSON.parse(raw) as TaishiIssueMetricsPage;
-    if (cachedPageMatchesRequestedScope(page, input)) {
+    if (cachedPageMatchesRequestedScope(page, { bookKey, ...input })) {
       return { mode: "issue", page, pagePath };
     }
     // Existing page is for a different / absent ticket scope — same kernel recompute.
@@ -234,8 +275,9 @@ export async function readOrComputeTaishiIssuePage(
     if (!isMissingPathError(error)) {
       // Corrupt / blocked page path — loud with issue identity, not absent.
       throw new TaishiIssueComputeError({
+        bookKey,
         projectRoot,
-        ...(input.issueNumber === undefined ? {} : { issueNumber: input.issueNumber }),
+        ...(issueNumber === undefined ? {} : { issueNumber }),
         cause: error,
       });
     }
@@ -246,8 +288,9 @@ export async function readOrComputeTaishiIssuePage(
   } catch (error) {
     if (error instanceof TaishiIssueComputeError) throw error;
     throw new TaishiIssueComputeError({
+      bookKey,
       projectRoot,
-      ...(input.issueNumber === undefined ? {} : { issueNumber: input.issueNumber }),
+      ...(issueNumber === undefined ? {} : { issueNumber }),
       cause: error,
     });
   }
@@ -265,48 +308,54 @@ async function runTaishiIssueMode(
   // Sweep entries carry projectRoot only; issue mode may add ticketNumber (C4).
   const ticketNumber =
     "ticketNumber" in input ? input.ticketNumber : undefined;
+  const inputBookKey =
+    "bookKey" in input && typeof input.bookKey === "string" && input.bookKey.trim() !== ""
+      ? input.bookKey
+      : undefined;
 
   const scan = precomputedScan ??
-    (ticketNumber === undefined
+    (inputBookKey !== undefined
+      ? await scanTaishiIssueRuns({
+          bookKey: inputBookKey,
+          ...(ticketNumber === undefined ? {} : { ticketNumber }),
+        })
+      : ticketNumber === undefined
       ? await scanTaishiIssueRuns({ projectRoot })
       : await scanTaishiIssueRuns({ projectRoot, ticketNumber }));
 
   // exactOptionalPropertyTypes: only pass optional faces when caller supplied them.
   const issueNumber =
     "issueNumber" in input ? input.issueNumber : undefined;
-  const conflictingProjectRoot =
-    "conflictingProjectRoot" in input ? input.conflictingProjectRoot : undefined;
-
-  // Caller dual-param conflict (ticket/index root already won): record C4 fact
-  // from the call faces themselves — independent of ledger alien runs.
-  const scopeConflicts = [...scan.scopeConflicts];
-  if (conflictingProjectRoot !== undefined && ticketNumber !== undefined) {
-    const losingRoot = physicalPathIdentity(conflictingProjectRoot);
-    const winningRoot = physicalPathIdentity(projectRoot);
-    if (losingRoot !== winningRoot) {
-      scopeConflicts.push({
-        ticketNumber,
-        projectRoot: losingRoot,
-        fact: "typed-ticketNumber-over-projectRoot",
-      });
-    }
-  }
+
+  const bookKey = resolveIssueBookKey({
+    ...(inputBookKey === undefined ? {} : { bookKey: inputBookKey }),
+    projectRoot,
+  });
+
+  // CLI book/ticket pages: no scopeRootIdentity.
+  // Sweep/legacy path-narrow (no explicit bookKey, no ticket): address includes root.
+  const scopeRootIdentity =
+    inputBookKey === undefined && ticketNumber === undefined && issueNumber === undefined
+      ? physicalPathIdentity(projectRoot)
+      : undefined;
 
   // Page build discovers metric families first — missing tree fails before write.
   const page = await buildTaishiIssueMetricsPage({
+    bookKey,
     projectRoot,
     runs: scan.runs,
     unreadable: scan.unreadable,
-    scopeConflicts,
+    scopeConflicts: scan.scopeConflicts,
     ...(input.changedLines === undefined ? {} : { changedLines: input.changedLines }),
     ...(issueNumber === undefined ? {} : { issueNumber }),
+    ...(scopeRootIdentity === undefined ? {} : { scopeRootIdentity }),
   });
 
   const pagePath = await writeTaishiIssueMetricsPage(ledgerHome, page);
 
-  // Issue number present → maintain the unique issueNumber→projectRoot index row
-  // so cohort can join without a second addressing kernel (ADR 0068 page key unchanged).
-  // Row carries C1 efficiency columns from the page (single index shape, no second kernel).
+  // Issue number present → maintain library-index row for cohort join (sole remaining
+  // consumer of the index; ticket CLI path never reads it — #399 D9).
+  // Row carries bookKey so cross-book same ticket numbers do not merge (D5).
   // Locked read→upsert→write so concurrent issue/sweep CLI writers do not drop rows.
   if (issueNumber !== undefined) {
     await mergeTaishiLibraryIndexRows(ledgerHome, [
@@ -357,20 +406,24 @@ async function runTaishiModelGroupsMode(
     runs.push(...scan.runs);
     unreadable.push(...scan.unreadable);
 
-    const pagePath = taishiIssuePagePath(ledgerHome, projectRoot);
+    const bookKey = resolveIssueBookKey({ projectRoot });
+    const pagePath = taishiIssuePagePath(ledgerHome, {
+      bookKey,
+      scopeRootIdentity: projectRoot,
+    });
     try {
       const raw = await readFile(pagePath, "utf8");
       JSON.parse(raw); // present page must parse (same loud face as readOrCompute)
     } catch (error) {
       if (!isMissingPathError(error)) {
-        throw new TaishiIssueComputeError({ projectRoot, cause: error });
+        throw new TaishiIssueComputeError({ bookKey, projectRoot, cause: error });
       }
       try {
         // Reuse this root's scan facts — no second ledger walk on compute-if-missing.
         await runTaishiIssueMode({ mode: "issue", projectRoot }, scan);
       } catch (computeError) {
         if (computeError instanceof TaishiIssueComputeError) throw computeError;
-        throw new TaishiIssueComputeError({ projectRoot, cause: computeError });
+        throw new TaishiIssueComputeError({ bookKey, projectRoot, cause: computeError });
       }
     }
   }
@@ -413,11 +466,20 @@ export async function runTaishi(input: TaishiInput): Promise<TaishiResult> {
   }
   if (input.mode === "cohort") {
     const ledgerHome = resolveActivationLedgerHome();
-    return runTaishiCohortMode(ledgerHome, input, async ({ projectRoot, issueNumber }) => {
+    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).
+      const realBookKey =
+        bookKey !== undefined && !bookKey.startsWith("root:")
+          ? bookKey
+          : undefined;
       const ensured = await readOrComputeTaishiIssuePage({
         mode: "issue",
         projectRoot,
         issueNumber,
+        ...(realBookKey === undefined ? {} : { bookKey: realBookKey }),
       });
       return ensured.page;
     });

package/src/taishi-index.ts

@@ -5,8 +5,10 @@
  * 完全耗时 / 排除后改动行数 / 耗时每千行 / 末次活动时间戳.
  * Rows carry their own sort keys — readers choose order (Story 6/8).
  *
- * Cross-book one row per issue. C2 joins cohort groups by issueNumber →
- * projectRoot page reference (ADR 0068 mechanical key). Missing row =
+ * #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 =
  * typed vacancy entry — never silent skip, never live recompute.
  *
  * Multi-process issue/sweep writers coordinate the whole read→upsert→write
@@ -77,12 +79,14 @@ async function withTaishiLibraryIndexLock<T>(
 }
 
 /**
- * One issue row on the cross-book library index.
- * projectRoot = page addressing key (ADR 0068).
+ * One issue row on the library index.
+ * bookKey = book identity (page address component; #399 D5).
+ * projectRoot = retained recording/display face (not sole address key after ADR 0068 revision).
  * issueNumber = optional caller typed field retained for cohort join.
  * C1 four columns make the row self-sufficient for cross-issue listing.
  */
 export type TaishiLibraryIndexRow = {
+  readonly bookKey: string;
   readonly projectRoot: string;
   /** Caller typed issue number — present when issue-mode supplied it for cohort join. */
   readonly issueNumber?: number;
@@ -113,6 +117,7 @@ export function rowFromIssueMetricsPage(
   page: TaishiIssueMetricsPage,
 ): TaishiLibraryIndexRow {
   return {
+    bookKey: page.bookKey,
     projectRoot: page.projectRoot,
     // exactOptionalPropertyTypes: only materialize when page carries it.
     ...(page.issueNumber === undefined ? {} : { issueNumber: page.issueNumber }),
@@ -126,9 +131,11 @@ export function rowFromIssueMetricsPage(
 function sortRows(
   rows: readonly TaishiLibraryIndexRow[],
 ): TaishiLibraryIndexRow[] {
-  // Stable projectRoot sort (C1 listing). Cohort join is by issueNumber find,
+  // Stable book → projectRoot sort (C1 listing). Cohort join is by issueNumber find,
   // not row order — issueNumber secondary keeps C2 rows deterministic too.
   return [...rows].sort((a, b) => {
+    const byBook = a.bookKey.localeCompare(b.bookKey);
+    if (byBook !== 0) return byBook;
     const byRoot = a.projectRoot.localeCompare(b.projectRoot);
     if (byRoot !== 0) return byRoot;
     const aNum = a.issueNumber;
@@ -162,39 +169,51 @@ export function findTaishiLibraryIndexRow(
   return index.rows.find((row) => row.issueNumber === issueNumber);
 }
 
+/** Row map key: book + root keeps cross-book same-ticket rows distinct (D5). */
+function indexRowKey(row: Pick<TaishiLibraryIndexRow, "bookKey" | "projectRoot">): string {
+  return `${row.bookKey}\0${row.projectRoot}`;
+}
+
+/** Within one book, issueNumber stays unique for cohort join. */
+function issueBookKey(bookKey: string, issueNumber: number): string {
+  return `${bookKey}\0${issueNumber}`;
+}
+
 /**
  * Upsert issue rows into an existing index (or empty).
- * - One row per projectRoot — re-sweep overwrites that issue's row only (C1).
- * - When issueNumber is present, also unique per issueNumber — re-issue
- *   overwrites that number's row only (C2 issueNumber→projectRoot join).
+ * - One row per (bookKey, projectRoot) — re-sweep overwrites that issue's row only (C1).
+ * - When issueNumber is present, unique per (bookKey, issueNumber) — re-issue
+ *   overwrites that number's row only within the book (C2; D5 cross-book safe).
  */
 export function upsertTaishiLibraryIndexRows(
   existing: TaishiLibraryIndexPage | undefined,
   upserts: readonly TaishiLibraryIndexRow[],
 ): TaishiLibraryIndexPage {
-  const byRoot = new Map<string, TaishiLibraryIndexRow>();
-  const rootByIssue = new Map<number, string>();
+  const byKey = new Map<string, TaishiLibraryIndexRow>();
+  const keyByIssue = new Map<string, string>();
 
   const ingest = (row: TaishiLibraryIndexRow): void => {
-    // C2 uniqueness: one row per issueNumber — drop prior root if number moved.
+    const key = indexRowKey(row);
+    // C2 uniqueness within book: one row per issueNumber — drop prior if number moved.
     if (row.issueNumber !== undefined) {
-      const priorRoot = rootByIssue.get(row.issueNumber);
-      if (priorRoot !== undefined && priorRoot !== row.projectRoot) {
-        byRoot.delete(priorRoot);
+      const issueKey = issueBookKey(row.bookKey, row.issueNumber);
+      const priorKey = keyByIssue.get(issueKey);
+      if (priorKey !== undefined && priorKey !== key) {
+        byKey.delete(priorKey);
       }
     }
-    // C1 uniqueness: one row per projectRoot — drop prior issue map if root reused.
-    const prior = byRoot.get(row.projectRoot);
+    // C1 uniqueness: one row per (book, projectRoot) — drop prior issue map if root reused.
+    const prior = byKey.get(key);
     if (
       prior !== undefined
       && prior.issueNumber !== undefined
       && prior.issueNumber !== row.issueNumber
     ) {
-      rootByIssue.delete(prior.issueNumber);
+      keyByIssue.delete(issueBookKey(prior.bookKey, prior.issueNumber));
     }
-    byRoot.set(row.projectRoot, row);
+    byKey.set(key, row);
     if (row.issueNumber !== undefined) {
-      rootByIssue.set(row.issueNumber, row.projectRoot);
+      keyByIssue.set(issueBookKey(row.bookKey, row.issueNumber), key);
     }
   };
 
@@ -206,7 +225,7 @@ export function upsertTaishiLibraryIndexRows(
   for (const row of upserts) {
     ingest(row);
   }
-  return buildTaishiLibraryIndexPage([...byRoot.values()]);
+  return buildTaishiLibraryIndexPage([...byKey.values()]);
 }
 
 /**

package/src/taishi-ledger.ts

@@ -1,14 +1,21 @@
 /**
- * Taishi ledger scan: S-family book/runs topology, issue scope by invocation
- * projectRoot, and loud unreadable exclusion for required sources.
+ * Taishi ledger scan: S-family book/runs topology, book × ticket issue scope
+ * (#399), and loud unreadable exclusion for required sources.
  * Reuses canonical session/artifact readers — does not parse session JSONL itself.
  *
+ * Scope unit = ledger book (git common-dir key) × optional typed ticket filter.
+ * CLI issue query never path-filters by projectRoot (owner #399: that face deleted).
+ * Sweep/legacy library may still pass projectRoot as a path-narrow when bookKey
+ * is absent — recording-side field, not the public query mechanical key.
+ * Typed ticketNumber, when requested, decides alone (no silent projectRoot fallback).
+ *
  * A2: classifyScopedRun retains typed per-run facts (frame span, tool intervals,
  * terminal face) for metric-family modules — no longer discarded after checks.
  */
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
   physicalPathIdentity,
   resolveActivationLedgerHome,
@@ -79,8 +86,8 @@ function parseRunDirectoryName(
 }
 
 /**
- * Invocation scope faces used for issue 圈定 (C4).
- * projectRoot remains required to place a run on any scope path;
+ * Invocation scope faces used for issue 圈定 (C4 / #399).
+ * projectRoot is retained for narrow path match and conflict facts;
  * ticketNumber is the #176 typed face when present (integer ≥ 1).
  * Single read of invocation.json — no second parse kernel.
  */
@@ -89,6 +96,25 @@ type InvocationScopeFields = {
   readonly ticketNumber?: number;
 };
 
+/** Best-effort book key from a projectRoot git common-dir; undefined when not a git tree. */
+function tryResolveBookKeyFromProjectRoot(projectRoot: string): string | undefined {
+  try {
+    return resolveBookKeyFromGit(projectRoot);
+  } catch {
+    return undefined;
+  }
+}
+
+async function listLedgerBookNames(booksRoot: string): Promise<string[]> {
+  try {
+    const entries = await readdir(booksRoot, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch (error) {
+    if (isMissingPathError(error)) return [];
+    throw error;
+  }
+}
+
 async function readInvocationScopeFields(
   runDirectory: string,
 ): Promise<InvocationScopeFields | undefined> {
@@ -117,31 +143,36 @@ async function readInvocationScopeFields(
 }
 
 /**
- * C4 issue scope decision for one run.
- * - Both sides carry ticketNumber → typed ticket decides; mismatch projectRoot = conflict.
- * - Otherwise → projectRoot mechanical-key fallback.
+ * Issue scope decision for one run (#399 / C4).
+ * - Scope ticket set → typed ticket alone decides (match in; else out).
+ *   No projectRoot fallback — that silent path labeled full-project pages as ticket N.
+ * - Whole-book scope (CLI bare / bookKey without ticket) → every run in the book.
+ * - Path-narrow (sweep/legacy only): no ticket + scopeRootIdentity → path match.
  */
 function decideIssueScope(input: {
-  readonly scopeProjectRootIdentity: string;
   readonly scopeTicketNumber: number | undefined;
+  /** Whole-book membership when true (CLI bare / git-resolved book). */
+  readonly wholeBook: boolean;
+  readonly scopeRootIdentity: string | undefined;
   readonly runProjectRootIdentity: string;
   readonly runTicketNumber: number | undefined;
-}): { readonly inScope: boolean; readonly conflict: boolean } {
-  const projectRootMatch =
-    input.runProjectRootIdentity === input.scopeProjectRootIdentity;
+}): { readonly inScope: boolean } {
+  if (input.scopeTicketNumber !== undefined) {
+    // Strict (book, N): typed ticket alone; never fall back to path match.
+    return { inScope: input.runTicketNumber === input.scopeTicketNumber };
+  }
 
-  if (
-    input.scopeTicketNumber !== undefined
-    && input.runTicketNumber !== undefined
-  ) {
-    if (input.runTicketNumber === input.scopeTicketNumber) {
-      return { inScope: true, conflict: !projectRootMatch };
-    }
-    // Run bound to a different ticket — typed face wins over projectRoot match.
-    return { inScope: false, conflict: false };
+  if (input.wholeBook) {
+    return { inScope: true };
   }
 
-  return { inScope: projectRootMatch, conflict: false };
+  if (input.scopeRootIdentity !== undefined) {
+    return {
+      inScope: input.runProjectRootIdentity === input.scopeRootIdentity,
+    };
+  }
+
+  return { inScope: true };
 }
 
 async function resolveSessionFile(
@@ -369,36 +400,59 @@ async function classifyScopedRun(input: {
 
 /**
  * Scan ledger home books/<book>/runs for runs in the issue scope.
- * C4: typed ticketNumber (when present on both scope and run) decides membership;
- * otherwise projectRoot mechanical key is the fallback. Ticket-vs-projectRoot
- * conflicts still admit the run and surface on scopeConflicts.
+ * #399: scope = book × optional ticket.
+ * - bookKey set → that book only; whole-book when no ticket; ticket filters alone.
+ * - projectRoot without bookKey (sweep/legacy): git-resolved → whole that book;
+ *   non-git → path-narrow across books (fixture isolation).
  * Damaged required sources become unreadable exclusions.
  * Readable runs retain typed facts for metric-family composition.
  */
 export async function scanTaishiIssueRuns(input: {
-  readonly projectRoot: string;
-  /** Caller typed ticket face — when set, prefer #176 invocation ticketNumber. */
+  /** Explicit book key — CLI issue query always supplies this. */
+  readonly bookKey?: string;
+  /** Caller typed ticket face — when set, only matching invocation.ticketNumber admits. */
   readonly ticketNumber?: number;
+  /**
+   * Sweep/legacy path-narrow pointer. Not a CLI issue-query face (#399 deleted).
+   * When bookKey absent: git common-dir → whole book; else path filter.
+   */
+  readonly projectRoot?: string;
 }): Promise<TaishiScopedRunScan> {
   // Package-owned machine home only (ADR 0048) — no invocation-varying override.
   const ledgerHome = resolveActivationLedgerHome();
-  const scopeIdentity = physicalPathIdentity(input.projectRoot);
   const scopeTicketNumber = input.ticketNumber;
   const booksRoot = join(ledgerHome, "books");
 
+  let wholeBook = false;
+  let scopeRootIdentity: string | undefined;
   let bookNames: string[];
-  try {
-    const entries = await readdir(booksRoot, { withFileTypes: true });
-    bookNames = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
-  } catch (error) {
-    if (isMissingPathError(error)) {
-      return { runs: [], unreadable: [], scopeConflicts: [] };
+
+  if (input.bookKey !== undefined && input.bookKey.trim() !== "") {
+    bookNames = [input.bookKey];
+    // CLI book scope: whole book unless ticket filters. Never path-narrow.
+    wholeBook = true;
+  } else if (input.projectRoot !== undefined) {
+    const resolved = tryResolveBookKeyFromProjectRoot(input.projectRoot);
+    if (resolved !== undefined) {
+      bookNames = [resolved];
+      wholeBook = true;
+    } else {
+      bookNames = await listLedgerBookNames(booksRoot);
+      scopeRootIdentity = physicalPathIdentity(input.projectRoot);
     }
-    throw error;
+  } else {
+    bookNames = await listLedgerBookNames(booksRoot);
+    wholeBook = true;
+  }
+
+  if (bookNames.length === 0) {
+    return { runs: [], unreadable: [], scopeConflicts: [] };
   }
 
   const runs: TaishiReadableRunFacts[] = [];
   const unreadable: TaishiUnreadableRun[] = [];
+  // scopeConflicts retained on the scan face for page envelope compat; book×ticket
+  // scope no longer emits projectRoot dual-key conflicts on the CLI path.
   const scopeConflicts: TaishiScopeConflict[] = [];
 
   for (const book of bookNames) {
@@ -429,23 +483,14 @@ export async function scanTaishiIssueRuns(input: {
 
       const runProjectRootIdentity = physicalPathIdentity(scopeFields.projectRoot);
       const decision = decideIssueScope({
-        scopeProjectRootIdentity: scopeIdentity,
         scopeTicketNumber,
+        wholeBook,
+        scopeRootIdentity,
         runProjectRootIdentity,
         runTicketNumber: scopeFields.ticketNumber,
       });
       if (!decision.inScope) continue;
 
-      if (decision.conflict) {
-        // ticketNumber is defined on both sides whenever conflict is true.
-        scopeConflicts.push({
-          runId: parsed.runId,
-          ticketNumber: scopeFields.ticketNumber as number,
-          projectRoot: runProjectRootIdentity,
-          fact: "typed-ticketNumber-over-projectRoot",
-        });
-      }
-
       const classified = await classifyScopedRun({
         book,
         runId: parsed.runId,