@fusengine/harness 0.1.90 → 0.1.92

package/src/policy/apex-authorization.ts

@@ -0,0 +1,100 @@
+import { resolveSessions, type AuthEntry } from "../freshness/doc-helpers";
+import { routeReferences } from "../refs/router";
+import { DEFAULT_TTL_SEC, ttlLabel } from "../config/ttl";
+import { CONTEXT7_SOURCE, getSkillSource } from "./skill-source";
+import type { ApexContext, ApexGate } from "./apex";
+
+/** Pending doc-credit target written on a Check-1 deny (parity enforce-apex-phases.ts:80 `state.target`). */
+export interface SessionTarget {
+  project: string;
+  framework: string;
+  set_by: string;
+  set_at: string;
+}
+
+/**
+ * Credit a doc consultation onto one framework's auth entry (parity
+ * track-doc-consultation.py): the once-per-session Check-2 fields
+ * (`doc_sessions` + `sources`) plus the per-framework Check-1 stamp
+ * (`sessions` + `doc_consulted`). Pure.
+ */
+export function creditDocConsultation(prev: AuthEntry | undefined, sessionId: string, source: string, nowIso: string): AuthEntry {
+  const p = prev ?? {};
+  const add = (list: string[], v: string): string[] => (v && !list.includes(v) ? [...list, v] : list);
+  return {
+    ...p,
+    sessions: add(resolveSessions(p), sessionId),
+    doc_sessions: add(p.doc_sessions ?? [], sessionId),
+    sources: add(p.sources ?? (p.source ? [p.source] : []), source),
+    doc_consulted: nowIso,
+  };
+}
+
+/**
+ * Check 1 (parity enforce-apex-phases.ts isAuthorized): the framework's doc or
+ * skill was consulted in THIS session (resolveSessions) AND the stamp is
+ * younger than the TTL (FUSE_ENFORCE_TTL_SEC via src/config/ttl.ts).
+ */
+export function isAuthorized(auth: AuthEntry | undefined, sessionId: string, now: number, ttlMs: number): boolean {
+  if (!auth?.doc_consulted || !resolveSessions(auth).includes(sessionId)) return false;
+  const readEpoch = Date.parse(auth.doc_consulted);
+  return !Number.isNaN(readEpoch) && now - readEpoch < ttlMs;
+}
+
+/**
+ * A fresh same-session `skills/**.md` read whose path names the framework also
+ * satisfies Check 1 (parity track-doc-consultation.py, which stamps
+ * `doc_consulted` on `skills/.*\.md` Reads; the harness records those Reads in
+ * `refsRead`/`refsReadAt` instead, and the track file is per-session).
+ */
+function skillReadAuthorized(ctx: ApexContext, now: number, ttlMs: number): boolean {
+  // Aliases keep every deny-promised path unblockable: laravel skills say "php",
+  // and tailwind's SKILL.md lives under "tailwindcss[-v4]" where \btailwind\b
+  // never matches (the boundary fails before the "c").
+  const alias: Record<string, string> = { laravel: "laravel|php", tailwind: "tailwindcss?" };
+  const nameRe = new RegExp(`\\b(${alias[ctx.framework] ?? ctx.framework})\\b`, "i");
+  return (ctx.refsRead ?? []).some((p) => {
+    if (!/skills\/.*\.md$/i.test(p) || !nameRe.test(p)) return false;
+    const at = ctx.refsReadAt?.[p];
+    return at !== undefined && now - at < ttlMs;
+  });
+}
+
+/**
+ * Gate (Check 1): deny until the framework's doc/skill is freshly consulted.
+ * The deny lists the routed SOLID refs when refs are loaded (parity
+ * formatRoutedDeny), else the framework's skill source (parity getSkillSource:
+ * a real installed SKILL.md path, or the context7 consigne). The RUNTIME
+ * caller persists `state.target` on deny (recordTarget, parity :80-81) so
+ * recordDoc can cross-credit this framework on the next doc consultation.
+ */
+export const apexAuthorizationGate: ApexGate = (ctx) => {
+  const windowMs = ctx.windowMs ?? DEFAULT_TTL_SEC * 1000;
+  const now = ctx.now ?? Date.now();
+  if (isAuthorized(ctx.authorizations?.[ctx.framework], ctx.sessionId, now, windowMs)) return null;
+  if (skillReadAuthorized(ctx, now, windowMs)) return null;
+  const ttl = ttlLabel(Math.round(windowMs / 1000));
+  const title = `APEX: ${ctx.framework} documentation required`;
+  const routed = ctx.refs?.length ? routeReferences(ctx.refs, ctx.filePath, ctx.content) : null;
+  if (!routed) {
+    // Parity enforce-apex-phases.ts:82-87: getSkillSource (skill-source.ts)
+    // resolves the REAL installed SKILL.md, or yields the context7 consigne —
+    // never SOLID_REF's phantom `${PLUGINS_DIR}/generic/SKILL.md`.
+    const src = getSkillSource(ctx.framework);
+    return {
+      kind: "block",
+      title,
+      reason: `APEX: Read doc first (expires every ${ttl}) for ${ctx.framework}! Source: ${src}`,
+      actions: [src === CONTEXT7_SOURCE ? `Query ${CONTEXT7_SOURCE} for ${ctx.framework} docs` : `Read ${src}`],
+    };
+  }
+  const optional = routed.optional.map((r) => r.meta.filePath);
+  const reason = [
+    // H2b: name the full set (required + Optional) and invite the retry.
+    `APEX: Read ALL SOLID references below (including Optional), then retry (expires every ${ttl}) for ${ctx.framework}.`,
+    `Editing: ${ctx.filePath}`,
+    ...(optional.length ? [`Optional: ${optional.join(", ")}`] : []),
+    `Full skill: ${routed.skillPath}`,
+  ].join("\n");
+  return { kind: "block", title, reason, actions: routed.required.map((r) => r.meta.filePath) };
+};

