@akagilnc/pi-workflow-roles 0.1.3262 → 0.1.3280

package/dist/public-cli/registry.js

@@ -6,22 +6,9 @@ import { PACKAGED_ROLE_REGISTRY, } from "../packaged-role-registry.js";
 /** Package-relative path of the Internal role entrypoint (explicit load only). */
 export const INTERNAL_ROLE_ENTRYPOINT_RELATIVE = "extensions/role-runtime.ts";
 export const PUBLIC_CALLABLE_ROLES = PACKAGED_ROLE_REGISTRY.map((entry) => entry.role);
-/** Automatic attendance seat — configurable, never a caller-selected command. */
-export const AUTOMATIC_NAVIGATOR_SEAT = "navigator";
-/** Automatic province seat — configurable model only; never a caller command. */
-export const AUTOMATIC_GATEKEEPER_SEAT = "gatekeeper";
-/** Automatic-only configurable seats. Inspector remains automatic-capable via its callable seat. */
-export const AUTOMATIC_CONFIGURABLE_SEATS = [
-    AUTOMATIC_GATEKEEPER_SEAT,
-    AUTOMATIC_NAVIGATOR_SEAT,
-];
 export const PUBLIC_CONFIGURABLE_SEATS = [
     ...PUBLIC_CALLABLE_ROLES,
-    ...AUTOMATIC_CONFIGURABLE_SEATS,
 ];
