@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/lifecycle/aipilot/solid-compliance.ts

@@ -0,0 +1,69 @@
+/**
+ * PostToolUse (matcher "Write|Edit") for the ai-pilot scope: validate SOLID
+ * file-size and interface-location compliance right after a code write.
+ * Ports `check-solid-compliance.py`.
+ */
+import { readText, pathExists } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { resolveMaxLines, splitTarget } from "../../../config/limits";
+import { maskCommentsAndStrings } from "../../../policy/conventions/strip";
+import { isVendorPath } from "../../../policy/conventions/langs";
+
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|py|php|swift|go|rs|rb|java|astro)$/;
+const COMPONENT_DIR = /\/(components|pages|views)\//;
+const BACKEND_DIR = /\/(Controllers|Models|Services)\//;
+const TS_INTERFACE_RE = /^(export )?(interface|type) [A-Z]/m;
+const PHP_INTERFACE_RE = /^interface /m;
+
+/** Count non-empty, non-comment (`//`/`#`/`*`-prefixed) lines. Shared with {@link checkSolidFromTranscript}. */
+export function countCodeLines(content: string): number {
+  let count = 0;
+  for (const raw of content.split("\n")) {
+    const s = raw.trim();
+    if (!s || s.startsWith("//") || s.startsWith("#") || s.startsWith("*")) continue;
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Validate SOLID compliance for a just-written file.
+ * @param payload - The raw PostToolUse hook payload (`tool_name`, `tool_input.file_path`).
+ * @returns The PostToolUse `additionalContext` response, or `""` when clean/not applicable.
+ */
+export function checkSolidCompliance(payload: Record<string, unknown>): string {
+  const tool = String(payload.tool_name ?? "");
+  if (tool !== "Write" && tool !== "Edit") return "";
+  const input = (payload.tool_input as Record<string, unknown> | undefined) ?? {};
+  const filePath = typeof input.file_path === "string" ? input.file_path : "";
+  if (!filePath || !CODE_EXTENSIONS.test(filePath) || !pathExists(filePath)) return "";
+  if (isVendorPath(filePath)) return ""; // dependency/build dirs are never convention-gated
+
+  let content: string;
+  try {
+    content = readText(filePath);
+  } catch {
+    return "";
+  }
+
+  const violations: string[] = [];
+  const max = resolveMaxLines();
+  const split = splitTarget(max);
+  const lc = countCodeLines(content);
+  if (lc > max) violations.push(`FILE SIZE: ${lc} lines (max: ${max})`);
+  else if (lc > split) violations.push(`FILE SIZE WARNING: ${lc} lines (split at ${split})`);
+
+  // Per-extension matching on MASKED content (no cross-language regex bleed,
+  // no comment/string false positives).
+  const masked = maskCommentsAndStrings(content, filePath.endsWith(".php") ? "php" : filePath.endsWith(".py") ? "py" : "c");
+  if (COMPONENT_DIR.test(filePath) && /\.(ts|tsx|js|jsx|astro)$/.test(filePath)) {
+    if (TS_INTERFACE_RE.test(masked)) violations.push("INTERFACE LOCATION: Move to src/interfaces/");
+  } else if (BACKEND_DIR.test(filePath) && filePath.endsWith(".php")) {
+    if (PHP_INTERFACE_RE.test(masked)) violations.push("INTERFACE LOCATION: Move to app/Contracts/");
+  }
+
+  if (violations.length === 0) return "";
+  const name = filePath.split("/").pop() ?? filePath;
+  const message = `SOLID COMPLIANCE CHECK: ${name}\n\n${violations.join("\n")}\nINSTRUCTION: Fix violations before continuing.\nRun sniper agent for full validation.`;
+  return contextResponse("PostToolUse", message);
+}

package/src/runtime/lifecycle/aipilot/solid-notice.ts

@@ -0,0 +1,47 @@
+/**
+ * SubagentStop SOLID-notice dedup (anti-loop): `checkSolidFromTranscript` is
+ * stateless, so an unchanged violation set re-emitted the same
+ * `additionalContext` on EVERY SubagentStop — re-invoking the agent in an
+ * observed ~15-repeat loop. The dedup fingerprint is a SHA-256 hash of the
+ * sorted `file:message` set, persisted per agent key in the canonical
+ * `.harness/track/solid-notice.json` sidecar (`config/layout.ts`), written
+ * under the synchronous track lock (this hook runs in an ephemeral sync
+ * process). Semantics: identical fingerprint within the TTL → silence;
+ * changed/absent/expired fingerprint → emit once and record (the TTL derives
+ * from `FUSE_ENFORCE_TTL_SEC`, no new env var). On lock contention the notice
+ * is emitted anyway (visibility beats a muted violation) but not recorded.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWrite } from "../../../util/json-io";
+import { LOCK_FAILED, withTrackLockSync } from "../../../tracking/track-lock-sync";
+
+/** SHA-256 (truncated) of the sorted violation set — the dedup fingerprint. */
+export function noticeFingerprint(violations: string[]): string {
+  return createHash("sha256").update([...violations].sort().join("\n")).digest("hex").slice(0, 16);
+}
+
+/** Sidecar shape: agent key → last emitted fingerprint + timestamp. */
+type NoticeState = Record<string, { hash: string; at: number }>;
+
+/**
+ * Decide whether the notice for `key` may be emitted, recording it when so.
+ * @param noticeFile - `projectLayout(cwd).solidNoticeFile`.
+ * @param key - Agent/transcript identity (e.g. `agent_transcript_path`).
+ * @param hash - The current set's fingerprint ({@link noticeFingerprint}).
+ * @param now - Clock (epoch ms).
+ * @param ttlMs - Reminder window (derived from `FUSE_ENFORCE_TTL_SEC`).
+ */
+export function shouldEmitNotice(noticeFile: string, key: string, hash: string, now: number, ttlMs: number): boolean {
+  let state: NoticeState = {};
+  try { state = JSON.parse(readFileSync(noticeFile, "utf8")) as NoticeState; } catch { /* absent/corrupt → emit */ }
+  const prev = state[key];
+  if (prev && prev.hash === hash && now - prev.at < ttlMs) return false;
+  const next: NoticeState = { ...state, [key]: { hash, at: now } };
+  const ran = withTrackLockSync(dirname(noticeFile), () => {
+    try { atomicWrite(noticeFile, JSON.stringify(next)); } catch { /* fail-open */ }
+  });
+  void (ran === LOCK_FAILED); // emit regardless (see module doc)
+  return true;
+}

package/src/runtime/lifecycle/aipilot/solid-transcript.ts

@@ -0,0 +1,60 @@
+/**
+ * SubagentStop (matcher "") for the ai-pilot scope: check SOLID file-size and
+ * interface-location compliance for every file a sub-agent wrote/edited, per
+ * the transcript. Ports `check-solid-from-transcript.py`. Fires unconditionally
+ * for every sub-agent, unlike the sniper/research-expert-scoped caches here.
+ */
+import { readText, pathExists } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { resolveMaxLines } from "../../../config/limits";
+import { resolveTtlSec } from "../../../config/ttl";
+import { projectLayout } from "../../../config/layout";
+import { transcriptFilePaths } from "./transcript";
+import { countCodeLines } from "./solid-compliance";
+import { noticeFingerprint, shouldEmitNotice } from "./solid-notice";
+
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|dart|vue|svelte|astro)$/;
+const INTERFACE_PATTERN = /^(export )?(interface|type) [A-Z]/m;
+/** Segment-anchored dirs (a substring like `app/` matched `livetest-app/`). */
+const INTERFACE_DIRS_RE = /\/(components|pages|views|app)\//;
+/** Canonical homes — never a violation there (owner decision: types/ is
+ * canonical; Contracts/ is the Laravel home taught by solid-php/laravelGate). */
+const INTERFACE_EXEMPT_RE = /\/(interfaces|types|Contracts|contracts)\//;
+
+/**
+ * Check every Write/Edit target in a subagent transcript against the SOLID
+ * line-count ceiling and interface-location convention. Deduped per
+ * transcript (`solid-notice.ts`): an unchanged violation set is emitted once
+ * per TTL window, never in a loop.
+ * @param transcript - Path to the agent JSONL transcript (`agent_transcript_path`).
+ * @param cwd - Project root (locates the `.harness/track` dedup sidecar).
+ * @param now - Clock (tests inject it).
+ * @returns The SubagentStop `additionalContext` response, or `""` when clean/deduped.
+ */
+export async function checkSolidFromTranscript(transcript: string | undefined, cwd: string = process.cwd(), now: number = Date.now()): Promise<string> {
+  if (!transcript || !pathExists(transcript)) return "";
+  const files = await transcriptFilePaths(transcript, ["Write", "Edit"]);
+  const max = resolveMaxLines();
+  const violations: string[] = [];
+
+  for (const fp of files.sort()) {
+    if (!pathExists(fp) || !CODE_EXTENSIONS.test(fp)) continue;
+    const name = fp.split("/").pop() ?? fp;
+    let content: string;
+    try {
+      content = readText(fp);
+    } catch {
+      continue;
+    }
+    const lc = countCodeLines(content);
+    if (lc > max) violations.push(`SOLID: ${name} = ${lc} lines (max ${max})`);
+    if (INTERFACE_DIRS_RE.test(fp) && !INTERFACE_EXEMPT_RE.test(fp) && INTERFACE_PATTERN.test(content)) {
+      const dest = fp.endsWith(".php") ? "app/Contracts/" : "interfaces/";
+      violations.push(`SOLID: ${name}: move interfaces to ${dest}`);
+    }
+  }
+
+  if (violations.length === 0) return "";
+  if (!shouldEmitNotice(projectLayout(cwd).solidNoticeFile, transcript, noticeFingerprint(violations), now, resolveTtlSec(process.env) * 1000)) return "";
+  return contextResponse("SubagentStop", `## SOLID VIOLATIONS DETECTED (subagent output)\n${violations.join("\n")}\nRun sniper to fix these issues.`);
+}

package/src/runtime/lifecycle/aipilot/source-scan.ts

@@ -0,0 +1,56 @@
+/**
+ * Source-file scanning + project-stack detection for the ai-pilot scope.
+ * Ported from the ai-pilot plugin's `cache/source-collector.ts` +
+ * the stack detection in `cache/lesson-helpers.ts` (now removed).
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { collectFiles } from "../../../util/runtime-io";
+
+/** Source extensions to collect (monorepo-aware, dot-prefixed for matching). */
+const SRC_EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+/** Roots walked: `src`, `app`, plus each child `src` under `apps/` and `packages/`. */
+const TOP_DIRS = ["src", "app"] as const;
+const NESTED_PARENTS = ["apps", "packages"] as const;
+
+/** Collect the existing monorepo `src` roots nested under `apps/` and `packages/`. */
+function nestedRoots(projectPath: string): string[] {
+  const roots: string[] = [];
+  for (const parent of NESTED_PARENTS) {
+    try {
+      for (const e of readdirSync(join(projectPath, parent), { withFileTypes: true })) {
+        if (e.isDirectory()) roots.push(join(projectPath, parent, e.name, "src"));
+      }
+    } catch { /* parent dir may not exist */ }
+  }
+  return roots;
+}
+
+/**
+ * Scan source files in `projectPath` (monorepo-aware), capped at `maxFiles`.
+ * Node+Bun portable: walks `node:fs` recursively (replaces the Bun `Glob`).
+ * @param projectPath - Absolute project root.
+ * @param maxFiles - Max files to collect (default 200).
+ * @returns Absolute paths matching the source extensions.
+ */
+export async function scanSourceFiles(projectPath: string, maxFiles = 200): Promise<string[]> {
+  const files: string[] = [];
+  const roots = [...TOP_DIRS.map((d) => join(projectPath, d)), ...nestedRoots(projectPath)];
+  for (const root of roots) {
+    collectFiles(root, SRC_EXTS, files, maxFiles);
+    if (files.length >= maxFiles) break;
+  }
+  return files;
+}
+
+/** Detect the project stack from config files in the project root. */
+export function detectStack(projectPath: string): string {
+  try {
+    const entries = readdirSync(projectPath);
+    if (entries.some((f) => f.startsWith("next.config"))) return "nextjs";
+    if (entries.includes("composer.json")) return "laravel";
+    if (entries.some((f) => f.endsWith(".xcodeproj")) || entries.includes("Package.swift")) return "swift";
+    if (entries.some((f) => f.startsWith("tailwind.config"))) return "tailwindcss";
+  } catch { /* fallback */ }
+  return "universal";
+}

package/src/runtime/lifecycle/aipilot/sync-task.ts

@@ -0,0 +1,75 @@
+/**
+ * PostToolUse (matcher "TaskCreate|TaskUpdate") for the ai-pilot scope:
+ * synchronize Claude task tools with `.claude/apex/task.json` and prompt an
+ * auto-commit on completion when git changes are detected. Ports
+ * `sync-task-tracking.ts`.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile } from "../../../util/json-io";
+import { spawnCapture } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { acquireLock, taskCreate, taskStart, taskComplete } from "./apex-task-store";
+import { harnessHomeSegment } from "../../../policy/apex-target";
+import type { ApexTaskFile } from "./types";
+
+/** True when the project has uncommitted git changes. */
+async function hasGitChanges(cwd: string): Promise<boolean> {
+  try {
+    return spawnCapture("git", ["status", "--porcelain"], cwd).trim().length > 0;
+  } catch { return false; }
+}
+
+/** Handle a completed task: emit the commit reminder (or the no-change note). */
+async function onComplete(taskFile: string, taskId: string, projectRoot: string): Promise<string> {
+  await taskComplete(taskFile, taskId);
+  if (!(await hasGitChanges(projectRoot))) {
+    return contextResponse("PostToolUse", "Task completed. No changes to commit.");
+  }
+  const data = await readJsonFile<ApexTaskFile>(taskFile);
+  const subject = data?.tasks[taskId]?.subject ?? "Task";
+  return contextResponse("PostToolUse", `Task #${taskId} completed: ${subject}\n\nChanges detected. MANDATORY: Run /fuse-commit-pro:commit to commit with smart detection.`);
+}
+
+/**
+ * PostToolUse TaskCreate/TaskUpdate handler. Claude-only by design: Codex never
+ * emits these native task tools, so the `toolName` matcher below intentionally
+ * stays as-is — only the target apex-dir segment is harness-aware.
+ * @param payload - The raw hook payload (`tool_name`, `tool_input`, `tool_response`).
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export async function syncTaskTracking(payload: Record<string, unknown>, cwd: string, id: string = "claude-code"): Promise<string> {
+  const toolName = String(payload.tool_name ?? "");
+  if (toolName !== "TaskCreate" && toolName !== "TaskUpdate") return "";
+
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const seg = harnessHomeSegment(id);
+  const taskFile = join(projectRoot, seg, "apex", "task.json");
+  if (!existsSync(taskFile)) return "";
+
+  const unlock = await acquireLock(join(projectRoot, seg, "apex", ".task.lock"), 10000);
+  if (!unlock) return "";
+  try {
+    const ti = (payload.tool_input ?? {}) as Record<string, string>;
+    if (toolName === "TaskCreate") {
+      const existing = (await readJsonFile<ApexTaskFile>(taskFile))?.tasks ?? {};
+      const respId = (payload.tool_response as { id?: string } | undefined)?.id;
+      const taskId = respId ?? String(Math.max(0, ...Object.keys(existing).map(Number)) + 1);
+      await taskCreate(taskFile, taskId, ti.subject ?? "", ti.description ?? "");
+      return "";
+    }
+    const taskId = ti.taskId ?? "";
+    if (!taskId) return "";
+    const newStatus = ti.status ?? "";
+    if (newStatus === "in_progress") {
+      const blocked = (ti.addBlockedBy as unknown as string[] | undefined)?.join(",") ?? "";
+      await taskStart(taskFile, taskId, ti.subject || undefined, ti.description || undefined, blocked || undefined);
+    }
+    if (newStatus === "completed") return onComplete(taskFile, taskId, projectRoot);
+    return "";
+  } finally {
+    await unlock();
+  }
+}

package/src/runtime/lifecycle/aipilot/transcript.ts

@@ -0,0 +1,88 @@
+/**
+ * JSONL transcript parsing helpers for the ai-pilot scope: project-root
+ * detection from file paths, file-path extraction, Edit extraction, and the
+ * assistant report extraction. Ported into the harness from the ai-pilot
+ * plugin's `cache/project-detect.ts` + `cache/lesson-helpers.ts` (now removed).
+ */
+import { readdirSync } from "node:fs";
+import { readText } from "../../../util/runtime-io";
+import type { EditEntry } from "./types";
+
+const ROOT_MARKERS = [".git", ".hg", "turbo.json", "nx.json", "lerna.json", "pnpm-workspace.yaml"];
+const PKG_MARKERS = ["package.json", "composer.json", "Package.swift", "Cargo.toml", "go.mod", "pyproject.toml", "Gemfile", "pom.xml"];
+
+/** Detect the project root by walking up from the first file path to a marker. */
+export function projectRootFromPaths(filePaths: string[]): string | null {
+  const firstPath = filePaths[0];
+  if (!firstPath) return null;
+  const lastSlash = firstPath.lastIndexOf("/");
+  if (lastSlash <= 0) return null;
+  let dir = firstPath.substring(0, lastSlash);
+  let bestRoot: string | null = null;
+  while (dir && dir !== "/" && dir.length > 1) {
+    try {
+      const entries = readdirSync(dir);
+      if (ROOT_MARKERS.some((m) => entries.includes(m))) return dir;
+      if (PKG_MARKERS.some((m) => entries.includes(m))) bestRoot = dir;
+    } catch { break; }
+    const parentSlash = dir.lastIndexOf("/");
+    if (parentSlash <= 0) break;
+    dir = dir.substring(0, parentSlash);
+  }
+  return bestRoot;
+}
+
+/** Extract absolute file paths from tool_use entries in a JSONL transcript, optionally restricted to `toolNames` (default: any tool). */
+export async function transcriptFilePaths(transcriptPath: string, toolNames?: readonly string[]): Promise<string[]> {
+  const text = readText(transcriptPath);
+  const paths = new Set<string>();
+  for (const line of text.split("\n").filter(Boolean)) {
+    try {
+      const content = (JSON.parse(line) as { message?: { content?: unknown } })?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block?.type !== "tool_use") continue;
+        if (toolNames && !toolNames.includes(block.name)) continue;
+        const fp = block.input?.file_path ?? block.input?.path ?? "";
+        if (typeof fp === "string" && fp.startsWith("/")) paths.add(fp);
+      }
+    } catch { /* skip malformed */ }
+  }
+  return [...paths];
+}
+
+/** Extract deduplicated Edit tool_use entries (keyed by basename) from a transcript. */
+export async function transcriptEdits(transcriptPath: string): Promise<EditEntry[]> {
+  const text = readText(transcriptPath);
+  const edits: EditEntry[] = [];
+  for (const line of text.split("\n").filter(Boolean)) {
+    try {
+      const content = (JSON.parse(line) as { message?: { content?: unknown } })?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block?.type === "tool_use" && block.name === "Edit" && block.input?.file_path) {
+          edits.push({ file: block.input.file_path, oldStr: block.input.old_string ?? "", newStr: block.input.new_string ?? "" });
+        }
+      }
+    } catch { /* skip malformed */ }
+  }
+  const seen = new Map<string, EditEntry>();
+  for (const e of edits) seen.set(e.file.split("/").pop() ?? e.file, e);
+  return [...seen.values()];
+}
+
+/** Extract the last assistant text report (first 500 lines) from a transcript. */
+export async function transcriptReport(transcriptPath: string): Promise<string> {
+  const text = readText(transcriptPath);
+  let lastReport = "";
+  for (const line of text.split("\n").filter(Boolean)) {
+    try {
+      const entry = JSON.parse(line) as { message?: { role?: string; content?: { type?: string; text?: string }[] } };
+      if (entry?.message?.role !== "assistant") continue;
+      for (const block of entry.message.content ?? []) {
+        if (block.type === "text" && block.text) lastReport = block.text;
+      }
+    } catch { /* skip malformed */ }
+  }
+  return lastReport.split("\n").slice(0, 500).join("\n");
+}

