@akagilnc/pi-workflow-roles 0.1.3685 → 0.1.3700

package/src/public-role-summons.ts

@@ -53,6 +53,19 @@ export type PublicSummonRequest = {
    * parent tool call is cancelled (#675).
    */
   readonly signal?: AbortSignal;
+  /**
+   * #753 plain-language re-ask when the prior officer reply was not three-state.
+   * Nested gate officers (notary + inspector) — rides same-ticket resume
+   * summons.instruction. Never folded into argv / parent-run lookup keys.
+   */
+  readonly reviewReask?: string;
+  /**
+   * #753/#750 same-parent re-summons: human-readable pointer materials for the
+   * new parent submission (source run + optional gate-submission-candidate).
+   * Rides summons.instruction when reviewReask is absent. Fresh mint ignores it.
+   * Never folded into argv / parent-run lookup keys.
+   */
+  readonly gateReviewInstruction?: string;
 };
 
 export type PublicSummonResult = {
@@ -278,6 +291,12 @@ export async function summonPublicRole(
       : { autoResumeLimit: config.autoResumeLimit }),
     // Parent cancellation reaches the nested activation's own turn dispatch.
     ...(options.signal === undefined ? {} : { signal: options.signal }),
+    // #753: reask rides the existing notary same-ticket resume summons.instruction.
+    ...(options.reviewReask === undefined ? {} : { reviewReask: options.reviewReask }),
+    // #753/#750: new-submission pointers on same-parent resume (not conclusion re-ask).
+    ...(options.gateReviewInstruction === undefined
+      ? {}
+      : { gateReviewInstruction: options.gateReviewInstruction }),
   };
   const captured = options.io === undefined ? createCapturingIo() : undefined;
   const io = options.io ?? captured!.io;
@@ -376,9 +395,9 @@ export async function summonPublicRole(
   };
 }
 