package/src/policy/apex-gates.ts

@@ -0,0 +1,91 @@
+import { routeReferences } from "../refs/router";
+import { skillRefKey } from "../refs/ref-key";
+import type { Prompt } from "../prompt/types";
+import { DEFAULT_TTL_SEC, ttlLabel } from "../config/ttl";
+import { PLUGINS_DIR, SOLID_REF } from "./file-size";
+import type { ApexContext, ApexGate } from "./apex";
+
+/**
+ * True when the SOLID ref read at `path` still counts. Parity require-solid-read.py
+ * `_check_solid_read` (FUSE_ENFORCE_TTL_SEC, default 120s): a SOLID read older than
+ * the window has expired and must be redone. PARITY NOTE: the TTL applies ONLY to
+ * this gate — Python TTL-izes SOLID reads exclusively; the other refsRead consumers
+ * (skillTriggerGate, shadcn/tailwind/design gates) stay session-scoped, so this
+ * predicate must never leak into them. Backward compat: a path with no `refsReadAt`
+ * stamp (tracks recorded before the field existed) or a context without a clock
+ * (`now` absent) counts as read.
+ */
+function refReadFresh(ctx: ApexContext, path: string, windowMs: number): boolean {
+  const at = ctx.refsReadAt?.[path];
+  return at === undefined || ctx.now === undefined || ctx.now - at < windowMs;
+}
+
+/** Gate: the routed SOLID references for this edit must have been read within the TTL. */
+export const solidReadGate: ApexGate = (ctx: ApexContext) => {
+  if (!ctx.refs?.length) return null;
+  const routed = routeReferences(ctx.refs, ctx.filePath, ctx.content);
+  const windowMs = ctx.windowMs ?? DEFAULT_TTL_SEC * 1000;
+  const ttl = ttlLabel(Math.round(windowMs / 1000));
+  if (!routed) {
+    // Parity require-solid-read.py::_build_reason (the `not routed` branch):
+    // refs ARE loaded but none score for this file — Python still denies here,
+    // pointing at the framework's SKILL.md. Note: `!ctx.refs?.length` above
+    // (no refs installed at all) intentionally stays allow — discoverRefs()'s
+    // documented contract ("with no refs the SOLID-read gate stays off").
+    const ref = SOLID_REF[ctx.framework] ?? "generic/";
+    return {
+      kind: "block",
+      title: `APEX: no SOLID reference matched ${ctx.filePath}`,
+      reason: `${ctx.refs.length} SOLID reference(s) are loaded but none scored for this edit (expires every ${ttl}) — read the framework skill directly instead.`,
+      actions: [`Read ${PLUGINS_DIR}/${ref}SKILL.md`],
+    };
+  }
+  // Only reads still inside the TTL window count — a stale read re-blocks
+  // (parity require-solid-read.py, which re-validates the TTL on EVERY edit,
+  // making the "(expires every …)" wording below actually true).
+  const read = new Set((ctx.refsRead ?? []).filter((p) => refReadFresh(ctx, p, windowMs)));
+  // A sub-agent/teammate reads the SAME skill material through a different
+  // root than the marketplace-first path discoverRefs put in ctx.refs (a
+  // version cache, or a standalone .codex/.cursor/.agents dir) — normalize
+  // both sides to the `skills/<skill>/...` suffix so that read still credits.
+  const readKeys = new Set([...read].map(skillRefKey).filter((k): k is string => k !== null));
+  const credited = (path: string): boolean => {
+    if (read.has(path)) return true;
+    const key = skillRefKey(path);
+    return key !== null && readKeys.has(key);
+  };
+  // Parity with the 3 other refsRead-consuming gates (skillTriggerGate's
+  // `skills/${s}/` substring match, shadcnBaseSkillRead, designSkillRead):
+  // reading the ref's PARENT SKILL.md counts as proof of consultation too,
+  // not just the exact ref file path.
+  const skillRead = !!routed.skillPath && credited(routed.skillPath);
+  const missing = skillRead ? [] : routed.required.map((r) => r.meta.filePath).filter((p) => !credited(p));
+  if (missing.length === 0) return null;
+  const optional = routed.optional.map((r) => r.meta.filePath);
+  const reason = [
+    // H2b: the credit needs the routed refs read — say ALL of them (the
+    // Optional line counts too) and that a retry is EXPECTED once read.
+    `Read ALL references below (including Optional), then retry — required before editing ${ctx.filePath} (expires every ${ttl}):`,
+    ...(optional.length ? [`Optional: ${optional.join(", ")}`] : []),
+    `Full skill: ${routed.skillPath}`,
+  ].join("\n");
+  return {
+    kind: "block",
+    title: `APEX: read SOLID references for ${ctx.framework}`,
+    reason,
+    actions: missing,
+  };
+};
+
+/** Gate: the required prior agents (explore + research) must have run within the window. */
+export const freshnessGate: ApexGate = (ctx: ApexContext): Prompt | null => {
+  if (ctx.agentsFresh !== false) return null;
+  const missing = ctx.missingAgents?.length ? ctx.missingAgents : ["explore-codebase", "research-expert"];
+  const ttl = ttlLabel(Math.round((ctx.windowMs ?? DEFAULT_TTL_SEC * 1000) / 1000));
+  return {
+    kind: "block",
+    title: "APEX: explore + research required",
+    reason: `Run ${missing.join(" and ")} within the freshness window (${ttl} TTL) before editing ${ctx.framework}.`,
+    actions: missing.map((name) => `Launch the ${name} agent`),
+  };
+};

