@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2014

package/src/public-cli/main.ts

@@ -1,11 +1,30 @@
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ensureHostPiRuntimeResolvable } from "./host-pi-runtime.ts";
 
 const here = dirname(fileURLToPath(import.meta.url));
-// dist/public-cli/main.js → package root is ../..
-const packageRoot = join(here, "..", "..");
+
+/**
+ * Resolve install package root from the public bin location.
+ *
+ * Shipped layout is `<packageRoot>/dist/public-cli/main.js` → two levels up when
+ * that ancestor owns package.json. A relocated single-file bundle (no package
+ * tree beside the bin) must NOT keep climbing: `join("/tmp/<bin>","..","..")`
+ * is `"/"` on Linux CI, and host-pi linking then does
+ * `mkdir('/node_modules/@earendil-works')` → EACCES. Fall back to the bin
+ * directory so links stay on the ESM ancestor walk and remain writable.
+ */
+function resolvePackageRoot(binDir: string): string {
+  const canonical = join(binDir, "..", "..");
+  if (existsSync(join(canonical, "package.json"))) {
+    return canonical;
+  }
+  return binDir;
+}
+
+const packageRoot = resolvePackageRoot(here);
 
 // The host-provided runtime must be resolvable before the CLI module graph loads it.
 ensureHostPiRuntimeResolvable(packageRoot);

package/src/public-cli/registry.ts

@@ -97,6 +97,12 @@ export function publicStartupCandidates(
   return STARTUP_CANDIDATES[seat];
 }
 
