mirror-mind 0.0.1 → 0.32.1

package/ts/src/frontDoor/tasksImportSyncRoute.ts

@@ -0,0 +1,110 @@
+// Front-door `tasks import|sync|sync-config` write handlers (CV22.DS7.US2
+// slice 3c). The testable core of routing these subcommands to the TS core,
+// mirroring `memory.cli.tasks_cmd`'s `cmd_import`/`cmd_sync`/`cmd_sync_config`.
+
+import { existsSync } from "node:fs";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { listIdentityByLayer } from "#identity/identityRead.ts";
+import { getSyncFile, JOURNEY_LAYER, setSyncFile } from "#journey/journeySyncFile.ts";
+import {
+  importTasksFromJourneyPath,
+  type SyncResult,
+  syncTasksFromFile,
+} from "#tasks/taskImportSync.ts";
+import type { Task } from "#tasks/taskStore.ts";
+import { normalizeProjectPath } from "#util/paths.ts";
+
+/** Journeys to operate on for `tasks import [journey]`: the explicit one, or every known journey (key order). */
+export function resolveImportJourneys(db: Database, explicitJourney: string | null): string[] {
+  if (explicitJourney) return [explicitJourney];
+  return listIdentityByLayer(db, JOURNEY_LAYER).map((row) => row.key);
+}
+
+/** One journey's import result, included in rendering only when it created at least one task. */
+export interface ImportJourneyResult {
+  journey: string;
+  created: Task[];
+}
+
+/**
+ * `tasks import [journey]`: import pending tasks for each resolved journey.
+ * Matches Python's `if created:` filter -- a journey with zero imports never
+ * appears in the render, but still contributes to nothing (not an error).
+ */
+export function applyTasksImport(
+  db: WritableDatabase,
+  explicitJourney: string | null,
+): ImportJourneyResult[] {
+  const journeys = resolveImportJourneys(db, explicitJourney);
+  const results: ImportJourneyResult[] = [];
+  for (const journey of journeys) {
+    const created = importTasksFromJourneyPath(db, journey);
+    if (created.length > 0) {
+      results.push({ journey, created });
+    }
+  }
+  return results;
+}
+
+/** Journeys to operate on for `tasks sync [journey]`: the explicit one (regardless of sync-file config), or every journey WITH a sync file configured. */
+export function resolveSyncJourneys(db: Database, explicitJourney: string | null): string[] {
+  if (explicitJourney) return [explicitJourney];
+  return listIdentityByLayer(db, JOURNEY_LAYER)
+    .map((row) => row.key)
+    .filter((key) => getSyncFile(db, key) !== null);
+}
+
+export type SyncJourneyOutcome =
+  | { kind: "no_sync_file"; journey: string }
+  | { kind: "synced"; journey: string; syncFile: string; result: SyncResult }
+  | { kind: "error"; journey: string; message: string };
+
+/**
+ * `tasks sync`'s per-journey step: re-checks the sync file (an explicit
+ * journey may have none configured -- Python's own per-iteration check, not a
+ * whole-command precondition), then syncs, catching ANY error the same way
+ * Python's two `except` clauses collapse to the identical print.
+ */
+export function applyTasksSyncForJourney(
+  db: WritableDatabase,
+  journey: string,
+): SyncJourneyOutcome {
+  const syncFile = getSyncFile(db, journey);
+  if (!syncFile) return { kind: "no_sync_file", journey };
+  try {
+    const result = syncTasksFromFile(db, journey);
+    return { kind: "synced", journey, syncFile, result };
+  } catch (error) {
+    return {
+      kind: "error",
+      journey,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export interface SyncConfigOutcome {
+  journey: string;
+  resolvedPath: string;
+  fileExisted: boolean;
+}
+
+/**
+ * `tasks sync-config <journey> <file>`: normalize the path (the same
+ * expanduser+resolve `normalizeProjectPath` already ports for `journey
+ * set-path`), record whether it currently exists (a warning, not a failure),
+ * and configure it. Throws `JourneyNotFoundError` for an unknown journey --
+ * Python's `cmd_sync_config` does not catch this either (see
+ * `journeySyncFile.ts`'s module doc).
+ */
+export function applyTasksSyncConfig(
+  db: WritableDatabase,
+  journey: string,
+  rawFilePath: string,
+  nowIso: string,
+): SyncConfigOutcome {
+  const resolvedPath = normalizeProjectPath(rawFilePath);
+  const fileExisted = existsSync(resolvedPath);
+  setSyncFile(db, journey, resolvedPath, nowIso);
+  return { journey, resolvedPath, fileExisted };
+}

package/ts/src/frontDoor/tasksWriteRoute.ts

@@ -0,0 +1,101 @@
+// Front-door `tasks add|done|doing|block|delete` write handlers (CV22.DS7.US2
+// slice 3a). The testable core of routing these subcommands to the TS core:
+// each function takes an already-open `WritableDatabase` plus injected
+// id/now (the DS4 determinism-injection idiom) and returns a result the
+// `render/tasks.ts` module turns into Python-identical stdout.
+//
+// `tasks import`/`sync`/`sync-config` (which also depend on the journey
+// sync-file/project-path metadata subsystem) and `week plan`/`save` (LLM-gated,
+// reassigned to US5) are NOT here -- see the plan's slice breakdown.
+
+import type { WritableDatabase } from "#db/database.ts";
+import {
+  completeTask,
+  createTask,
+  deleteTaskById,
+  resolveTaskByIdOrPrefix,
+  type Task,
+  updateTaskStatus,
+} from "#tasks/taskStore.ts";
+
+/** Fields accepted by `tasks add`, mirroring the Python CLI's flags. */
+export interface AddTaskParams {
+  title: string;
+  journey?: string | null;
+  due?: string | null;
+  stage?: string | null;
+}
+
+/** `tasks add`: create the task and return it for rendering. */
+export function applyTasksAdd(
+  db: WritableDatabase,
+  params: AddTaskParams,
+  id: string,
+  nowIso: string,
+): Task {
+  return createTask(
+    db,
+    { title: params.title, journey: params.journey, dueDate: params.due, stage: params.stage },
+    id,
+    nowIso,
+  );
+}
+
+/** The Python-visible status a `done|doing|block` command applies. */
+export type TaskStatusTarget = "doing" | "blocked" | "done";
+
+export type StatusChangeOutcome =
+  | { kind: "changed"; task: Task; newStatus: TaskStatusTarget }
+  | { kind: "ambiguous"; idOrPrefix: string; matches: Task[] }
+  | { kind: "not_found"; idOrPrefix: string };
+
+/**
+ * `tasks done|doing|block`: resolve the id/prefix via the ONE shared resolver,
+ * apply the status change, and report the outcome. `done` completes the task
+ * (status + completed_at); `doing`/`blocked` only change status -- matching
+ * Python's `if new_status == "done": complete_task(...) else: update_task(...)`.
+ */
+export function applyTasksStatusChange(
+  db: WritableDatabase,
+  idOrPrefix: string,
+  newStatus: TaskStatusTarget,
+  nowIso: string,
+): StatusChangeOutcome {
+  const resolved = resolveTaskByIdOrPrefix(db, idOrPrefix);
+  if (resolved.kind === "not_found") return { kind: "not_found", idOrPrefix };
+  if (resolved.kind === "ambiguous") {
+    return { kind: "ambiguous", idOrPrefix, matches: resolved.matches };
+  }
+
+  if (newStatus === "done") {
+    completeTask(db, resolved.task.id, nowIso);
+  } else {
+    updateTaskStatus(db, resolved.task.id, newStatus, nowIso);
+  }
+
+  const task: Task = {
+    ...resolved.task,
+    status: newStatus,
+    updated_at: nowIso,
+    completed_at: newStatus === "done" ? nowIso : resolved.task.completed_at,
+  };
+  return { kind: "changed", task, newStatus };
+}
+
+export type DeleteOutcome =
+  | { kind: "deleted"; task: Task }
+  | { kind: "not_found"; idOrPrefix: string };
+
+/**
+ * `tasks delete`: resolve via the SAME shared resolver as status-change, but
+ * fold "ambiguous" into "not_found" -- Python's `cmd_delete` only branches on
+ * `len(matches) == 1`, treating both zero AND multiple matches as "not found".
+ * This is the deliberate asymmetry the plan calls out; it is expressed here,
+ * in presentation, not inside the shared resolver.
+ */
+export function applyTasksDelete(db: WritableDatabase, idOrPrefix: string): DeleteOutcome {
+  const resolved = resolveTaskByIdOrPrefix(db, idOrPrefix);
+  if (resolved.kind !== "found") return { kind: "not_found", idOrPrefix };
+  deleteTaskById(db, resolved.task.id);
+  return { kind: "deleted", task: resolved.task };
+}

package/ts/src/frontDoor/usage.ts

@@ -0,0 +1,176 @@
+// The front door's own answer for a name it does not know (CV22.DS10.TS5, D2).
+//
+// Until TS5 every such name fell through to Python: an unknown command reached
+// `_dispatch`'s `Unknown command` and its usage block, an unknown subcommand
+// reached argparse, which names the program `__main__.py`. With the fallback
+// gone nobody would own the answer, and an unowned answer is how a surface
+// disappears without anyone deciding to remove it. So TypeScript owns it, in
+// the shapes D2 records:
+//
+//   * top level -- `Unknown command: <name>`, a blank line, and the usage
+//     block, all on stdout, exit 1: `_dispatch`'s shape, the one scripts saw.
+//     No command at all prints the usage block alone, exit 1.
+//   * a family -- argparse's shape: one `usage:` line and one `error:` line on
+//     stderr, exit 2, with the FAMILY as the program name instead of
+//     `__main__.py`. US2 gave `runtime` exactly this shape first; this module
+//     generalizes it, byte-for-byte.
+//   * `-h` / `--help` -- the usage on stdout, exit 0, at either level (the
+//     plateau-2 amendment to D2): help must not become an error just because
+//     the program that used to print it is gone.
+//
+// Seven families answered an unknown subcommand differently in the oracle
+// (inventory F6): a usage line on stdout with exit 1, `Unknown subcommand` with
+// exit 1, or -- `conversation-logger` -- nothing at all with exit 0. They move
+// to the uniform shape deliberately; the table is in the story's inventory.
+
+import { PROGRAM } from "#util/program.ts";
+
+/** The program name the top-level usage prints: `#util/program.ts`, the one place US3 renames. */
+export { PROGRAM };
+
+/**
+ * Every top-level command the front door answers, in the oracle's order, with a
+ * one-line summary. The unknown-command answer prints this; a test proves every
+ * name here routes somewhere other than the unknown-command answer.
+ */
+export const FRONT_DOOR_COMMANDS: ReadonlyArray<readonly [name: string, summary: string]> = [
+  ["init", "Initialize a user home from identity templates"],
+  ["seed", "Seed identity YAML files into the database"],
+  ["identity", "Read and update identity in the database"],
+  ["list", "List personas, journeys, extensions, or all"],
+  ["inspect", "Inspect a persona, an extension, the runtime catalog, or the call ledgers"],
+  ["detect-persona", "Show persona routing matches for a query"],
+  ["extensions", "List, validate, sync, install, or uninstall extensions"],
+  ["ext", "Run a command-skill extension's CLI"],
+  ["mirror", "Mirror Mode: load context, log, deactivate"],
+  ["mode", "Operating mode lifecycle"],
+  ["conversation-logger", "Conversation logging"],
+  ["backup", "Create a zipped backup of the memory database"],
+  ["repair-encoding", "Repair reversible UTF-8 mojibake in user text"],
+  ["journal", "Record a journal entry"],
+  ["journey", "Inspect or update a journey"],
+  ["build", "Builder Mode and the Ariad lifecycle"],
+  ["explore", "Explorer Mode"],
+  ["soul", "Soul Mode"],
+  ["memories", "List or search memories"],
+  ["conversations", "List conversations, or append a message batch"],
+  ["recall", "Load messages from a previous conversation"],
+  ["tasks", "Task management"],
+  ["week", "Weekly planning"],
+  ["journeys", "List journeys with status and stage"],
+  ["consult", "Ask other LLMs through OpenRouter"],
+  ["descriptor", "Generate and list routing descriptors"],
+  ["consolidate", "Scan memories for patterns and manage consolidation proposals"],
+  ["shadow", "Surface and promote shadow-layer observations"],
+  ["mcp", "Run the Mirror MCP server over stdio"],
+  ["runtime", "Runtime status, drift, backups, version, and updates"],
+  ["welcome", "Render the welcome card"],
+];
+
+const NAME_WIDTH = Math.max(...FRONT_DOOR_COMMANDS.map(([name]) => name.length)) + 2;
+
+/** The top-level usage block. */
+export const USAGE = [
+  `Usage: ${PROGRAM} <command> [args]`,
+  "",
+  "Commands:",
+  ...FRONT_DOOR_COMMANDS.map(([name, summary]) => `  ${name.padEnd(NAME_WIDTH)}${summary}`),
+  "",
+].join("\n");
+
+/** What routing hands the front door when a name is not one it answers. */
+export type UsageRequest =
+  | {
+      readonly scope: "top-level";
+      /** The unknown name, or null when no command was given at all. */
+      readonly given: string | null;
+    }
+  | {
+      readonly scope: "family";
+      /** The family as a user types it: `build`, `explore story`. */
+      readonly program: string;
+      /** What the family does answer, from routing's own allowlist. */
+      readonly choices: readonly string[];
+      /** The unrecognized subcommand, or "" when none was given. */
+      readonly given: string;
+    };
+
+export interface UsageAnswer {
+  readonly stream: "stdout" | "stderr";
+  readonly exitCode: number;
+  readonly text: string;
+}
+
+const HELP = new Set(["-h", "--help"]);
+
+/** One family's `usage:` line. */
+export function familyUsageLine(program: string, choices: readonly string[]): string {
+  return `usage: ${program} [-h] {${choices.join(",")}} ...\n`;
+}
+
+/**
+ * argparse's refusal, in the product's vocabulary: the usage line, then one
+ * `error:` line naming what was wrong.
+ */
+export function renderUnknownSubcommand(
+  program: string,
+  choices: readonly string[],
+  given: string,
+): string {
+  const detail =
+    given === ""
+      ? "the following arguments are required: command"
+      : `argument command: invalid choice: '${given}' (choose from ${choices.join(", ")})`;
+  return `${familyUsageLine(program, choices)}${program}: error: ${detail}\n`;
+}
+
+/**
+ * What the front door knows about the machine when it answers bare `mirror`:
+ * whether any source configured a user, and where the config file would be.
+ */
+export interface UsageContext {
+  readonly userConfigured: boolean;
+  readonly configFile: string;
+}
+
+/**
+ * The first seconds after `npm install -g mirror-mind` (CV22.DS10.US3): bare
+ * `mirror` on a machine with no user configured is an orientation, not a
+ * usage dump -- three lines that say what is missing, what to run, and where
+ * the configuration will live. With a user configured, bare `mirror` is the
+ * usage block, as before.
+ */
+export function renderOrientation(configFile: string): string {
+  return [
+    "No user configured yet.",
+    `  Run: ${PROGRAM} init <your-name>`,
+    `  Configuration will live at: ${configFile}`,
+    "",
+  ].join("\n");
+}
+
+/** Render the answer for a request routing could not place. */
+export function answerUsage(request: UsageRequest, context?: UsageContext): UsageAnswer {
+  if (request.scope === "top-level") {
+    if (request.given !== null && HELP.has(request.given)) {
+      return { stream: "stdout", exitCode: 0, text: USAGE };
+    }
+    if (request.given === null && context !== undefined && !context.userConfigured) {
+      return { stream: "stdout", exitCode: 1, text: renderOrientation(context.configFile) };
+    }
+    const unknown = request.given === null ? "" : `Unknown command: ${request.given}\n\n`;
+    return { stream: "stdout", exitCode: 1, text: `${unknown}${USAGE}` };
+  }
+  if (HELP.has(request.given)) {
+    return {
+      stream: "stdout",
+      exitCode: 0,
+      text: familyUsageLine(request.program, request.choices),
+    };
+  }
+  return {
+    stream: "stderr",
+    exitCode: 2,
+    text: renderUnknownSubcommand(request.program, request.choices, request.given),
+  };
+}

package/ts/src/guards/claudePlugin.ts

@@ -0,0 +1,252 @@
+// Generate the canonical Mirror Mind Claude plugin (manifest + skills), and the
+// Claude Code copies of Pi-sourced skills.
+//
+// The Node port of `src/memory/plugins/claude.py` and its wrapper
+// `scripts/build_claude_plugin.py` (CV22.DS10.TS5, slice B).
+//
+// The Zero Python gate assigns the builder to **US3**, on the grounds that US3
+// decides what it builds. But it is a `.py` file, and TS5's done condition is
+// that `git ls-files '*.py'` is empty -- so the file cannot survive this story
+// whoever owns its content. Decision D6 resolves that: the port lands here,
+// byte-identical in output; US3 still owns the shape of what it emits when the
+// npm entry point becomes real.
+//
+// The plugin skills are generated from `.claude/skills/` (the Claude-tuned
+// source), with one exception since CR102. A Pi-sourced skill
+// (`piSourcedSkills.ts`) has one body in every runtime, so this module also
+// generates its `.claude/skills/` copy from `.pi/skills/`, and takes its plugin
+// copy from that generated content rather than from the file on disk. Hooks
+// under `plugins/mirror-mind/hooks/` are hand-authored plugin source and are
+// NOT managed by this module -- which is precisely why TS5's inventory had to
+// find their interpreter spawns by reading them.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+import { packageVersion } from "#runtime/version.ts";
+import { claudeVariant, PI_SKILLS_DIR, PI_SOURCED_SKILLS } from "./piSourcedSkills.ts";
+
+export const PLUGIN_NAME = "mirror-mind";
+export const PLUGIN_DESCRIPTION =
+  "Mirror Mind — local-first memory and identity for agentic runtimes.";
+export const PLUGIN_AUTHOR = "Mirror Mind";
+
+export const SKILLS_SOURCE_DIR = ".claude/skills";
+export const PLUGIN_DIR = "plugins/mirror-mind";
+export const SKILL_FILENAME = "SKILL.md";
+
+/** A file the generator owns, addressed relative to the repo root. */
+export interface GeneratedFile {
+  readonly relativePath: string;
+  readonly content: string;
+  /** The authored file it derives from, when a person could mistake it for one. */
+  readonly source?: string;
+}
+
+/**
+ * The project version, read from source.
+ *
+ * Read from source rather than from installed metadata, so the build is
+ * deterministic. `packageVersion` is the single body that answers this for the
+ * whole core (US2 decision D2); CV22.DS10.TS5 re-pointed it at
+ * `package.json` and this builder followed with no edit, which is the point
+ * of there being one body.
+ */
+export function readVersion(repoRoot: string): string {
+  const version = packageVersion(repoRoot);
+  if (!version) throw new Error(`version not found from ${repoRoot}`);
+  return version;
+}
+
+/**
+ * The Claude plugin manifest (minimal; no unsupported keys).
+ *
+ * Declares the Mirror MCP server so the canonical package carries it. Since
+ * CV22.DS9.TS2 the entry is the plugin's own launcher rather than an engine,
+ * so reverting never requires editing a plugin installed inside someone's
+ * runtime (DS9 decision D5). TS5 removes that launcher's Python branch; US3
+ * repoints this at the npm entry point.
+ */
+export function buildManifest(version: string): Record<string, unknown> {
+  return {
+    name: PLUGIN_NAME,
+    version,
+    description: PLUGIN_DESCRIPTION,
+    author: { name: PLUGIN_AUTHOR },
+    mcpServers: {
+      // The placeholder is Claude Code's, expanded when it loads the plugin. A
+      // JavaScript template would resolve at BUILD time, against this
+      // repository, shipping an absolute path from the release machine.
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: Claude expands this at load time, not JS
+      [PLUGIN_NAME]: { command: "${CLAUDE_PLUGIN_ROOT}/mcp/launch.sh" },
+    },
+  };
+}
+
+/** The manifest as deterministic JSON text, byte-identical to Python's. */
+export function manifestJson(version: string): string {
+  return `${JSON.stringify(buildManifest(version), null, 2)}\n`;
+}
+
+/**
+ * The skill markdown file, matching `skill.md` case-insensitively.
+ *
+ * Case-insensitive makes the generator robust on both case-sensitive and
+ * case-insensitive filesystems, including older checkouts that may still
+ * contain lowercase `skill.md`.
+ */
+function findSkillMarkdown(skillDir: string): string | null {
+  for (const entry of readdirSync(skillDir, { withFileTypes: true, encoding: "utf8" }).sort(
+    (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+  )) {
+    if (entry.isFile() && entry.name.toLowerCase() === SKILL_FILENAME.toLowerCase()) {
+      return join(skillDir, entry.name);
+    }
+  }
+  return null;
+}
+
+/**
+ * `[skillDirName, markdownPath]` for each skill under `.claude/skills/`. Most
+ * are authored there. A Pi-sourced skill's file is generated instead
+ * (`piSourcedSkills.ts`), and `planGeneratedFiles` takes that one from its Pi
+ * copy, never from this path.
+ */
+export function discoverSkillSources(repoRoot: string): [string, string][] {
+  const base = join(repoRoot, SKILLS_SOURCE_DIR);
+  const sources: [string, string][] = [];
+  const entries = readdirSync(base, { withFileTypes: true, encoding: "utf8" }).sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
+  for (const child of entries) {
+    if (!child.isDirectory()) continue;
+    const markdown = findSkillMarkdown(join(base, child.name));
+    if (markdown === null) continue;
+    sources.push([child.name, markdown]);
+  }
+  return sources;
+}
+
+/**
+ * The `.claude/skills/` copy of each Pi-sourced skill, generated from its Pi
+ * copy. Refuses, before anything is written, when a listed skill has no Pi
+ * copy: generation would otherwise stop without a word, and the old Claude copy
+ * would pass for an authored one again.
+ */
+function planPiSourcedClaudeCopies(repoRoot: string): Map<string, GeneratedFile> {
+  const copies = new Map<string, GeneratedFile>();
+  for (const skill of PI_SOURCED_SKILLS) {
+    const source = join(PI_SKILLS_DIR, skill, SKILL_FILENAME);
+    const path = join(repoRoot, source);
+    if (!existsSync(path)) {
+      throw new Error(
+        `${source}: missing, but ${skill} is listed as Pi-sourced in ts/src/guards/piSourcedSkills.ts`,
+      );
+    }
+    copies.set(skill, {
+      relativePath: join(SKILLS_SOURCE_DIR, skill, SKILL_FILENAME),
+      content: claudeVariant(skill, readFileSync(path, "utf8"), source),
+      source,
+    });
+  }
+  return copies;
+}
+
+/** Every file the generator owns, without touching the filesystem. */
+export function planGeneratedFiles(repoRoot: string): GeneratedFile[] {
+  const version = readVersion(repoRoot);
+  const claudeCopies = planPiSourcedClaudeCopies(repoRoot);
+
+  const pluginSkills = new Map<string, GeneratedFile>();
+  for (const [name, markdown] of discoverSkillSources(repoRoot)) {
+    if (claudeCopies.has(name)) continue;
+    pluginSkills.set(name, {
+      relativePath: join(PLUGIN_DIR, "skills", name, SKILL_FILENAME),
+      content: readFileSync(markdown, "utf8"),
+    });
+  }
+  for (const [name, claudeCopy] of claudeCopies) {
+    pluginSkills.set(name, {
+      relativePath: join(PLUGIN_DIR, "skills", name, SKILL_FILENAME),
+      content: claudeCopy.content,
+      source: claudeCopy.source,
+    });
+  }
+
+  return [
+    {
+      relativePath: join(PLUGIN_DIR, ".claude-plugin", "plugin.json"),
+      content: manifestJson(version),
+    },
+    ...claudeCopies.values(),
+    ...[...pluginSkills].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, file]) => file),
+  ];
+}
+
+/** One drift line; a derived file also names the source a person should edit. */
+function driftLine(kind: "missing" | "out of date", file: GeneratedFile): string {
+  const from = file.source
+    ? ` (generated from ${file.source}: edit the source, then regenerate)`
+    : "";
+  return `${kind}: ${file.relativePath}${from}`;
+}
+
+function generatedSkillFiles(repoRoot: string): string[] {
+  const skillsRoot = join(repoRoot, PLUGIN_DIR, "skills");
+  if (!existsSync(skillsRoot)) return [];
+  const found: string[] = [];
+  for (const entry of readdirSync(skillsRoot, { withFileTypes: true, encoding: "utf8" })) {
+    if (!entry.isDirectory()) continue;
+    const candidate = join(skillsRoot, entry.name, SKILL_FILENAME);
+    if (existsSync(candidate)) found.push(candidate);
+  }
+  return found.sort();
+}
+
+/**
+ * Write every generated file, the plugin and the `.claude/skills/` copies of
+ * Pi-sourced skills, or report drift when `write` is false.
+ *
+ * Returns human-readable drift descriptions. In check mode the list is the
+ * assertion target (empty == in sync). In write mode it is empty and the files
+ * are written; stale generated skills are removed.
+ */
+export function materialize(repoRoot: string, options: { write: boolean }): string[] {
+  const desired = planGeneratedFiles(repoRoot);
+  const desiredPaths = new Set(desired.map((file) => file.relativePath));
+  const problems: string[] = [];
+
+  for (const generated of desired) {
+    const target = join(repoRoot, generated.relativePath);
+    if (options.write) {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, generated.content, "utf8");
+    } else if (!existsSync(target)) {
+      problems.push(driftLine("missing", generated));
+    } else if (readFileSync(target, "utf8") !== generated.content) {
+      problems.push(driftLine("out of date", generated));
+    }
+  }
+
+  for (const existing of generatedSkillFiles(repoRoot)) {
+    const rel = relative(repoRoot, existing);
+    if (desiredPaths.has(rel)) continue;
+    if (options.write) {
+      const parent = dirname(existing);
+      for (const leftover of readdirSync(parent).sort()) unlinkSync(join(parent, leftover));
+      rmdirSync(parent);
+    } else {
+      problems.push(`stale: ${rel}`);
+    }
+  }
+
+  return problems;
+}