package/src/policy/apex-target-steps.ts

@@ -0,0 +1,73 @@
+/**
+ * Per-target phrasing tables for the APEX task-tracking step trio/pair
+ * (view-pending / mark-in-progress / mark-done) — split out of
+ * `apex-target.ts` to keep both files under the SOLID 100-line ceiling.
+ * Kimi Code CLI's native tool is `TodoList` (single tool, full-list re-emit
+ * per call; status enum is `pending | in_progress | done` — never
+ * `completed`, that is Claude's idiom; omitting `todos` queries the current
+ * list without mutating it). Kimi has no documented auto-commit tied to a
+ * status transition, unlike Claude's `TaskUpdate(completed)` — so these
+ * phrasings must NOT promise one. `TaskList` is a distinct Kimi tool for
+ * async background tasks and must never be used here.
+ */
+import type { HarnessId } from "../detect/interfaces/types";
+import type { ApexTaskSteps, ApexAgentSteps } from "./interfaces/types";
+
+/** Codex/Kimi step-trio overrides; any other target falls back to {@link DEFAULT_TASK_STEPS}. */
+const TASK_STEPS: Partial<Record<HarnessId, ApexTaskSteps>> = {
+  codex: {
+    step3: "update_plan → review the current plan",
+    step4: "update_plan → mark the active step in_progress before starting",
+    step7: "update_plan → mark the step completed when done",
+  },
+  kimi: {
+    step3: "TodoList → review the current list (omit todos to query)",
+    step4: "TodoList → mark the active item in_progress before starting",
+    step7: "TodoList → mark the item done when finished",
+  },
+};
+
+/** Default (Claude Code) step trio — zero-regression fallback for any unlisted target. */
+const DEFAULT_TASK_STEPS: ApexTaskSteps = {
+  step3: "TaskList → see pending tasks",
+  step4: "TaskUpdate(in_progress) → before starting",
+  step7: "TaskUpdate(completed) → triggers auto-commit",
+};
+
+/**
+ * Resolve the step3/step4/step7 phrasing for a harness target (APEX
+ * task-context injection). Replaces the former `isCodex` binary ternary.
+ * @param id - Harness id.
+ * @returns The {@link ApexTaskSteps} for that target.
+ */
+export function apexTaskSteps(id: string): ApexTaskSteps {
+  return TASK_STEPS[id as HarnessId] ?? DEFAULT_TASK_STEPS;
+}
+
+/** Codex/Kimi before/done overrides; any other target falls back to {@link DEFAULT_AGENT_STEPS}. */
+const AGENT_STEPS: Partial<Record<HarnessId, ApexAgentSteps>> = {
+  codex: {
+    beforeStart: "Use update_plan → mark the active step in_progress before starting",
+    whenDone: "update_plan → mark the step completed when done",
+  },
+  kimi: {
+    beforeStart: "Use TodoList → mark the active item in_progress before starting",
+    whenDone: "TodoList → mark the item done when finished",
+  },
+};
+
+/** Default (Claude Code) before/done pair — zero-regression fallback for any unlisted target. */
+const DEFAULT_AGENT_STEPS: ApexAgentSteps = {
+  beforeStart: "Use TaskUpdate(taskId, status: in_progress) before starting",
+  whenDone: "TaskUpdate(taskId, status: completed) triggers auto-commit",
+};
+
+/**
+ * Resolve the beforeStart/whenDone phrasing for a harness target (APEX
+ * sub-agent injection). Replaces the former `isCodex` binary ternary.
+ * @param id - Harness id.
+ * @returns The {@link ApexAgentSteps} for that target.
+ */
+export function apexAgentSteps(id: string): ApexAgentSteps {
+  return AGENT_STEPS[id as HarnessId] ?? DEFAULT_AGENT_STEPS;
+}