-export function isAutomaticConfigurableSeat(value) {
-    return AUTOMATIC_CONFIGURABLE_SEATS.includes(value);
-}
 export const PUBLIC_CLI_SUPPORT_COMMANDS = [
     "roles",
     "config",
@@ -82,7 +69,8 @@ const STARTUP_CANDIDATES = {
     ],
     // #620: subordinate officers inherit gatekeeper; no package startup model.
     notary: [],
-    // #453/#620: gatekeeper unset inherits audited session (province path only).
+    // #453/#620/#639: gatekeeper callable but no package startup model — caller
+    // configures it or the institutional resolution applies on the province path.
     gatekeeper: [],
     inspector: [],
     navigator: [

package/dist/session-opening-materials.js

@@ -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";
@@ -42,22 +42,17 @@ export async function joinPackageMaterials(relativePaths) {
     }
     return chunks.join("\n\n");
 }
-/** 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])),
-    navigator: ["CLAUDE.md", "souls/navigator.md"],
 };
 export function loadMainRoleSessionMaterials(role) {
     return joinPackageMaterials(MAIN_ROLE_SESSION_MATERIALS[role]);
 }
 /** 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,
 };

package/extensions/role-runtime.ts

@@ -36,7 +36,7 @@ import {
   formatNavigatorRoleHelp,
 } from "../src/role-runtime.ts";
 import { createPiJudgeAuditor } from "../src/judge-auditor.ts";
-import { loadMainRoleSessionMaterials } from "../src/session-opening-materials.ts";
+import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "../src/session-opening-materials.ts";
 const extensionPath = fileURLToPath(import.meta.url);
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const navigatorRoutePlaybookPath = fileURLToPath(new URL("../resources/navigator-route-playbook.md", import.meta.url));
@@ -128,6 +128,8 @@ export default function roleRuntime(pi: ExtensionAPI): void {
     loadCountersignSoul: () => loadMainRoleSessionMaterials("countersign"),
     loadGleanerLeftSoul: () => loadMainRoleSessionMaterials("gleaner-left"),
     loadInspectorSoul: () => loadMainRoleSessionMaterials("inspector"),
+    loadGatekeeperSoul: () => loadGatekeeperSessionMaterials("gatekeeper"),
+    loadNavigatorSoul: () => loadMainRoleSessionMaterials("navigator"),
     loadNotarySourceRun: loadNotarySourceRunLocator,
     loadNavigatorWorkContext: (options) => loadNavigatorWorkContext(pi, options),
     createNavigatorAttendance: (options) => {

package/package.json

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

package/resources/navigator-route-playbook.md

@@ -1,6 +1,6 @@
 ## 宿主轴（与角色命令面）
 
-游奕使自动出席，不另立调用命令。主会话宿主由公开角色的 host 轴决定：调用 `--host` → 席位 `config set-host` → 默认 `pi`。配置默认 host 后，调用者仍用与 Pi 相同的 `ak-role <role> …` 命令面；游奕使随该宿主下的角色跑次出席，席位模型走 run 目录 `institutional-resolution.json` 的 navigator 座（显式 `config set navigator` 优先，否则继承父席有效模型），不再依赖父宿主 ExtensionContext。
+游奕使自动出席，亦可 `ak-role navigator` 直调（自动出席不变）。主会话宿主由公开角色的 host 轴决定：调用 `--host` → 席位 `config set-host` → 默认 `pi`。配置默认 host 后，调用者仍用与 Pi 相同的 `ak-role <role> …` 命令面；游奕使随该宿主下的角色跑次出席，席位模型走 run 目录 `institutional-resolution.json` 的 navigator 座（显式 `config set navigator` 优先，否则继承父席有效模型），不再依赖父宿主 ExtensionContext。
 
 ## 常用交付线
 

package/src/gatekeeper-role.ts

@@ -8,8 +8,12 @@ import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { loadGatekeeperSessionMaterials } from "./session-opening-materials.ts";
 import { GatekeeperDecisionError } from "./submission-errors.ts";
 import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
-
-export const GATEKEEPER_OUTPUT_TOOL = "ak_gatekeeper_output";
+import {
+  GATEKEEPER_OUTPUT_TOOL_NAME,
+  gatekeeperDecisionSchema,
+  gatekeeperOutputSchema,
+  projectLawfulGatekeeperOutput,
+} from "./package-contracts/gatekeeper-output.ts";
 export const INSPECTOR_OUTPUT_TOOL = INSPECTOR_OUTPUT_TOOL_NAME;
 export const NOTARY_OUTPUT_TOOL = "ak_notary_output";
 const SUBJECT_TOOL = "ak_gatekeeper_subject";
@@ -82,11 +86,23 @@ const officerDecisionSchema = openToolObject(Type.Object({
   findings: Type.Unknown({ description: "string[] findings，随 pass 或 bounce 留存" }),
 }));
 
-const gatekeeperDecisionSchema = openToolObject(Type.Object({
-  status: Type.Unknown({ description: "dispatch | pass — 形状指引，非 schema 闸" }),
-  officer: Type.Unknown({ description: "status 为 dispatch 时为 inspector | notary" }),
-  findings: Type.Unknown({ description: "status 为 pass 时可选 string[] findings" }),
-}));
+
+/**
+ * Direct-seat decision tool spec (#639). Lifecycle assembly stays on the
+ * 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: "门下省终局决议，状态为 dispatch 或 pass。",
+  promptSnippet: "门下省决议",
+  parameters: gatekeeperOutputSchema,
+} as const;
+
+export type GatekeeperRuntimeDependencies = {
+  loadSoul(): Promise<string>;
+};
 
 function result(content: string, details: unknown) {
   return { content: [{ type: "text" as const, text: content }], details };
@@ -111,10 +127,10 @@ export function createOfficerDecisionTool(name: string): AuditorDecisionTool {
   };
 }
 
-/** Gatekeeper province decision tool — open transport; projection owns legality. */
+/** Gatekeeper province decision tool — open transport; package-contract projection owns legality. */
 export function createGatekeeperOutputTool(): AuditorDecisionTool {
   return {
-    name: GATEKEEPER_OUTPUT_TOOL,
+    name: GATEKEEPER_OUTPUT_TOOL_NAME,
     description: "提交门下省派官决定。",
     parameters: gatekeeperDecisionSchema,
     async execute(_id, args) { return result(`已收 ${String((args as { status?: unknown })?.status)}`, args); },
@@ -174,17 +190,16 @@ function readRecord(value: unknown): Record<string, unknown> | undefined {
 }
 
 function projectProvinceDecision(decision: unknown): GatekeeperResult | { status: "dispatch"; officer: "inspector" | "notary" } {
-  const record = readRecord(decision);
-  if (record === undefined) return noUsableReleaseFailure("gatekeeper", decision);
-  if (record.status === "dispatch" && (record.officer === "inspector" || record.officer === "notary")) {
-    return { status: "dispatch", officer: record.officer };
+  // Lawful dispatch/pass discriminant is owned by package-contracts; province
+  // wraps undefined into transport_failure while retaining the submission.
+  const projected = projectLawfulGatekeeperOutput(decision);
+  if (projected === undefined) return noUsableReleaseFailure("gatekeeper", decision);
+  if (projected.status === "dispatch") {
+    return { status: "dispatch", officer: projected.officer };
   }
   // Lawful non-dispatch release — province may pass without dispatching an officer
   // (ADR 0074 gate-non-mandatory; gate-output-guide pass = 正常放行; #597).
-  if (record.status === "pass") {
-    return { status: "pass", findings: asStringArray(record.findings) };
-  }
-  return noUsableReleaseFailure("gatekeeper", decision);
+  return { status: "pass", findings: projected.findings ?? [] };
 }
 
 function projectOfficerDecision(

package/src/grok/production-host.ts

@@ -32,7 +32,7 @@ import { loadPackagedCanonicalSkillBinding } from "../package-resources/method-s
 import { createPerDispatchReviewerAgent } from "../reviewer-agent.ts";
 import { formatNavigatorRoleHelp, type RoleRuntimeDependencies } from "../role-runtime.ts";
 import { createReviewerPinnedGitReader } from "../reviewer-pinned-git.ts";
-import { loadMainRoleSessionMaterials } from "../session-opening-materials.ts";
+import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "../session-opening-materials.ts";
 import { createComposedGrokRoleTurnHost } from "./role-envelope.ts";
 import {
   assertControlledGrokAuthIsNotSymlink,
@@ -221,6 +221,8 @@ export function createGrokRoleRuntimeDependencies(packageRoot: string): RoleRunt
     loadDoctorSoul: () => loadMainRoleSessionMaterials("doctor"),
     loadDoctorCase,
     loadInspectorSoul: () => loadMainRoleSessionMaterials("inspector"),
+    loadGatekeeperSoul: () => loadGatekeeperSessionMaterials("gatekeeper"),
+    loadNavigatorSoul: () => loadMainRoleSessionMaterials("navigator"),
     loadNotarySoul: () => loadMainRoleSessionMaterials("notary"),
     loadCountersignSoul: () => loadMainRoleSessionMaterials("countersign"),
     loadGleanerLeftSoul: () => loadMainRoleSessionMaterials("gleaner-left"),

package/src/host-contracts.ts

@@ -123,7 +123,9 @@ export type RoleTurnActivation =
       /** Required comparison-base revision for the unanchored merge-candidate diff. */
       readonly baseRevision: string;
     }
-  | { readonly role: "inspector" };
+  | { readonly role: "inspector" }
+  | { readonly role: "gatekeeper" }
+  | { readonly role: "navigator" };
 
 export type RoleTurnContinuation =
   | { readonly kind: "initial"; readonly prompt: string }

package/src/navigator-role.ts

@@ -0,0 +1,17 @@
+import { NAVIGATOR_OUTPUT_TOOL_NAME, navigatorOutputSchema } from "./package-contracts/navigator-output.ts";
+
+/**
+ * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
+ * Candidates share the route-advice shape the attendance prepare tool owns.
+ */
+export const NAVIGATOR_TOOL_SPEC = {
+  name: NAVIGATOR_OUTPUT_TOOL_NAME,
+  label: "游奕使建议",
+  description: "游奕使终局回执：排好序的下一步角色路线建议。",
+  promptSnippet: "游奕使建议",
+  parameters: navigatorOutputSchema,
+} as const;
+
+export type NavigatorRuntimeDependencies = {
+  loadSoul(): Promise<string>;
+};

package/src/package-contracts/gatekeeper-output.ts

@@ -0,0 +1,89 @@
+/**
+ * Public Gatekeeper (门下省) terminating receipt contracts (#639).
+ * Direct public seat shares the province decision shape: dispatch | pass.
+ * No usable result is infrastructure failure via public settlement, not a judgment status (#475).
+ */
+import { Type } from "typebox";
+
+import { openToolObject } from "../open-tool-schema.ts";
+import { withInfrastructureFailureDeclaration } from "./terminating-infrastructure.ts";
+
+export const GATEKEEPER_OUTPUT_TOOL_NAME = "ak_gatekeeper_output";
+export const GATEKEEPER_ACCEPTED_TEXT = "门下省决议已受理";
+
+/** Same open decision shape the province uses inside audit sessions. */
+export const gatekeeperDecisionSchema = openToolObject(
+  Type.Object({
+    status: Type.Unknown({
+      description: "dispatch | pass — 形状指引，非 schema 闸",
+    }),
+    officer: Type.Unknown({
+      description: "status 为 dispatch 时为 inspector | notary",
+    }),
+    findings: Type.Unknown({
+      description: "status 为 pass 时可选 string[] findings",
+    }),
+  }),
+);
+
+export const gatekeeperOutputSchema = withInfrastructureFailureDeclaration(
+  gatekeeperDecisionSchema,
+);
+
+export type GatekeeperDirectOutput =
+  | { readonly status: "dispatch"; readonly officer: "inspector" | "notary" }
+  | { readonly status: "pass"; readonly findings?: readonly string[] };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asStringArray(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+/**
+ * Project one lawful explicit Gatekeeper decision (dispatch | pass).
+ * No throw on shape — ADR 0055 / 第 0 条: already-submitted params are retained as-is;
+ * public-terminal projects non-usable releases via typed failure cause.
+ */
+export function projectLawfulGatekeeperOutput(value: unknown): GatekeeperDirectOutput | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.status === "pass") {
+    return Array.isArray(value.findings)
+      ? { status: "pass", findings: asStringArray(value.findings) }
+      : { status: "pass" };
+  }
+  if (
+    value.status === "dispatch" &&
+    (value.officer === "inspector" || value.officer === "notary")
+  ) {
+    return { status: "dispatch", officer: value.officer };
+  }
+  return undefined;
+}
+
+/**
+ * Settlement/recording path: only lawful recorded dispatch/pass.
+ * Does not gate role admission — callers must not use this to reject a submission.
+ */
+export function validateRecordedGatekeeperOutput(value: unknown): GatekeeperDirectOutput {
+  const projected = projectLawfulGatekeeperOutput(value);
+  if (projected === undefined) {
+    throw new Error("Gatekeeper output has no recognized execution discriminator");
+  }
+  return projected;
+}
+
+export function gatekeeperDecisiveFacts(
+  output: GatekeeperDirectOutput,
+): Record<string, unknown> {
+  const facts: Record<string, unknown> = { status: output.status };
+  if (output.status === "dispatch") {
+    facts.officer = output.officer;
+  } else if (Array.isArray(output.findings)) {
+    facts.findingsCount = output.findings.length;
+  }
+  return facts;
+}

package/src/package-contracts/navigator-output.ts

@@ -0,0 +1,59 @@
+/**
+ * Public Navigator (游奕使) terminating receipt contracts (#639).
+ * Direct public seat submits route advice with the same candidate shape the
+ * attendance prepare tool owns — one shape authority for navigator advice.
+ * No usable result is infrastructure failure via public settlement, not a judgment status (#475).
+ */
+import { Type } from "typebox";
+
+import { openToolObject } from "../open-tool-schema.ts";
+import { withInfrastructureFailureDeclaration } from "./terminating-infrastructure.ts";
+
+export const NAVIGATOR_OUTPUT_TOOL_NAME = "ak_navigator_output";
+export const NAVIGATOR_ACCEPTED_TEXT = "游奕使建议已受理";
+
+export const navigatorOutputSchema = withInfrastructureFailureDeclaration(
+  openToolObject(
+    Type.Object({
+      status: Type.Unknown({
+        description: "advice — 形状指引，非 schema 闸",
+      }),
+      candidates: Type.Unknown({
+        description: "排好序的路线建议数组，元素含 next/phase/reason — 形状指引，非 schema 闸",
+      }),
+    }),
+  ),
+);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export type NavigatorAdvice = { readonly status: "advice"; readonly candidates: readonly unknown[] };
+
+/**
+ * Project one lawful explicit Navigator advice receipt: candidates array,
+ * each candidate a record. Broken ancillary fields are preserved as submitted —
+ * shape is not an admission gate (ADR 0055 / 第 0 条).
+ */
+export function projectLawfulNavigatorOutput(value: unknown): NavigatorAdvice | undefined {
+  if (!isRecord(value) || !Array.isArray(value.candidates)) return undefined;
+  if (value.status !== "advice") return undefined;
+  return { status: "advice", candidates: value.candidates.filter(isRecord) };
+}
+
+/**
+ * Settlement/recording path: only lawful recorded candidate arrays.
+ * Does not gate role admission — callers must not use this to reject a submission.
+ */
+export function validateRecordedNavigatorOutput(value: unknown): NavigatorAdvice {
+  const projected = projectLawfulNavigatorOutput(value);
+  if (projected === undefined) {
+    throw new Error("Navigator output has no recognized execution discriminator");
+  }
+  return projected;
+}
+
+export function navigatorDecisiveFacts(output: { readonly candidates: readonly unknown[] }): Record<string, unknown> {
+  return { status: "advice", candidates: output.candidates };
+}

package/src/package-contracts/terminating-tools.ts

@@ -27,6 +27,8 @@ import {
 import { isAuditEscalationResult } from "../audit-escalation.ts";
 import { CorrectableSubmissionError } from "../submission-correctable-error.ts";
 import { DOCTOR_ACCEPTED_TEXT, DOCTOR_OUTPUT_TOOL_NAME, validateDoctorSubmissionShape, validateRecordedDoctorOutput, type DoctorOutput, type DoctorSubmission } from "../doctor-contracts.ts";
+import { GATEKEEPER_ACCEPTED_TEXT, GATEKEEPER_OUTPUT_TOOL_NAME, validateRecordedGatekeeperOutput, type GatekeeperDirectOutput } from "./gatekeeper-output.ts";
+import { NAVIGATOR_ACCEPTED_TEXT, NAVIGATOR_OUTPUT_TOOL_NAME, validateRecordedNavigatorOutput, type NavigatorAdvice } from "./navigator-output.ts";
 import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateMergerOutput, type MergerOutput } from "../merger-contracts.ts";
 import { NOTARY_ACCEPTED_TEXT, NOTARY_OUTPUT_TOOL_NAME, validateRecordedNotaryOutput, type NotaryOutput } from "../notary-contracts.ts";
 import { COUNTERSIGN_ACCEPTED_TEXT, COUNTERSIGN_OUTPUT_TOOL_NAME, validateRecordedCountersignOutput, type CountersignVerdict } from "../countersign-contracts.ts";
@@ -67,6 +69,8 @@ export {
   validateRecordedCountersignOutput,
   validateRecordedGleanerLeftOutput,
   validateRecordedInspectorOutput,
+  validateRecordedGatekeeperOutput,
+  validateRecordedNavigatorOutput,
 };
 export type {
   CollectorReceipt,
@@ -81,6 +85,8 @@ export type {
   CountersignVerdict,
   GleanerLeftOutput,
   InspectorOutput,
+  GatekeeperDirectOutput,
+  NavigatorAdvice,
 };
 
 export const TERMINATING_TOOL_NAMES = [
@@ -95,6 +101,8 @@ export const TERMINATING_TOOL_NAMES = [
   COUNTERSIGN_OUTPUT_TOOL_NAME,
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
   INSPECTOR_OUTPUT_TOOL_NAME,
+  GATEKEEPER_OUTPUT_TOOL_NAME,
+  NAVIGATOR_OUTPUT_TOOL_NAME,
 ] as const;
 
 export type TerminatingToolName = (typeof TERMINATING_TOOL_NAMES)[number];
@@ -109,7 +117,9 @@ export type AcceptedDetails =
   | NotaryOutput
   | CountersignVerdict
   | GleanerLeftOutput
-  | InspectorOutput;
+  | InspectorOutput
+  | GatekeeperDirectOutput
+  | NavigatorAdvice;
 
 export function isTerminatingToolName(
   name: string,
@@ -141,6 +151,10 @@ export function acceptedTextFor(toolName: TerminatingToolName): string {
       return GLEANER_LEFT_ACCEPTED_TEXT;
     case INSPECTOR_OUTPUT_TOOL_NAME:
       return INSPECTOR_ACCEPTED_TEXT;
+    case GATEKEEPER_OUTPUT_TOOL_NAME:
+      return GATEKEEPER_ACCEPTED_TEXT;
+    case NAVIGATOR_OUTPUT_TOOL_NAME:
+      return NAVIGATOR_ACCEPTED_TEXT;
   }
 }
 
@@ -197,6 +211,8 @@ export function validateAcceptedDetails(
     [COUNTERSIGN_OUTPUT_TOOL_NAME]: ["converged", "continue", "escalate"],
     [GLEANER_LEFT_OUTPUT_TOOL_NAME]: ["completed"],
     [INSPECTOR_OUTPUT_TOOL_NAME]: ["pass", "bounce"],
+    [GATEKEEPER_OUTPUT_TOOL_NAME]: ["dispatch", "pass"],
+    [NAVIGATOR_OUTPUT_TOOL_NAME]: ["advice"],
   };
   const collectorDiscriminator = toolName === COLLECTOR_OUTPUT_TOOL && Array.isArray(candidate?.groups);
   const baseDiscriminator = discriminator;
@@ -233,6 +249,10 @@ export function validateAcceptedDetails(
       return validateRecordedGleanerLeftOutput(details);
     case INSPECTOR_OUTPUT_TOOL_NAME:
       return validateRecordedInspectorOutput(details);
+    case GATEKEEPER_OUTPUT_TOOL_NAME:
+      return validateRecordedGatekeeperOutput(details);
+    case NAVIGATOR_OUTPUT_TOOL_NAME:
+      return validateRecordedNavigatorOutput(details);
     }
   } catch (error) {
     if (error instanceof Error && error.constructor === Error) throw new AcceptedDetailsContractError(error.message, { cause: error });
@@ -279,7 +299,9 @@ export function acceptedFacts(toolName: TerminatingToolName, details: AcceptedDe
     case DOCTOR_OUTPUT_TOOL_NAME:
     case NOTARY_OUTPUT_TOOL_NAME:
     case GLEANER_LEFT_OUTPUT_TOOL_NAME:
-    case INSPECTOR_OUTPUT_TOOL_NAME: return { status: (details as { status: string }).status };
+    case INSPECTOR_OUTPUT_TOOL_NAME:
+    case GATEKEEPER_OUTPUT_TOOL_NAME:
+    case NAVIGATOR_OUTPUT_TOOL_NAME: return { status: (details as { status: string }).status };
     case JUDGE_OUTPUT_TOOL_NAME: return { status: (details as { judgeStatus: string }).judgeStatus };
     case COUNTERSIGN_OUTPUT_TOOL_NAME: return { status: (details as { countersignStatus: string }).countersignStatus };
     case MERGER_OUTPUT_TOOL_NAME: {

package/src/packaged-role-registry.ts

@@ -1,5 +1,7 @@
 /** Composition-root unique authoritative public-role records (#509 / #524). */
 import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.ts";
+import { GATEKEEPER_OUTPUT_TOOL_NAME } from "./package-contracts/gatekeeper-output.ts";
+import { NAVIGATOR_OUTPUT_TOOL_NAME } from "./package-contracts/navigator-output.ts";
 import { JUDGE_OUTPUT_TOOL_NAME } from "./package-contracts/judge-output.ts";
 import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.ts";
 import { CODER_OUTPUT_TOOL_NAME, FIXER_OUTPUT_TOOL_NAME } from "./package-contracts/worker-output.ts";
@@ -28,8 +30,7 @@ export const INSPECTOR_SESSION_MATERIALS = [
 ] as const;
 
 /**
- * One record per public callable role. Navigator is absent (name-only materials
- * live on the session-opening projection).
+ * One record per public callable role (#639: includes gatekeeper and navigator).
  */
 export const PUBLIC_ROLE_RECORDS = [
   {
@@ -162,6 +163,28 @@ export const PUBLIC_ROLE_RECORDS = [
     activationStage: "load-and-install",
     sessionMaterials: INSPECTOR_SESSION_MATERIALS,
   },
+  // #639: gatekeeper and navigator are roles like any other — public ak-role
+  // entries; automatic attendance (province dispatch, navigator sidecar) is
+  // unchanged and orthogonal to callability.
+  {
+    role: "gatekeeper",
+    phases: [null],
+    outputTool: GATEKEEPER_OUTPUT_TOOL_NAME,
+    inputFlag: undefined,
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    // Province materials; officers reuse their own public records below.
+    sessionMaterials: ["CLAUDE.md", "souls/gatekeeper.md", "souls/quality-law.md", "souls/gate-output-guide.md"],
+  },
+  {
+    role: "navigator",
+    phases: [null],
+    outputTool: NAVIGATOR_OUTPUT_TOOL_NAME,
+    inputFlag: undefined,
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: ["CLAUDE.md", "souls/navigator.md"],
+  },
 ] as const;
 
 export type PublicRoleRecord = (typeof PUBLIC_ROLE_RECORDS)[number];

package/src/pi/role-turn-host.ts

@@ -142,6 +142,10 @@ function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
       ];
     case "inspector":
       return ["--ak-role", "inspector"];
+    case "gatekeeper":
+      return ["--ak-role", "gatekeeper"];
+    case "navigator":
+      return ["--ak-role", "navigator"];
     default: {
       const _exhaustive: never = activation;
       return _exhaustive;

package/src/public-cli/cli.ts

@@ -52,9 +52,11 @@ import {
   parseGleanerLeftArgv,
   parseDoctorArgv,
   parseFixerArgv,
+  parseGatekeeperArgv,
   parseJudgeArgv,
   parseInspectorArgv,
   parseMergerArgv,
+  parseNavigatorArgv,
   parseNotaryArgv,
   parseReviewerArgv,
   recordLaunchedPiIdentity,
@@ -71,6 +73,7 @@ import {
   type TypedOptionConsumer,
 } from "./option-definitions.ts";
 import { runPublicCoder, runPublicCoderResume } from "./coder-run.ts";
+import { runPublicInstructionSeat } from "./instruction-seat-run.ts";
 import { runPublicCollector } from "./collector-run.ts";
 import { runPublicCountersign, runPublicCountersignResume } from "./countersign-run.ts";
 import { runPublicGleanerLeft, runPublicGleanerLeftResume } from "./gleaner-left-run.ts";
@@ -90,7 +93,6 @@ import {
 } from "./run-lifecycle.ts";
 import {
   INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
-  isAutomaticConfigurableSeat,
   isPublicCallableRole,
   isPublicCliSupportCommand,
   isPublicConfigurableSeat,
@@ -128,6 +130,8 @@ export const PUBLIC_ROLE_ARGV = {
   notary: { parse: parseNotaryArgv, options: optionsForOwner("notary") },
   inspector: { parse: parseInspectorArgv, options: optionsForOwner("inspector") },
   reviewer: { parse: parseReviewerArgv, options: optionsForOwner("reviewer") },
+  gatekeeper: { parse: parseGatekeeperArgv, options: optionsForOwner("gatekeeper") },
+  navigator: { parse: parseNavigatorArgv, options: optionsForOwner("navigator") },
   /** Deterministic analysis seat (#336) — argv parse only; no LLM admission. */
   analyst: { parse: parseAnalystArgv, options: optionsForOwner("analyst") },
 } as const;
@@ -596,17 +600,12 @@ function requireLegalEngineName(name: string): string {
   }
 }
 
-/** Callable seats own persistent call axes; automatic seats have no call path. */
+/** Callable seats own persistent call axes (checked against the callable predicate). */
 function requireCallableSeat(
   seat: string,
   axis: "engine" | "host",
   verb: "set-engine" | "unset-engine" | "set-host" | "unset-host",
 ): asserts seat is PublicCallableRole {
-  if (isAutomaticConfigurableSeat(seat)) {
-    throw new CliUsageError(
-      `config ${verb} refuses ${seat}: no independent activation path; storing would be silently ineffective`,
-    );
-  }
   if (!isPublicCallableRole(seat)) {
     throw new CliUsageError(`unknown ${axis}-axis seat: ${seat}`);
   }
@@ -765,12 +764,11 @@ function renderCommandHelp(command: string): string | undefined {
 }
 
 function renderRoles(seats: readonly EffectiveSeat[]): string {
-  const lines: string[] = ["seat\tkind\tsource\tmodel"];
+  const lines: string[] = ["seat\tsource\tmodel"];
   for (const seat of seats) {
-    const kind = seat.automatic ? "automatic" : "callable";
     const model =
       seat.selection === undefined ? "-" : formatModelSpec(seat.selection);
-    lines.push(`${seat.seat}\t${kind}\t${seat.source}\t${model}`);
+    lines.push(`${seat.seat}\t${seat.source}\t${model}`);
   }
   return `${lines.join("\n")}\n`;
 }
@@ -1569,6 +1567,35 @@ export async function runAkRole(
       };
     }
 
+    // Gatekeeper/Navigator direct public run paths (#639) — instruction seats,
+    // a role like any other; one parameterized branch for both.
+    if (parsed.command === "gatekeeper" || parsed.command === "navigator") {
+      const agentDir = resolveAgentDir(env, home);
+      const cwd = env.cwd ?? process.cwd();
+      const config = await loadAndValidateConfig(home, env.packageRoot);
+      const credentials =
+        env.credentials ?? (await loadCredentialProviders(agentDir));
+      const seat = resolveEffectiveSeat(
+        config,
+        parsed.command,
+        credentials,
+        invocationFromParsed(parsed),
+      );
+      const result = await runPublicInstructionSeat(
+        parsed.args,
+        createRoleEnvironment(env, { role: parsed.command, home, agentDir, cwd, credentials, seat, config }),
+        io,
+        parsed.command,
+        parsed.command === "gatekeeper"
+          ? PUBLIC_ROLE_ARGV.gatekeeper.parse
+          : PUBLIC_ROLE_ARGV.navigator.parse,
+      );
+      return {
+        exitCode: result.exitCode,
+        ...(result.terminal === undefined ? {} : { terminal: result.terminal }),
+      };
+    }
+
     // Analyst public run path: deterministic analysis seat (#336 issue / #337 sweep).
     // Not an LLM PUBLIC_CALLABLE_ROLE — registered only on PUBLIC_ROLE_ARGV (#176).
     if (parsed.command === "analyst") {