+/** Deterministic public commands — discoverable, never LLM-configurable seats. */
+export const PUBLIC_DETERMINISTIC_COMMANDS = ["taishi"] as const;
+
+export type PublicDeterministicCommand =
+  (typeof PUBLIC_DETERMINISTIC_COMMANDS)[number];
+
 export type HelpCapability =
   | {
       kind: "support";
@@ -107,11 +113,16 @@ export type HelpCapability =
       name: PublicCallableRole;
       phases: readonly (string | null)[];
       defaultPhase: string | null;
+    }
+  | {
+      kind: "deterministic";
+      name: PublicDeterministicCommand;
     };
 
 /**
  * Typed help surface. Presentation formats these facts; tests must not assert
  * exact help prose or layout (锚定宪法 / ADR 0016 / #105 AC).
+ * taishi is a deterministic analysis command on the public CLI — not an LLM seat.
  */
 export function listHelpCapabilities(): readonly HelpCapability[] {
   const support: HelpCapability[] = PUBLIC_CLI_SUPPORT_COMMANDS.map((name) => ({
@@ -133,7 +144,13 @@ export function listHelpCapabilities(): readonly HelpCapability[] {
       defaultPhase,
     };
   });
-  return [...support, ...roles];
+  const deterministic: HelpCapability[] = PUBLIC_DETERMINISTIC_COMMANDS.map(
+    (name) => ({
+      kind: "deterministic" as const,
+      name,
+    }),
+  );
+  return [...support, ...roles, ...deterministic];
 }
 
 export function isPublicCallableRole(value: string): value is PublicCallableRole {

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

@@ -100,6 +100,15 @@ function buildModelArgs(model: SeatModelConfig | undefined): string[] {
   ];
 }
 
+/** Encode admitted ticketNumber as CLI argv for activation/resume (no defaults). */
+function buildReviewerTicketNumberArgs(
+  ticketNumber: number | undefined,
+): string[] {
+  return ticketNumber === undefined
+    ? []
+    : ["--ak-review-ticket-number", String(ticketNumber)];
+}
+
 /**
  * Build Internal activation extra-args for an admitted Reviewer run.
  * Package code-review Skill is forced via --skill; ambient home skills stay off.
@@ -122,6 +131,7 @@ export function buildReviewerActivationExtraArgs(
     admitted.authorityRefs.length === 0
       ? []
       : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
+  const ticketNumberArgs = buildReviewerTicketNumberArgs(admitted.ticketNumber);
   return [
     "--no-skills",
     "--skill",
@@ -139,6 +149,7 @@ export function buildReviewerActivationExtraArgs(
     "--ak-review-base",
     admitted.baseRevision,
     ...authorityRefArgs,
+    ...ticketNumberArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),
@@ -166,6 +177,7 @@ export function buildReviewerResumeActivationExtraArgs(
     admitted.authorityRefs.length === 0
       ? []
       : ["--ak-review-authority-refs", JSON.stringify([...admitted.authorityRefs])];
+  const ticketNumberArgs = buildReviewerTicketNumberArgs(admitted.ticketNumber);
   return [
     "--no-skills",
     "--skill",
@@ -183,6 +195,7 @@ export function buildReviewerResumeActivationExtraArgs(
     "--ak-review-base",
     admitted.baseRevision,
     ...authorityRefArgs,
+    ...ticketNumberArgs,
     "--mode",
     "json",
     ...buildModelArgs(options.model),

package/src/public-cli/settlement.ts

@@ -242,6 +242,15 @@ export function presentStructuralRejection(
   io.stderr(formatCliDiagnostic(error.message));
 }
 
+/** ControlledFailure face without admitted-run Terminal (stdout body + stderr line). */
+export function presentControlledFailure(
+  failure: ControlledFailure,
+  io: { stdout: (text: string) => void; stderr: (text: string) => void },
+): void {
+  io.stdout(`${JSON.stringify(failure, null, 2)}\n`);
+  io.stderr(formatFailureStderrDiagnostic(failure));
+}
+
 /** Session readiness after an admitted activation attempt. */
 export type SessionReadiness =
   | { readonly state: "missing" }
@@ -3176,6 +3185,10 @@ export async function publishReviewerArtifacts(
         ...(admitted.instructionEmpty
           ? {}
           : { callerProvenance: admitted.instruction }),
+        // Self-fetch Spec bytes + source annotation when primary path produced material (#343).
+        ...(options.reviewerReceipt?.specFetchedMaterial === undefined
+          ? {}
+          : { specFetchedMaterial: options.reviewerReceipt.specFetchedMaterial }),
         attachments: admitted.attachments.map((a) => ({
           provenancePath: a.provenancePath,
           frozenPath: a.frozenPath,

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

@@ -0,0 +1,235 @@
+/**
+ * Public taishi adapter (#336/#337/#338): argv → typed query → runTaishi family.
+ * Deterministic analysis seat — no Pi runner, no admission lease.
+ * Reuses existing CLI failure envelope (CliUsageError + structural reject +
+ * ControlledFailure).
+ * Index read reuses readTaishiLibraryIndexPage / findTaishiLibraryIndexRow.
+ * #337 sweep: exactly one typed JSON attachment → TaishiSweepModeInput → #329 kernel.
+ * #338: three query faces; sync compute-if-missing; whole-compute failure →
+ * ControlledFailure terminal (code/projectRoot/issueNumber/real cause).
+ * "Unobtrusive" binds #337 merge auto-trigger only, not this user-initiated query.
+ */
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { Value } from "typebox/value";
+
+import {
+  errnoCode,
+  physicalPathIdentity,
+  resolveActivationLedgerHome,
+} from "../activation-ledger-topology.ts";
+import { exactUtf8 } from "../exact-utf8.ts";
+import {
+  findTaishiLibraryIndexRow,
+  readTaishiLibraryIndexPage,
+} from "../taishi-index.ts";
+import {
+  readOrComputeTaishiIssuePage,
+  runTaishi,
+  taishiSweepModeInputSchema,
+  TaishiIssueComputeError,
+  type TaishiIssueModeInput,
+  type TaishiSweepModeInput,
+} from "../taishi-entry.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import type { CliIo } from "./cli-io.ts";
+import type {
+  ParseTaishiArgvResult,
+  ParseTaishiIssueArgv,
+} from "./invocation.ts";
+import { presentControlledFailure, presentStructuralRejection } from "./settlement.ts";
+
+export type TaishiRunEnv = {
+  readonly home: string;
+};
+
+/**
+ * Build the sole library issue-mode input from public argv faces.
+ * - ticket N → issueNumber = ticketNumber = N; projectRoot from index (or project-root fallback).
+ * - project-root P → direct mechanical key.
+ * - both + index hit → index projectRoot wins; when direct root differs, retain it as
+ *   conflictingProjectRoot so runTaishi records the C4 dual-param conflict fact on the page.
+ * - both + index miss → project-root fallback.
+ * Bare both-missing is owned by parseTaishiArgv — no second reject here.
+ */
+export async function buildTaishiIssueModeInputFromPublicArgv(
+  parsed: ParseTaishiIssueArgv,
+  ledgerHome: string,
+): Promise<TaishiIssueModeInput> {
+  const ticket = parsed.ticket;
+  const directRoot = parsed.projectRoot;
+
+  if (ticket === undefined) {
+    return {
+      mode: "issue",
+      projectRoot: directRoot!,
+    };
+  }
+
+  // ticket N = issueNumber (no conversion); also the C4 typed ticket face.
+  const index = await readTaishiLibraryIndexPage(ledgerHome);
+  const row = findTaishiLibraryIndexRow(index, ticket);
+
+  let projectRoot: string;
+  if (row !== undefined) {
+    // Ticket-resolved index projectRoot wins over any concurrent --project-root.
+    projectRoot = row.projectRoot;
+  } else if (directRoot !== undefined) {
+    // Index miss with project-root fallback (ticket faces still set for C4).
+    projectRoot = directRoot;
+  } else {
+    throw new CliUsageError(
+      `taishi library index has no row for ticket ${ticket}`,
+    );
+  }
+
+  // Dual-param conflict: index root won, but caller also supplied a distinct --project-root.
+  // Carry the losing root so the metrics page records the call-face conflict fact.
+  const dualParamConflict =
+    row !== undefined
+    && directRoot !== undefined
+    && physicalPathIdentity(directRoot) !== physicalPathIdentity(projectRoot);
+
+  return {
+    mode: "issue",
+    projectRoot,
+    ticketNumber: ticket,
+    issueNumber: ticket,
+    ...(dualParamConflict ? { conflictingProjectRoot: directRoot } : {}),
+  };
+}
+
+/**
+ * Attachment JSON → library TaishiSweepModeInput via the sole schema (#337).
+ * No parallel hand shape; rejects missing/extra/wrong-type fields only.
+ */
+export function parseTaishiSweepModeInputFromJsonValue(
+  value: unknown,
+): TaishiSweepModeInput {
+  if (!Value.Check(taishiSweepModeInputSchema, value)) {
+    throw new CliUsageError(
+      "taishi sweep attachment must match TaishiSweepModeInput",
+    );
+  }
+  return value;
+}
+
+/**
+ * Load sweep typed input from exactly one public CLI attachment path.
+ * Rejects: wrong cardinality, unreadable path, non-UTF-8, JSON fail, field contract.
+ * Zero ledger writes — read-only path resolve + parse.
+ */
+export async function buildTaishiSweepModeInputFromAttachmentPaths(
+  attachmentPaths: readonly string[],
+): Promise<TaishiSweepModeInput> {
+  if (attachmentPaths.length !== 1) {
+    throw new CliUsageError(
+      "taishi sweep requires exactly one --attach typed JSON attachment",
+    );
+  }
+
+  const sourcePath = attachmentPaths[0]!;
+  const absolute = isAbsolute(sourcePath) ? sourcePath : resolve(sourcePath);
+
+  let bytes: Buffer;
+  try {
+    bytes = await readFile(absolute);
+  } catch (error) {
+    throw new CliUsageError(
+      `taishi sweep attachment is not a readable regular file: ${sourcePath}`,
+      { cause: error },
+    );
+  }
+
+  let text: string;
+  try {
+    text = exactUtf8(bytes, "taishi sweep attachment");
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CliUsageError(detail, { cause: error });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new CliUsageError(
+      "taishi sweep attachment is not valid JSON",
+      { cause: error },
+    );
+  }
+
+  return parseTaishiSweepModeInputFromJsonValue(parsed);
+}
+
+/**
+ * Public taishi run path — parse → resolve → query → typed receipt on stdout.
+ * Issue (#336/#338 compute-if-missing), sweep (#337), cohort/model-groups (#338).
+ */
+export async function runPublicTaishi(
+  argv: readonly string[],
+  _env: TaishiRunEnv,
+  io: CliIo,
+  parseTaishiArgv: (args: readonly string[]) => ParseTaishiArgvResult,
+): Promise<{ exitCode: number }> {
+  try {
+    const parsed = parseTaishiArgv(argv);
+    // Machine home is package-owned (ADR 0048) — same primitive runTaishi uses.
+    const ledgerHome = resolveActivationLedgerHome();
+
+    if (parsed.query === "sweep") {
+      const input = await buildTaishiSweepModeInputFromAttachmentPaths(
+        parsed.attachmentPaths,
+      );
+      const result = await runTaishi(input);
+      io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+      return { exitCode: 0 };
+    }
+
+    if (parsed.query === "cohort") {
+      const result = await runTaishi({
+        mode: "cohort",
+        groups: parsed.groups,
+      });
+      io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+      return { exitCode: 0 };
+    }
+
+    if (parsed.query === "model-groups") {
+      const result = await runTaishi({
+        mode: "model-groups",
+        projectRoots: parsed.projectRoots,
+      });
+      io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+      return { exitCode: 0 };
+    }
+
+    // issue query — compute-if-missing (#338); sole kernel on miss.
+    const input = await buildTaishiIssueModeInputFromPublicArgv(parsed, ledgerHome);
+    const result = await readOrComputeTaishiIssuePage(input);
+    io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+    return { exitCode: 0 };
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    if (error instanceof TaishiIssueComputeError) {
+      // Existing ControlledFailure: details carry code/projectRoot/issueNumber;
+      // identity.code carries distinguishable real cause (errno). No parallel schema.
+      const code = errnoCode(error.cause);
+      presentControlledFailure({
+        cause: "output",
+        diagnostic: error.message,
+        ...(code === undefined ? {} : { identity: { code } }),
+        details: {
+          code: error.code,
+          projectRoot: error.projectRoot,
+          ...(error.issueNumber === undefined ? {} : { issueNumber: error.issueNumber }),
+        },
+      }, io);
+      return { exitCode: 1 };
+    }
+    throw error;
+  }
+}

package/src/reviewer-construction.ts

@@ -101,12 +101,49 @@ export function reviewerAxisMethodAdapter(axis: ReviewerAxis): string {
 }
 
 export type ConstructedReviewerLeg = Readonly<{ axis: "standards" | "spec"; prompt: ReviewerPromptText }>;
+
+/** Ticket-number provenance for Spec self-fetch (#343). High-priority source wins. */
+export type ReviewerTicketNumberSource =
+  | "typed-ticket-number"
+  | "branch-token"
+  | "commit-message";
+
+export type ReviewerTicketNumberCandidate = Readonly<{
+  source: ReviewerTicketNumberSource;
+  ticketNumber: number;
+}>;
+
+/** One docs/adr path referenced by the fetched issue body. */
+export type ReviewerFetchedAdr =
+  | Readonly<{ path: string; status: "present"; body: string }>
+  | Readonly<{ path: string; status: "missing" }>;
+
+/**
+ * Actual Spec bytes pulled on the self-fetch primary path (fetch-then-store).
+ * Carried into Spec-child material and retained on the accepted dispatch for audit.
+ */
+export type ReviewerSpecFetchedMaterial = Readonly<{
+  issueRef: string;
+  owner: string;
+  repo: string;
+  ticketNumber: number;
+  adopted: ReviewerTicketNumberCandidate;
+  abandoned: readonly ReviewerTicketNumberCandidate[];
+  issueBody: string;
+  adrs: readonly ReviewerFetchedAdr[];
+}>;
+
 /**
  * Unique discovery product for Skill step 2: durable refs Spec child can read, or confirmed missing.
+ * Optional `fetched` is present only when the self-fetch primary path produced issue bytes.
  * Construction builds Standards/Spec solely from this product — no secondary launch decision.
  */
 export type ReviewerSpecAuthorityDiscovery =
-  | Readonly<{ status: "available"; refs: readonly string[] }>
+  | Readonly<{
+      status: "available";
+      refs: readonly string[];
+      fetched?: ReviewerSpecFetchedMaterial;
+    }>
   | Readonly<{ status: "missing" }>;
 /** Spec-child cardinality decision recorded on the accepted dispatch. */
 export type ReviewerSpecDisposition = "launched" | "skipped-missing";
@@ -123,6 +160,8 @@ export type ConstructedReviewerDispatch = Readonly<{
   authorityRefs: readonly string[];
   /** Honest Spec-child disposition: launched, or skipped after confirmed missing Spec. */
   specDisposition: ReviewerSpecDisposition;
+  /** Self-fetch bytes + source annotation when primary path produced material. */
+  specFetchedMaterial?: ReviewerSpecFetchedMaterial;
   legs: readonly ConstructedReviewerLeg[];
 }>;
 
@@ -138,6 +177,35 @@ export function reviewerAuthorityRefsMaterial(authorityRefs: readonly string[]):
   ].join("\n");
 }
 
+/**
+ * Spec-only material carrier for self-fetched issue bytes + source annotation (#343).
+ * Actual issue body and referenced ADR bytes are embedded for audit (fetch-then-store).
+ * Single JSON payload keeps external issue/ADR bytes inside structured field values so they
+ * cannot forge package framing markers on the same text layer (no plain-text section protocol).
+ */
+export function reviewerFetchedSpecMaterial(fetched: ReviewerSpecFetchedMaterial): string {
+  return [
+    "Authority-Fetched-Spec:",
+    JSON.stringify(
+      Object.freeze({
+        source: fetched.adopted.source,
+        ticketNumber: fetched.ticketNumber,
+        issueRef: fetched.issueRef,
+        abandoned: Object.freeze([...fetched.abandoned]),
+        issueBody: fetched.issueBody,
+        adrs: Object.freeze(
+          fetched.adrs.map((adr) =>
+            adr.status === "present"
+              ? Object.freeze({ path: adr.path, status: adr.status, body: adr.body })
+              : Object.freeze({ path: adr.path, status: adr.status }),
+          ),
+        ),
+      }),
+    ),
+    "These are self-fetched Spec grounding materials. Do not invent Spec prose from caller instruction.",
+  ].join("\n");
+}
+
 /** Deterministic compiler: fixed target/range plus discovery product in, dispatch text out. */
 export function constructReviewerDispatch(input: {
   identity: string;
@@ -152,6 +220,10 @@ export function constructReviewerDispatch(input: {
   const authorityRefs = Object.freeze(
     input.specAuthority.status === "available" ? [...input.specAuthority.refs] : [],
   );
+  const specFetchedMaterial =
+    input.specAuthority.status === "available" && input.specAuthority.fetched !== undefined
+      ? input.specAuthority.fetched
+      : undefined;
   const specDisposition: ReviewerSpecDisposition = launchSpec ? "launched" : "skipped-missing";
   const common = [
     `Target: ${input.range.target}`,
@@ -170,8 +242,13 @@ export function constructReviewerDispatch(input: {
   const legs = axes.map((x) => {
     const parts = [common, reviewerAxisMethodAdapter(x.axis)];
     // Spec evidence-child only — never Standards or a parent replacement Spec leg.
-    if (x.axis === "spec" && authorityRefs.length > 0) {
-      parts.push(reviewerAuthorityRefsMaterial(authorityRefs));
+    if (x.axis === "spec") {
+      if (specFetchedMaterial !== undefined) {
+        parts.push(reviewerFetchedSpecMaterial(specFetchedMaterial));
+      }
+      if (authorityRefs.length > 0) {
+        parts.push(reviewerAuthorityRefsMaterial(authorityRefs));
+      }
     }
     return Object.freeze({
       axis: x.axis,
@@ -189,6 +266,7 @@ export function constructReviewerDispatch(input: {
     range: input.range,
     authorityRefs,
     specDisposition,
+    ...(specFetchedMaterial === undefined ? {} : { specFetchedMaterial }),
     legs: Object.freeze(legs),
   });
 }