@remnic/core 9.65.3 → 9.65.5

package/src/cli/skills-commands.ts

@@ -0,0 +1,150 @@
+/**
+ * Skill bundle export / import commands (issue #2369) — registered as
+ * `remnic export skills` and `remnic import skills <dir>`.
+ *
+ * Lives outside cli.ts (which is at its structural ceiling) and mirrors the
+ * registerMeetingsCommands seam: one registrar, no behavior of its own beyond
+ * option parsing and rendering. All projection, path safety, and persistence
+ * live in `procedural/skill-projection.ts` + `procedural/skill-io.ts`, so the
+ * CLI and the Codex materializer share one contract.
+ */
+
+import type { CliCommand } from "../cli.js";
+import type { Orchestrator } from "../orchestrator.js";
+import {
+  exportSkillBundles,
+  persistImportedSkills,
+  readSkillBundlesFromDir,
+} from "../procedural/skill-io.js";
+import { projectProceduresToSkills } from "../procedural/skill-projection.js";
+import { BUILTIN_SKILLS } from "../skills-registry.js";
+import { expandTildePath } from "../utils/path.js";
+
+/**
+ * Parse `--max-skills`. Rejects non-integers and negatives rather than
+ * silently defaulting (Review Prevention Checklist §1, §39); `0` is honored as
+ * the documented disable value (§33).
+ */
+function parseMaxSkills(raw: unknown, fallback: number): number {
+  if (raw === undefined || raw === null || raw === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`Invalid --max-skills '${String(raw)}'. Expected a non-negative integer (0 exports nothing).`);
+  }
+  return value;
+}
+
+export function registerSkillsCommands(
+  exportCmd: CliCommand,
+  importCmd: CliCommand,
+  orchestrator: Orchestrator,
+): void {
+  exportCmd
+    .command("skills")
+    .description(
+      "Export active procedure memories as portable skills/<slug>/SKILL.md bundles (issue #2369). Read-only with respect to memory.",
+    )
+    .option("--out <dir>", "Output directory (e.g. a host skills dir or a git repo)")
+    .option("--max-skills <n>", "Cap on exported bundles (0 exports none; default from config)")
+    .option("--namespace <ns>", "Namespace to export (default: config defaultNamespace)", "")
+    .action(async (...args: unknown[]) => {
+      const options = (args[0] ?? {}) as Record<string, unknown>;
+      const out = options.out ? String(options.out) : "";
+      if (!out) {
+        console.error("Missing --out. Example: remnic export skills --out ./exported-skills");
+        process.exitCode = 1;
+        return;
+      }
+      if (orchestrator.config.procedural.enabled !== true) {
+        console.error(
+          "procedural memory is disabled (procedural.enabled=false); there are no procedure memories to export.",
+        );
+        process.exitCode = 1;
+        return;
+      }
+      let maxSkills: number;
+      try {
+        maxSkills = parseMaxSkills(options.maxSkills, orchestrator.config.procedural.skillProjection.maxSkills);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return;
+      }
+
+      const namespace = options.namespace ? String(options.namespace) : "";
+      const storage = await orchestrator.getStorageForNamespace(namespace || undefined);
+      const bundles = projectProceduresToSkills(await storage.readAllMemories(), {
+        maxSkills,
+        reservedSlugs: BUILTIN_SKILLS.map((skill) => skill.slug),
+      });
+      const result = await exportSkillBundles({ bundles, outDir: expandTildePath(out) });
+      console.log(`Exported ${result.slugs.length} skill bundle(s) to ${result.outDir}`);
+      for (const slug of result.slugs) {
+        console.log(`  ${slug}/SKILL.md`);
+      }
+      console.log("OK");
+    });
+
+  importCmd
+    .command("skills <dir>")
+    .description(
+      "Import skills/<slug>/SKILL.md bundles as pending_review procedure memories (issue #2369). Never executes bundle scripts.",
+    )
+    .option("--namespace <ns>", "Namespace to import into (default: config defaultNamespace)", "")
+    .action(async (...args: unknown[]) => {
+      const dir = args[0] ? String(args[0]) : "";
+      const options = (args[1] ?? {}) as Record<string, unknown>;
+      if (!dir) {
+        console.error("Usage: remnic import skills <dir>");
+        process.exitCode = 1;
+        return;
+      }
+      if (orchestrator.config.procedural.enabled !== true) {
+        console.error(
+          "procedural memory is disabled (procedural.enabled=false); enable it before importing procedures.",
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      let read;
+      try {
+        read = await readSkillBundlesFromDir(expandTildePath(dir));
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return;
+      }
+      for (const skip of read.skipped) {
+        console.log(`Skipped ${skip.entry}: ${skip.reason}`);
+      }
+      if (read.bundles.length === 0) {
+        console.log("No SKILL.md bundles found.");
+        console.log("OK");
+        return;
+      }
+
+      const namespace = options.namespace ? String(options.namespace) : "";
+      const storage = await orchestrator.getStorageForNamespace(namespace || undefined);
+      const { imported, rejected } = await persistImportedSkills({ storage, bundles: read.bundles });
+
+      // Direct writes bypass extraction, so the search index needs an explicit
+      // refresh or imported procedures stay undiscoverable (§31).
+      await orchestrator.qmd.probe();
+      if (orchestrator.qmd.isAvailable()) {
+        await orchestrator.qmd.update();
+      } else {
+        console.log(`QMD unavailable in this process; skipped reindex. Status: ${orchestrator.qmd.debugStatus()}`);
+      }
+
+      console.log(`Imported ${imported.length} procedure(s) as pending_review (promote after review).`);
+      for (const record of imported) {
+        const resources = record.hasUnimportedResources ? " [has unimported resources]" : "";
+        console.log(`  ${record.slug}: ${record.steps} step(s)${resources}`);
+      }
+      for (const reject of rejected) {
+        console.log(`  ${reject.slug}: ${reject.reason}`);
+      }
+      console.log("OK");
+    });
+}

package/src/cli.ts

@@ -16,6 +16,7 @@ import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerMeetingsCommands } from "./cli/meetings-commands.js";
 import { registerOkfCommands } from "./cli/okf-commands.js";
+import { registerSkillsCommands } from "./cli/skills-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
 import { registerCreationLedgerCommands } from "./cli/creation-ledger-commands.js";
 import type {
@@ -4316,7 +4317,7 @@ export function registerCli(
           }
         });
 
