@akagilnc/pi-workflow-roles 0.1.4800 → 0.1.4870

package/dist/analyst-book-key.js

@@ -0,0 +1,63 @@
+/**
+ * Single true source for the Analyst 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.js";
+import { errnoCode, physicalPathIdentity } from "./activation-ledger-topology.js";
+export function resolveAnalystBookKey(projectRoot) {
+    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 Analyst 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 isSyntheticAnalystBookKey(bookKey) {
+    return bookKey.startsWith("root:")
+        && isAbsolute(bookKey.slice("root:".length));
+}

package/dist/analyst-cohort.js

@@ -0,0 +1,167 @@
+/**
+ * Analyst cohort contrast aggregation (ADR 0068 / PRD #298 output ③ / #330 / #338).
+ *
+ * Query product — joins the library index, ensures each hit has a metrics page
+ * (compute-if-missing via caller-supplied sole issue kernel), then folds pages.
+ * No second ledger scan, no second parse kernel, no persistence of the contrast.
+ *
+ * Aggregation nails (ticket #330):
+ * - ratios (first-pass / success / rework): merge numerators & denominators
+ * - convergence rounds sample = one per lane×role (page byRole.convergenceRounds)
+ * - leg wall-clock median sample = one per leg (page legWallClock.ranking)
+ * - missing index row / zero denominator → typed 空缺 (LOC vacancy shape)
+ * - index hit + missing page → sync ensure (compute-if-missing); ensure failure is
+ *   typed terminal for this pull (never washed into absent/pending) — #338.
+ * - single-run unreadable on a page stays page-local exclusion, not whole failure.
+ */
+import { findAnalystLibraryIndexRow, readAnalystLibraryIndexPage, } from "./analyst-index.js";
+import { medianNumber } from "./analyst-median.js";
+const ABSENT = { status: "absent" };
+function presentMetric(value) {
+    return { status: "present", value };
+}
+function rateMetric(numerator, denominator) {
+    if (denominator === 0)
+        return ABSENT;
+    return presentMetric(numerator / denominator);
+}
+function optionalMedian(values) {
+    const median = medianNumber(values);
+    return median === undefined ? ABSENT : presentMetric(median);
+}
+function emptyRoleAccum() {
+    return {
+        convergenceRounds: [],
+        firstPassLaneCount: 0,
+        appearanceLaneCount: 0,
+        successCount: 0,
+        successEligibleCount: 0,
+    };
+}
+function absorbRole(accum, stats) {
+    accum.convergenceRounds.push(...stats.convergenceRounds);
+    accum.firstPassLaneCount += stats.firstPassLaneCount;
+    accum.appearanceLaneCount += stats.appearanceLaneCount;
+    accum.successCount += stats.successCount;
+    accum.successEligibleCount += stats.successEligibleCount;
+}
+function finishRole(role, accum) {
+    return {
+        role,
+        convergenceRounds: accum.convergenceRounds,
+        convergenceRoundsMedian: optionalMedian(accum.convergenceRounds),
+        firstPassRate: rateMetric(accum.firstPassLaneCount, accum.appearanceLaneCount),
+        successRate: rateMetric(accum.successCount, accum.successEligibleCount),
+    };
+}
+function emptyGateOfficerNumeratorAccum() {
+    return { rounds: 0, bounceCount: 0, passCount: 0, wallSum: 0 };
+}
+function absorbGateOfficerSummary(accum, summary) {
+    accum.rounds += summary.rounds;
+    accum.bounceCount += summary.bounceCount;
+    accum.passCount += summary.passCount;
+    if (summary.meanOfficerWallMs !== undefined) {
+        accum.wallSum += summary.meanOfficerWallMs * summary.rounds;
+    }
+}
+function finishGateOfficerNumerators(officer, accum) {
+    return {
+        officer,
+        rounds: accum.rounds,
+        bounceCount: accum.bounceCount,
+        passCount: accum.passCount,
+        bounceRate: rateMetric(accum.bounceCount, accum.rounds),
+        meanOfficerWallMs: accum.rounds === 0 ? ABSENT : presentMetric(accum.wallSum / accum.rounds),
+    };
+}
+async function aggregateGroup(index, input, ensureIssuePage) {
+    const issueEntries = [];
+    const roleAccums = new Map();
+    const gateOfficerAccums = new Map();
+    let reworkWallMs = 0;
+    let totalWallMs = 0;
+    let hasReworkSample = false;
+    const legWalls = [];
+    for (const ref of input.issues) {
+        const { issueNumber, bookKey } = ref;
+        const row = findAnalystLibraryIndexRow(index, issueNumber, bookKey);
+        if (row === undefined) {
+            // 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,
+            bookKey: row.bookKey,
+        }));
+        issueEntries.push({
+            issueNumber,
+            status: "present",
+            bookKey: row.bookKey,
+            projectRoot: row.projectRoot,
+        });
+        const acceptance = page.acceptanceSuccessRework;
+        if (acceptance !== undefined) {
+            for (const roleStats of acceptance.byRole) {
+                const accum = roleAccums.get(roleStats.role) ?? emptyRoleAccum();
+                absorbRole(accum, roleStats);
+                roleAccums.set(roleStats.role, accum);
+            }
+            reworkWallMs += acceptance.rework.reworkWallMs;
+            totalWallMs += acceptance.rework.totalWallMs;
+            hasReworkSample = true;
+        }
+        const legWallClock = page.legWallClock;
+        if (legWallClock !== undefined) {
+            for (const leg of legWallClock.ranking) {
+                legWalls.push(leg.wallMs);
+            }
+        }
+        // Gate-cycle fold: merge page-projected byOfficer numerators (no rescan,
+        // no second status→bounce/pass classifier — sole owner is gate-cycles family).
+        const gateCycles = page.gateCycles;
+        if (gateCycles !== undefined) {
+            for (const summary of gateCycles.byOfficer) {
+                const accum = gateOfficerAccums.get(summary.officer) ?? emptyGateOfficerNumeratorAccum();
+                absorbGateOfficerSummary(accum, summary);
+                gateOfficerAccums.set(summary.officer, accum);
+            }
+        }
+    }
+    const byRole = [...roleAccums.keys()]
+        .sort((a, b) => a.localeCompare(b))
+        .map((role) => finishRole(role, roleAccums.get(role)));
+    const gateCyclesByOfficer = ["inspector", "notary"]
+        .filter((officer) => gateOfficerAccums.has(officer))
+        .map((officer) => finishGateOfficerNumerators(officer, gateOfficerAccums.get(officer)));
+    return {
+        groupLabel: input.groupLabel,
+        issues: issueEntries,
+        byRole,
+        reworkRatio: hasReworkSample ? rateMetric(reworkWallMs, totalWallMs) : ABSENT,
+        medianWallMs: optionalMedian(legWalls),
+        gateCyclesByOfficer,
+    };
+}
+/**
+ * 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.
+ */
+export async function runAnalystCohortMode(ledgerHome, input, ensureIssuePage) {
+    const index = await readAnalystLibraryIndexPage(ledgerHome);
+    const group0 = await aggregateGroup(index, input.groups[0], ensureIssuePage);
+    const group1 = await aggregateGroup(index, input.groups[1], ensureIssuePage);
+    return {
+        mode: "cohort",
+        groups: [group0, group1],
+    };
+}