package/src/policy/apex-target.ts

@@ -0,0 +1,49 @@
+/**
+ * Harness-target helpers for the APEX context builders. Single source of
+ * truth for the home-dir segment / root doc name / plan-tool idiom that
+ * differ between Claude Code and Codex (and beyond), so the builders in
+ * `claude-md-context.ts`, `apex-task-context.ts`, and `inject-apex.ts` never
+ * hardcode `.claude`/`CLAUDE.md`/`TaskCreate` again. Runtime `id` values flow
+ * through the pipeline as plain `string` (see `handleHook(id: string, ...)`),
+ * so these helpers accept `string` and narrow internally — same idiom as the
+ * existing `HOME_DIR[id] ?? ".claude"` precedent in `cartographer/detect.ts`.
+ */
+import { HOME_DIR } from "../config/dotenv";
+import type { HarnessId } from "../detect/interfaces/types";
+
+/**
+ * Home-dir segment for a harness target (".claude", ".codex", ...). Falls
+ * back to ".claude" for any harness without a {@link HOME_DIR} entry.
+ * @param id - Harness id (e.g. "claude-code", "codex").
+ * @returns The home-dir segment, e.g. ".claude".
+ */
+export function harnessHomeSegment(id: string): string {
+  return HOME_DIR[id as HarnessId] ?? ".claude";
+}
+
+/**
+ * Root instructions doc name for a harness target: "AGENTS.md" for Codex and
+ * Kimi Code CLI (both documented conventions), "CLAUDE.md" for every other
+ * target (including the default/unknown fallback).
+ * @param id - Harness id.
+ * @returns The doc file name.
+ */
+export function apexDocName(id: string): string {
+  return id === "codex" || id === "kimi" ? "AGENTS.md" : "CLAUDE.md";
+}
+
+/**
+ * Native plan/track tool name for a harness target: Codex's `update_plan`,
+ * Kimi Code CLI's `TodoList`, or Claude's `TaskCreate` (default). Covers only
+ * the PLAN-step line — other target-specific tool references (`TaskList`,
+ * `TaskUpdate`) are resolved via `apexTaskSteps`/`apexAgentSteps` in
+ * `apex-target-steps.ts` since their surrounding prose differs structurally,
+ * not just by token.
+ * @param id - Harness id.
+ * @returns The plan-tool name.
+ */
+export function apexPlanTool(id: string): string {
+  if (id === "codex") return "update_plan";
+  if (id === "kimi") return "TodoList";
+  return "TaskCreate";
+}

