@akagilnc/pi-workflow-roles 0.1.4528 → 0.1.4586

package/dist/public-role-summons.js

@@ -1,7 +1,12 @@
+import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, sep } from "node:path";
+import { promisify } from "node:util";
 import { pickEngineAxis } from "./package-resources/engine-material.js";
 const AK_ROLE_PACKAGE_ROOT_ENV = "AK_ROLE_PACKAGE_ROOT";
+const execFileAsync = promisify(execFile);
 function createCapturingIo() {
   const chunks = [];
   return {
@@ -89,13 +94,14 @@ async function createSummonEnv(options, afterHost) {
     import("./public-cli/role-turn-host-resolution.js"),
     import("./public-cli/config.js")
   ]);
-  const principalAuthority = piDurablePrincipalAuthority;
+  const principalAuthority = options.principalAuthority ?? piDurablePrincipalAuthority;
   const roleTurnHost = resolveRoleTurnHost(
     {
       packageRoot: options.packageRoot,
       ...options.roleTurnHost === void 0 ? {} : { roleTurnHost: options.roleTurnHost },
       ...options.hostAdapters === void 0 ? {} : { hostAdapters: options.hostAdapters },
-      ...options.extraPiArgs === void 0 || options.extraPiArgs.length === 0 ? {} : { extraPiArgs: options.extraPiArgs }
+      ...options.extraPiArgs === void 0 || options.extraPiArgs.length === 0 ? {} : { extraPiArgs: options.extraPiArgs },
+      ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
     },
     { role: options.role, seat: options.seat, principalAuthority }
   );
@@ -108,13 +114,16 @@ async function createSummonEnv(options, afterHost) {
     };
   }
   const hostName = seatWithModel.host ?? "pi";
-  const { loadHostProvidersTable, projectHostFacingProvider } = await import("./public-cli/host-providers.js");
-  const hostFacingSelection = projectHostFacingProvider(
-    seatWithModel.selection,
-    hostName,
-    loadHostProvidersTable(options.home),
-    options.home
-  );
+  let hostFacingSelection = options.hostFacingModel;
+  if (hostFacingSelection === void 0) {
+    const { loadHostProvidersTable, projectHostFacingProvider } = await import("./public-cli/host-providers.js");
+    hostFacingSelection = projectHostFacingProvider(
+      seatWithModel.selection,
+      hostName,
+      loadHostProvidersTable(options.home),
+      options.home
+    );
+  }
   return {
     ok: true,
     env: {
@@ -128,7 +137,8 @@ async function createSummonEnv(options, afterHost) {
       credentials: options.credentials,
       ...hostFacingSelection === void 0 ? {} : { model: hostFacingSelection },
       ...projectSeatEngine(seatWithModel),
-      ...projectSeatHost(seatWithModel)
+      ...projectSeatHost(seatWithModel),
+      ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
     }
   };
 }
@@ -143,7 +153,19 @@ async function summonPublicRole(options) {
   } = await import("./public-cli/config.js");
   const credentials = options.credentials ?? await loadCredentialProviders(agentDir);
   const config = await loadPublicCliConfig(home);