package/src/runtime/lifecycle/aipilot/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Cache + APEX interfaces for the ai-pilot scope (separated from implementation
+ * per SOLID interface-segregation).
+ */
+
+/** Index file for the per-project documentation cache. */
+export interface CacheIndex {
+  project: string;
+  docs: CacheEntry[];
+}
+
+/** Single cached document entry in the doc index. */
+export interface CacheEntry {
+  hash: string;
+  library: string;
+  topic: string;
+  timestamp: string;
+  size_kb: number;
+}
+
+/** Lesson entry extracted from a sniper transcript. */
+export interface LessonEntry {
+  error_type: string;
+  pattern: string;
+  fix: string;
+  count: number;
+  last_seen: string;
+  files: string[];
+  code: { line: string[] };
+}
+
+/** An Edit tool_use extracted from a sniper transcript. */
+export interface EditEntry {
+  file: string;
+  oldStr: string;
+  newStr: string;
+}
+
+/** Cached lint/test result for a single source file. */
+export interface TestResult {
+  checksum: string;
+  eslint: "pass" | "fail";
+  tsc: "pass" | "fail";
+  last_tested: string;
+}
+
+/** Test cache structure stored on disk. */
+export interface TestCache {
+  timestamp: string;
+  files: Record<string, TestResult>;
+}
+
+/** A task entry in `.claude/apex/task.json`. */
+export interface ApexTask {
+  subject: string;
+  description: string;
+  status: string;
+  phase: string;
+  started_at?: string;
+  completed_at?: string;
+  created_at?: string;
+  doc_consulted: Record<string, unknown>;
+  files_modified: string[];
+  blockedBy?: string[];
+}
+
+/** Structure of `.claude/apex/task.json`. */
+export interface ApexTaskFile {
+  current_task: string;
+  created_at: string;
+  tasks: Record<string, ApexTask>;
+}

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.`;
+}