@fusengine/harness 0.1.90 → 0.1.92

package/src/runtime/lifecycle/auto-document-reads.ts

@@ -0,0 +1,73 @@
+/**
+ * PostToolUse (matcher "Read") for the core scope: auto-document important
+ * reads (SKILL.md/README/CLAUDE.md/docs/references) into
+ * `.claude/apex/docs/task-<current>-<framework>.md`, once per file per task.
+ * Ports `post-tool-use/auto-document-reads.py`.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { readJsonFile } from "../../util/json-io";
+import { detectProjectType } from "../../policy/detect-project";
+import { projectRootOrNull } from "../../util/project-root";
+import { systemMessage } from "../../adapters/claude";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import type { ApexTaskFile } from "./aipilot/types";
+
+/** Read-tool file paths worth auto-documenting. */
+const DOC_PATTERNS = [
+  /(SKILL\.md|README\.md|CLAUDE\.md)$/,
+  /\/docs\/.*\.md$/,
+  /\/references\/.*\.md$/,
+  /skills\/[^/]+\/SKILL\.md$/,
+];
+
+/** First matching marker (in order) labels the doc-type; "File" otherwise. */
+const TYPE_MAP: Array<[string, string]> = [
+  ["SKILL.md", "Skill"], ["README.md", "README"], ["CLAUDE.md", "Rules"],
+  ["/references/", "Reference"], ["/docs/", "Doc"],
+];
+
+/** The doc-type label for a matched file path. */
+function docTypeOf(filePath: string): string {
+  return TYPE_MAP.find(([marker]) => filePath.includes(marker))?.[1] ?? "File";
+}
+
+/**
+ * Auto-document a Read of a SKILL.md/README/CLAUDE.md/docs/references file
+ * into the target apex docs dir (`.claude/apex/docs/`, `.codex/apex/docs/`,
+ * ...) as `task-<current>-<framework>.md` (skipped when the file is already
+ * logged, or no project root is found from `filePath`).
+ * @param filePath - The path passed to the Read tool.
+ * @param now - Clock (defaults to `Date.now()`).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native `systemMessage` stdout, or "" when nothing was logged.
+ */
+export async function autoDocumentRead(filePath: string, now: number = Date.now(), id: string = "claude-code"): Promise<string> {
+  if (!filePath || !DOC_PATTERNS.some((p) => p.test(filePath))) return "";
+  const root = projectRootOrNull(dirname(filePath));
+  if (!root) return "";
+
+  const seg = harnessHomeSegment(id);
+  const framework = detectProjectType(root);
+  const taskData = await readJsonFile<ApexTaskFile>(join(root, seg, "apex", "task.json"));
+  const current = taskData?.current_task ?? "1";
+
+  const docDir = join(root, seg, "apex", "docs");
+  const docFile = join(docDir, `task-${current}-${framework}.md`);
+  const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const fname = basename(filePath);
+  const docType = docTypeOf(filePath);
+
+  try {
+    mkdirSync(docDir, { recursive: true });
+    if (!existsSync(docFile)) {
+      const fc = framework.charAt(0).toUpperCase() + framework.slice(1);
+      writeFileSync(docFile, `# Task ${current} - ${fc} Documentation\n## Consulted: ${ts} | Source: skill:Read\n## Key Info\n\n`, "utf-8");
+    }
+    if (readFileSync(docFile, "utf-8").includes(`\`${fname}\``)) return "";
+    appendFileSync(docFile, `- **[${docType}]** \`${fname}\` - ${ts}\n`, "utf-8");
+  } catch {
+    return "";
+  }
+  return systemMessage(`📖 [${docType}] ${fname} logged`);
+}

package/src/runtime/lifecycle/cartographer/detect.ts

