@akagilnc/pi-workflow-roles 0.1.4422 → 0.1.4489

package/src/diarist-contracts.ts

@@ -4,13 +4,11 @@
  * Machine facts about the volume come from the mechanical reproject seam, never
  * from model self-report (锚定宪法); this module owns the receipt shape only.
  *
- * #901: LLM submits bounds (+ optional amendments); mechanical layer projects.
+ * #901: LLM submits bounds; the mechanical layer projects source bytes.
  */
 
 import {
-  projectTicketProvenanceAmendments,
   projectTicketProvenanceSessions,
-  type TicketProvenanceAmendment,
   type TicketProvenanceSession,
 } from "./ticket-provenance-contracts.ts";
 import {
@@ -45,11 +43,6 @@ export type DiaristOutput =
        * Malformed endpoints → accept hook reasks (`reask-not-explode`).
        */
       readonly sessions?: readonly TicketProvenanceSession[];
-      /**
-       * Optional amendments for unparsable source lines (s + line + speaker + text).
-       * Absent = no amendments this turn (not a shape rejection).
-       */
-      readonly amendments?: readonly TicketProvenanceAmendment[];
     }
   | {
       /** LLM cannot tell which ticket this summons is about — escalate, never wash into 无录. */
@@ -187,14 +180,3 @@ export function projectDiaristSessions(
   if (raw === undefined) return [];
   return projectTicketProvenanceSessions(raw);
 }
-
-/**
- * Project optional amendments. Absent / non-array → empty (not a rejection).
- */
-export function projectDiaristAmendments(
-  value: unknown,
-): readonly TicketProvenanceAmendment[] {
-  const raw = (value as { amendments?: unknown } | null)?.amendments;
-  if (raw === undefined) return [];
-  return projectTicketProvenanceAmendments(raw);
-}

package/src/diarist-role.ts

@@ -18,7 +18,7 @@ export { validateRecordedDiaristOutput };
 
 /**
  * 起居郎交卷形状；形状指引，非 schema 闸。
- * #901：交边界（sessions）+ 可选坏行补写（amendments）；正文由机械投影。
+ * #901：交边界（sessions）；正文与不可解析原字节由机械投影。
  */
 export const diaristOutputSchema = withTerminatingOutputDeclarations(
   openToolObject(
@@ -93,34 +93,6 @@ export const diaristOutputSchema = withTerminatingOutputDeclarations(
           },
         ),
       ),
-      amendments: Type.Optional(
-        Type.Array(
-          Type.Object(
-            {
-              s: Type.Optional(
-                Type.Unknown({ description: "卷下标（sessions 位置）" }),
-              ),
-              line: Type.Optional(
-                Type.Unknown({ description: "源卷 1-based 行号" }),
-              ),
-              speaker: Type.Optional(
-                Type.String({ description: "owner | runner" }),
-              ),
-              text: Type.Optional(
-                Type.String({ description: "补写正文（原话）" }),
-              ),
-            },
-            {
-              additionalProperties: true,
-              description: "一条坏行补写；缺字段的成员机械跳过",
-            },
-          ),
-          {
-            description:
-              "可选；机械解析不了的行交此补写。缺本字段＝无补写，不拒收。",
-          },
-        ),
-      ),
     }),
   ),
 );
@@ -138,7 +110,7 @@ export const DIARIST_TOOL_SPEC = {
   name: DIARIST_OUTPUT_TOOL_NAME,
   label: "起居郎输出",
   description:
-    "起居郎交本票对话边界（sessions）与可选坏行补写（amendments）；认不出本庭对象则 escalate。",
-  promptSnippet: "起居郎交边界与可选补写",
+    "起居郎交本票对话边界（sessions）；认不出本庭对象则 escalate。",
+  promptSnippet: "起居郎交边界",
   parameters: diaristOutputSchema,
 } as const;

package/src/diarist.ts

@@ -1,17 +1,11 @@
 /**
  * 起居郎 volume commit — ADR 0075 `diarist-is-role` / #901.
- * LLM submits bounds (+ optional amendments); mechanical layer reprojects the
+ * LLM submits bounds; mechanical layer reprojects the
  * unique records.jsonl from session volumes. No human view. No lifecycle here
  * (ADR 0018): the seat prepares, the role envelope commits.
  */