-/** Gate officer summons: notary via --source-run; inspector via pointer instruction. */
+/** Gate officer summons: notary/auditor via --source-run; inspector via pointer instruction. */
 export async function summonGateOfficer(options: {
-  readonly officer: "inspector" | "notary";
+  readonly officer: "inspector" | "notary" | "auditor";
   readonly sourceRunDirectory: string;
   readonly cwd: string;
   readonly home?: string;
@@ -386,6 +405,17 @@ export async function summonGateOfficer(options: {
   readonly io?: CliIo;
   /** Parent cancellation for the nested officer activation (#675). */
   readonly signal?: AbortSignal;
+  /**
+   * Plain-language re-ask when the prior officer reply was not three-state (#753 / #756).
+   * All three officers: reviewReask → same-ticket resume summons.instruction.
+   * Never concatenated into argv (inspector parentRunPath is the pure 卷宗指针).
+   */
+  readonly reask?: string;
+  /**
+   * Path of this turn's gate-submission-candidate when written (#632 / #753).
+   * Becomes human-readable resume materials when reask is absent.
+   */
+  readonly submissionCandidatePath?: string;
 }): Promise<PublicSummonResult> {
   let home = options.home;
   if (home === undefined) {
@@ -393,24 +423,58 @@ export async function summonGateOfficer(options: {
     // Hard path resolve: fail loud — never fall through to packageMachineHome (#604 / #675).
     home = homeFromRunDirectory(options.sourceRunDirectory);
   }
+  // Conclusion re-ask keeps sole ownership of reviewReask. New-submission materials
+  // ride a separate field so first mint never fails the "reask requires prior" gate.
+  let gateReviewInstruction: string | undefined;
+  if (options.reask === undefined) {
+    const { buildGateOfficerReviewInstruction } = await import("./auditor-dossier-tool.ts");
+    gateReviewInstruction = buildGateOfficerReviewInstruction({
+      sourceRunDirectory: options.sourceRunDirectory,
+      ...(options.submissionCandidatePath === undefined
+        ? {}
+        : { submissionCandidatePath: options.submissionCandidatePath }),
+    });
+  }
+  const common = {
+    cwd: options.cwd,
+    ...(home === undefined ? {} : { home }),
+    ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),
+    ...(options.io === undefined ? {} : { io: options.io }),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    ...(options.reask === undefined ? {} : { reviewReask: options.reask }),
+    ...(gateReviewInstruction === undefined
+      ? {}
+      : { gateReviewInstruction }),
+  } as const;
   if (options.officer === "notary") {
+    // #753: reask rides summonPublicRole → runPublicNotary summons.instruction
+    // (same resume seam as ordinary same-parent re-summons — no parallel stack).
     return summonPublicRole({
       role: "notary",
       argv: ["--source-run", options.sourceRunDirectory, "--project", options.cwd],
-      cwd: options.cwd,
-      ...(home === undefined ? {} : { home }),
-      ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),
-      ...(options.io === undefined ? {} : { io: options.io }),
-      ...(options.signal === undefined ? {} : { signal: options.signal }),
+      ...common,
     });
   }
+  if (options.officer === "auditor") {
+    // #756: judge compliance path — same queue law as notary/inspector.
+    // Subject is judge (doctor compliance stays on the disposeCompliance path).
+    const { AUDITOR_DOSSIER_PROMPT } = await import("./compliance-transport.ts");
+    return summonPublicRole({
+      role: "auditor",
+      argv: [
+        "--subject",
+        "judge",
+        "--source-run",
+        options.sourceRunDirectory,
+        AUDITOR_DOSSIER_PROMPT,
+      ],
+      ...common,
+    });
+  }
+  // Inspector: argv stays pure 卷宗指针 (#747 parentRunPath); reask rides env only.
   return summonPublicRole({
     role: "inspector",
     argv: [`卷宗指针：${options.sourceRunDirectory}`],
-    cwd: options.cwd,
-    ...(home === undefined ? {} : { home }),
-    ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),
-    ...(options.io === undefined ? {} : { io: options.io }),
-    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    ...common,
   });
 }

package/src/role-runtime.ts

@@ -116,7 +116,6 @@ import { PACKAGED_ROLE_REGISTRY, packagedRoleMetadata, packagedRoleOutputTool, p
 import { isAuditEscalationProjection } from "./audit-escalation.ts";
 import {
   createJudgeRoleRuntime,
-  type SoulAuditResult,
 } from "./judge-role.ts";
 import {
   createReviewerRoleRuntime,
@@ -364,7 +363,9 @@ export {
   createGatekeeperOutputTool,
   runGatekeeper,
 } from "./gatekeeper-role.ts";
-export type { GatekeeperResult, GatekeeperSubject, GatekeeperNonPassResult, RunGatekeeperOptions } from "./gatekeeper-role.ts";
+export type { GatekeeperResult, GatekeeperSubject, GatekeeperNonPassResult, GateOfficer, RunGatekeeperOptions } from "./gatekeeper-role.ts";
+export { gateOfficerForSubject } from "./gatekeeper-role.ts";
+import { ParentQueueReaskError } from "./submission-errors.ts";
 
 export {
   DOCTOR_EVIDENCE_TOOL_NAME,
@@ -376,7 +377,6 @@ export { loadDoctorCase } from "./doctor-evidence.ts";
 export {
   JUDGE_OUTPUT_TOOL_NAME,
   type JudgeVerdict,
-  type SoulAuditResult,
 } from "./judge-role.ts";
 export { ENGINE_DETOUR_TOOL_NAME, AK_ROLE_ENGINE_ENV } from "./engine-detour.ts";
 export {
@@ -410,7 +410,7 @@ export {
   resolveAuditorSubject,
 } from "./auditor-soul.ts";
 export type { AuditorSoulRole } from "./auditor-soul.ts";
-export { JUDGE_AUDIT_TOOL_NAME, SOUL_AUDIT_TOOL_NAME, createPiJudgeAuditor } from "./judge-auditor.ts";
+export { JUDGE_AUDIT_TOOL_NAME, SOUL_AUDIT_TOOL_NAME } from "./judge-auditor.ts";
 export { DOCTOR_AUDIT_TOOL_NAME, createPiDoctorAuditor } from "./doctor-auditor.ts";
 export type { ComplianceDecision } from "./compliance-transport.ts";
 export {
@@ -651,9 +651,6 @@ export type RoleRuntimeDependencies = {
     options: { context: HostContext; signal?: AbortSignal },
   ): Promise<ReviewerDispatchRunResult>;
   shutdownReviewerAgent?(): Promise<void>;
-  auditSoulCompliance(
-    options: { context: HostContext; signal?: AbortSignal },
-  ): Promise<SoulAuditResult>;
   activationClock?(): string;
   activationTraceWriter?: (record: ActivationTraceRecord) => void | Promise<void>;
   /** Wall-clock ISO timestamps for tool-execution observation records; defaults to activationClock/Date. */
@@ -1090,6 +1087,16 @@ function loadFrozenDiaristCatalog(
   return loadDiaristSourceCatalog(raw);
 }
 
+/** Countersign status words the queue reads (#753). */
+const COUNTERSIGN_QUEUE_STATUSES = new Set(["converged", "continue", "escalate"]);
+
+/**
+ * Plain-language re-ask when countersignStatus is not a known queue word.
+ * Back to countersign itself — notary is not summoned (#753).
+ */
+const COUNTERSIGN_STATUS_REASK =
+  "countersignStatus 不是 converged、continue、escalate 三态之一。请重新交卷，status 写明其一。" as const;
+
 export function createCountersignRoleRuntime(
   roleHost: RoleHost,
   dependencies: CountersignRuntimeDependencies,
@@ -1097,9 +1104,28 @@ export function createCountersignRoleRuntime(
 ) {
   // Notary inner gate difference only — lifecycle stays on the shared envelope.
   // Pointer-only summons: officer self-fetches from run dossier (#632 / ADR 0079).
+  // #753 queue: read countersignStatus only — escalate skips gate (thrown to caller);
+  // unreadable status returns to countersign; else notary inner gate.
   const beforeAccept: FiledOfficerBeforeAccept | undefined =
     hostActions !== undefined && roleHost.requireGatekeeperPass !== undefined
-      ? async ({ toolCallId, signal, ctx }) => {
+      ? async ({ toolCallId, parameters, signal, ctx }) => {
+          const record =
+            parameters !== null && typeof parameters === "object" && !Array.isArray(parameters)
+              ? (parameters as Record<string, unknown>)
+              : undefined;
+          const status =
+            record !== undefined && typeof record.countersignStatus === "string"
+              ? record.countersignStatus
+              : undefined;
+          if (status === undefined || !COUNTERSIGN_QUEUE_STATUSES.has(status)) {
+            // Parent status unreadable → back to countersign itself; do not summon notary,
+            // do not forge an officer bounce face (#753).
+            throw new ParentQueueReaskError(COUNTERSIGN_STATUS_REASK);
+          }
+          if (status === "escalate") {
+            // Parent escalate → throw to caller as-is; notary does not attend (#753).
+            return undefined;
+          }
           await roleHost.requireGatekeeperPass!({
             context: ctx,
             subject: { kind: "countersign_verdict" },
@@ -1483,7 +1509,6 @@ export function createRoleRuntimeExtension(
       roleHost,
       {
         loadSoul: dependencies.loadJudgeSoul,
-        auditSoulCompliance: dependencies.auditSoulCompliance,
       },
       hostActions,
     );

package/src/submission-correctable-error.ts

@@ -1,5 +1,6 @@
 import {
   GatekeeperDecisionError,
+  ParentQueueReaskError,
   WorkerCommitReminderError,
   WorkerPrefixReminderError,
   WorkerUnfinishedReasonReminderError,
@@ -25,6 +26,7 @@ export function isCorrectableExecuteError(error: unknown): boolean {
   return (
     isCorrectableSubmissionError(error)
     || error instanceof GatekeeperDecisionError
+    || error instanceof ParentQueueReaskError
     || error instanceof WorkerCommitReminderError
     || error instanceof WorkerPrefixReminderError
     || error instanceof WorkerUnfinishedReasonReminderError

package/src/submission-errors.ts

@@ -1,24 +1,29 @@
 import type { GatekeeperNonPassResult } from "./gatekeeper-role.ts";
-import { joinReadableGateItems } from "./readable-gate-item.ts";
+import { readableGateItem } from "./readable-gate-item.ts";
+
+/**
+ * Tool-result text the parent model sees (#753 / #750 evidence).
+ * bounce | escalate → officer receipt verbatim (JSON when structured).
+ * no_receipt → honest lifecycle fact. No findings rewrite, no「（无 findings）」.
+ * #775: structured field content via readableGateItem (DRY with other gate seams).
+ */
+function serializeReceipt(receipt: unknown): string {
+  return readableGateItem(receipt);
+}
 
 function gatekeeperNonPassMessage(result: GatekeeperNonPassResult): string {
-  if (result.status === "bounce") {
-    const findings = result.findings.length === 0
-      ? "（无 findings）"
-      : joinReadableGateItems(result.findings);
-    return `门下省打回重写，findings：${findings}`;
-  }
-  if (result.status === "unreadable") {
-    return `门下省官回执形状不可读（${result.officer}）：${result.reason}`;
+  if (result.status === "bounce" || result.status === "escalate") {
+    return serializeReceipt(result.receipt);
   }
+  // no_receipt
   return `门下省 ${result.status}（${result.stage}）：${result.reason}`;
 }
 
 /** Structured non-pass; `.result` is session-projected via tool_result, message feeds the model. */
 export class GatekeeperDecisionError extends Error {
   readonly result: GatekeeperNonPassResult;
-  constructor(result: GatekeeperNonPassResult) {
-    super(gatekeeperNonPassMessage(result));
+  constructor(result: GatekeeperNonPassResult, message?: string) {
+    super(message ?? gatekeeperNonPassMessage(result));
     this.name = "GatekeeperDecisionError";
     this.result = result;
   }
@@ -47,3 +52,15 @@ export class WorkerUnfinishedReasonReminderError extends Error {
     this.name = "WorkerUnfinishedReasonReminderError";
   }
 }
+
+/**
+ * Parent seat status unreadable for queueing (#753).
+ * Correctable back to the parent itself — not a gate officer bounce, no officer field.
+ */
+export class ParentQueueReaskError extends Error {
+  readonly code = "parent_queue_reask" as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "ParentQueueReaskError";
+  }
+}

package/src/submission-ledger.ts

@@ -3,8 +3,8 @@ import {
   tryHomeFromAkRolesPath,
 } from "./activation-ledger-topology.ts";
 import type { HostContext, HostToolResult, RoleHost } from "./host-contracts.ts";
-import { isAuditEscalationProjection, projectAuditEscalation } from "./audit-escalation.ts";
-import { GatekeeperEscalationError } from "./gatekeeper-role.ts";
+import { isAuditEscalationProjection } from "./audit-escalation.ts";
+
 
 import {
   acceptedFacts,
@@ -358,18 +358,6 @@ export function createSubmissionLedgerHost(
           // correctable-rejection path as execute-thrown rejections below. The
           // candidate is booked first so the bounced attempt stays observable.
           append({ type: "candidate", attemptId, toolCallId, toolName: tool.name, sequence: ++state.sequence });
-          const projectOfficerEscalation = (
-            officer: "inspector" | "notary",
-            original: Record<string, unknown>,
-            deliveredOutput: Record<string, unknown> = original,
-          ): HostToolResult<unknown> => projectAuditEscalation({
-            ...original,
-            status: "escalate",
-            officer,
-            reason: original.reason === undefined
-              ? `门下省${officer}上呈（原卷未附 reason）`
-              : original.reason,
-          }, deliveredOutput);
           let result: HostToolResult<unknown>;
           try {
             failOnInfrastructureFailureDeclaration(
@@ -385,14 +373,9 @@ export function createSubmissionLedgerHost(
             );
             result = await tool.execute(toolCallId, params, signal, update, context);
           } catch (error) {
-            if (error instanceof GatekeeperEscalationError) {
-              const decision = error.gatekeeper as unknown as Record<string, unknown>;
-              result = projectOfficerEscalation(
-                error.gatekeeper.officer,
-                decision,
-                params as Record<string, unknown>,
-              );
-            } else if (isCorrectableExecuteError(error)) {
+            // #753: gate no longer throws GatekeeperEscalationError to select parent
+            // next-step. Officer bounce|escalate returns as correctable with raw receipt.
+            if (isCorrectableExecuteError(error)) {
               append({
                 type: "outcome",
                 attemptId,
@@ -413,16 +396,9 @@ export function createSubmissionLedgerHost(
               throw error;
             }
           }
-          if (
-            (role === "inspector" || role === "notary") &&
-            typeof result.details === "object" &&
-            result.details !== null &&
-            !Array.isArray(result.details) &&
-            (result.details as Record<string, unknown>).status === "escalate"
-          ) {
-            const details = result.details as Record<string, unknown>;
-            result = projectOfficerEscalation(role, details);
-          }
+          // #753 escalate-thrown-verbatim: officer escalate seals as accepted with the
+          // raw receipt — no projectOfficerEscalation rewrite, no fabricated reason.
+          // Compliance seats still return live audit_escalation projections below.
           if (isAuditEscalationProjection(result.details)) {
             const candidates = rounds.get(attemptId) ?? [];
             candidates.push({

package/dist/shape-unreadable-failure.js

@@ -1,34 +0,0 @@
-/**
- * Single authoritative shape-unreadable marker (#675 / ADR 0055).
- * Settlement stamps it; consumers only read it — never re-derive from cause=output.
- */
-export const SHAPE_UNREADABLE_KEY = "shapeUnreadable";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Settlement seat path: stamp retained candidate as shape-unreadable (not infrastructure). */
-export function stampShapeUnreadableDetails(candidate) {
-    return {
-        [SHAPE_UNREADABLE_KEY]: true,
-        candidate,
-        acceptedReceipt: false,
-    };
-}
-/**
- * Read the settlement-stamped shape candidate from a failure decisiveFacts payload.
- * Looks at root and secondaryEvidence only for the typed marker — no cause inference.
- */
-export function retainedShapeUnreadable(decisiveFacts) {
-    if (!isRecord(decisiveFacts))
-        return undefined;
-    if (decisiveFacts[SHAPE_UNREADABLE_KEY] === true) {
-        return { candidate: decisiveFacts.candidate };
-    }
-    const secondary = isRecord(decisiveFacts.secondaryEvidence)
-        ? decisiveFacts.secondaryEvidence
-        : undefined;
-    if (secondary !== undefined && secondary[SHAPE_UNREADABLE_KEY] === true) {
-        return { candidate: secondary.candidate };
-    }
-    return undefined;
-}