@@ -0,0 +1,57 @@
+/**
+ * Plugin discovery (fs). Ports `detect_plugins.py`: marketplace `plugins` dir
+ * resolution + `plugin.json` meta reading.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { HOME_DIR } from "../../../config/dotenv";
+import { detectHarness } from "../../../detect/harness";
+import type { HarnessId } from "../../../detect/harness";
+
+/** Sorted entry names of `dir` (alpha, byte-order), or `[]` on error. */
+function sortedNames(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort((a, b) => a.localeCompare(b, "en"));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read `[version, name]` from `<pluginPath>/.claude-plugin/plugin.json`.
+ * @param pluginPath - Absolute plugin directory.
+ * @returns The `[version, name]` pair (both "" when absent/unreadable).
+ */
+export function readPluginMeta(pluginPath: string): [string, string] {
+  const pj = join(pluginPath, ".claude-plugin", "plugin.json");
+  if (!existsSync(pj)) return ["", ""];
+  try {
+    const meta = JSON.parse(readFileSync(pj, "utf-8")) as { version?: string; name?: string };
+    return [meta.version ?? "", meta.name ?? ""];
+  } catch {
+    return ["", ""];
+  }
+}
+
+/**
+ * Auto-detect the marketplace `plugins` dir that contains `cartographer`,
+ * falling back to the first marketplace with a `plugins` dir, else `cwd`.
+ * Ports `find_marketplace_plugins`, but harness-agnostic: the config dir is
+ * derived from the detected harness (`.claude`, `.codex`, `.cursor`, …) via the
+ * shared `HOME_DIR` mapping instead of a hardcoded `.claude`.
+ * @param home - Home directory (defaults to `~`).
+ * @param id - Detected harness id (defaults to runtime detection).
+ * @returns The resolved plugins directory.
+ */
+export function findMarketplacePlugins(home: string = homedir(), id: HarnessId = detectHarness().id): string {
+  const mp = join(home, HOME_DIR[id] ?? ".claude", "plugins", "marketplaces");
+  const markets = sortedNames(mp);
+  for (const m of markets) {
+    if (existsSync(join(mp, m, "plugins", "cartographer"))) return join(mp, m, "plugins");
+  }
+  for (const m of markets) {
+    if (existsSync(join(mp, m, "plugins"))) return join(mp, m, "plugins");
+  }
+  return process.cwd();
+}

package/src/runtime/lifecycle/cartographer/ecosystem-map.ts

@@ -0,0 +1,56 @@
+/**
+ * Ecosystem (plugin) map generation (fs). Ports `generate_map.py`: scans every
+ * installed plugin into a level-1 `.cartographer/index.md` + per-plugin level-2+
+ * trees, preserving enriched descriptions. Reuses `findMarketplacePlugins`,
+ * `readPluginMeta`, `scanPlugin`, `mergeLines`, `writePluginMap`.
+ */
+import { mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findMarketplacePlugins, readPluginMeta } from "./detect";
+import { scanPlugin } from "./scan";
+import { mergeLines } from "./merge";
+import { writePluginMap } from "./write-plugin-map";
+
+function pluginDirs(dir: string): string[] {
+  let entries: string[] = [];
+  try { entries = readdirSync(dir); } catch { return []; }
+  return entries
+    .filter((n) => !n.startsWith("_") && !n.startsWith("."))
+    .filter((n) => { try { return statSync(join(dir, n)).isDirectory(); } catch { return false; } })
+    .sort((a, b) => a.localeCompare(b, "en"));
+}
+
+function utcStamp(now: number): string {
+  return new Date(now).toISOString().slice(0, 16).replace("T", " ");
+}
+
+/**
+ * Generate the plugin ecosystem map under `<pluginsDir>/.cartographer`.
+ * @param now - Clock for the banner timestamp.
+ * @param pluginsDirOverride - Override for the marketplace plugins directory.
+ * @returns The map navigation context, or "".
+ */
+export function generateEcosystemMap(now: number, pluginsDirOverride?: string): string {
+  const pluginsDir = resolve(pluginsDirOverride ?? findMarketplacePlugins());
+  try { if (!statSync(pluginsDir).isDirectory()) return ""; } catch { return ""; }
+  const outputDir = join(pluginsDir, ".cartographer");
+  mkdirSync(outputDir, { recursive: true });
+  const dirs = pluginDirs(pluginsDir);
+  const lines = [`# Ecosystem Map (${dirs.length} plugins)\n`, `> Auto-generated by cartographer — ${utcStamp(now)}\n`];
+  for (const name of dirs) {
+    const pluginPath = join(pluginsDir, name);
+    const [version, pkgName] = readPluginMeta(pluginPath);
+    const display = pkgName || name;
+    const items = scanPlugin(pluginPath);
+    const agents = items.filter(([t]) => t === "agent").map(([, n]) => n);
+    const ver = version ? ` (v${version})` : "";
+    lines.push(`- [${display}](./${display}/index.md)${ver} → ${agents.length ? agents.join(", ") : "(no agents)"}`);
+    writePluginMap(outputDir, display, version, items, pluginPath);
+    writePluginMap(pluginPath, ".cartographer", version, items, pluginPath);
+  }
+  const indexPath = join(outputDir, "index.md");
+  writeFileSync(indexPath, mergeLines(lines, indexPath).join("\n") + "\n", "utf-8");
+  return `Project map: .cartographer/project/index.md — navigate project files. ` +
+    `Plugin skills map: ${outputDir}/index.md — navigate agent skills. ` +
+    `Branches link to deeper index.md, leaves link to real files.`;
+}

package/src/runtime/lifecycle/cartographer/fs-util.ts

@@ -0,0 +1,64 @@
+/**
+ * Filesystem helpers for the cartographer tree walk. Ports the fs parts of
+ * `describe.py` (file desc) and `write_recursive.py` (children + counts).
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { extname, join } from "node:path";
+import { descFromText } from "../../../policy/cartographer/describe";
+import { parseField } from "../../../policy/cartographer/frontmatter";
+
+/**
+ * Read a file and derive its one-line description (frontmatter / heading /
+ * comment). "" on any error or when nothing is found.
+ * @param filePath - Absolute path to the file.
+ * @returns The description, or "".
+ */
+export function getFileDesc(filePath: string): string {
+  let text = "";
+  try {
+    text = readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+  const suffix = extname(filePath);
+  const mdField = suffix === ".md" ? parseField(text, "description") : "";
+  return descFromText(suffix, text, mdField);
+}
+
+/**
+ * Recursively count files whose relative path parts are all visible (no leading
+ * "." or "_") and none excluded. Best-effort (partial count on errors).
+ * @param dir - Directory to count under.
+ * @param exclude - Directory/name set to skip.
+ * @returns The file count.
+ */
+export function countFiles(dir: string, exclude: ReadonlySet<string>): number {
+  let total = 0;
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
+      if (e.isDirectory()) total += countFiles(join(dir, e.name), exclude);
+      else if (e.isFile()) total += 1;
+    }
+  } catch { /* best effort */ }
+  return total;
+}
+
+/** Absolute children of `source`, split into dirs/files, sorted by full path. */
+export function listChildren(source: string, exclude: ReadonlySet<string>): { dirs: string[]; files: string[] } {
+  const dirs: string[] = [];
+  const files: string[] = [];
+  let entries;
+  try {
+    entries = readdirSync(source, { withFileTypes: true });
+  } catch {
+    return { dirs, files };
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
+    const abs = join(source, e.name);
+    if (e.isDirectory()) dirs.push(abs);
+    else if (e.isFile()) files.push(abs);
+  }
+  return { dirs: dirs.sort(), files: files.sort() };
+}