package/src/policy/apex-task-context.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveMaxLines } from "../config/limits";
+import { harnessHomeSegment } from "./apex-target";
+import { apexTaskSteps } from "./apex-target-steps";
+
+/** Parsed task state injected into a Task sub-agent prompt. */
+export interface ApexTaskState {
+  /** Current task id (defaults to "1"). */
+  id: string;
+  /** Task subject (defaults to ""). */
+  subject: string;
+  /** Current phase (defaults to "analyze"). */
+  phase: string;
+  /** Comma-joined consulted doc keys, or "none". */
+  docs: string;
+}
+
+/**
+ * Read the current task state from `task.json`, reproducing the legacy Python
+ * logic. Any read/parse error falls back to `("1", "", "analyze", "none")`.
+ * @param taskFile - Absolute path to `.claude/apex/task.json`.
+ * @returns The parsed {@link ApexTaskState}.
+ */
+export function loadApexTaskState(taskFile: string): ApexTaskState {
+  try {
+    const data = JSON.parse(readFileSync(taskFile, "utf-8")) as Record<string, unknown>;
+    const id = String(data.current_task ?? "1");
+    const tasks = (data.tasks as Record<string, unknown> | undefined) ?? {};
+    const task = (tasks[id] as Record<string, unknown> | undefined) ?? {};
+    const subject = typeof task.subject === "string" ? task.subject : "";
+    const phase = typeof task.phase === "string" ? task.phase : "analyze";
+    const consultedMap = (task.doc_consulted as Record<string, unknown> | undefined) ?? {};
+    const consulted = Object.entries(consultedMap)
+      .filter(([, v]) => typeof v === "object" && v !== null && (v as Record<string, unknown>).consulted === true)
+      .map(([k]) => k);
+    return { id, subject, phase, docs: consulted.join(", ") || "none" };
+  } catch {
+    return { id: "1", subject: "", phase: "analyze", docs: "none" };
+  }
+}
+
+/**
+ * Build the APEX context string injected into a Task sub-agent prompt.
+ * @param state - The parsed task state.
+ * @param maxLines - SOLID per-file line ceiling.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The injection text.
+ */
+export function buildApexTaskContext(state: ApexTaskState, maxLines: number, id: string = "claude-code"): string {
+  const seg = harnessHomeSegment(id);
+  const { step3, step4, step7 } = apexTaskSteps(id);
+  return (
+    `⚠️ APEX MODE - Read ${seg}/apex/AGENTS.md for rules\n\n` +
+    `Current: Task #${state.id} - ${state.subject} (Phase: ${state.phase})\n` +
+    `Docs consulted: ${state.docs}\n\n` +
+    `Agent must:\n` +
+    `1. Read task.json → find last 3 completed tasks\n` +
+    `2. Read their notes in docs/ (task-{ID}-{subject}.md)\n` +
+    `3. ${step3}\n` +
+    `4. ${step4}\n` +
+    `5. Apply SOLID (files < ${maxLines} lines)\n` +
+    `6. Write notes to docs/task-{ID}-{subject}.md\n` +
+    `7. ${step7}`
+  );
+}
+
+/**
+ * Build the PreToolUse Task injection, gated on the existence of the
+ * project's target apex dir (`.claude/apex/`, `.codex/apex/`, ...). Returns
+ * `null` when APEX is not active (no dir).
+ * @param projectRoot - `CLAUDE_PROJECT_DIR` or cwd.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The injection text, or `null` to emit nothing.
+ */
+export function buildApexTaskInjection(projectRoot: string, id: string = "claude-code"): string | null {
+  const apexDir = join(projectRoot, harnessHomeSegment(id), "apex");
+  if (!existsSync(apexDir)) return null;
+  const state = loadApexTaskState(join(apexDir, "task.json"));
+  return buildApexTaskContext(state, resolveMaxLines(), id);
+}