-import {
-  reprojectTicketProvenance,
-  type UnparsableSessionLine,
-} from "./ticket-provenance.ts";
-import type {
-  TicketProvenanceAmendment,
-  TicketProvenanceSession,
-} from "./ticket-provenance-contracts.ts";
+import { reprojectTicketProvenance } from "./ticket-provenance.ts";
+import type { TicketProvenanceSession } from "./ticket-provenance-contracts.ts";
 
 /**
  * Honest machine facts about what this turn actually committed to the volume.
@@ -22,16 +16,11 @@ export type DiaristCommitFacts = {
   readonly volumeRecordFile: string;
   /** Dialogue lines written by this reproject. */
   readonly lineCount: number;
-  /**
-   * Session lines inside the bounds that still have no amendment.
-   * Accept hook turns a non-empty list into ParentQueueReaskError.
-   */
-  readonly unparsable: readonly UnparsableSessionLine[];
 };
 
 /**
- * Reproject the unique diary from LLM-submitted bounds + optional amendments.
- * Shape projection of sessions/amendments is the caller's job (accept hook);
+ * Reproject the unique diary from LLM-submitted bounds.
+ * Shape projection of sessions is the caller's job (accept hook);
  * this seam only copies source facts into the volume.
  */
 export async function commitDiaristProjection(input: {
@@ -39,19 +28,16 @@ export async function commitDiaristProjection(input: {
   readonly cwd: string;
   readonly home?: string;
   readonly sessions: readonly TicketProvenanceSession[];
-  readonly amendments?: readonly TicketProvenanceAmendment[];
 }): Promise<DiaristCommitFacts> {
   const result = await reprojectTicketProvenance({
     ticketNumber: input.ticketNumber,
     cwd: input.cwd,
     ...(input.home === undefined ? {} : { home: input.home }),
     sessions: input.sessions,
-    ...(input.amendments === undefined ? {} : { amendments: input.amendments }),
   });
   return {
     ticketNumber: input.ticketNumber,
     volumeRecordFile: result.recordFile,
     lineCount: result.lines.length,
-    unparsable: result.unparsable,
   };
 }

package/src/headless-host/description.ts

@@ -90,6 +90,8 @@ export function headlessTurnArgs(options: {
   readonly effort?: string;
   /** Fresh session: pass as session id. Resume: pass as resume id. */
   readonly session: { readonly kind: "new"; readonly id: string } | { readonly kind: "resume"; readonly id: string };
+  /** Packaged method plugin dir (`--plugin-dir`). */
+  readonly pluginDir?: string;
 }): string[] {
   const { description } = options;
   const args: string[] = [
@@ -100,6 +102,7 @@ export function headlessTurnArgs(options: {
     description.jsonSchemaFlag,
     JSON.stringify(options.jsonSchema),
   ];
+  if (options.pluginDir) args.push("--plugin-dir", options.pluginDir);
   if (options.mcpConfigPath !== undefined && options.mcpConfigPath !== "") {
     args.push(description.mcpConfigFlag, options.mcpConfigPath);
   }
@@ -422,9 +425,7 @@ export function codexTurnArgs(options: {
 
   // JSONL event stream: thread_id + final agent_message + turn.completed/failed.
   args.push("--json");
-  // Operator config/MCP off; auth still uses CODEX_HOME (official).
-  // Project/system config and AGENTS.md have no official suppression switch.
-  args.push("--ignore-user-config", "--ignore-rules");
+  // Operator config/skills stay open (#922 host-native-loader). Auth uses CODEX_HOME.
   const roots = (options.writableRoots ?? []).filter((root) => root !== "");
   if (roots.length > 0) {
     // Resume has no --add-dir; the config key keeps extra roots available on both paths.

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

@@ -23,6 +23,12 @@ import {
 } from "../prepared-role-turn.ts";
 
 import { reportHostSessionEvent } from "../host-session-record.ts";
+import {
+  applyClaudeSkillInvocation,
+  applyCodexSkillInvocation,
+  hostMethodSkills,
+  packagedMethodPluginDir,
+} from "../host-native-method.ts";
 import {
   closeJsonSchemaForCodex,
   codexTurnArgs,
@@ -410,6 +416,7 @@ function buildTurnArgs(options: {
   readonly sessionKind: "new" | "resume";
   readonly cwd: string;
   readonly writableRoots?: readonly string[];
+  readonly pluginDir?: string;
 }): readonly string[] {
   if (isCodexExecDescription(options.description)) {
     if (options.sessionKind === "resume" && !options.sessionId) {
@@ -441,6 +448,7 @@ function buildTurnArgs(options: {
     ...(options.model === undefined ? {} : { model: options.model }),
     ...(options.effort === undefined ? {} : { effort: options.effort }),
     session: { kind: options.sessionKind, id: options.sessionId },
+    ...(options.pluginDir === undefined ? {} : { pluginDir: options.pluginDir }),
   });
 }
 
@@ -469,11 +477,17 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
       await writeFile(systemPromptPath, systemPrompt, "utf8");
       let mcpConfigPath: string | undefined;
       let outputSchemaPath: string | undefined;
+      let pluginDir: string | undefined;
+      let applyMethodPrompt: (prompt: string) => string = codex
+        ? (prompt) => applyCodexSkillInvocation(request.methods, prompt)
+        : (prompt) => prompt;
       if (codex) {
-        // Codex --output-schema needs a closed transport projection on disk.
         outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
-        const closed = closeJsonSchemaForCodex(prepared.jsonSchema);
-        await writeFile(outputSchemaPath, `${JSON.stringify(closed, null, 2)}\n`, "utf8");
+        await writeFile(
+          outputSchemaPath,
+          `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+          "utf8",
+        );
       } else {
         mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
         await writeFile(
@@ -481,6 +495,14 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
           `${JSON.stringify(headlessMcpConfigDocument(prepared.mcpServers), null, 2)}\n`,
           "utf8",
         );
+        if (hostMethodSkills(request.methods).length > 0) {
+          const packageRoot = env.AK_PACKAGE_ROOT ?? process.env.AK_PACKAGE_ROOT;
+          if (typeof packageRoot !== "string" || packageRoot === "") {
+            throw new Error("claude method plugin-dir requires AK_PACKAGE_ROOT");
+          }
+          pluginDir = packagedMethodPluginDir(packageRoot);
+          applyMethodPrompt = (prompt) => applyClaudeSkillInvocation(request.methods, prompt);
+        }
       }
 
       const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
@@ -505,6 +527,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               sessionKind,
               cwd: request.cwd,
               ...(gitCommonDir === undefined ? {} : { writableRoots: [gitCommonDir] }),
+              ...(pluginDir === undefined ? {} : { pluginDir }),
             });
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -522,7 +545,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               args,
               cwd: request.cwd,
               env,
-              stdin: prompt,
+              stdin: applyMethodPrompt(prompt),
               ...(abortSignal === undefined ? {} : { signal: abortSignal }),
               ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
               onStdoutLine(line) {

package/src/host-descriptions.ts

@@ -9,13 +9,6 @@
 import type { AcpHostDescription } from "./acp-host/description.ts";
 import type { HeadlessHostDescription } from "./headless-host/description.ts";
 
-/** Grok CLI reads vendor-private compat surfaces unless each is disabled by name. */
-const PRIVATE_COMPAT_ENV = Object.fromEntries(
-  ["CLAUDE", "CURSOR", "CODEX"].flatMap((vendor) =>
-    ["SKILLS", "RULES", "AGENTS", "MCPS", "HOOKS", "SESSIONS"].map((kind) =>
-      [`GROK_${vendor}_${kind}_ENABLED`, "false"] as const)),
-);
-
 export const DEFAULT_ROLE_TURN_HOST = "pi" as const;
 
 export type HostFamily = "acp" | "headless";
@@ -32,11 +25,6 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
     modelPassing: "argv",
     boundResume: "session/load",
     sessionBindingFile: "grok-acp-session.json",
-    childEnv: Object.freeze({
-      ...PRIVATE_COMPAT_ENV,
-      GROK_MEMORY: "0",
-      GROK_SUBAGENTS: "0",
-    }),
   }),
   /**
    * Operator home `~/.hermes`, native session/load resume, `acp` subcommand.
@@ -55,7 +43,6 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
     modelPassing: "set_model",
     boundResume: "session/load",
     sessionBindingFile: "hermes-acp-session.json",
-    childEnv: Object.freeze({}),
     seatProfileSoul: Object.freeze({
       flag: "-p",
       namePrefix: "ak-",
@@ -69,12 +56,9 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
  * Headless CLI family (#645 / #646). Claude print-mode is the first row;
  * codex exec (#646) adds another. Protocol-specific argv/parse live in
  * headless-host helpers (#752 per-host impl).
- * Claude fixedArgs: print mode, isolation without `--bare` (OAuth stays), full
- * permissions. stream-json + verbose: live host events for sitian records
- * (#811); result is last line. `--setting-sources` empty = load no
- * user/project/local CLAUDE.md/hooks/skills (role envelope is delivered via
- * `--system-prompt` wholesale replace). `--strict-mcp-config` with no
- * `--mcp-config` drops operator MCP + claude.ai connectors.
+ * Claude fixedArgs: print mode, full permissions. stream-json + verbose: live
+ * host events for sitian records (#811); result is last line. Forced methods
+ * ride `--plugin-dir` (#922); operator skill/setting surfaces stay open.
  */
 export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDescription>> = Object.freeze({
   "claude": Object.freeze({
@@ -87,10 +71,6 @@ export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDes
       // Intermediate assistant/tool/system events require verbose with stream-json.
       "--verbose",
       "--permission-mode", "bypassPermissions",
-      // Empty sources: no user/project/local operator surface (envelope owns materials).
-      "--setting-sources", "",
-      // With adapter-supplied --mcp-config only (AK relay); drops operator + claude.ai MCP.
-      "--strict-mcp-config",
     ]),
     promptFlag: "-p",
     modelFlag: "--model",

package/src/host-native-method.ts

@@ -0,0 +1,67 @@
+/** #922 host-native packaged method delivery. */
+import { lstat, mkdir, readlink, realpath, symlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import type { MethodBinding } from "./host-contracts.ts";
+
+type HostMethodSkill = Readonly<{ name: string }>;
+export const HOST_METHOD_PLUGIN_NAME = "ak-methods" as const;
+export const packagedMethodsDir = (root: string) => join(root, "resources", "methods");
+export const packagedMethodPluginDir = (root: string) => join(root, "dist", "method-host-plugin");
+
+export function hostMethodSkills(methods: readonly MethodBinding[]): readonly HostMethodSkill[] {
+  return Object.freeze(methods.flatMap((method) => {
+    if (method.kind !== "skill") return [];
+    const name = basename(dirname(method.path));
+    return name ? [Object.freeze({ name })] : [];
+  }));
+}
+
+const alreadyPrefixed = (prompt: string, token: string) => {
+  const text = prompt.trimStart();
+  return text === token || text.startsWith(`${token} `) || text.startsWith(`${token}\n`);
+};
+
+function prefixMethodInvocation(token: string, prompt: string): string {
+  if (alreadyPrefixed(prompt, token)) return prompt;
+  return prompt ? `${token} ${prompt}` : token;
+}
+
+/** Claude's documented plugin Skill invocation syntax. */
+export function applyClaudeSkillInvocation(methods: readonly MethodBinding[], prompt: string): string {
+  const skills = hostMethodSkills(methods);
+  if (skills.length !== 1) return prompt;
+  return prefixMethodInvocation(`/${HOST_METHOD_PLUGIN_NAME}:${skills[0]!.name}`, prompt);
+}
+
+/** Codex's documented explicit Skill invocation syntax. */
+export function applyCodexSkillInvocation(methods: readonly MethodBinding[], prompt: string): string {
+  return hostMethodSkills(methods).reduceRight(
+    (invocation, skill) => prefixMethodInvocation(`$${skill.name}`, invocation),
+    prompt,
+  );
+}
+
+/** Install the documented project Skill catalog once and leave it in place. */
+export async function installWorkspaceMethodSkills(cwd: string, packageRoot: string): Promise<void> {
+  const target = await realpath(packagedMethodsDir(packageRoot));
+  const link = join(cwd, ".agents", "skills");
+  try {
+    const stat = await lstat(link);
+    if (!stat.isSymbolicLink() || await realpath(link) !== target) {
+      const detail = stat.isSymbolicLink() ? `symlink to ${await readlink(link)}` : "non-symlink entry";
+      throw new Error(`workspace method catalog conflict at ${link}: ${detail}`);
+    }
+    return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  await mkdir(dirname(link), { recursive: true });
+  try {
+    await symlink(target, link);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    if ((await realpath(link).catch(() => "")) !== target) {
+      throw new Error(`workspace method catalog conflict at ${link}`);
+    }
+  }
+}

package/src/ledger-session-read.ts

@@ -40,8 +40,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  * One physical JSONL line as the single kernel saw it.
  * `row` present = syntactically complete session object at that 1-based line.
  * `error` present = the line is complete but unreadable as a session object;
- * `raw` carries its original bytes so a reader that must keep going (起居录
- * projection, ADR 0075 `unparsable-line-to-diarist`) can hand the line back
+ * `raw` carries its original bytes so readers can preserve source evidence
  * instead of inventing content. The unfinished final fragment at EOF is not a
  * line — live tail is honest absence, never a bad line.
  */

package/src/role-envelope.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { createServer, type Server, type Socket } from "node:net";
-import { basename, dirname, join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -13,15 +13,14 @@ import { requireGatekeeperPass } from "./gatekeeper-pass-envelope.ts";
 import type {
   HostContext,
   HostEventRegistration,
-  HostSkillExpansionEvidence,
   HostToolDefinition,
   RoleEnvelopeHost,
   RoleHost,
   RoleTurnKnownFailure,
   RoleTurnRequest,
 } from "./host-contracts.ts";
+import { hostMethodSkills, installWorkspaceMethodSkills } from "./host-native-method.ts";
 import { packagedRoleOutputTool } from "./packaged-role-registry.ts";
-import { stripSkillFrontmatter } from "./package-resources/method-skill.ts";
 import {
   createRoleRuntimeExtension,
   type RoleRuntimeDependencies,
@@ -44,30 +43,6 @@ type RpcRequest = { readonly id: number; readonly token: string; readonly method
 type ToolCallParams = { readonly name?: unknown; readonly arguments?: unknown };
 type ContentPart = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
 
-/**
- * Build host-side Skill expansion evidence from pre-read RoleTurnRequest.methods.
- * Non-pi hosts never parse Pi `/skill:` syntax (ADR 0082: pi is one adapter with
- * no privilege; Pi-only seams stay inside the pi adapter);
- * a single bound method treats the plain prompt as the preserved user message.
- * Pi-native slash forms stay inside `src/pi/` only.
- */
-export function buildSkillExpansion(
-  methodSkills: ReadonlyMap<string, { readonly path: string; readonly body: string }>,
-  prompt: string,
-): HostSkillExpansionEvidence | undefined {
-  if (methodSkills.size !== 1) return undefined;
-  const entry = methodSkills.entries().next().value;
-  if (entry === undefined) return undefined;
-  const [name, method] = entry;
-  return Object.freeze({
-    name,
-    location: method.path,
-    content: method.body,
-    // Non-pi typed chain keeps original task bytes (ticket #822 r3); no consumer trim.
-    userMessage: prompt,
-  });
-}
-
 async function listen(server: Server, path: string): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     server.once("error", reject);
@@ -129,7 +104,6 @@ export async function prepareRoleEnvelope(options: {
   const customEntries: Array<{ customType: string; data: unknown }> = [];
   /** In-memory turn books for role lifecycle and audit subjects. */
   const sessionEntries: Array<Record<string, unknown>> = [];
-  const methodSkills = new Map<string, { path: string; body: string }>();
   let preferredTools: string[] = [];
   let rejection:
     | { readonly code: string; readonly toolCallIds: readonly string[]; readonly message: string }
@@ -140,14 +114,6 @@ export async function prepareRoleEnvelope(options: {
   const runId = request.runDirectory.split("/").filter(Boolean).at(-1) ?? randomUUID();
   await mkdir(request.runDirectory, { recursive: true });
 
-  // Canonical Skill expansion consumes RoleTurnRequest.methods (typed true source).
-  for (const method of request.methods) {
-    if (method.kind !== "skill") continue;
-    const name = basename(dirname(method.path));
-    const raw = await readFile(method.path, "utf8");
-    methodSkills.set(name, { path: method.path, body: stripSkillFrontmatter(raw).trim() });
-  }
-
   // Durable principal file for isAvailable / resumable settlement (public-cli).
   // #617 DK-4: header layout only — never host conversation/tool writeback into Pi JSONL.
   let sessionFile = options.sessionFile ?? join(request.runDirectory, "session", "session.jsonl");
@@ -219,9 +185,8 @@ export async function prepareRoleEnvelope(options: {
       // #836 删 1/A4.5: do not arm closeRound retry with「终局交卷并非本轮唯一工具调用」.
     },
     capabilities: {
-      skillExpansion(prompt): HostSkillExpansionEvidence | undefined {
-        return buildSkillExpansion(methodSkills, prompt);
-      },
+      // #922: native loaders own expansion; package does not pre-read bodies (ADR 0032).
+      skillExpansion() { return undefined; },
     },
     registerFlag(name, definition) { if (!flags.has(name) && definition.default !== undefined) flags.set(name, definition.default); },
     getFlag(name) { return flags.get(name); },
@@ -625,14 +590,10 @@ export async function prepareRoleEnvelope(options: {
         message: { role: "user", content: prompt },
       });
     }
-    // Method notes only here — role before_agent_start injects soul once.
-    // Preloading session materials duplicated soul under the role tag (#632).
-    // #879: case-dossier owner reads runDirectory from this turn's HostContext.
-
-    const methodPrompt = (await Promise.all(request.methods.map(({ path }) => readFile(path, "utf8")))).join("\n\n");
+    // Soul/materials only — forced methods use host-native loaders (#922/#632/#879).
     const promptResults = await emit("before_agent_start", {
       prompt,
-      systemPrompt: methodPrompt,
+      systemPrompt: "",
       systemPromptOptions: {},
     });
     const systemPromptParts = promptResults.flatMap((value) => {
@@ -640,7 +601,7 @@ export async function prepareRoleEnvelope(options: {
       if (!("systemPrompt" in value) || typeof value.systemPrompt !== "string") return [];
       return [value.systemPrompt];
     });
-    const systemPromptBody = systemPromptParts.length > 0 ? systemPromptParts.join("\n\n") : methodPrompt;
+    const systemPromptBody = systemPromptParts.join("\n\n");
     // Typed reading materials from agent-start handlers (incl. single shared
     // case-dossier owner). Folded into provider-visible systemPrompt at send.
     const readingMaterials: unknown[] = [];
@@ -656,6 +617,15 @@ export async function prepareRoleEnvelope(options: {
       throw new Error(`terminating tool not registered after activation: ${terminatingToolName}`);
     }
     const jsonSchema = terminatingToolJsonSchema(terminating.parameters);
+
+    if (request.host === "codex" && hostMethodSkills(request.methods).length > 0) {
+      const packageRoot = options.dependencies.packageRoot;
+      if (typeof packageRoot !== "string" || packageRoot === "") {
+        throw new Error("codex project Skill catalog requires packageRoot");
+      }
+      await installWorkspaceMethodSkills(request.cwd, packageRoot);
+    }
+
     return {
       mcpServers: [{
         name: `ak-${request.activation.role}`,

package/src/role-runtime-dependencies.ts

@@ -10,8 +10,15 @@ import { loadNavigatorWorkContext } from "./navigator-work-context.ts";
 import { loadNotarySourceRunLocator } from "./notary-source-run.ts";
 import { loadPackagedCanonicalSkillBinding } from "./package-resources/method-skill-binding.ts";
 import { formatNavigatorRoleHelp, type RoleRuntimeDependencies } from "./role-runtime.ts";
-import { loadAuditorSoulFromSubjectInput } from "./auditor-soul.ts";
-import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "./session-opening-materials.ts";
+import {
+  loadAuditorReferenceMaterialsFromSubjectInput,
+  loadAuditorSoulFromSubjectInput,
+} from "./auditor-soul.ts";
+import {
+  loadGatekeeperSessionMaterials,
+  loadMainRoleReferenceMaterials,
+  loadMainRoleSessionMaterials,
+} from "./session-opening-materials.ts";
 
 const navigatorRoutePlaybookPath = fileURLToPath(
   new URL("../resources/navigator-route-playbook.md", import.meta.url),
@@ -20,12 +27,20 @@ const collectorHandbookSeedPath = fileURLToPath(
   new URL("../resources/collector-bot-handbook.md", import.meta.url),
 );
 
+/** Single packaged source for reference materials across production composition roots. */
+export function loadPackagedRoleReferenceMaterials(role: Parameters<NonNullable<RoleRuntimeDependencies["loadRoleReferenceMaterials"]>>[0]): Promise<string> {
+  return role === "auditor"
+    ? loadAuditorReferenceMaterialsFromSubjectInput()
+    : loadMainRoleReferenceMaterials(role);
+}
+
 /** Host-neutral packaged role runtime deps for the parent-process envelope. */
 export function createRoleRuntimeDependencies(packageRoot: string): RoleRuntimeDependencies {
   const doctorAuditor = createPiDoctorAuditor();
   const navigatorSessionFactory = createNativeNavigatorSessionFactory();
   return {
     packageRoot,
+    loadRoleReferenceMaterials: loadPackagedRoleReferenceMaterials,
     loadJudgeSoul: () => loadMainRoleSessionMaterials("judge"),
     loadFixerSoul: () => loadMainRoleSessionMaterials("fixer"),
     loadFixPacket: (path) => readFile(path, "utf8"),