package/src/runtime/lifecycle/cartographer/merge.ts

@@ -0,0 +1,51 @@
+/**
+ * Index merge — preserves enriched descriptions across regenerations. Ports
+ * `merge_index.py` (merge_lines + .enriched.json sidecar).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseEntry } from "../../../policy/cartographer/entry";
+
+/**
+ * Load the `.enriched.json` sidecar's `entries` map for an output index.
+ * @param outputIndexPath - Path to the index.md being written.
+ * @returns The path→desc enrichment map (possibly empty).
+ */
+export function loadEnriched(outputIndexPath: string): Record<string, string> {
+  const sidecar = join(dirname(outputIndexPath), ".enriched.json");
+  try {
+    if (!existsSync(sidecar)) return {};
+    const data = JSON.parse(readFileSync(sidecar, "utf-8")) as { entries?: Record<string, string> };
+    return data.entries ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge freshly generated lines with prior descriptions: enriched sidecar wins,
+ * else a longer pre-existing description is preserved.
+ * @param newLines - The freshly generated index lines.
+ * @param outputIndexPath - Path to the existing index.md (if any).
+ * @returns The merged lines.
+ */
+export function mergeLines(newLines: string[], outputIndexPath: string): string[] {
+  const enriched = loadEnriched(outputIndexPath);
+  const existingDescs: Record<string, string> = {};
+  if (existsSync(outputIndexPath)) {
+    try {
+      for (const line of readFileSync(outputIndexPath, "utf-8").split("\n")) {
+        const e = parseEntry(line);
+        if (e) existingDescs[e.path] = e.desc;
+      }
+    } catch { /* ignore */ }
+  }
+  return newLines.map((line) => {
+    const e = parseEntry(line);
+    if (!e) return line;
+    if (e.path in enriched) return `${e.prefix}[${e.name}](${e.path}) — ${enriched[e.path]}`;
+    const old = existingDescs[e.path] ?? "";
+    if (old.length > e.desc.length) return `${e.prefix}[${e.name}](${e.path}) — ${old}`;
+    return line;
+  });
+}

package/src/runtime/lifecycle/cartographer/project-map.ts

@@ -0,0 +1,49 @@
+/**
+ * Project map generation. Ports `generate_project_map.py` (project map only).
+ */
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { EXCLUDE_DIRS, PROJECT_INDICATORS } from "../../../policy/cartographer/indicators";
+import { writeTree } from "./write-tree";
+
+/** True when `dir` is a real directory. */
+function isDirectory(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when `dir` looks like a project root (has an indicator file) and is not
+ * the home directory or filesystem root.
+ * @param dir - Directory to test.
+ * @returns Whether `dir` is a project root.
+ */
+export function isProject(dir: string): boolean {
+  const resolved = resolve(dir);
+  const home = resolve(homedir());
+  if (resolved === home || resolved === "/") return false;
+  for (const f of PROJECT_INDICATORS) {
+    if (existsSync(join(dir, f))) return true;
+  }
+  return false;
+}
+
+/**
+ * Generate the `.cartographer/project` index tree for `cwd` when it is a real
+ * project directory. Always returns "" (no additionalContext emitted).
+ * @param cwd - The working directory.
+ * @param outputDir - Override for the output tree root.
+ * @returns "" (side-effect only).
+ */
+export function generateProjectMap(cwd: string, outputDir?: string): string {
+  const projectDir = resolve(cwd);
+  const out = outputDir ?? join(projectDir, ".cartographer", "project");
+  if (!isDirectory(projectDir)) return "";
+  if (!isProject(projectDir)) return "";
+  writeTree(projectDir, out, "", EXCLUDE_DIRS);
+  return "";
+}

package/src/runtime/lifecycle/cartographer/scan-hooks.ts

@@ -0,0 +1,48 @@
+/**
+ * Hook scanning (fs). Ports `_scan_hooks` from `scan_plugins.py`: reads a
+ * plugin's `hooks/hooks.json` and reduces it to a single `("hooks", "<events>", "")`
+ * row. The `hooks` value (or the whole document) is either a MAP of event →
+ * entries (keys are the events) or a LIST of entries each carrying an `event`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ScanRow } from "../../../policy/cartographer/build-tree";
+
+/** True for a non-null plain object (excludes arrays), mirroring Python `isinstance(x, dict)`. */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Sort unique non-empty strings alpha (byte-order). */
+function sortedEvents(events: Iterable<string>): string[] {
+  return [...new Set([...events].filter((e) => e))].sort((a, b) => a.localeCompare(b, "en"));
+}
+
+/** Derive hook event names from the `hooks.json` data (map keys, or list `event` fields). */
+function hookEvents(hooksData: unknown): string[] {
+  if (isPlainObject(hooksData)) {
+    return sortedEvents(Object.keys(hooksData).filter((k) => !k.startsWith("_")));
+  }
+  if (Array.isArray(hooksData)) {
+    return sortedEvents(hooksData.map((h) => (isPlainObject(h) ? String(h.event ?? "") : "")));
+  }
+  return [];
+}
+
+/**
+ * Scan `hooks/hooks.json` into a single `("hooks", "<events>", "")` row.
+ * @param root - Absolute plugin directory.
+ * @returns The single hooks row, or `[]` when absent/empty/unreadable.
+ */
+export function scanHooks(root: string): ScanRow[] {
+  const file = join(root, "hooks", "hooks.json");
+  if (!existsSync(file)) return [];
+  try {
+    const raw: unknown = JSON.parse(readFileSync(file, "utf-8"));
+    const hooksData = isPlainObject(raw) ? (raw.hooks ?? raw) : {};
+    const events = hookEvents(hooksData);
+    return events.length ? [["hooks", events.join(", "), ""]] : [];
+  } catch {
+    return [];
+  }
+}

package/src/runtime/lifecycle/cartographer/scan.ts

@@ -0,0 +1,81 @@
+/**
+ * Plugin scanning (fs). Ports `scan_plugins.py`: turns a plugin's
+ * agents/skills/commands/hooks into ordered `[type, name, desc]` rows.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import type { ScanRow } from "../../../policy/cartographer/build-tree";
+import { parseBodyDesc, parseField } from "../../../policy/cartographer/frontmatter";
+import { scanHooks } from "./scan-hooks";
+
+/** Sorted entry names of `dir` (alpha, byte-order), or `[]` on error. */
+function sortedNames(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort((a, b) => a.localeCompare(b, "en"));
+  } catch {
+    return [];
+  }
+}
+
+/** Read a `.md` frontmatter field from a file path, "" when missing/unreadable. */
+function fileField(path: string, field: string): string {
+  try {
+    return parseField(readFileSync(path, "utf-8"), field);
+  } catch {
+    return "";
+  }
+}
+
+/** Scan `agents/*.md` → `("agent", name, desc[:50])` rows. */
+export function scanAgents(root: string): ScanRow[] {
+  const dir = join(root, "agents");
+  return sortedNames(dir)
+    .filter((n) => extname(n) === ".md")
+    .map((n): ScanRow => {
+      const f = join(dir, n);
+      const name = fileField(f, "name") || n.replace(/\.md$/, "");
+      return ["agent", name, fileField(f, "description").slice(0, 50)];
+    });
+}
+
+/** Scan `skills/<dir>/SKILL.md` → `("skill", dir, desc)` rows. */
+function scanSkills(root: string): ScanRow[] {
+  const dir = join(root, "skills");
+  const rows: ScanRow[] = [];
+  for (const name of sortedNames(dir)) {
+    try {
+      if (!statSync(join(dir, name)).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const skillMd = join(dir, name, "SKILL.md");
+    let desc = "";
+    if (existsSync(skillMd)) {
+      desc = fileField(skillMd, "description");
+      if (!desc) {
+        try {
+          desc = parseBodyDesc(readFileSync(skillMd, "utf-8"));
+        } catch { /* keep "" */ }
+      }
+    }
+    rows.push(["skill", name, desc || "(no description)"]);
+  }
+  return rows;
+}
+
+/** Scan `commands/*.md` → `("command", "/name", desc[:50])` rows. */
+function scanCommands(root: string): ScanRow[] {
+  const dir = join(root, "commands");
+  return sortedNames(dir)
+    .filter((n) => extname(n) === ".md")
+    .map((n): ScanRow => ["command", `/${n.replace(/\.md$/, "")}`, fileField(join(dir, n), "description").slice(0, 50)]);
+}
+
+/**
+ * Scan a single plugin directory into ordered `[type, name, desc]` rows.
+ * @param pluginDir - Absolute plugin directory.
+ * @returns The agents + skills + commands + hooks rows.
+ */
+export function scanPlugin(pluginDir: string): ScanRow[] {
+  return [...scanAgents(pluginDir), ...scanSkills(pluginDir), ...scanCommands(pluginDir), ...scanHooks(pluginDir)];
+}

package/src/runtime/lifecycle/cartographer/session-start.ts

@@ -0,0 +1,33 @@
+/**
+ * Cartographer SessionStart handler. Ports BOTH halves of the Python maps:
+ * `generate_project_map.py` (regenerate `.cartographer/project`) and
+ * `generate_map.py` (regenerate the plugin ecosystem map), emitting the
+ * navigation context from the latter as additionalContext.
+ */
+import { resolve } from "node:path";
+import { generateProjectMap } from "./project-map";
+import { generateEcosystemMap } from "./ecosystem-map";
+import { contextResponse } from "../../../adapters/claude";
+
+/**
+ * Resolve the marketplace plugins dir from `CLAUDE_PLUGIN_ROOT`, mirroring the
+ * Python hook which passes `${CLAUDE_PLUGIN_ROOT}/..` to `generate_map.py`.
+ * @returns The plugins dir (env `/..`), or `undefined` to fall back to auto-detect.
+ */
+function pluginsDirFromEnv(): string | undefined {
+  const root = process.env.CLAUDE_PLUGIN_ROOT;
+  return root ? resolve(root, "..") : undefined;
+}
+
+/**
+ * Regenerate the project map + plugin ecosystem map for `cwd` on SessionStart.
+ * Emits the ecosystem navigation context as additionalContext (or "").
+ * @param cwd - The working directory.
+ * @param now - Clock for the ecosystem map banner timestamp.
+ * @returns The SessionStart additionalContext response, or "".
+ */
+export function cartoSessionStart(cwd: string, now: number = Date.now()): string {
+  generateProjectMap(cwd);
+  const ctx = generateEcosystemMap(now, pluginsDirFromEnv());
+  return ctx ? contextResponse("SessionStart", ctx) : "";
+}

package/src/runtime/lifecycle/cartographer/track-enrichment.ts

@@ -0,0 +1,45 @@
+/**
+ * Enrichment tracker (PostToolUse Edit/Write on `.cartographer/**\/index.md`).
+ * Ports `track-enrichment.py`: persists manual descriptions to a sidecar so the
+ * next regeneration can preserve them.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseEnrichment } from "../../../policy/cartographer/entry";
+
+/** Shape of the `.enriched.json` sidecar. */
+interface EnrichedSidecar {
+  version: number;
+  entries: Record<string, string>;
+}
+
+/**
+ * Record manually-edited descriptions from a cartographer `index.md` into the
+ * adjacent `.enriched.json` sidecar. No-op for unrelated paths. No stdout.
+ * @param filePath - The edited file path.
+ */
+export function trackEnrichment(filePath: string): void {
+  if (!filePath || !filePath.includes(".cartographer") || !filePath.endsWith("index.md")) return;
+  if (!existsSync(filePath)) return;
+  const sidecar = join(dirname(filePath), ".enriched.json");
+  let existing: EnrichedSidecar = { version: 1, entries: {} };
+  if (existsSync(sidecar)) {
+    try {
+      existing = JSON.parse(readFileSync(sidecar, "utf-8")) as EnrichedSidecar;
+    } catch { /* keep default */ }
+  }
+  const entries = (existing.entries ??= {});
+  let text = "";
+  try {
+    text = readFileSync(filePath, "utf-8");
+  } catch {
+    return;
+  }
+  for (const line of text.split("\n")) {
+    const e = parseEnrichment(line);
+    if (e) entries[e[0]] = e[1];
+  }
+  try {
+    writeFileSync(sidecar, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/cartographer/write-plugin-map.ts

@@ -0,0 +1,43 @@
+/**
+ * Per-plugin map writer (fs). Ports `write_plugin_map.py`: writes a level-2
+ * `<plugin>/index.md` (indented linked tree) then recurses agents/skills/
+ * commands into deeper index trees. Reuses `buildTree`, `mergeLines`, `writeTree`.
+ */
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildTree, type ScanRow } from "../../../policy/cartographer/build-tree";
+import { mergeLines } from "./merge";
+import { writeTree } from "./write-tree";
+
+/** True when `dir` is a real directory. */
+function isDir(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write `<outputDir>/<pluginName>/index.md` (indented linked tree) and recurse
+ * agents/skills/commands into their own index trees rooted there.
+ * @param outputDir - The map root directory.
+ * @param pluginName - Display name of the plugin (the index subfolder).
+ * @param version - Plugin version ("" to omit).
+ * @param items - The scanned `[type, name, desc]` rows.
+ * @param pluginPath - Absolute source plugin directory (for recursion).
+ */
+export function writePluginMap(outputDir: string, pluginName: string, version: string, items: ReadonlyArray<ScanRow>, pluginPath: string): void {
+  const pluginDir = join(outputDir, pluginName);
+  mkdirSync(pluginDir, { recursive: true });
+  const ver = version ? ` (v${version})` : "";
+  const tree = items.length ? buildTree(items, true) : "└── (empty)";
+  const newLines = `# ${pluginName}${ver}\n\n${tree}`.split("\n");
+  const indexPath = join(pluginDir, "index.md");
+  writeFileSync(indexPath, mergeLines(newLines, indexPath).join("\n") + "\n", "utf-8");
+
+  for (const section of ["agents", "skills", "commands"]) {
+    const src = join(pluginPath, section);
+    if (isDir(src)) writeTree(src, join(pluginDir, section), "../index.md");
+  }
+}

package/src/runtime/lifecycle/cartographer/write-tree.ts

@@ -0,0 +1,44 @@
+/**
+ * Recursive index.md tree writer. Ports `write_recursive.py`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { countFiles, getFileDesc, listChildren } from "./fs-util";
+import { mergeLines } from "./merge";
+
+/**
+ * Write `index.md` files mirroring `source` under `output`, recursing into
+ * subdirectories. Directory lines carry a file-count hint; file lines carry a
+ * derived description and link to the real absolute source path.
+ * @param source - Absolute source directory.
+ * @param output - Absolute output directory for the index tree.
+ * @param back - Relative `← back` link target ("" at the root).
+ * @param exclude - Directory/name set to skip.
+ */
+export function writeTree(source: string, output: string, back: string = "", exclude?: ReadonlySet<string>): void {
+  const ex = exclude ?? new Set<string>();
+  mkdirSync(output, { recursive: true });
+  const { dirs, files } = listChildren(source, ex);
+  const lines: string[] = [`# ${basename(source)}\n`];
+  if (back) lines.push(`> [← back](${back})\n`);
+  const total = dirs.length + files.length;
+  let idx = 0;
+  for (const d of dirs) {
+    idx += 1;
+    const conn = idx === total ? "└──" : "├──";
+    const count = countFiles(d, ex);
+    const hint = count ? ` — ${count} files` : "";
+    lines.push(`${conn} [${basename(d)}/](./${basename(d)}/index.md)${hint}`);
+    writeTree(d, join(output, basename(d)), "../index.md", exclude);
+  }
+  for (const f of files) {
+    idx += 1;
+    const conn = idx === total ? "└──" : "├──";
+    const desc = getFileDesc(f);
+    const suffix = desc ? ` — ${desc}` : "";
+    lines.push(`${conn} [${basename(f)}](${f})${suffix}`);
+  }
+  const indexPath = join(output, "index.md");
+  const merged = mergeLines(lines, indexPath);
+  writeFileSync(indexPath, merged.join("\n") + "\n", "utf-8");
+}