package/src/policy/apex.ts

@@ -0,0 +1,94 @@
+import { formatDocDeny, isDocConsulted, type AuthEntry } from "../freshness/doc-helpers";
+import type { RefMeta } from "../refs/types";
+import type { Prompt } from "../prompt/types";
+
+/**
+ * Session context for the stateful APEX gates. The harness adapter supplies this
+ * (the package owns the gate LOGIC; recording the session activity is the
+ * adapter's tracking layer).
+ */
+export interface ApexContext {
+  sessionId: string;
+  framework: string;
+  filePath: string;
+  content: string;
+  /** Doc-consultation authorizations from session state (Context7/Exa). */
+  authorizations?: Record<string, AuthEntry>;
+  /** Available SOLID references for the framework's skill. */
+  refs?: RefMeta[];
+  /** Absolute paths of SOLID refs already read this session. */
+  refsRead?: string[];
+  /**
+   * Epoch-ms read timestamp per `refsRead` path (parity track-solid-reads.py
+   * `solid_reads[].timestamp`). PARITY: the TTL applies ONLY to solidReadGate —
+   * Python TTL-izes SOLID reads exclusively (require-solid-read.py); the
+   * skill-trigger/design/shadcn gates stay session-scoped (no TTL). A path in
+   * `refsRead` with no stamp here (tracks recorded before this field existed)
+   * counts as read — backward compat.
+   */
+  refsReadAt?: Record<string, number>;
+  /** Current epoch ms for the SOLID-read TTL check; absent → reads never expire. */
+  now?: number;
+  /** Whether the required prior agents (explore + research) ran within the freshness window. */
+  agentsFresh?: boolean;
+  /** Names of REQUIRED_AGENTS that have NOT run fresh (subset), for a precise freshnessGate message. Absent → generic wording. */
+  missingAgents?: string[];
+  /** Freshness window in ms: labels the block messages' TTL (e.g. "2min") and bounds the SOLID-read TTL in solidReadGate. */
+  windowMs?: number;
+  /** Whether brainstorming is required for this edit (creation intent on a new file). */
+  brainstormRequired?: boolean;
+  /** Whether the brainstorming agent ran within the window. */
+  brainstormFresh?: boolean;
+}
+
+/** A single APEX gate: returns a blocking {@link Prompt}, or null to pass. */
+export type ApexGate = (ctx: ApexContext) => Prompt | null;
+
+/** Gate: BOTH Context7 AND Exa (or a web fallback alone) must have been consulted this session. */
+export const docConsultedGate: ApexGate = (ctx) =>
+  isDocConsulted(ctx.authorizations, ctx.sessionId)
+    ? null
+    : {
+        kind: "block",
+        title: "APEX: documentation not consulted",
+        reason: formatDocDeny(ctx.framework),
+        actions: ["Use BOTH mcp__context7__query-docs AND mcp__exa__web_search_exa, or a web fallback alone (WebSearch/WebFetch)"],
+      };
+
+/** Gate: brainstorming must precede creating new files when flagged. */
+export const brainstormGate: ApexGate = (ctx) =>
+  ctx.brainstormRequired && ctx.brainstormFresh === false
+    ? {
+        kind: "block",
+        title: "APEX: brainstorm first",
+        reason: `Creation intent detected — brainstorm before creating new ${ctx.framework} files.`,
+        actions: ["Launch the brainstorming agent"],
+      }
+    : null;
+
+// solidReadGate/freshnessGate live in ./apex-gates (kept out of this file for
+// the SOLID file-size ceiling — they import ApexContext/ApexGate from here).
+export { solidReadGate, freshnessGate } from "./apex-gates";
+import { solidReadGate, freshnessGate } from "./apex-gates";
+
+/** Gates that run BEFORE Check 1 (harness-specific brainstorm + agent freshness, pre-dating enforce-apex-phases). */
+export const PRE_AUTH_GATES: ReadonlyArray<ApexGate> = [brainstormGate, freshnessGate];
+
+/** Gates that run AFTER Check 1: Check 2 (doc consulted once per session) then the SOLID refs. */
+export const POST_AUTH_GATES: ReadonlyArray<ApexGate> = [docConsultedGate, solidReadGate];
+
+/**
+ * Default APEX gate chain (brainstorm, freshness, docs, SOLID refs). Check 1
+ * (`apexAuthorizationGate`, policy/apex-authorization.ts) is wired BETWEEN the
+ * PRE and POST sub-chains by the runtime (gate-apex.ts), which owns its
+ * target-write side effect — parity enforce-apex-phases.ts Check1 -> Check2.
+ */
+export const APEX_GATES: ReadonlyArray<ApexGate> = [...PRE_AUTH_GATES, ...POST_AUTH_GATES];
+
+/**
+ * Run the APEX gates (chain-of-responsibility): the first failing gate's prompt
+ * wins; null means every gate passed (allow).
+ */
+export function evaluateApex(ctx: ApexContext, gates: ReadonlyArray<ApexGate> = APEX_GATES): Prompt | null {
+  return gates.reduce<Prompt | null>((hit, gate) => hit ?? gate(ctx), null);
+}