-      cmd
+      const exportCmd = cmd
         .command("export")
         .description("Export Remnic memory to JSON, Markdown bundle, or SQLite")
         .option("--format <format>", "Export format: json|md|sqlite", "json")
@@ -4368,7 +4369,7 @@ export function registerCli(
           console.log("OK");
         });
 
-      cmd
+      const importCmd = cmd
         .command("import")
         .description("Import Remnic memory from JSON bundle, Markdown bundle, or SQLite")
         .option("--from <path>", "Import source path (dir or file)")
@@ -4424,6 +4425,7 @@ export function registerCli(
           }
           console.log("OK");
         });
+      registerSkillsCommands(exportCmd, importCmd, orchestrator);
 
       cmd
         .command("backup")

package/src/config.ts

@@ -43,6 +43,7 @@ import { parseExtractionLivenessConfig } from "./extraction-liveness.js";
 import { parseReplicaPeersConfig } from "./replica-peers-config.js";
 import { parseDependencyPropagationConfig } from "./dependency-propagation-config.js";
 import { parseProceduralMaintenanceConfig } from "./procedural/maintenance-config.js";
+import { parseSkillProjectionConfig } from "./procedural/skill-projection.js";
 import { parseDriftDetectionConfig } from "./preferences/drift-config.js";
 import {
   parseContradictionLocalizationConfig,
@@ -1128,8 +1129,8 @@ export function parseConfig(
       ? Math.min(10, Math.max(1, Math.floor(recallMaxCoerced)))
       : 2;
   const maintenance = parseProceduralMaintenanceConfig(rawProcedural.maintenance);
-  // Default-on procedural memory (issue #567 PR 4/5). Explicit false-ish
-  // values stay off. Unknown values throw.
+  const skillProjection = parseSkillProjectionConfig(rawProcedural.skillProjection);
+  // Default-on procedural memory (issue #567 PR 4/5). Explicit false-ish values stay off. Unknown values throw.
   const rawEnabledValue = rawProcedural.enabled;
   let proceduralEnabled: boolean;
   if (rawEnabledValue === undefined) {
@@ -1154,6 +1155,7 @@ export function parseConfig(
     lookbackDays,
     proceduralMiningCronAutoRegister: coerceBool(rawProcedural.proceduralMiningCronAutoRegister) === true,
     recallMaxProcedures,
+    skillProjection,
   };
   const wearables = parseWearablesConfig(cfg.wearables);
   const { activity, meetings, provenance } = parseCaptureCompanionConfigs(cfg);

package/src/connectors/codex-materialize-runner.ts

@@ -14,6 +14,8 @@ import { existsSync } from "node:fs";
 import { log } from "../logger.js";
 import { resolveNamespaceChildRoot } from "../namespaces/path.js";
 import { isSafeRouteNamespace } from "../routing/engine.js";
+import { projectProceduresToSkills } from "../procedural/skill-projection.js";
+import { BUILTIN_SKILLS } from "../skills-registry.js";
 import { StorageManager } from "../storage.js";
 import { excludeSupportPassportPrivateMemories } from "../support-passport/card-projection.js";
 import type { PluginConfig, MemoryFile } from "../types.js";
@@ -109,6 +111,19 @@ export async function runCodexMaterialize(
   }
   memories = excludeSupportPassportPrivateMemories(memories);
 
+  // Skill projection (issue #2369). Gated on `procedural.enabled` AND
+  // `procedural.skillProjection.enabled`; `maxSkills: 0` disables it too.
+  // Passing `undefined` leaves `skills/` untouched, so a disabled gate never
+  // deletes a folder the user curated.
+  const skillProjection = cfg.procedural?.skillProjection;
+  const skills =
+    cfg.procedural?.enabled === true && skillProjection?.enabled === true
+      ? projectProceduresToSkills(memories, {
+          maxSkills: skillProjection.maxSkills,
+          reservedSlugs: BUILTIN_SKILLS.map((skill) => skill.slug),
+        })
+      : undefined;
+
   // Intentionally NOT catching here: per the JSDoc contract above,
   // schema-validation and I/O errors from `materializeForNamespace` must
   // surface to callers so they can exit non-zero (CLI) or log + recover
@@ -122,6 +137,7 @@ export async function runCodexMaterialize(
     maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,
     rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,
     rolloutSummaries: options.rolloutSummaries,
+    skills,
     now: options.now,
   });
   if (options.reason) {

package/src/connectors/codex-materialize-skills.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Skill-bundle section of the Codex materializer (issue #2369).
+ *
+ * Synthetic fixtures only — never real user data.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  ensureSentinel,
+  materializeForNamespace,
+  SENTINEL_FILE,
+} from "./codex-materialize.js";
+import { parseProcedureStepsFromBody } from "../procedural/procedure-types.js";
+import { parseSkillBundle, projectProceduresToSkills } from "../procedural/skill-projection.js";
+import type { MemoryFile } from "../types.js";
+
+function makeProcedure(id: string, title: string, updated = "2026-08-18T00:00:00Z"): MemoryFile {
+  return {
+    path: `/tmp/remnic-test/procedures/${id}.md`,
+    frontmatter: {
+      id,
+      category: "procedure",
+      created: "2026-08-18T00:00:00Z",
+      updated,
+      source: "procedure-miner",
+      confidence: 0.8,
+      confidenceTier: "implied",
+      tags: [],
+    } as MemoryFile["frontmatter"],
+    content: [title, "", "## Step 1", "", "Read the plan.", "", "## Step 2", "", "Apply the change.", ""].join("\n"),
+  };
+}
+
+function makeTempCodexHome(): { root: string; memoriesDir: string } {
+  const root = mkdtempSync(path.join(os.tmpdir(), "codex-materialize-skills-"));
+  const memoriesDir = path.join(root, "memories");
+  mkdirSync(memoriesDir, { recursive: true });
+  return { root, memoriesDir };
+}
+
+test("writes skills/<slug>/SKILL.md whose body round-trips to the same steps", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const memories = [makeProcedure("procedure-1", "Ship a focused change")];
+    const skills = projectProceduresToSkills(memories);
+
+    const result = materializeForNamespace("synthetic-ns", { memories, codexHome: root, skills });
+    assert.equal(result.wrote, true);
+    assert.ok(result.filesWritten.includes(path.join("skills", "ship-a-focused-change", "SKILL.md")));
+
+    const skillPath = path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md");
+    const parsed = parseSkillBundle(readFileSync(skillPath, "utf-8"), "ship-a-focused-change");
+    assert.ok(parsed);
+    assert.deepEqual(parsed.steps, parseProcedureStepsFromBody(memories[0].content));
+    assert.equal(parsed.provenance.memoryId, "procedure-1");
+
+    const sentinel = JSON.parse(readFileSync(path.join(memoriesDir, SENTINEL_FILE), "utf-8")) as {
+      projected_skills?: string[];
+    };
+    assert.deepEqual(sentinel.projected_skills, ["ship-a-focused-change"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("re-running with unchanged procedures is a hash no-op", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const memories = [makeProcedure("procedure-1", "Ship a focused change")];
+    const skills = projectProceduresToSkills(memories);
+
+    const first = materializeForNamespace("synthetic-ns", { memories, codexHome: root, skills });
+    assert.equal(first.wrote, true);
+    const second = materializeForNamespace("synthetic-ns", { memories, codexHome: root, skills });
+    assert.equal(second.wrote, false);
+    assert.equal(second.skippedIdempotent, true);
+    assert.deepEqual(second.filesWritten, []);
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("retiring a procedure removes its projected folder and leaves hand-created folders alone", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const kept = makeProcedure("procedure-1", "Ship a focused change", "2026-08-18T02:00:00Z");
+    const retired = makeProcedure("procedure-2", "Rotate the token", "2026-08-18T01:00:00Z");
+
+    materializeForNamespace("synthetic-ns", {
+      memories: [kept, retired],
+      codexHome: root,
+      skills: projectProceduresToSkills([kept, retired]),
+    });
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "rotate-the-token", "SKILL.md")));
+
+    // A skill folder the user curated by hand — never in projected_skills.
+    const handMade = path.join(memoriesDir, "skills", "hand-authored");
+    mkdirSync(handMade, { recursive: true });
+    writeFileSync(path.join(handMade, "SKILL.md"), "---\nname: hand-authored\n---\n\nMine.\n");
+
+    materializeForNamespace("synthetic-ns", {
+      memories: [kept],
+      codexHome: root,
+      skills: projectProceduresToSkills([kept]),
+    });
+    assert.equal(existsSync(path.join(memoriesDir, "skills", "rotate-the-token")), false);
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md")));
+    assert.ok(existsSync(path.join(handMade, "SKILL.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("omitting the skills option leaves an existing skills/ directory untouched", () => {
+  const { root, memoriesDir } = makeTempCodexHome();
+  try {
+    ensureSentinel(memoriesDir, "synthetic-ns", new Date("2026-08-18T00:00:00Z"));
+    const kept = makeProcedure("procedure-1", "Ship a focused change");
+    materializeForNamespace("synthetic-ns", {
+      memories: [kept],
+      codexHome: root,
+      skills: projectProceduresToSkills([kept]),
+    });
+
+    // Gate turned off on a later run: `skills` omitted entirely.
+    const later = makeProcedure("procedure-1", "Ship a focused change", "2026-08-19T00:00:00Z");
+    materializeForNamespace("synthetic-ns", { memories: [later], codexHome: root });
+    assert.ok(existsSync(path.join(memoriesDir, "skills", "ship-a-focused-change", "SKILL.md")));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/connectors/codex-materialize.ts

@@ -48,7 +48,18 @@ import { log } from "../logger.js";
 import { readEnvVar, resolveHomeDir } from "../runtime/env.js";
 import type { MemoryFile } from "../types.js";
 import { estimateTokenCount } from "../token-estimate.js";
+import type { SkillBundle } from "../procedural/skill-projection.js";
 import { expandTildePath } from "../utils/path.js";
+import { ensureSafeManagedSubdir } from "./materialize-paths.js";
+import {
+  commitSkillFiles,
+  planSkillFiles,
+  retiredSkillsAlreadyRemoved,
+  skillFilePath,
+  skillFileRelPath,
+  stageSkillFiles,
+  type SkillFile,
+} from "./materialize-skills.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -67,6 +78,13 @@ export interface MaterializeOptions {
   rolloutRetentionDays?: number;
   /** Per-session rollout summaries to render. */
   rolloutSummaries?: RolloutSummaryInput[];
+  /**
+   * Projected procedural skill bundles (issue #2369). `undefined` leaves
+   * `skills/` untouched; an array — even an empty one — is authoritative for
+   * the slugs Remnic projected, so retired procedures get their folder
+   * removed. Folders this materializer never projected are never touched.
+   */
+  skills?: SkillBundle[];
   /** Current time, injected for deterministic tests. */
   now?: Date;
   /** Optional logger override for tests. */
@@ -115,6 +133,12 @@ interface SentinelFile {
   namespace: string;
   updated_at: string;
   content_hash: string;
+  /**
+   * Slugs under `skills/` that THIS materializer projected (issue #2369).
+   * Absent on sentinels written before skill projection existed, which reads
+   * as "we have projected nothing", so hand-created folders stay untouched.
+   */
+  projected_skills?: string[];
 }
 
 // ─── Constants ─────────────────────────────────────────────────────────────
@@ -297,6 +321,10 @@ export function materializeForNamespace(
   const destRolloutsDir = path.join(memoriesDir, ROLLOUT_SUBDIR);
   const retainedRolloutNames = new Set(rolloutFiles.map((r) => r.name));
 
+  // Skill bundles (issue #2369) — planning, ownership, and disk layout live in
+  // materialize-skills.ts.
+  const skillPlan = planSkillFiles(options.skills, existingSentinel.projected_skills ?? []);
+
   // ── Idempotence check ──────────────────────────────────────────────────
   const hash = computeContentHash({
     namespace,
@@ -304,6 +332,7 @@ export function materializeForNamespace(
     memoryMd,
     rawMemories,
     rolloutFiles,
+    skillFiles: skillPlan.files,
   });
 
   if (existingSentinel.content_hash === hash) {
@@ -318,15 +347,17 @@ export function materializeForNamespace(
       path.join(memoriesDir, "MEMORY.md"),
       path.join(memoriesDir, "raw_memories.md"),
       ...rolloutFiles.map((r) => path.join(memoriesDir, ROLLOUT_SUBDIR, r.name)),
+      ...skillPlan.files.map((s) => skillFilePath(memoriesDir, s.slug)),
     ];
     const allPresent = requiredFiles.every((f) => fs.existsSync(f));
     const rolloutsClean =
       !rolloutsSupplied ||
       rolloutDirectoryMatchesRetainedSet(
-        ensureSafeRolloutsDir(memoriesDir, destRolloutsDir),
+        ensureSafeManagedSubdir(memoriesDir, destRolloutsDir, ROLLOUT_SUBDIR),
         retainedRolloutNames,
       );
-    if (allPresent && rolloutsClean) {
+    const skillsClean = retiredSkillsAlreadyRemoved(memoriesDir, skillPlan.retiredSlugs);
+    if (allPresent && rolloutsClean && skillsClean) {
       logger.debug?.(`no-op materialization for namespace=${namespace} (hash unchanged)`);
       return {
         namespace,
@@ -403,6 +434,11 @@ export function materializeForNamespace(
     filesWritten.push(path.join(ROLLOUT_SUBDIR, rollout.name));
   }
 
+  stageSkillFiles(tmpDir, skillPlan.files);
+  for (const skill of skillPlan.files) {
+    filesWritten.push(skillFileRelPath(skill.slug));
+  }
+
   // Rename into place. Atomic per-file is sufficient — Codex reads each file
   // independently and tolerates an inconsistent in-between snapshot across
   // files for the duration of the rename loop (milliseconds).
@@ -412,7 +448,7 @@ export function materializeForNamespace(
     fs.renameSync(src, dest);
   }
 
-  const safeDestRolloutsDir = ensureSafeRolloutsDir(memoriesDir, destRolloutsDir);
+  const safeDestRolloutsDir = ensureSafeManagedSubdir(memoriesDir, destRolloutsDir, ROLLOUT_SUBDIR);
   // Only garbage-collect rollout files when the caller actually supplied a
   // `rolloutSummaries` array — otherwise we'd wipe legitimately
   // user/Codex-created recap files on every session-end run, since those
@@ -447,12 +483,17 @@ export function materializeForNamespace(
     fs.renameSync(src, dest);
   }
 
+  commitSkillFiles(memoriesDir, tmpDir, skillPlan);
+
   // Update sentinel last so a crash leaves hash mismatched → next run rewrites.
   const sentinel: SentinelFile = {
     version: MATERIALIZE_VERSION,
     namespace,
     updated_at: now.toISOString(),
     content_hash: hash,
+    projected_skills: skillPlan.supplied
+      ? skillPlan.files.map((s) => s.slug)
+      : (existingSentinel.projected_skills ?? []),
   };
   writeSentinelAtomically(sentinelPath, sentinel);
 
@@ -805,43 +846,6 @@ function rolloutDirectoryMatchesRetainedSet(
   return true;
 }
 
-function isPathInside(parent: string, child: string): boolean {
-  const relative = path.relative(parent, child);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function ensureSafeRolloutsDir(memoriesDir: string, rolloutsDir: string): string {
-  const memoriesReal = fs.realpathSync(memoriesDir);
-
-  try {
-    const stat = fs.lstatSync(rolloutsDir);
-    if (stat.isSymbolicLink()) {
-      throw new Error("is a symbolic link");
-    }
-    if (!stat.isDirectory()) {
-      throw new Error("is not a directory");
-    }
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-      throw new Error(
-        `codex-materialize: unsafe ${ROLLOUT_SUBDIR} directory at ${rolloutsDir}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-    fs.mkdirSync(rolloutsDir, { recursive: true });
-  }
-
-  const rolloutsReal = fs.realpathSync(rolloutsDir);
-  if (!isPathInside(memoriesReal, rolloutsReal)) {
-    throw new Error(
-      `codex-materialize: unsafe ${ROLLOUT_SUBDIR} directory at ${rolloutsDir}: resolves outside ${memoriesDir}`,
-    );
-  }
-
-  return rolloutsDir;
-}
-
 function readSentinel(sentinelPath: string): SentinelFile | null {
   if (!fs.existsSync(sentinelPath)) return null;
   try {
@@ -857,11 +861,18 @@ function readSentinel(sentinelPath: string): SentinelFile | null {
     ) {
       throw new Error("invalid sentinel schema");
     }
+    // A sentinel written before issue #2369 has no `projected_skills`, which
+    // reads as "nothing projected" — so an unrelated skills/ folder written by
+    // a user or another tool is never treated as ours.
+    const projected = Array.isArray(parsed.projected_skills)
+      ? parsed.projected_skills.filter((slug): slug is string => typeof slug === "string")
+      : [];
     return {
       version: parsed.version,
       namespace: parsed.namespace,
       updated_at: parsed.updated_at,
       content_hash: parsed.content_hash,
+      projected_skills: projected,
     };
   } catch (err) {
     throw new Error(
@@ -1040,6 +1051,7 @@ function computeContentHash(input: {
   memoryMd: string;
   rawMemories: string;
   rolloutFiles: Array<{ name: string; body: string }>;
+  skillFiles: Array<{ slug: string; body: string }>;
 }): string {
   const hash = createHash("sha256");
   hash.update(`v${MATERIALIZE_VERSION}\n`);
@@ -1055,6 +1067,12 @@ function computeContentHash(input: {
     hash.update(`\n---rollout:${r.name}---\n`);
     hash.update(r.body);
   }
+  // Sorted by slug so call order cannot flip the hash (§26).
+  const sortedSkills = [...input.skillFiles].sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+  for (const s of sortedSkills) {
+    hash.update(`\n---skill:${s.slug}---\n`);
+    hash.update(s.body);
+  }
   return hash.digest("hex");
 }
 

package/src/connectors/materialize-paths.ts

@@ -0,0 +1,50 @@
+/**
+ * materialize-paths.ts — containment guard for the materializer's managed
+ * sub-directories (`rollout_summaries/`, `skills/`).
+ *
+ * Extracted from codex-materialize.ts so the skills section (issue #2369) and
+ * the rollout section share ONE containment implementation instead of forking
+ * the check (rule 22).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { pathIsInside } from "../utils/path-containment.js";
+
+/**
+ * Resolve a managed sub-directory of `memoriesDir`, creating it when absent,
+ * and refuse a symlinked or escaping target. Returns the (unchanged) path so
+ * callers can use it directly.
+ */
+export function ensureSafeManagedSubdir(memoriesDir: string, subdir: string, label: string): string {
+  const memoriesReal = fs.realpathSync(memoriesDir);
+
+  try {
+    const stat = fs.lstatSync(subdir);
+    if (stat.isSymbolicLink()) {
+      throw new Error("is a symbolic link");
+    }
+    if (!stat.isDirectory()) {
+      throw new Error("is not a directory");
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new Error(
+        `codex-materialize: unsafe ${label} directory at ${subdir}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+    fs.mkdirSync(subdir, { recursive: true });
+  }
+
+  const subdirReal = fs.realpathSync(subdir);
+  if (!pathIsInside(memoriesReal, subdirReal)) {
+    throw new Error(
+      `codex-materialize: unsafe ${label} directory at ${subdir}: resolves outside ${memoriesDir}`,
+    );
+  }
+
+  return path.normalize(subdir);
+}