-  const seat = resolveEffectiveSeat(config, options.role, credentials);
+  const resolvedSeat = resolveEffectiveSeat(config, options.role, credentials);
+  const inheritedSelection = options.model === void 0 ? void 0 : {
+    provider: options.model.provider,
+    model: options.model.model,
+    ...options.model.thinking === void 0 ? {} : { thinking: options.model.thinking }
+  };
+  const seat = {
+    ...resolvedSeat,
+    ...inheritedSelection === void 0 ? {} : { selection: inheritedSelection, source: "invocation" },
+    ...options.host === void 0 ? {} : { host: options.host, hostSource: "invocation" },
+    ...options.engine === void 0 ? {} : { engine: options.engine, engineSource: "invocation" },
+    ...options.engineModel === void 0 ? {} : { engineModel: options.engineModel }
+  };
   const captured = options.io === void 0 ? createCapturingIo() : void 0;
   const io = options.io ?? captured.io;
   const summonEnvInput = {
@@ -156,7 +178,11 @@ async function summonPublicRole(options) {
     seat,
     ...options.extraPiArgs === void 0 ? {} : { extraPiArgs: options.extraPiArgs },
     ...options.roleTurnHost === void 0 ? {} : { roleTurnHost: options.roleTurnHost },
-    ...options.hostAdapters === void 0 ? {} : { hostAdapters: options.hostAdapters }
+    ...options.hostAdapters === void 0 ? {} : { hostAdapters: options.hostAdapters },
+    ...options.principalAuthority === void 0 ? {} : { principalAuthority: options.principalAuthority },
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+    // Parent model is already host-facing; child must not project again.
+    ...options.model === void 0 ? {} : { hostFacingModel: options.model }
   };
   async function prepareSummonEnv(afterHost) {
     try {
@@ -168,7 +194,9 @@ async function summonPublicRole(options) {
         ok: true,
         env: {
           ...built.env,
-          stationChild: true,
+          // Nested court stations keep station-child semantics; dual-lens
+          // ordinary Reviewer axes opt out (#946 / ADR 0082).
+          ...options.stationChild === false ? {} : { stationChild: true },
           // Forward composition-root adapters so nested court stations (e.g.
           // countersign → diarist) select the same faux/production table (#924).
           ...options.hostAdapters === void 0 ? {} : { hostAdapters: options.hostAdapters },
@@ -178,7 +206,8 @@ async function summonPublicRole(options) {
           ...options.gateReviewInstruction === void 0 ? {} : { gateReviewInstruction: options.gateReviewInstruction },
           ...options.boundTicketNumber === void 0 ? {} : { boundTicketNumber: options.boundTicketNumber },
           ...options.correlationId === void 0 || options.correlationId.trim() === "" ? {} : { correlationId: options.correlationId },
-          ...options.createRunId === void 0 ? {} : { createRunId: options.createRunId }
+          ...options.createRunId === void 0 ? {} : { createRunId: options.createRunId },
+          ...options.executionCwd === void 0 ? {} : { executionCwd: options.executionCwd }
         }
       };
     } catch (error) {
@@ -290,6 +319,16 @@ async function summonPublicRole(options) {
       result = stepped.ok;
       break;
     }
+    case "reviewer": {
+      const [{ runPublicReviewer }, { parseReviewerArgv }] = await Promise.all([
+        import("./public-cli/reviewer-run.js"),
+        import("./public-cli/invocation.js")
+      ]);
+      const stepped = await runPrepared(parseReviewerArgv, (env, once) => runPublicReviewer(options.argv, env, io, once));
+      if ("fail" in stepped) return stepped.fail;
+      result = stepped.ok;
+      break;
+    }
   }
   const stderr = captured?.stderrText();
   const runDirectory = result.admitted?.runDirectory;
@@ -301,6 +340,296 @@ async function summonPublicRole(options) {
     ...stderr === void 0 || stderr === "" ? {} : { stderr }
   };
 }
+function withReviewerLens(argv, lens) {
+  const separator = argv.indexOf("--");
+  if (separator === -1) return [...argv, "--lens", lens];
+  return [...argv.slice(0, separator), "--lens", lens, ...argv.slice(separator)];
+}
+async function resolveReviewerWorktreeRoots(projectRoot) {
+  const callerProjectRoot = await realpath(projectRoot);
+  const sourceProjectRoot = await realpath((await execFileAsync(
+    "git",
+    ["rev-parse", "--show-toplevel"],
+    { cwd: callerProjectRoot }
+  )).stdout.trim());
+  const callerRelative = relative(sourceProjectRoot, callerProjectRoot);
+  const projectRelative = callerRelative === "" || callerRelative === "." || callerRelative.startsWith(`..${sep}`) || callerRelative === ".." ? "" : callerRelative;
+  return { callerProjectRoot, sourceProjectRoot, projectRelative };
+}
+function reviewerSandboxPath(worktreeAxis, projectRelative) {
+  return projectRelative === "" ? worktreeAxis : join(worktreeAxis, projectRelative);
+}
+async function openEphemeralReviewerWorktree(options) {
+  const { sourceProjectRoot, projectRelative } = await resolveReviewerWorktreeRoots(
+    options.projectRoot
+  );
+  const { stdout: headStdout } = await execFileAsync(
+    "git",
+    ["rev-parse", "--verify", "HEAD^{commit}"],
+    { cwd: sourceProjectRoot }
+  );
+  const targetCommit = headStdout.trim();
+  const root = await mkdtemp(join(tmpdir(), "ak-reviewer-sandbox-"));
+  const worktreeRoot = join(root, "work");
+  let registered = false;
+  const rollback = async (cause) => {
+    const cleanupErrors = [];
+    if (registered) {
+      try {
+        await execFileAsync("git", ["worktree", "remove", "--force", worktreeRoot], {
+          cwd: sourceProjectRoot
+        });
+      } catch (error) {
+        cleanupErrors.push(error);
+      }
+    }
+    try {
+      await rm(root, { recursive: true, force: true });
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+    if (cleanupErrors.length > 0) {
+      options.onCleanupDiagnostic?.([
+        "reviewer worktree cleanup failed",
+        ...cleanupErrors.map((error) => error instanceof Error ? error.message : String(error))
+      ].join("\n"));
+    }
+    throw cause;
+  };
+  try {
+    await execFileAsync("git", ["worktree", "add", "--detach", worktreeRoot, targetCommit], {
+      cwd: sourceProjectRoot
+    });
+    registered = true;
+    if (projectRelative !== "") {
+      await mkdir(reviewerSandboxPath(worktreeRoot, projectRelative), { recursive: true });
+    }
+  } catch (error) {
+    await rollback(error);
+  }
+  let closed = false;
+  return {
+    executionCwd: reviewerSandboxPath(worktreeRoot, projectRelative),
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      const cleanupErrors = [];
+      try {
+        await execFileAsync("git", ["worktree", "remove", worktreeRoot], {
+          cwd: sourceProjectRoot
+        });
+      } catch (error) {
+        cleanupErrors.push(error);
+      }
+      try {
+        await rm(root, { recursive: true, force: true });
+      } catch (error) {
+        cleanupErrors.push(error);
+      }
+      if (cleanupErrors.length > 0) {
+        options.onCleanupDiagnostic?.([
+          "reviewer worktree cleanup failed",
+          ...cleanupErrors.map((error) => error instanceof Error ? error.message : String(error))
+        ].join("\n"));
+      }
+    }
+  };
+}
+async function withEphemeralReviewerWorktree(options) {
+  const sandbox = await openEphemeralReviewerWorktree({
+    projectRoot: options.projectRoot,
+    ...options.onCleanupDiagnostic === void 0 ? {} : { onCleanupDiagnostic: options.onCleanupDiagnostic }
+  });
+  try {
+    return await options.run(sandbox.executionCwd);
+  } finally {
+    await sandbox.close();
+  }
+}
+async function summonParallelReviewerLenses(options) {
+  const describeFailure = (error) => {
+    if (error instanceof AggregateError) {
+      return [error.message, ...error.errors.map(describeFailure)].join("\n");
+    }
+    return error instanceof Error ? error.message : String(error);
+  };
+  const failedResult = (error) => ({
+    exitCode: 1,
+    stderr: describeFailure(error)
+  });
+  const dualFailure = (error) => {
+    const failure = failedResult(error);
+    return { completeness: failure, correctness: failure };
+  };
+  let sourceProjectRoot;
+  let projectRelative;
+  let targetCommit;
+  const statusArgs = [
+    "status",
+    "--porcelain=v1",
+    "--untracked-files=all",
+    "--",
+    ":/",
+    ":(top,exclude).claude/worktrees/**"
+  ];
+  try {
+    const roots = await resolveReviewerWorktreeRoots(options.projectRoot);
+    sourceProjectRoot = roots.sourceProjectRoot;
+    projectRelative = roots.projectRelative;
+    const { stdout: statusStdout } = await execFileAsync("git", statusArgs, {
+      cwd: sourceProjectRoot
+    });
+    if (statusStdout !== "") {
+      const diagnostic = [
+        "Reviewer target status gate failed:",
+        "git status --porcelain=v1 --untracked-files=all -- :/ ':(top,exclude).claude/worktrees/**'",
+        statusStdout
+      ].join("\n");
+      return dualFailure(new Error(diagnostic));
+    }
+    const { stdout: targetStdout } = await execFileAsync(
+      "git",
+      ["rev-parse", "--verify", "HEAD^{commit}"],
+      { cwd: sourceProjectRoot }
+    );
+    targetCommit = targetStdout.trim();
+    await execFileAsync(
+      "git",
+      ["rev-parse", "--verify", `${options.baseRevision}^{commit}`],
+      { cwd: sourceProjectRoot }
+    );
+  } catch (error) {
+    return dualFailure(error);
+  }
+  const root = await mkdtemp(join(tmpdir(), "ak-reviewer-lenses-"));
+  const completenessRoot = join(root, "completeness");
+  const correctnessRoot = join(root, "correctness");
+  const worktrees = [completenessRoot, correctnessRoot];
+  const created = /* @__PURE__ */ new Set();
+  let results;
+  const creation = await Promise.allSettled(
+    worktrees.map(async (path) => {
+      await execFileAsync("git", ["worktree", "add", "--detach", path, targetCommit], {
+        cwd: sourceProjectRoot
+      });
+      created.add(path);
+      if (projectRelative !== "") {
+        await mkdir(reviewerSandboxPath(path, projectRelative), { recursive: true });
+      }
+    })
+  );
+  const creationFailures = creation.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+  if (creationFailures.length > 0) {
+    const failure = failedResult(new AggregateError(
+      creationFailures,
+      "parallel reviewer worktree creation failed"
+    ));
+    results = { completeness: failure, correctness: failure };
+  } else {
+    const summon = (lens, worktreeAxis) => {
+      const sandbox = reviewerSandboxPath(worktreeAxis, projectRelative);
+      return summonPublicRole({
+        role: "reviewer",
+        argv: withReviewerLens(options.argv, lens),
+        cwd: options.cwd,
+        executionCwd: sandbox,
+        // Ordinary single-axis public semantics — not a nested court station.
+        stationChild: false,
+        home: options.home,
+        ...options.agentDir === void 0 ? {} : { agentDir: options.agentDir },
+        ...options.credentials === void 0 ? {} : { credentials: options.credentials },
+        ...options.model === void 0 ? {} : { model: options.model },
+        ...options.host === void 0 ? {} : { host: options.host },
+        ...options.engine === void 0 ? {} : { engine: options.engine },
+        ...options.engineModel === void 0 ? {} : { engineModel: options.engineModel },
+        ...options.signal === void 0 ? {} : { signal: options.signal },
+        ...options.correlationId === void 0 ? {} : { correlationId: options.correlationId },
+        ...options.packageRoot === void 0 ? {} : { packageRoot: options.packageRoot },
+        ...options.roleTurnHost === void 0 ? {} : { roleTurnHost: options.roleTurnHost },
+        ...options.hostAdapters === void 0 ? {} : { hostAdapters: options.hostAdapters },
+        ...options.principalAuthority === void 0 ? {} : { principalAuthority: options.principalAuthority },
+        ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+      });
+    };
+    const settled = await Promise.allSettled([
+      summon("completeness", completenessRoot),
+      summon("correctness", correctnessRoot)
+    ]);
+    results = {
+      completeness: settled[0].status === "fulfilled" ? settled[0].value : failedResult(settled[0].reason),
+      correctness: settled[1].status === "fulfilled" ? settled[1].value : failedResult(settled[1].reason)
+    };
+  }
+  let sealDiagnostic;
+  try {
+    const { stdout: headBeforeStdout } = await execFileAsync(
+      "git",
+      ["rev-parse", "--verify", "HEAD^{commit}"],
+      { cwd: sourceProjectRoot }
+    );
+    const { stdout: sealedStatusStdout } = await execFileAsync("git", statusArgs, {
+      cwd: sourceProjectRoot
+    });
+    const { stdout: headAfterStdout } = await execFileAsync(
+      "git",
+      ["rev-parse", "--verify", "HEAD^{commit}"],
+      { cwd: sourceProjectRoot }
+    );
+    const headBefore = headBeforeStdout.trim();
+    const headAfter = headAfterStdout.trim();
+    if (headBefore !== targetCommit || headAfter !== targetCommit || sealedStatusStdout !== "") {
+      sealDiagnostic = [
+        "Reviewer target final seal failed:",
+        `HEAD before status => ${headBefore}`,
+        `HEAD after status => ${headAfter}`,
+        `expected PRE_HEAD ${targetCommit}`,
+        "git status --porcelain=v1 --untracked-files=all -- :/ ':(top,exclude).claude/worktrees/**'",
+        sealedStatusStdout
+      ].join("\n");
+    }
+  } catch (error) {
+    sealDiagnostic = `Reviewer target final seal failed:
+${describeFailure(error)}`;
+  }
+  if (sealDiagnostic !== void 0) {
+    const withSealFailure = (result) => ({
+      ...result,
+      exitCode: 1,
+      stderr: [result.stderr, sealDiagnostic].filter(
+        (text) => typeof text === "string" && text !== ""
+      ).join("\n")
+    });
+    results = {
+      completeness: withSealFailure(results.completeness),
+      correctness: withSealFailure(results.correctness)
+    };
+  }
+  const cleanup = await Promise.allSettled(
+    [...created].map((path) => execFileAsync("git", ["worktree", "remove", path], { cwd: sourceProjectRoot }))
+  );
+  const cleanupFailures = cleanup.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+  if (cleanupFailures.length === 0) {
+    const rootCleanup = await Promise.allSettled([rm(root, { recursive: true, force: true })]);
+    cleanupFailures.push(...rootCleanup.flatMap((result) => result.status === "rejected" ? [result.reason] : []));
+  }
+  if (cleanupFailures.length > 0) {
+    const diagnostic = [
+      "parallel reviewer worktree cleanup failed",
+      ...cleanupFailures.map((failure) => failure instanceof Error ? failure.message : String(failure))
+    ].join("\n");
+    const withCleanupDiagnostic = (result) => ({
+      ...result,
+      stderr: [result.stderr, diagnostic].filter(
+        (text) => typeof text === "string" && text !== ""
+      ).join("\n")
+    });
+    results = {
+      completeness: withCleanupDiagnostic(results.completeness),
+      correctness: withCleanupDiagnostic(results.correctness)
+    };
+  }
+  return results;
+}
 async function summonGateOfficer(options) {
   let home = options.home;
   if (home === void 0) {
@@ -352,7 +681,10 @@ async function summonGateOfficer(options) {
 }
 export {
   AK_ROLE_PACKAGE_ROOT_ENV,
+  openEphemeralReviewerWorktree,
   resolveSummonsPackageRoot,
   summonGateOfficer,
-  summonPublicRole
+  summonParallelReviewerLenses,
+  summonPublicRole,
+  withEphemeralReviewerWorktree
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4528",
+  "version": "0.1.4586",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/host-contracts.ts

@@ -100,7 +100,6 @@ export type RoleTurnActivation =
   | {
       readonly role: "reviewer";
       readonly baseRevision: string;
-      /** Caller-selected single lens; no default (ADR 0082 reviewer-method-lens). */
       readonly lens: "completeness" | "correctness";
       readonly authorityRefs: readonly string[];
       readonly ticketNumber?: number;

package/src/public-cli/invocation.ts

@@ -239,14 +239,14 @@ export type AdmittedNotaryInvocation = AdmittedRoleInvocationBase & {
   readonly sourceRun: NotarySourceRunLocator;
 };
 
-/** Public Reviewer single-lens token; no default and no `all` (caller-selected parent run). */
+/** Durable single-axis Reviewer lens. Parallel default is parse-only omission, never admitted. */
 export type ReviewerLens = "completeness" | "correctness";
 
 export type AdmittedReviewerInvocation = AdmittedRoleInvocationBase & {
   readonly role: "reviewer";
   /** Required fixed base revision for the pinned review target (ADR 0037). */
   readonly baseRevision: string;
-  /** Required single lens; frozen at admission and reused on resume. */
+  /** Frozen single-axis shape for an ordinary Reviewer run; reused on resume. */
   readonly lens: ReviewerLens;
   /**
    * Required durable authority references/URLs frozen at admission.
@@ -929,8 +929,11 @@ export type ParseReviewerArgvResult = {
   attachmentPaths: string[];
   /** Required fixed base revision for the pinned review target. */
   baseRevision: string;
-  /** Required single lens; no default. */
-  lens: ReviewerLens;
+  /**
+   * Explicit single-axis override. Omitted public `--lens` is the internal
+   * parallel two-axis branch mark only — never persisted on an admitted run.
+   */
+  lens?: ReviewerLens;
   /** Repeatable durable authority references/URLs (exact order preserved; at least one). */
   authorityRefs: string[];
   project?: string;
@@ -1048,7 +1051,7 @@ export function isReviewerLens(value: unknown): value is ReviewerLens {
   return value === "completeness" || value === "correctness";
 }
 
-/** Public --lens enum; sole owner for parse + fresh admission. */
+/** Admitted single-axis lens enum; public `--lens all` and bare omission are not admitted values. */
 export function requireReviewerLens(value: string | undefined): ReviewerLens {
   const trimmed = (value ?? "").trim();
   if (!isReviewerLens(trimmed)) {
@@ -3073,7 +3076,7 @@ export function parseReviewerArgv(
         continue;
       }
       if (taken.def.id === "lens") {
-        // Empty and other non-enum values share one message — do not borrow path helper.
+        // Public override is single-axis only; omission stays undefined for the parallel branch.
         lens = requireReviewerLens(taken.value);
         continue;
       }
@@ -3090,13 +3093,13 @@ export function parseReviewerArgv(
     positional.push(token);
   }
 
-  // Unconditional required (--base/--lens/--authority-ref) from typed table (#342).
+  // Base and authority are required; omitted lens selects the parallel two-axis mode.
   options.assertRequired();
   return {
     instruction: positional.join(" "),
     attachmentPaths,
     baseRevision: baseRevision!,
-    lens: lens!,
+    ...(lens === undefined ? {} : { lens }),
     authorityRefs,
     ...(project === undefined ? {} : { project }),
   };
@@ -3110,12 +3113,13 @@ export type AdmitReviewerInvocationOptions = {
   instruction: string;
   attachmentPaths: readonly string[];
   baseRevision: string;
-  /** Required single lens; frozen unchanged at admission. */
+  /** Explicit single-axis shape, frozen unchanged at admission and resume. */
   lens: ReviewerLens;
   /** Required durable authority references/URLs; frozen unchanged at admission. */
   authorityRefs: readonly string[];
   project?: string;
   createRunId?: () => string;
+  correlationId?: string;
   /** Effective model for this invocation — written onto invocation.json. */
   model?: InvocationEffectiveModel;
 };
@@ -3175,6 +3179,9 @@ export async function admitReviewerInvocation(
     baseRevision,
     lens,
     authorityRefs: [...authorityRefs],
+    ...(options.correlationId === undefined
+      ? {}
+      : { correlationId: options.correlationId }),
     attachments: attachments.map((a) => ({
       provenancePath: a.provenancePath,
       frozenPath: a.frozenPath,
@@ -3204,6 +3211,9 @@ export async function admitReviewerInvocation(
     baseRevision,
     lens,
     authorityRefs,
+    ...(options.correlationId === undefined
+      ? {}
+      : { correlationId: options.correlationId }),
   };
 }
 

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

@@ -552,12 +552,12 @@ const REVIEWER_OPTIONS = [
     canonical: "--lens",
     aliases: [],
     valueMetavar: "completeness|correctness",
-    required: true,
+    required: false,
     repeatable: false,
     form: "option",
     description: {
-      en: "Required single review lens: completeness or correctness (no default).",
-      zh: "必填单 lens：completeness 或 correctness（无默认值）。",
+      en: "Optional single-lens override: completeness or correctness; omitted runs both in parallel.",
+      zh: "可选单 lens 覆盖：completeness 或 correctness；省略时并行运行两轴。",
     },
   },
   {
@@ -1227,9 +1227,9 @@ const ROLE_COMMAND_HELP = {
   },
   reviewer: {
     command: "reviewer",
-    summary: "Fixed-target single-lens review (completeness or correctness).",
+    summary: "Fixed-target parallel two-lens review, with an optional single-lens override.",
     usage: [
-      "ak-role reviewer --base <revision> --lens completeness|correctness --authority-ref <ref> [options] <instruction>",
+      "ak-role reviewer --base <revision> [--lens completeness|correctness] --authority-ref <ref> [options] <instruction>",
     ],
     examples: [
       'ak-role reviewer --base main --lens completeness --authority-ref docs/adr/0001.md "Review the branch."',