package/src/policy/cartographer/build-tree.ts

@@ -0,0 +1,69 @@
+/**
+ * Indented Unicode tree from scanned plugin items — pure text in, markdown out
+ * (no fs). Ports `build_tree.py`.
+ */
+
+/** A scanned `[type, name, desc]` plugin item (agent/skill/command/hooks). */
+export type ScanRow = readonly [type: string, name: string, desc: string];
+
+const SECTION_ORDER: readonly string[] = ["agent", "skill", "command"];
+
+/**
+ * Format grouped items with tree connectors and optional markdown links.
+ * Skill sections link to `./skills/<name>/index.md`; other sections to
+ * `./<folder>/<name>.md`; unlinked sections render the bare name.
+ * @param prefix - The line prefix (indent + branch glyphs).
+ * @param items - The `[name, desc]` pairs to render.
+ * @param folder - The link folder ("" disables linking).
+ * @param asDirs - Whether items link to a subdirectory `index.md`.
+ * @returns The rendered lines.
+ */
+function printItems(prefix: string, items: ReadonlyArray<[string, string]>, folder: string, asDirs: boolean): string[] {
+  return items.map(([name, desc], i) => {
+    const connector = i === items.length - 1 ? "└──" : "├──";
+    const safe = name.replace(/^\/+/, "");
+    let label = name;
+    if (folder && asDirs) label = `[${name}](./${folder}/${safe}/index.md)`;
+    else if (folder) label = `[${name}](./${folder}/${safe}.md)`;
+    const short = desc && desc !== "(no description)" ? ` — ${desc.slice(0, 80)}` : "";
+    return `${prefix}${connector} ${label}${short}`;
+  });
+}
+
+/**
+ * Build an indented tree from scanned items. The `hooks` row renders as a single
+ * trailing `└── hooks: …` line; agents/skills/commands render as folder sections.
+ * @param items - The scanned `[type, name, desc]` rows.
+ * @param linked - When true, leaf names become markdown links.
+ * @returns The joined tree text.
+ */
+export function buildTree(items: ReadonlyArray<ScanRow>, linked: boolean = false): string {
+  const groups: Record<string, [string, string][]> = {};
+  let hooksLine = "";
+  for (const [typ, name, desc] of items) {
+    if (typ === "hooks") hooksLine = name;
+    else (groups[typ] ??= []).push([name, desc]);
+  }
+
+  const sections = SECTION_ORDER.filter((s) => s in groups);
+  if (hooksLine) sections.push("hooks");
+
+  const lines: string[] = [];
+  const total = sections.length;
+  for (let idx = 0; idx < total; idx++) {
+    const section = sections[idx] ?? "";
+    if (section === "hooks") {
+      lines.push(`└── hooks: ${hooksLine}`);
+      continue;
+    }
+    const isLast = idx === total - 1;
+    const folder = `${section}s`;
+    const prefix = isLast ? "└──" : "├──";
+    const subPrefix = isLast ? "    " : "│   ";
+    lines.push(`${prefix} ${folder}/`);
+    const linkFolder = linked ? folder : "";
+    const isDirSection = section === "skill";
+    lines.push(...printItems(subPrefix, groups[section] ?? [], linkFolder, linked && isDirSection));
+  }
+  return lines.join("\n");
+}