package/dist/analyst-entry.js

@@ -0,0 +1,320 @@
+/**
+ * 太史 sole entry (ADR 0068 / PRD #298).
+ * Deterministic analysis seat: read ledger records, write sibling metrics pages.
+ * A1/A2: issue-mode typed input; C1 adds sweep mode on this same seam.
+ * A2: scan retains typed per-run facts; page builder folds registered metric families.
+ * C1: sweep = merged PR list + LOC → backfill issue pages + maintain library index.
+ * C2: cohort = two issue-number groups → join library index → contrast query output.
+ * C3: model-groups = caller issue set → scan union → per-leg model aggregate.
+ * #338: retrieval compute-if-missing — sync wait for sole kernel, then full result.
+ * Whole-compute failure is typed terminal for this pull (no pending envelope).
+ * "Unobtrusive / non-blocking" binds #337 merge auto-trigger only, not user query.
+ */
+import { readFile } from "node:fs/promises";
+import { Type } from "typebox";
+import { physicalPathIdentity, resolveActivationLedgerHome } from "./activation-ledger-topology.js";
+import { isSyntheticAnalystBookKey, resolveAnalystBookKey } from "./analyst-book-key.js";
+import { runAnalystCohortMode, } from "./analyst-cohort.js";
+import { scanAnalystIssueRuns, } from "./analyst-ledger.js";
+import { mergeAnalystLibraryIndexRows, rowFromIssueMetricsPage, } from "./analyst-index.js";
+import { buildAnalystModelGroupsPage, } from "./analyst-model-groups.js";
+import { assertAnalystChangedLinesInput, buildAnalystIssueMetricsPage, analystIssuePagePath, writeAnalystIssueMetricsPage, } from "./analyst-page.js";
+/** #338 compute-if-missing failure — issue identity + real cause (CLI → ControlledFailure). */
+export class AnalystIssueComputeError extends Error {
+    code = "analyst-issue-compute-failed";
+    bookKey;
+    projectRoot;
+    issueNumber;
+    constructor(input) {
+        const root = physicalPathIdentity(input.projectRoot);
+        const causeText = input.cause instanceof Error
+            ? input.cause.message || input.cause.name
+            : String(input.cause);
+        const issueFace = input.issueNumber === undefined
+            ? `book ${input.bookKey} (projectRoot ${root})`
+            : `issue ${input.issueNumber} book ${input.bookKey} (projectRoot ${root})`;
+        super(`analyst compute failed for ${issueFace}: ${causeText}`, {
+            cause: input.cause,
+        });
+        this.name = "AnalystIssueComputeError";
+        this.bookKey = input.bookKey;
+        this.projectRoot = root;
+        if (input.issueNumber !== undefined) {
+            this.issueNumber = input.issueNumber;
+        }
+    }
+}
+function isMissingPathError(error) {
+    return (error instanceof Error
+        && "code" in error
+        && (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+/**
+ * Sole sweep-mode input contract (#298/#329/#337).
+ * Schema is the single definition; TS types are derived (no parallel hand shape).
+ * projectRoot = string (not nonempty); changedLines optional finite non-negative;
+ * 0 remains typed 空缺; no extra keys.
+ */
+export const analystSweepModeInputSchema = Type.Object({
+    mode: Type.Literal("sweep"),
+    mergedPullRequests: Type.Array(Type.Object({
+        projectRoot: Type.String(),
+        /** 排除后改动行数 — omit or 0 → typed 空缺; finite ≥ 0 only. */
+        changedLines: Type.Optional(Type.Number({ minimum: 0, maximum: Number.MAX_VALUE })),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+/**
+ * #338 retrieval primitive (sync): use persisted page when present; otherwise
+ * await the sole issue compute kernel (runAnalystIssueMode) which writes via the
+ * existing page entry, then return the full result. No pending/async envelope.
+ * Compute failures throw AnalystIssueComputeError (issue identity + real cause)
+ * and terminate this pull — never washed to absent/partial success.
+ * Single-run unreadable/damaged stays page-local exclusion (PRD #298), not a
+ * whole-compute failure. Sweep / explicit recompute still use runAnalystIssueMode.
+ */
+/**
+ * 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 book page)
+ */
+function cachedPageMatchesRequestedScope(page, input) {
+    if (page.bookKey !== input.bookKey)
+        return false;
+    const requestedTicket = input.ticketNumber ?? input.issueNumber;
+    if (requestedTicket === undefined) {
+        return page.issueNumber === undefined;
+    }
+    return page.issueNumber === requestedTicket;
+}
+/**
+ * Resolve page/scan book identity for issue mode (#399).
+ * CLI supplies bookKey from cwd git common-dir.
+ * Sweep/legacy without bookKey falls back to the single shared
+ * projectRoot→bookKey rule (git common-dir, else `root:<identity>`).
+ */
+function resolveIssueBookKey(input) {
+    if (input.bookKey !== undefined && input.bookKey.trim() !== "") {
+        return input.bookKey;
+    }
+    return resolveAnalystBookKey(input.projectRoot);
+}
+export async function readOrComputeAnalystIssuePage(input, 
+/**
+ * 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) {
+    const ledgerHome = resolveActivationLedgerHome(options?.home);
+    const projectRoot = physicalPathIdentity(input.projectRoot);
+    const bookKey = resolveIssueBookKey(input);
+    const issueNumber = input.ticketNumber ?? input.issueNumber;
+    const pagePath = analystIssuePagePath(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);
+        if (cachedPageMatchesRequestedScope(page, { bookKey, ...input })) {
+            // #855 ghost legs are live observations — always fresh, never from the page cache.
+            const ghostScan = await scanAnalystIssueRuns({
+                bookKey,
+                ...(issueNumber === undefined ? {} : { ticketNumber: issueNumber }),
+                ...(options?.scanProjectRoot === undefined
+                    ? {}
+                    : { projectRoot: options.scanProjectRoot }),
+                ...(options?.home === undefined ? {} : { home: options.home }),
+            });
+            return { mode: "issue", page, pagePath, ghostLegs: ghostScan.ghostLegs };
+        }
+        // Existing page is for a different / absent ticket scope — same kernel recompute.
+    }
+    catch (error) {
+        if (!isMissingPathError(error)) {
+            // Corrupt / blocked page path — loud with issue identity, not absent.
+            throw new AnalystIssueComputeError({
+                bookKey,
+                projectRoot,
+                ...(issueNumber === undefined ? {} : { issueNumber }),
+                cause: error,
+            });
+        }
+    }
+    try {
+        return await runAnalystIssueMode(input, undefined, options?.scanProjectRoot, options?.home);
+    }
+    catch (error) {
+        if (error instanceof AnalystIssueComputeError)
+            throw error;
+        throw new AnalystIssueComputeError({
+            bookKey,
+            projectRoot,
+            ...(issueNumber === undefined ? {} : { issueNumber }),
+            cause: error,
+        });
+    }
+}
+async function runAnalystIssueMode(input, 
+/** Caller-supplied scan facts — skip a second ledger walk when already scanned. */
+precomputedScan, 
+/** Cohort ensure conjunction (#412): scan this root inside the selected book. */
+scanProjectRoot, home) {
+    // Programmatic issue/sweep entry boundary — same finite non-negative rule as attach schema.
+    assertAnalystChangedLinesInput(input.changedLines);
+    const ledgerHome = resolveActivationLedgerHome(home);
+    const projectRoot = input.projectRoot;
+    // 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 ??
+        (inputBookKey !== undefined
+            ? await scanAnalystIssueRuns({
+                bookKey: inputBookKey,
+                ...(scanProjectRoot === undefined ? {} : { projectRoot: scanProjectRoot }),
+                ...(ticketNumber === undefined ? {} : { ticketNumber }),
+                ...(home === undefined ? {} : { home }),
+            })
+            : ticketNumber === undefined
+                ? await scanAnalystIssueRuns({ projectRoot, ...(home === undefined ? {} : { home }) })
+                : await scanAnalystIssueRuns({ projectRoot, ticketNumber, ...(home === undefined ? {} : { home }) }));
+    // exactOptionalPropertyTypes: only pass optional faces when caller supplied them.
+    const issueNumber = "issueNumber" in input ? input.issueNumber : undefined;
+    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 buildAnalystIssueMetricsPage({
+        bookKey,
+        projectRoot,
+        runs: scan.runs,
+        unreadable: scan.unreadable,
+        scopeConflicts: scan.scopeConflicts,
+        ...(input.changedLines === undefined ? {} : { changedLines: input.changedLines }),
+        ...(issueNumber === undefined ? {} : { issueNumber }),
+        ...(scopeRootIdentity === undefined ? {} : { scopeRootIdentity }),
+    });
+    const pagePath = await writeAnalystIssueMetricsPage(ledgerHome, page);
+    // 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 mergeAnalystLibraryIndexRows(ledgerHome, [
+            rowFromIssueMetricsPage(page),
+        ]);
+    }
+    return { mode: "issue", page, pagePath, ghostLegs: scan.ghostLegs };
+}
+async function runAnalystSweepMode(input, home) {
+    const ledgerHome = resolveActivationLedgerHome(home);
+    const issuePages = [];
+    for (const entry of input.mergedPullRequests) {
+        issuePages.push(await runAnalystIssueMode(entry, undefined, undefined, home));
+    }
+    const upserts = issuePages.map((result) => rowFromIssueMetricsPage(result.page));
+    const { index, indexPath } = await mergeAnalystLibraryIndexRows(ledgerHome, upserts);
+    return { mode: "sweep", issuePages, index, indexPath };
+}
+async function runAnalystModelGroupsMode(input, home) {
+    const ledgerHome = resolveActivationLedgerHome(home);
+    const runs = [];
+    const unreadable = [];
+    // Dedupe scope roots by physical identity while preserving caller order for scan.
+    const seen = new Set();
+    const projectRoots = [];
+    for (const root of input.projectRoots) {
+        const identity = physicalPathIdentity(root);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        projectRoots.push(identity);
+    }
+    // One ledger scan per root — shared by #338 ensure-page and model-group aggregate.
+    // No second scan pass; sole issue kernel + existing writer when page is missing.
+    for (const projectRoot of projectRoots) {
+        const scan = await scanAnalystIssueRuns({ projectRoot, ...(home === undefined ? {} : { home }) });
+        runs.push(...scan.runs);
+        unreadable.push(...scan.unreadable);
+        const bookKey = resolveIssueBookKey({ projectRoot });
+        const pagePath = analystIssuePagePath(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 AnalystIssueComputeError({ bookKey, projectRoot, cause: error });
+            }
+            try {
+                // Reuse this root's scan facts — no second ledger walk on compute-if-missing.
+                await runAnalystIssueMode({ mode: "issue", projectRoot }, scan, undefined, home);
+            }
+            catch (computeError) {
+                if (computeError instanceof AnalystIssueComputeError)
+                    throw computeError;
+                throw new AnalystIssueComputeError({ bookKey, projectRoot, cause: computeError });
+            }
+        }
+    }
+    // exactOptionalPropertyTypes: only pass mapping when caller supplied it.
+    const page = input.combinationMapping === undefined
+        ? buildAnalystModelGroupsPage({ projectRoots, runs, unreadable })
+        : buildAnalystModelGroupsPage({
+            projectRoots,
+            runs,
+            unreadable,
+            combinationMapping: input.combinationMapping,
+        });
+    return { mode: "model-groups", page };
+}
+export async function runAnalyst(input, options) {
+    if (input.mode === "sweep") {
+        return runAnalystSweepMode(input, options?.home);
+    }
+    if (input.mode === "cohort") {
+        const ledgerHome = resolveActivationLedgerHome(options?.home);
+        return runAnalystCohortMode(ledgerHome, input, async ({ projectRoot, issueNumber, bookKey }) => {
+            // 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 && !isSyntheticAnalystBookKey(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 readOrComputeAnalystIssuePage({
+                mode: "issue",
+                projectRoot,
+                issueNumber,
+                ticketNumber: issueNumber,
+                ...(realBookKey === undefined ? {} : { bookKey: realBookKey }),
+            }, { scanProjectRoot: projectRoot, ...(options?.home === undefined ? {} : { home: options.home }) });
+            return ensured.page;
+        });
+    }
+    if (input.mode === "model-groups") {
+        return runAnalystModelGroupsMode(input, options?.home);
+    }
+    return runAnalystIssueMode(input, undefined, undefined, options?.home);
+}