@akagilnc/pi-workflow-roles 0.1.3262 → 0.1.3280

package/src/public-cli/settlement.ts

@@ -102,6 +102,16 @@ import {
   inspectorDecisiveFacts,
   validateRecordedInspectorOutput,
 } from "../inspector-contracts.ts";
+import {
+  GATEKEEPER_OUTPUT_TOOL_NAME,
+  gatekeeperDecisiveFacts,
+  validateRecordedGatekeeperOutput,
+} from "../package-contracts/gatekeeper-output.ts";
+import {
+  NAVIGATOR_OUTPUT_TOOL_NAME,
+  navigatorDecisiveFacts,
+  validateRecordedNavigatorOutput,
+} from "../package-contracts/navigator-output.ts";
 import {
   observePackagedMethodSkillInvocation,
   type ObservedPackagedMethodSkillInvocation,
@@ -136,6 +146,8 @@ import {
   type AdmittedCountersignInvocation,
   type AdmittedGleanerLeftInvocation,
   type AdmittedInspectorInvocation,
+  type AdmittedGatekeeperInvocation,
+  type AdmittedNavigatorInvocation,
   type AdmittedNotaryInvocation,
   type AdmittedReviewerInvocation,
   type AdmittedRoleInvocation,
@@ -3116,7 +3128,13 @@ export async function trySettleDoctorTerminalResult(
  * Role-specific validator / decisiveFacts / diagnostics stay on the seat.
  */
 type OneShotAcceptedSettlementSpec = {
-  readonly role: "notary" | "countersign" | "gleaner-left" | "inspector";
+  readonly role:
+    | "notary"
+    | "countersign"
+    | "gleaner-left"
+    | "inspector"
+    | "gatekeeper"
+    | "navigator";
   readonly toolName: string;
   readonly nonUsableDiagnostic: string;
   readonly projectAccepted: (
@@ -3144,7 +3162,13 @@ function currentAttemptStartIndex(entries: readonly SessionEntry[]): number {
 }
 
 async function settleLawfulOneShotAcceptedTerminalResult(
-  admitted: AdmittedNotaryInvocation | AdmittedCountersignInvocation | AdmittedGleanerLeftInvocation | AdmittedInspectorInvocation,
+  admitted:
+    | AdmittedNotaryInvocation
+    | AdmittedCountersignInvocation
+    | AdmittedGleanerLeftInvocation
+    | AdmittedInspectorInvocation
+    | AdmittedGatekeeperInvocation
+    | AdmittedNavigatorInvocation,
   authority: DurablePrincipalAuthority,
   spec: OneShotAcceptedSettlementSpec,
 ): Promise<TerminalResult | undefined> {
@@ -3197,10 +3221,22 @@ async function settleLawfulOneShotAcceptedTerminalResult(
     }
     return undefined;
   }
+  if (!spec.tryAcceptDetails(roleOutcome.decisiveFacts)) {
+    return settleFailureTerminalResult(
+      admitted,
+      {
+        cause: "output",
+        diagnostic: spec.nonUsableDiagnostic,
+        details: { candidate: roleOutcome.decisiveFacts, acceptedReceipt: false },
+      },
+      authority,
+    );
+  }
+  const acceptedOutcome = spec.projectAccepted(roleOutcome);
   const navigator = extractNavigatorFact(entries);
   return withOptionalGateProjection(
     {
-      roleOutcome: spec.projectAccepted(roleOutcome),
+      roleOutcome: acceptedOutcome,
       navigator,
       artifacts: [],
       runId: admitted.runId,
@@ -3415,6 +3451,82 @@ export async function trySettleInspectorTerminalResult(
   return settleLawfulInspectorTerminalResult(admitted, authority);
 }
 
+/** Lawful Gatekeeper accepted outcome (dispatch | pass, #639). */
+export type LawfulGatekeeperRoleOutcome = {
+  kind: "accepted";
+  role: "gatekeeper";
+  status: string;
+  decisiveFacts: Readonly<Record<string, unknown>>;
+};
+
+async function settleLawfulGatekeeperTerminalResult(
+  admitted: AdmittedGatekeeperInvocation,
+  authority: DurablePrincipalAuthority,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulOneShotAcceptedTerminalResult(admitted, authority, {
+    role: "gatekeeper",
+    toolName: GATEKEEPER_OUTPUT_TOOL_NAME,
+    nonUsableDiagnostic: "门下省决议无显式 dispatch/pass",
+    tryAcceptDetails: tryAcceptWithValidator(validateRecordedGatekeeperOutput),
+    projectAccepted: (sealed) => {
+      const output = validateRecordedGatekeeperOutput(sealed.decisiveFacts);
+      const accepted: LawfulGatekeeperRoleOutcome = {
+        kind: "accepted",
+        role: "gatekeeper",
+        status: output.status,
+        decisiveFacts: gatekeeperDecisiveFacts(output),
+      };
+      return accepted;
+    },
+  });
+}
+
+/** Try to settle a lawful Gatekeeper Terminal; undefined only for genuine absence. */
+export async function trySettleGatekeeperTerminalResult(
+  admitted: AdmittedGatekeeperInvocation,
+  authority: DurablePrincipalAuthority,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulGatekeeperTerminalResult(admitted, authority);
+}
+
+/** Lawful Navigator accepted outcome (route advice, #639). */
+export type LawfulNavigatorRoleOutcome = {
+  kind: "accepted";
+  role: "navigator";
+  status: string;
+  decisiveFacts: Readonly<Record<string, unknown>>;
+};
+
+async function settleLawfulNavigatorTerminalResult(
+  admitted: AdmittedNavigatorInvocation,
+  authority: DurablePrincipalAuthority,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulOneShotAcceptedTerminalResult(admitted, authority, {
+    role: "navigator",
+    toolName: NAVIGATOR_OUTPUT_TOOL_NAME,
+    nonUsableDiagnostic: "游奕使回执无显式路线建议",
+    tryAcceptDetails: tryAcceptWithValidator(validateRecordedNavigatorOutput),
+    projectAccepted: (sealed) => {
+      const output = validateRecordedNavigatorOutput(sealed.decisiveFacts);
+      const accepted: LawfulNavigatorRoleOutcome = {
+        kind: "accepted",
+        role: "navigator",
+        status: "advice",
+        decisiveFacts: navigatorDecisiveFacts(output),
+      };
+      return accepted;
+    },
+  });
+}
+
+/** Try to settle a lawful Navigator Terminal; undefined only for genuine absence. */
+export async function trySettleNavigatorTerminalResult(
+  admitted: AdmittedNavigatorInvocation,
+  authority: DurablePrincipalAuthority,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulNavigatorTerminalResult(admitted, authority);
+}
+
 /** Try to settle a lawful Coder Terminal; undefined only for genuine absence. */
 export async function trySettleCoderTerminalResult(
   admitted: AdmittedCoderInvocation,

package/src/public-cli/terminal.ts

@@ -38,7 +38,9 @@ export type TerminalRoleName =
   | "notary"
   | "countersign"
   | "gleaner-left"
-  | "inspector";
+  | "inspector"
+  | "gatekeeper"
+  | "navigator";
 
 /** Merger/Collector residual only — Notary/audit residual abolished (#475). */
 export type ResidualIncompleteTerminalOutcome = {

package/src/role-runtime.ts

@@ -74,6 +74,16 @@ import {
   type InspectorRuntimeDependencies,
 } from "./inspector-role.ts";
 import { INSPECTOR_ACCEPTED_TEXT } from "./inspector-contracts.ts";
+import {
+  GATEKEEPER_TOOL_SPEC,
+  type GatekeeperRuntimeDependencies,
+} from "./gatekeeper-role.ts";
+import {
+  NAVIGATOR_TOOL_SPEC,
+  type NavigatorRuntimeDependencies,
+} from "./navigator-role.ts";
+import { GATEKEEPER_ACCEPTED_TEXT } from "./package-contracts/gatekeeper-output.ts";
+import { NAVIGATOR_ACCEPTED_TEXT } from "./package-contracts/navigator-output.ts";
 import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorAttendanceOptions, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorTargetRole, type NavigatorWorkContext } from "./navigator-attendance.ts";
 import {
   buildNavigatorInfrastructureFailureFact,
@@ -337,7 +347,6 @@ export type { AuditorDecisionTool } from "./evidence-child-executor.ts";
 export {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
-  GATEKEEPER_OUTPUT_TOOL,
   GatekeeperDecisionError,
   createGatekeeperOutputTool,
   createOfficerDecisionTool,
@@ -443,6 +452,8 @@ type ActivationRuntime = {
   countersign: { activate(): Promise<void> };
   gleanerLeft: { activate(): Promise<void> };
   inspector: { activate(): Promise<void> };
+  gatekeeper: { activate(): Promise<void> };
+  navigator: { activate(): Promise<void> };
   merger(): Promise<void>;
 };
 
@@ -489,6 +500,8 @@ function activationStage(role: PackagedRole, runtime: ActivationRuntime): { id:
     case "countersign": return { id: "load-and-install", run: async () => runtime.countersign.activate() };
     case "gleaner-left": return { id: "load-and-install", run: async () => runtime.gleanerLeft.activate() };
     case "inspector": return { id: "load-and-install", run: async () => runtime.inspector.activate() };
+    case "gatekeeper": return { id: "load-and-install", run: async () => runtime.gatekeeper.activate() };
+    case "navigator": return { id: "load-and-install", run: async () => runtime.navigator.activate() };
     case "merger": return { id: "prepare-git-and-install", run: async () => runtime.merger() };
   }
 }
@@ -594,6 +607,8 @@ export type RoleRuntimeDependencies = {
   loadCountersignSoul?(): Promise<string>;
   loadGleanerLeftSoul?(): Promise<string>;
   loadInspectorSoul?(): Promise<string>;
+  loadGatekeeperSoul?(): Promise<string>;
+  loadNavigatorSoul?(): Promise<string>;
   loadDoctorCase?(path: string): Promise<import("./doctor-contracts.ts").DoctorCase>;
   loadMergerSoul?(): Promise<string>;
   loadMergerInput?(path: string): Promise<unknown>;
@@ -930,6 +945,40 @@ export function createInspectorRoleRuntime(
   );
 }
 
+/** #639: direct Gatekeeper public seat on the shared filed-officer envelope. */
+export function createGatekeeperRoleRuntime(
+  roleHost: RoleHost,
+  dependencies: GatekeeperRuntimeDependencies,
+) {
+  return createFiledOfficerRuntime(
+    roleHost,
+    {
+      role: "gatekeeper",
+      tool: GATEKEEPER_TOOL_SPEC,
+      acceptedText: GATEKEEPER_ACCEPTED_TEXT,
+      soulTag: "gatekeeper",
+    },
+    dependencies,
+  );
+}
+
+/** #639: direct Navigator public seat on the shared filed-officer envelope. */
+export function createNavigatorRoleRuntime(
+  roleHost: RoleHost,
+  dependencies: NavigatorRuntimeDependencies,
+) {
+  return createFiledOfficerRuntime(
+    roleHost,
+    {
+      role: "navigator",
+      tool: NAVIGATOR_TOOL_SPEC,
+      acceptedText: NAVIGATOR_ACCEPTED_TEXT,
+      soulTag: "navigator",
+    },
+    dependencies,
+  );
+}
+
 export function createCountersignRoleRuntime(
   roleHost: RoleHost,
   dependencies: CountersignRuntimeDependencies,
@@ -1435,6 +1484,18 @@ export function createRoleRuntimeExtension(
         return dependencies.loadInspectorSoul();
       },
     });
+    const gatekeeper = createGatekeeperRoleRuntime(roleHost, {
+      async loadSoul() {
+        if (!dependencies.loadGatekeeperSoul) throw new Error("Gatekeeper runtime dependencies are not configured");
+        return dependencies.loadGatekeeperSoul();
+      },
+    });
+    const navigator = createNavigatorRoleRuntime(roleHost, {
+      async loadSoul() {
+        if (!dependencies.loadNavigatorSoul) throw new Error("Navigator runtime dependencies are not configured");
+        return dependencies.loadNavigatorSoul();
+      },
+    });
     let sessionMergerGitState = dependencies.mergerGitState;
     const merger = createMergerRoleRuntime(roleHost, {
       async loadSoul() { if (!dependencies.loadMergerSoul) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
@@ -1583,6 +1644,8 @@ export function createRoleRuntimeExtension(
         countersign,
         gleanerLeft,
         inspector,
+        gatekeeper,
+        navigator,
         merger: async () => {
           if (dependencies.mergerGitState === undefined) {
             sessionMergerGitState = dependencies.createMergerGitState?.(ctx.cwd);

package/src/session-opening-materials.ts

@@ -1,8 +1,8 @@
 /**
  * Session opening materials (#443 / #524). Missing files fail as native readFile
- * errors. Main-role materials derive from PUBLIC_ROLE_RECORDS; gatekeeper seats
- * stay independent except notary (shared NOTARY_SESSION_MATERIALS). Navigator is
- * name-only here, not a public role record. Auditor composition stays in
+ * errors. Main-role materials derive from PUBLIC_ROLE_RECORDS (including
+ * gatekeeper and navigator). Province map reuses that public gatekeeper record
+ * plus officer material constants (notary shared). Auditor composition stays in
  * loadAuditorSoul; loaders share joinPackageMaterials.
  */
 import { existsSync } from "node:fs";
@@ -61,12 +61,11 @@ type PublicRoleMaterials = {
   >["sessionMaterials"];
 };
 
-/** Derived projection: public records + navigator name-only materials. */
+/** Derived projection: public records (#639 includes navigator/gatekeeper). */
 export const MAIN_ROLE_SESSION_MATERIALS = {
   ...(Object.fromEntries(
     PUBLIC_ROLE_RECORDS.map((record) => [record.role, record.sessionMaterials]),
   ) as PublicRoleMaterials),
-  navigator: ["CLAUDE.md", "souls/navigator.md"] as const,
 } as const;
 
 export type MainRoleSession = keyof typeof MAIN_ROLE_SESSION_MATERIALS;
@@ -79,12 +78,8 @@ export function loadMainRoleSessionMaterials(
 
 /** Gatekeeper province; notary reuses the public notary materials definition. */
 export const GATEKEEPER_SESSION_MATERIALS = {
-  gatekeeper: [
-    "CLAUDE.md",
-    "souls/gatekeeper.md",
-    "souls/quality-law.md",
-    "souls/gate-output-guide.md",
-  ],
+  // #639: single authority — the public gatekeeper record owns the province list.
+  gatekeeper: PUBLIC_ROLE_RECORDS.find((entry) => entry.role === "gatekeeper")!.sessionMaterials,
   inspector: INSPECTOR_SESSION_MATERIALS,
   notary: NOTARY_SESSION_MATERIALS,
 } as const;