package/src/policy/cartographer/describe.ts

@@ -0,0 +1,53 @@
+/**
+ * File-description heuristics — pure text in, description out (no fs). Ports
+ * `describe.py`.
+ */
+
+const SOURCE_SUFFIXES: ReadonlySet<string> = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".swift"]);
+
+/**
+ * First `# ` Markdown heading text (sans hashes), sliced to 60. "" when none.
+ * @param text - The document text.
+ * @returns The heading text, or "".
+ */
+export function firstHeading(text: string): string {
+  for (const line of text.split("\n")) {
+    if (line.startsWith("# ")) return line.replace(/^#+/, "").trim().slice(0, 60);
+  }
+  return "";
+}
+
+/**
+ * First leading comment among the first 10 lines (`//`, `#` but not `#!`, or a
+ * `"""`/`'''` docstring), sliced to 60. "" when none.
+ * @param text - The source text.
+ * @returns The comment text, or "".
+ */
+export function firstComment(text: string): string {
+  const lines = text.split("\n").slice(0, 10);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if ((line.startsWith("//") || line.startsWith("#")) && !line.startsWith("#!")) {
+      return line.replace(/^[/#! ]+/, "").slice(0, 60);
+    }
+    if (line.startsWith('"""') || line.startsWith("'''")) {
+      return line.replace(/^['"\s]+|['"\s]+$/g, "").slice(0, 60);
+    }
+  }
+  return "";
+}
+
+/**
+ * Derive a description from a file's suffix + text. For `.md`, the supplied
+ * frontmatter `description` (truncated) wins over the first heading; for known
+ * source suffixes, the first comment; else "".
+ * @param suffix - The file extension (with dot).
+ * @param text - The file text.
+ * @param mdField - The pre-parsed frontmatter `description` (md only).
+ * @returns The derived description, or "".
+ */
+export function descFromText(suffix: string, text: string, mdField: string): string {
+  if (suffix === ".md") return mdField.slice(0, 60) || firstHeading(text);
+  if (SOURCE_SUFFIXES.has(suffix)) return firstComment(text);
+  return "";
+}

package/src/policy/cartographer/entry.ts

@@ -0,0 +1,38 @@
+/**
+ * Tree-entry parsing — pure line regexes. Ports the line parsers of
+ * `merge_index.py` and `track-enrichment.py`.
+ */
+
+/** A parsed `prefix[name](path) — desc` tree line. */
+export interface TreeEntry {
+  prefix: string;
+  name: string;
+  path: string;
+  desc: string;
+}
+
+const ENTRY_RE = /^(.*?)\[([^\]]+)\]\(([^)]+)\)\s*(?:—|-{1,2})\s*(.*)$/;
+const ENRICH_RE = /^(?:.*?)\[([^\]]+)\]\(([^)]+)\)\s*(?:—|-{1,2})\s*(.+)$/;
+
+/**
+ * Parse a `merge_index` tree line into its parts. Returns null on no match.
+ * @param line - The raw tree line.
+ * @returns The parsed entry, or null.
+ */
+export function parseEntry(line: string): TreeEntry | null {
+  const m = ENTRY_RE.exec(line);
+  if (!m || m[1] === undefined || m[2] === undefined || m[3] === undefined || m[4] === undefined) return null;
+  return { prefix: m[1], name: m[2], path: m[3], desc: m[4] };
+}
+
+/**
+ * Parse an enrichment line into `[path, desc]`, requiring a non-empty desc.
+ * @param line - The raw index line.
+ * @returns The `[path, desc]` pair, or null.
+ */
+export function parseEnrichment(line: string): [string, string] | null {
+  const m = ENRICH_RE.exec(line);
+  if (!m || m[2] === undefined || m[3] === undefined) return null;
+  const desc = m[3].trim();
+  return desc ? [m[2], desc] : null;
+}