@akagilnc/pi-workflow-roles 0.1.5375 → 0.1.5382

package/dist/submission-gate.js

@@ -1,6 +1,7 @@
 import { bookDirectOfficerRunPointer } from "./archivist-record-pointer.js";
 import { GatekeeperDecisionError, officerConclusionReask, projectGatekeeperRun, } from "./gatekeeper-role.js";
-/** Queue word of the latest this-terminal payload. History does not outrank it. */
+import { receivedDiscriminator } from "./submission-errors.js";
+/** Received discriminator of the latest payload, retained verbatim for re-ask. */
 export function latestQueueStatus(terminal) {
     const outcome = terminal?.roleOutcome;
     if (outcome === undefined)
@@ -10,14 +11,10 @@ export function latestQueueStatus(terminal) {
     if (outcome.kind !== "accepted")
         return undefined;
     const latest = outcome.payloads?.[outcome.payloads.length - 1];
-    if (isRecord(latest)) {
-        const status = latest.status;
-        if (typeof status === "string" && status.trim() !== "")
-            return status;
+    if (isRecord(latest) && Object.hasOwn(latest, "status")) {
+        return receivedDiscriminator(latest, "status");
     }
-    return typeof outcome.status === "string" && outcome.status.trim() !== ""
-        ? outcome.status
-        : undefined;
+    return outcome.status;
 }
 export function latestQueuePayload(terminal) {
     const outcome = terminal?.roleOutcome;

package/package.json

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

package/src/auditor-role.ts

@@ -3,8 +3,8 @@
  */
 import {
   AUDITOR_OUTPUT_TOOL_NAME,
-  auditorOutputSchema,
 } from "./package-contracts/auditor-output.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 export { AUDITOR_OUTPUT_TOOL_NAME };
 
@@ -12,10 +12,4 @@ export type AuditorRuntimeDependencies = {
   loadSoul(): Promise<string>;
 };
 
-export const AUDITOR_TOOL_SPEC = {
-  name: AUDITOR_OUTPUT_TOOL_NAME,
-  label: "审刑院输出",
-  description: "审刑院终局回执，status 为 converged、continue 或 escalate。",
-  promptSnippet: "审刑院终局回执",
-  parameters: auditorOutputSchema,
-} as const;
+export const AUDITOR_TOOL_SPEC = roleSubmissionDeclaration("auditor");

package/src/collector-role.ts

@@ -3,8 +3,9 @@
  * #1088: code no longer observes/requests/merges GitHub findings — the LLM
  * uses host CLI tools. Envelope owns host-surface + construction seatbelt.
  */
-import type { RoleHost, HostContext, HostToolResult } from "./host-contracts.ts";
-import type { Static } from "typebox";
+import type { RoleHost, HostContext } from "./host-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 import {
   emptyCollectorManifest,
@@ -17,8 +18,6 @@ import {
 import {
   COLLECTOR_OUTPUT_TOOL,
 } from "./package-contracts/collector-output.ts";
-import { collectorOutputArgsSchema } from "./collector-tool-schemas.ts";
-
 export { COLLECTOR_OUTPUT_TOOL };
 
 export const COLLECTOR_REQUIRED_TOOLS = [COLLECTOR_OUTPUT_TOOL] as const;
@@ -54,8 +53,6 @@ export const COLLECTOR_TRANSPORT_FLAGS = Object.freeze([
   }),
 ] as const);
 
-const outputSchema = collectorOutputArgsSchema;
-type OutputParams = Static<typeof outputSchema>;
 
 export type CollectorRoleDependencies = {
   loadSoul(): Promise<string>;
@@ -164,28 +161,8 @@ export function createCollectorRoleRuntime(
       if (toolsRegistered) return;
       toolsRegistered = true;
 
-      pi.registerTool({
-        name: COLLECTOR_OUTPUT_TOOL,
-        label: "通进司输出",
-        description: "提交通进司回执。",
-        promptSnippet: "提交通进司回执",
-        parameters: outputSchema,
-        async execute(
-          _toolCallId: string,
-          params: OutputParams,
-          _signal: AbortSignal | undefined,
-          _onUpdate: unknown,
-          _ctx: HostContext,
-        ): Promise<HostToolResult<unknown>> {
-          const activation = getActivation();
-          if (activation === undefined) throw new Error("通进司未激活");
-          // #1088 / #836: record as submitted — runtime does not merge findings.
-          return {
-            content: [],
-            details: params,
-            terminate: true as const,
-          };
-        },
+      registerFiledSubmissionTool(pi, roleSubmissionDeclaration("collector"), {
+        readyError: () => (getActivation() === undefined ? "通进司未激活" : undefined),
       });
     },
   };

package/src/countersign-role.ts

@@ -1,4 +1,5 @@
 import { reviewSubmissionSchema } from "./review-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import {
   COUNTERSIGN_OUTPUT_TOOL_NAME,
   validateRecordedCountersignOutput,
@@ -26,10 +27,4 @@ export type CountersignRuntimeDependencies = {
  * 决定工具规格。生命周期装配（注册、activate、prompt 注入、singleton 检查、
  * terminate）归注册信封 owner——src/role-runtime.ts（ADR 0018 / #572 R2 判词）。
  */
-export const COUNTERSIGN_TOOL_SPEC = {
-  name: COUNTERSIGN_OUTPUT_TOOL_NAME,
-  label: "给事中输出",
-  description: "给事中决议。",
-  promptSnippet: "给事中决议",
-  parameters: countersignVerdictSchema,
-} as const;
+export const COUNTERSIGN_TOOL_SPEC = roleSubmissionDeclaration("countersign");

package/src/diarist-contracts.ts

@@ -7,6 +7,10 @@
  * #901: LLM submits bounds; the mechanical layer projects source bytes.
  */
 
+import { Type } from "typebox";
+
+import { openToolObject } from "./open-tool-schema.ts";
+import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 import {
   projectTicketProvenanceSessions,
   type TicketProvenanceSession,
@@ -88,3 +92,36 @@ export function projectDiaristTicketSessions(
   }
   return Array.from(perTicket, ([ticketNumber, sessions]) => ({ ticketNumber, sessions }));
 }
+
+/**
+ * 起居郎交卷形状。
+ * #901：交边界（sessions）；正文与不可解析原字节由机械投影。
+ * status 的合法词（completed | escalate）写在 description，结算认这些词。
+ * sessions / ticketSessions 是投影所读的边界：卷路径或端点读不出时走既有 reask，不中止本轮。
+ * 声明只留字段名和语义说明，不留类型、嵌套、长度、必填。
+ */
+const DIARIST_SESSIONS_DESCRIPTION =
+  "对话边界。每卷含 path（会话卷绝对或可读路径）与 ranges（本卷本轮各区间）。每段区间含 from / to；起点与终点各写 id（原生 id）或 line（本轮行号），二选一。空列表＝本轮无对话可划。端点无法指名时走 reask，不中止。" as const;
+
+export const diaristOutputSchema = withTerminatingOutputDeclarations(
+  openToolObject(
+    Type.Object({
+      status: Type.Unknown({
+        description: "completed | escalate",
+      }),
+      ticketNumber: Type.Optional(
+        Type.Unknown({
+          description:
+            "本庭对象票号（正整数）或 null/省略＝真无票；下游走 typed 键；认不出用 status=escalate，不洗成无录。机械层不重判。",
+        }),
+      ),
+      reason: Type.Unknown({
+        description: "status 为 escalate 时：认不出本庭对象的原因",
+      }),
+      sessions: Type.Optional(Type.Unknown({ description: DIARIST_SESSIONS_DESCRIPTION })),
+      ticketSessions: Type.Unknown({
+        description: `多票庭逐票对话边界；每票含 ticketNumber（本条边界所归票号，正整数）与 sessions（${DIARIST_SESSIONS_DESCRIPTION}）。一次交卷各票各自分录。与单票 sessions 二选一。`,
+      }),
+    }),
+  ),
+);

package/src/diarist-role.ts

@@ -1,53 +1,20 @@
 import type { Static } from "typebox";
-import { Type } from "typebox";
 
-import { openToolObject } from "./open-tool-schema.ts";
-import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 import {
   DIARIST_OUTPUT_TOOL_NAME,
+  diaristOutputSchema,
   validateRecordedDiaristOutput,
   type DiaristOutput,
 } from "./diarist-contracts.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 export {
   DIARIST_OUTPUT_TOOL_NAME,
+  diaristOutputSchema,
 } from "./diarist-contracts.ts";
 export type { DiaristOutput };
 export { validateRecordedDiaristOutput };
 
-/**
- * 起居郎交卷形状。
- * #901：交边界（sessions）；正文与不可解析原字节由机械投影。
- * status 的合法词（completed | escalate）写在 description，结算认这些词。
- * sessions / ticketSessions 是投影所读的边界：卷路径或端点读不出时走既有 reask，不中止本轮。
- * 声明只留字段名和语义说明，不留类型、嵌套、长度、必填。
- */
-const DIARIST_SESSIONS_DESCRIPTION =
-  "对话边界。每卷含 path（会话卷绝对或可读路径）与 ranges（本卷本轮各区间）。每段区间含 from / to；起点与终点各写 id（原生 id）或 line（本轮行号），二选一。空列表＝本轮无对话可划。端点无法指名时走 reask，不中止。" as const;
-
-export const diaristOutputSchema = withTerminatingOutputDeclarations(
-  openToolObject(
-    Type.Object({
-      status: Type.Unknown({
-        description: "completed | escalate",
-      }),
-      ticketNumber: Type.Optional(
-        Type.Unknown({
-          description:
-            "本庭对象票号（正整数）或 null/省略＝真无票；下游走 typed 键；认不出用 status=escalate，不洗成无录。机械层不重判。",
-        }),
-      ),
-      reason: Type.Unknown({
-        description: "status 为 escalate 时：认不出本庭对象的原因",
-      }),
-      sessions: Type.Optional(Type.Unknown({ description: DIARIST_SESSIONS_DESCRIPTION })),
-      ticketSessions: Type.Unknown({
-        description: `多票庭逐票对话边界；每票含 ticketNumber（本条边界所归票号，正整数）与 sessions（${DIARIST_SESSIONS_DESCRIPTION}）。一次交卷各票各自分录。与单票 sessions 二选一。`,
-      }),
-    }),
-  ),
-);
-
 export type DiaristOutputParameters = Static<typeof diaristOutputSchema>;
 
 export type DiaristRuntimeDependencies = {
@@ -57,11 +24,4 @@ export type DiaristRuntimeDependencies = {
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  */
-export const DIARIST_TOOL_SPEC = {
-  name: DIARIST_OUTPUT_TOOL_NAME,
-  label: "起居郎输出",
-  description:
-    "起居郎交单票 sessions 或多票逐票 ticketSessions 边界；认不出本庭对象则 escalate。",
-  promptSnippet: "起居郎交边界",
-  parameters: diaristOutputSchema,
-} as const;
+export const DIARIST_TOOL_SPEC = roleSubmissionDeclaration("diarist");

package/src/doctor-role.ts

@@ -1,7 +1,9 @@
-import type { RoleHost, HostContext, HostToolResult } from "./host-contracts.ts";
+import type { RoleHost, HostContext } from "./host-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { ComplianceResponseRetentionError } from "./compliance-transport.ts";
 import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.ts";
-import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, doctorSubmissionSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
+import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
 
 import { sitianReport } from "./sitian-facade.ts";
 
@@ -36,15 +38,18 @@ export function createDoctorRoleRuntime(pi: RoleHost, dependencies: DoctorRoleDe
   let activation: { soul: string; patient: DoctorCase; store: DoctorEvidenceStore } | undefined; let registered = false; pi.registerFlag(DOCTOR_CASE_FLAG.name, DOCTOR_CASE_FLAG.definition);
   return { async activate() { const path = pi.getFlag(DOCTOR_CASE_FLAG.name); if (typeof path !== "string" || !path.trim()) throw new Error("Doctor requires --ak-doctor-case"); const soul = (await dependencies.loadSoul()).trim(); if (!soul) throw new Error("Doctor soul is empty"); const patient = await dependencies.loadCase(path); activation = { soul, patient, store: new DoctorEvidenceStore(patient) };
     if (!registered) { registered = true; pi.registerTool({ name: DOCTOR_EVIDENCE_TOOL_NAME, label: "太医署证据", description: "分页读取留存的 Pi session 字节。", parameters: doctorEvidenceReadSchema, async execute(_id: string, params: { evidenceId: string; offset?: number; limit?: number }) { if (!activation) throw new Error("太医署未激活"); const details = activation.store.read(params.evidenceId, params.offset, params.limit); return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details }; } });
-      pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "太医署输出", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id: string, params: unknown, _signal: AbortSignal | undefined, _update: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
-        if (!activation) throw new Error("太医署未激活");
-        const active = activation;
-        const testimony = validateDoctorOutput(params, active.patient, active.store);
-        try {
-          appendCandidate(ctx, { version: 1, testimony, cost: active.patient.cost, readRecord: active.store.readRecord(), patientIdentity: active.patient.identity });
-        } catch (error) { host.failInfrastructure(error, ctx, id); }
-        return { content: [], details: testimony, terminate: true };
-      } });
+      registerFiledSubmissionTool(pi, roleSubmissionDeclaration("doctor"), {
+        readyError: () => (activation === undefined ? "太医署未激活" : undefined),
+        beforeAccept: async ({ toolCallId, parameters, ctx }) => {
+          if (activation === undefined) throw new Error("太医署未激活");
+          const active = activation;
+          const testimony = validateDoctorOutput(parameters, active.patient, active.store);
+          try {
+            appendCandidate(ctx, { version: 1, testimony, cost: active.patient.cost, readRecord: active.store.readRecord(), patientIdentity: active.patient.identity });
+          } catch (error) { host.failInfrastructure(error, ctx, toolCallId); }
+          return testimony;
+        },
+      });
       pi.on("before_agent_start", (event) => { if (!activation) throw new Error("太医署未激活"); const catalog = { version: activation.patient.version, identity: activation.patient.identity, admittedMetrics: { cost: activation.patient.cost }, lawfulTargetKeys: ["case", ...activation.patient.cost.invocations.sources], evidence: activation.patient.evidence.map(({ id, kind, sha256, byteLength, contentLength }) => ({ id, kind, sha256, byteLength, contentLength })) }; return { systemPrompt: `${event.systemPrompt}\n\n<doctor_soul>\n${activation.soul}\n</doctor_soul>\n\n<doctor_case>\n${JSON.stringify(catalog)}\n</doctor_case>` }; }); }
     const required = [DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME]; const names = pi.getAllTools().map((tool) => tool.name); for (const name of required) if (names.filter((item) => item === name).length !== 1) throw new Error(`Doctor required tool collision or missing: ${name}`); pi.setActiveTools(required); const active = pi.getActiveTools?.() ?? required; if (active.length !== 2 || !required.every((name) => active.includes(name))) throw new Error("Doctor active tool narrowing failed"); } };
 }

package/src/filed-submission.ts

@@ -0,0 +1,44 @@
+import type { HostContext, HostToolResult, RoleHost } from "./host-contracts.ts";
+import type { RoleSubmissionDeclaration } from "./role-submission-declarations.ts";
+
+export type FiledSubmissionBeforeAccept = (input: {
+  readonly toolCallId: string;
+  readonly parameters: unknown;
+  readonly signal: AbortSignal | undefined;
+  readonly ctx: HostContext;
+}) => Promise<unknown>;
+
+/**
+ * One host-neutral submission execute for every public seat.
+ * Records nothing itself — the ledger seam already appends the original payload.
+ * Ends this tool call. Does not summon an auditor and does not end the role run.
+ * Shape is not an admission gate (ADR 0055). Seat reminders stay on beforeAccept.
+ */
+export function registerFiledSubmissionTool(
+  roleHost: RoleHost,
+  tool: RoleSubmissionDeclaration,
+  options: {
+    readonly readyError: () => string | undefined;
+    readonly beforeAccept?: FiledSubmissionBeforeAccept;
+  },
+): void {
+  roleHost.registerTool({
+    name: tool.name,
+    label: tool.label,
+    description: tool.description,
+    ...(tool.promptSnippet === undefined ? {} : { promptSnippet: tool.promptSnippet }),
+    parameters: tool.parameters as never,
+    async execute(toolCallId, parameters, signal, _onUpdate, ctx): Promise<HostToolResult<unknown>> {
+      const blocked = options.readyError();
+      if (blocked !== undefined) throw new Error(blocked);
+      const projected = options.beforeAccept === undefined
+        ? undefined
+        : await options.beforeAccept({ toolCallId, parameters, signal, ctx });
+      return {
+        content: [],
+        details: projected === undefined ? parameters : projected,
+        terminate: true as const,
+      };
+    },
+  });
+}

package/src/gatekeeper-role.ts

@@ -7,10 +7,8 @@ import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { GatekeeperDecisionError, receivedDiscriminator, unreadableDiscriminatorNotice } from "./submission-errors.ts";
 import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
 import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
-import {
-  GATEKEEPER_OUTPUT_TOOL_NAME,
-  gatekeeperOutputSchema,
-} from "./package-contracts/gatekeeper-output.ts";
+import { GATEKEEPER_OUTPUT_TOOL_NAME } from "./package-contracts/gatekeeper-output.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import type { PublicSummonResult } from "./public-role-summons.ts";
 import type { TerminalResult } from "./public-cli/terminal.ts";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
@@ -158,13 +156,7 @@ export type SubmissionGateHostActions = {
  * registration envelope — src/role-runtime.ts (ADR 0018). Schema authority is
  * the shared contract module (with infrastructure-failure declaration).
  */
-export const GATEKEEPER_TOOL_SPEC = {
-  name: GATEKEEPER_OUTPUT_TOOL_NAME,
-  label: "门下省决议",
-  description: "门下省终局决议。status 为 dispatch 或 pass。",
-  promptSnippet: "门下省决议",
-  parameters: gatekeeperOutputSchema,
-} as const;
+export const GATEKEEPER_TOOL_SPEC = roleSubmissionDeclaration("gatekeeper");
 
 export type GatekeeperRuntimeDependencies = {
   loadSoul(): Promise<string>;
@@ -199,9 +191,9 @@ function projectOfficerDecision(
 ): GatekeeperResult {
   const receipt = retainedReceipt(decision);
   const record = isRecord(decision) ? decision : undefined;
-  const status =
-    (record !== undefined && typeof record.status === "string" ? record.status : undefined)
-    ?? fallbackStatus;
+  const status = record !== undefined && Object.hasOwn(record, "status")
+    ? receivedDiscriminator(record, "status")
+    : fallbackStatus;
   const queueStatus = typeof status === "string" ? reviewQueueStatus(status) : undefined;
   if (queueStatus === "converged") {
     return { status: "converged", officer, receipt };

package/src/gleaner-left-contracts.ts

@@ -4,10 +4,36 @@
  * No bounce / verdict channel (言不为狱). 原卷保真 (ADR 0055).
  */
 
+import { Type } from "typebox";
+
+import { openToolObject } from "./open-tool-schema.ts";
+import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 import { isRecord } from "./unknown-value.ts";
 
 export const GLEANER_LEFT_OUTPUT_TOOL_NAME = "ak_gleaner_left_output";
 
+// #836 r16 class 1: pointer/statement are LLM/human-read narrative content — no
+// code branches on their presence.
+// #1134: `status` alone is the trajectory field (src/gleaner-left-contracts.ts:38
+// recognizes completed to settle); its word rides the description. findings is
+// narrative content declared name + semantic description only — the array type
+// and the nested pointer/statement object shape are deleted, because the package
+// declaration IS the host's pre-dispatch validator. An empty findings list stays
+// a lawful completion; an omitted one is now expressible too.
+export const gleanerLeftOutputSchema = withTerminatingOutputDeclarations(
+  openToolObject(
+    Type.Object({
+      status: Type.Unknown({
+        description: "completed",
+      }),
+      findings: Type.Unknown({
+        description:
+          "弹章列表；每条可含 pointer（文件/行指针）与 statement（疑点陈述），原样留存。空列表合法完局；机器不判弹章是否成立。",
+      }),
+    }),
+  ),
+);
+
 /** Internal transport: comparison-base revision for the unanchored merge-candidate diff. */
 export const GLEANER_LEFT_BASE_FLAG = {
   name: "ak-gleaner-left-base",
@@ -42,4 +68,3 @@ export function validateRecordedGleanerLeftOutput(value: unknown): GleanerLeftOu
   }
   throw new Error("Gleaner-left output has no execution discriminator");
 }
-

package/src/gleaner-left-role.ts

@@ -1,42 +1,20 @@
 import type { Static } from "typebox";
-import { Type } from "typebox";
 
-import { openToolObject } from "./open-tool-schema.ts";
-import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 import {
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
+  gleanerLeftOutputSchema,
   validateRecordedGleanerLeftOutput,
   type GleanerLeftOutput,
 } from "./gleaner-left-contracts.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 export {
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
+  gleanerLeftOutputSchema,
 } from "./gleaner-left-contracts.ts";
 export type { GleanerLeftOutput };
 export { validateRecordedGleanerLeftOutput };
 
-// #836 r16 class 1: pointer/statement are LLM/human-read narrative content — no
-// code branches on their presence.
-// #1134: `status` alone is the trajectory field (src/gleaner-left-contracts.ts:38
-// recognizes completed to settle); its word rides the description. findings is
-// narrative content declared name + semantic description only — the array type
-// and the nested pointer/statement object shape are deleted, because the package
-// declaration IS the host's pre-dispatch validator. An empty findings list stays
-// a lawful completion; an omitted one is now expressible too.
-export const gleanerLeftOutputSchema = withTerminatingOutputDeclarations(
-  openToolObject(
-    Type.Object({
-      status: Type.Unknown({
-        description: "completed",
-      }),
-      findings: Type.Unknown({
-        description:
-          "弹章列表；每条可含 pointer（文件/行指针）与 statement（疑点陈述），原样留存。空列表合法完局；机器不判弹章是否成立。",
-      }),
-    }),
-  ),
-);
-
 export type GleanerLeftOutputParameters = Static<typeof gleanerLeftOutputSchema>;
 
 export type GleanerLeftRuntimeDependencies = {
@@ -46,10 +24,4 @@ export type GleanerLeftRuntimeDependencies = {
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  */
-export const GLEANER_LEFT_TOOL_SPEC = {
-  name: GLEANER_LEFT_OUTPUT_TOOL_NAME,
-  label: "左拾遗输出",
-  description: "左拾遗弹章。",
-  promptSnippet: "左拾遗弹章",
-  parameters: gleanerLeftOutputSchema,
-} as const;
+export const GLEANER_LEFT_TOOL_SPEC = roleSubmissionDeclaration("gleaner-left");

package/src/inspector-role.ts

@@ -1,5 +1,6 @@
 import type { Static } from "typebox";
 import { reviewSubmissionSchema } from "./review-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import {
   INSPECTOR_OUTPUT_TOOL_NAME,
   validateRecordedInspectorOutput,
@@ -25,10 +26,4 @@ export type InspectorRuntimeDependencies = {
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  */
-export const INSPECTOR_TOOL_SPEC = {
-  name: INSPECTOR_OUTPUT_TOOL_NAME,
-  label: "台院输出",
-  description: "台院终局回执，状态为 converged、continue 或 escalate。",
-  promptSnippet: "台院终局回执",
-  parameters: inspectorOutputSchema,
-} as const;
+export const INSPECTOR_TOOL_SPEC = roleSubmissionDeclaration("inspector");

package/src/judge-role.ts

@@ -1,10 +1,7 @@
-import {
-  type RoleHost,
-  type HostContext,
-  type HostToolResult,
-} from "./host-contracts.ts";
-import type { Static } from "typebox";
-import { reviewSubmissionSchema } from "./review-submission.ts";
+import { type RoleHost } from "./host-contracts.ts";
+import { REVIEW_QUEUE_STATUSES, reviewSubmissionSchema, type ReviewQueueWord } from "./review-submission.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { type GatekeeperSubject } from "./gatekeeper-role.ts";
 import {
   JUDGE_OUTPUT_TOOL_NAME,
@@ -31,10 +28,10 @@ export async function runJudgeGates(input: {
     readonly runDirectory?: string;
   } | void>;
 }): Promise<{
-  readonly status: "converged" | "continue" | "escalate";
+  readonly status: ReviewQueueWord;
   readonly passes: readonly {
     readonly subject: GatekeeperSubject;
-    readonly status: "converged" | "continue" | "escalate";
+    readonly status: ReviewQueueWord;
     readonly receipt: unknown;
     readonly runId?: string;
     readonly runDirectory?: string;
@@ -42,7 +39,7 @@ export async function runJudgeGates(input: {
 }> {
   const passes: {
     subject: GatekeeperSubject;
-    status: "converged" | "continue" | "escalate";
+    status: ReviewQueueWord;
     receipt: unknown;
     runId?: string;
     runDirectory?: string;
@@ -50,10 +47,11 @@ export async function runJudgeGates(input: {
   for (const subject of JUDGE_GATES) {
     if (await input.gateAlreadyConverged(subject)) continue;
     const pass = await input.runGate(subject);
-    const status = pass?.status;
-    if (pass === undefined || (status !== "converged" && status !== "continue" && status !== "escalate")) {
+    const received = pass?.status;
+    if (pass === undefined || typeof received !== "string" || !REVIEW_QUEUE_STATUSES.has(received)) {
       throw new Error("judge gate returned no conclusion");
     }
+    const status = received as ReviewQueueWord;
     passes.push({
       subject,
       status,
@@ -90,18 +88,8 @@ export function createJudgeRoleRuntime(
       if (soul.length === 0) throw new Error("Judge soul is empty");
       if (!lifecycleRegistered) {
         lifecycleRegistered = true;
-        pi.registerTool({
-          name: JUDGE_OUTPUT_TOOL_NAME,
-          label: "大理寺输出",
-          description: "提交大理寺终局判词；交卷调用结束后，由公开调用接缝按判词状态执行适用审核。",
-          promptSnippet: "提交大理寺终局判词",
-          parameters: judgeVerdictSchema,
-          async execute(toolCallId: string, parameters: Static<typeof judgeVerdictSchema>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
-            if (soul === undefined) throw new Error("大理寺职分未装载");
-            // ADR 0003: record the original receipt and end the tool call first.
-            // The public seam reads status and chooses the next route.
-            return { content: [], details: parameters, terminate: true };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("judge"), {
+          readyError: () => (soul === undefined ? "大理寺职分未装载" : undefined),
         });
         pi.on("before_agent_start", (event) => {
           if (soul === undefined) throw new Error("大理寺职分未装载");

package/src/merger-role.ts

@@ -1,10 +1,11 @@
-import type { RoleHost, HostContext } from "./host-contracts.ts";
+import type { RoleHost } from "./host-contracts.ts";
 import {
   MERGER_OUTPUT_TOOL_NAME,
-  mergerOutputSchema,
   validateMergerInput,
   type MergerInput,
 } from "./merger-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { exactUtf8 } from "./exact-utf8.ts";
 
 export { MERGER_OUTPUT_TOOL_NAME };
@@ -35,12 +36,8 @@ export function createMergerRoleRuntime(pi: RoleHost, dependencies: MergerRoleDe
       activation = { soul, input };
       if (!registered) {
         registered = true;
-        pi.registerTool({
-          name: MERGER_OUTPUT_TOOL_NAME, label: "合并输出", description: "提交合并结果；输出分支为 completed 与 escalate。", promptSnippet: "提交合并结果", parameters: mergerOutputSchema,
-          async execute(_id: string, params: unknown, _signal: AbortSignal | undefined, _update: unknown, _ctx: HostContext) {
-            if (!activation) throw new Error("校书郎未激活");
-            return { content: [], details: params, terminate: true as const };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("merger"), {
+          readyError: () => (activation === undefined ? "校书郎未激活" : undefined),
         });
         pi.on("before_agent_start", (event) => {
           if (!activation) throw new Error("校书郎未激活");

package/src/navigator-role.ts

@@ -1,16 +1,10 @@
-import { NAVIGATOR_OUTPUT_TOOL_NAME, navigatorOutputSchema } from "./package-contracts/navigator-output.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  * #959: navigator speaks free-form prose; tool is a lifecycle vehicle only.
  */
-export const NAVIGATOR_TOOL_SPEC = {
-  name: NAVIGATOR_OUTPUT_TOOL_NAME,
-  label: "游奕使建议",
-  description: "游奕使终局回执：散文建议，原样呈现。",
-  promptSnippet: "游奕使建议",
-  parameters: navigatorOutputSchema,
-} as const;
+export const NAVIGATOR_TOOL_SPEC = roleSubmissionDeclaration("navigator");
 
 export type NavigatorRuntimeDependencies = {
   loadSoul(): Promise<string>;