@fusengine/harness 0.1.90 → 0.1.92

package/src/runtime/lifecycle/aipilot/doc-cache-gate.ts

@@ -0,0 +1,69 @@
+/**
+ * @module aipilot/doc-cache-gate
+ * PreToolUse gate for the ai-pilot scope: DENY a Context7/Exa doc call when the
+ * per-project doc cache already holds that library fresh (< 7d). Ports the
+ * source `doc-cache-gate.ts`. The inject side (`inject-doc.ts`) serves the same
+ * cache on SubagentStart; this side avoids the redundant live re-query.
+ * @packageDocumentation
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile } from "../../../util/json-io";
+import { pathExists } from "../../../util/runtime-io";
+import { denyResponse } from "../../../adapters/claude";
+import { cacheDirFor, cacheAge, projectHash, DOC_CACHE_TTL_SECONDS } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import { canonicalizeMcpToolName } from "../../mcp-tool-name";
+import type { CacheIndex } from "./types";
+
+const GATED_TOOLS = /context7__query-docs|exa__get_code_context|exa__web_search/;
+
+/** The library key a gated tool call targets (Context7 libraryId / Exa query), or "". */
+function libraryOf(payload: Record<string, unknown>): string {
+  const tool = String(payload.tool_name ?? "");
+  const input = (payload.tool_input as Record<string, unknown> | undefined) ?? {};
+  if (tool.includes("context7")) {
+    // Real mcp__context7__query-docs input is {libraryId, query} — no "topic"
+    // field exists (confirmed against cache-doc.ts and mcp-key.ts's queryOf,
+    // which both key on `query`, never `topic`).
+    const libraryId = typeof input.libraryId === "string" ? input.libraryId : "";
+    const query = typeof input.query === "string" ? input.query : "";
+    return libraryId && query ? libraryId : "";
+  }
+  if (tool.includes("exa")) return typeof input.query === "string" ? input.query : "";
+  return "";
+}
+
+/**
+ * DENY a redundant doc call when the library is cached fresh, else `null`.
+ * @param payload - The raw PreToolUse hook payload.
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @param home - Home dir (defaults to `~`).
+ * @param id - Harness adapter id (defaults to "claude-code"); on `"codex"`,
+ *   `payload.tool_name` is canonicalized before the {@link GATED_TOOLS} match
+ *   so the Codex-mangled underscore form (`mcp__context7__query_docs`) gates
+ *   exactly like the dash form does on every other harness.
+ * @returns A native deny response, or `null` to fall through to the live call.
+ */
+export async function docCacheGate(payload: Record<string, unknown>, cwd: string, now: number = Date.now(), home: string = homedir(), id: string = "claude-code"): Promise<string | null> {
+  const tool = canonicalizeMcpToolName(id, String(payload.tool_name ?? ""));
+  if (!GATED_TOOLS.test(tool)) return null;
+  const library = libraryOf(payload);
+  if (!library) return null;
+
+  const projPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const cacheDir = cacheDirFor("doc", projPath, home);
+  const index = await readJsonFile<CacheIndex>(join(cacheDir, "index.json"));
+  const entry = index?.docs?.find((d) => d.library === library);
+  if (!entry?.hash || !entry.timestamp) return null;
+
+  const docFile = join(cacheDir, "docs", `${entry.hash}.md`);
+  if (!pathExists(docFile)) return null;
+  const age = cacheAge(entry.timestamp, now);
+  if (age >= DOC_CACHE_TTL_SECONDS) return null;
+
+  logCacheEvent("doc", "blocked", projectHash(projPath), { library }, home);
+  const ageH = Math.floor(age / 3600);
+  return denyResponse("PreToolUse", `Doc already cached at ${docFile} (age: ${ageH}h). Use the Read tool to access it instead of re-querying.`);
+}

package/src/runtime/lifecycle/aipilot/inject-apex.ts

@@ -0,0 +1,98 @@
+/**
+ * SubagentStart (matcher "") for the ai-pilot scope: inject APEX AGENTS.md +
+ * task context + cartographer paths into every sub-agent. Ports
+ * `inject-subagent-context.ts`. The core-scope SubagentStart already surfaces
+ * the MCP cache table (`subagent-cache.ts`) in a separate hook entry — this
+ * handler only emits the APEX/cartographer block, so there is no double-emit.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { readJsonFile } from "../../../util/json-io";
+import { readText } from "../../../util/runtime-io";
+import { resolveMaxLines } from "../../../config/limits";
+import { contextResponse } from "../../../adapters/claude";
+import { capFragment } from "../../inject-budget";
+import { harnessHomeSegment } from "../../../policy/apex-target";
+import { apexAgentSteps } from "../../../policy/apex-target-steps";
+import type { ApexTaskFile } from "./types";
+
+type TaskMap = ApexTaskFile["tasks"];
+
+/** Last 3 completed task subjects (newest first), or "none". */
+function completedTasks(tasks: TaskMap): string {
+  const done = Object.entries(tasks)
+    .filter(([, t]) => t.status === "completed")
+    .sort((a, b) => (b[1].completed_at ?? "").localeCompare(a[1].completed_at ?? ""))
+    .slice(0, 3)
+    .map(([id, t]) => `#${id}: ${t.subject}`);
+  return done.length > 0 ? done.join(", ") : "none";
+}
+
+/** Pending task subjects, or "none". */
+function pendingTasks(tasks: TaskMap): string {
+  const pending = Object.entries(tasks)
+    .filter(([, t]) => t.status === "pending")
+    .map(([id, t]) => `#${id}: ${t.subject}`);
+  return pending.length > 0 ? pending.join(", ") : "none";
+}
+
+/** Cartographer navigation block, or "" when no plugin map is present. */
+function cartographerContext(): string {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!pluginRoot) return "";
+  const pluginsMap = resolve(pluginRoot, "..", ".cartographer", "index.md");
+  if (!existsSync(pluginsMap)) return "";
+  return `\n### 7. Cartographer Maps\nNavigate branches (index.md) -> leaves link to real files:\n- Plugin skills: ${pluginsMap}\n- Project files: .cartographer/project/index.md`;
+}
+
+/**
+ * Build the APEX sub-agent injection for SubagentStart, or "" when the project has no target apex dir (`.claude/apex/`, `.codex/apex/`, ...). Reads AGENTS.md (first 4KB) + task.json.
+ * @param cwd - Fallback project root when `CLAUDE_PROJECT_DIR` is unset.
+ * @param home - Home dir (unused placeholder; kept for symmetry/testing).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export async function injectApexSubagentContext(cwd: string, home: string = homedir(), id: string = "claude-code"): Promise<string> {
+  void home;
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const seg = harnessHomeSegment(id);
+  const apexDir = join(projectRoot, seg, "apex");
+  if (!existsSync(apexDir)) return "";
+
+  const agentsPath = join(apexDir, "AGENTS.md");
+  const agents = existsSync(agentsPath) ? readText(agentsPath).slice(0, 4000) : "";
+  const taskData = await readJsonFile<ApexTaskFile>(join(apexDir, "task.json"));
+  const completed = taskData ? completedTasks(taskData.tasks) : "none";
+  const pending = taskData ? pendingTasks(taskData.tasks) : "none";
+  const { beforeStart, whenDone } = apexAgentSteps(id);
+
+  const context = `## APEX Sub-Agent Instructions
+
+You are a sub-agent in APEX workflow. Follow these rules:
+
+### 1. AGENTS.md Rules
+${agents}
+
+### 2. Task Context
+- Last completed: ${completed}
+- Pending: ${pending}
+
+### 3. Before Starting Work
+- ${beforeStart}
+
+### 4. SOLID Rules
+- Files < ${resolveMaxLines()} lines | Interfaces in src/interfaces/ | JSDoc/PHPDoc required
+
+### 5. Research Before Code
+- Use Context7/Exa for docs | Write notes to ${seg}/apex/docs/
+
+### 6. Before Done (NEVER skip)
+- eLicit: self-review with a NAMED elicitation technique; fix findings first
+- Verify: run/functional-check your changes (references⇔declarations)
+
+### 7. When Done
+- ${whenDone}${cartographerContext()}`;
+
+  return contextResponse("SubagentStart", capFragment("apex-subagent", context));
+}

package/src/runtime/lifecycle/aipilot/inject-doc.ts

@@ -0,0 +1,62 @@
+/**
+ * SubagentStart (matcher "research-expert") for the ai-pilot scope: inject
+ * cached documentation summaries. Ports `doc-cache-inject.ts`. Doc *saving*
+ * happens on SubagentStop (`cache-doc.ts`).
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile } from "../../../util/json-io";
+import { readText, pathExists } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { cacheDirFor, cacheAge, projectHash, DOC_CACHE_TTL_SECONDS } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import type { CacheEntry, CacheIndex } from "./types";
+
+const MAX_SIZE = 8192;
+
+/** Concatenate fresh, dedup-by-hash cached doc bodies. */
+async function buildDocsContext(entries: CacheEntry[], docsDir: string, now: number): Promise<{ ctx: string; count: number; maxAge: number }> {
+  let ctx = "";
+  let count = 0;
+  let maxAge = 0;
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    if (!entry.timestamp) continue;
+    const age = cacheAge(entry.timestamp, now);
+    if (age >= DOC_CACHE_TTL_SECONDS) continue;
+    if (age > maxAge) maxAge = age;
+    if (!entry.hash || seen.has(entry.hash)) continue;
+    seen.add(entry.hash);
+    const docPath = join(docsDir, `${entry.hash}.md`);
+    if (!pathExists(docPath)) continue;
+    const content = readText(docPath);
+    if (!content) continue;
+    ctx += `\n${content}\n`;
+    count++;
+  }
+  return { ctx, count, maxAge };
+}
+
+/**
+ * SubagentStart for research-expert: inject cached doc summaries, or "".
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (possibly empty).
+ */
+export async function injectDocCache(cwd: string, home: string = homedir(), now: number = Date.now()): Promise<string> {
+  const projPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const pHash = projectHash(projPath);
+  const cacheDir = cacheDirFor("doc", projPath, home);
+  const index = await readJsonFile<CacheIndex>(join(cacheDir, "index.json"));
+  if (!index?.docs?.length) return "";
+
+  const { ctx, count, maxAge } = await buildDocsContext(index.docs, join(cacheDir, "docs"), now);
+  if (count === 0) return "";
+  logCacheEvent("doc", "hit", pHash, { docs_injected: count }, home);
+
+  const ageH = Math.ceil(maxAge / 3600);
+  const header = `## CACHED DOCUMENTATION (${count} docs, ${ageH}h ago)\nUse this knowledge. Only query Context7 for topics NOT covered below.\n`;
+  const full = `${header}${ctx}Full docs: ${join(cacheDir, "docs")}/`.slice(0, MAX_SIZE);
+  return contextResponse("SubagentStart", full);
+}

package/src/runtime/lifecycle/aipilot/inject-explore.ts

@@ -0,0 +1,64 @@
+/**
+ * SubagentStart (matcher "explore-codebase") for the ai-pilot scope: serve a
+ * cached architecture report when fresh + config-matching, else inject save
+ * instructions. Ports `explore-cache-check.ts`.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile } from "../../../util/json-io";
+import { readText, pathExists, spawnCapture } from "../../../util/runtime-io";
+import { contextResponse } from "../../../adapters/claude";
+import { hashText16, cacheDirFor, cacheAge, projectHash } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+
+const TTL_SECONDS = 86_400;
+const CONFIG_FILES = ["package.json", "tsconfig.json", "composer.json", "go.mod", "Cargo.toml", "Package.swift", "biome.json", ".eslintrc.js", ".eslintrc.json"];
+
+/** Compute a config hash from git-tracked config files; "noconfig" on failure. */
+async function configHash(cwd: string): Promise<string> {
+  try {
+    const output = spawnCapture("git", ["ls-tree", "HEAD", ...CONFIG_FILES], cwd);
+    return output.trim() ? hashText16(output) : "noconfig";
+  } catch {
+    return "noconfig";
+  }
+}
+
+/** Build the cache-miss save-instructions block. */
+function missBlock(cacheDir: string, metaFile: string, snapFile: string, ts: string, cfgHash: string, projPath: string): string {
+  return `## EXPLORATION CACHE INSTRUCTIONS\nAfter completing your exploration, save the report for future runs:\n\`\`\`bash\nmkdir -p ${cacheDir}\ncat > ${metaFile} << 'METAEOF'\n{"timestamp":"${ts}","config_hash":"${cfgHash}","project":"${projPath}"}\nMETAEOF\n\`\`\`\nThen write your full exploration report (markdown) to: ${snapFile}`;
+}
+
+/**
+ * SubagentStart for explore-codebase: inject cached architecture or save block.
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout.
+ */
+export async function injectExploreCache(cwd: string, home: string = homedir(), now: number = Date.now()): Promise<string> {
+  const projPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const pHash = projectHash(projPath);
+  const cacheDir = cacheDirFor("explore", projPath, home);
+  const metaFile = join(cacheDir, "metadata.json");
+  const snapFile = join(cacheDir, "snapshot.md");
+  const cfgHash = await configHash(projPath);
+
+  let context = "";
+  const meta = await readJsonFile<{ timestamp: string; config_hash: string }>(metaFile);
+  const snapshot = pathExists(snapFile) ? readText(snapFile) : "";
+
+  if (meta?.timestamp && snapshot) {
+    const age = cacheAge(meta.timestamp, now);
+    if (age < TTL_SECONDS && meta.config_hash === cfgHash) {
+      context = `## CACHED ARCHITECTURE AVAILABLE (age: ${Math.floor(age / 60)}min)\nUSE this cached report. Do NOT run full exploration. Return it immediately.\n\n${snapshot}`;
+      logCacheEvent("explore", "hit", pHash, {}, home);
+    }
+  }
+  if (!context) {
+    logCacheEvent("explore", "miss", pHash, {}, home);
+    const ts = new Date(now).toISOString().replace(/\.\d+Z$/, "");
+    context = missBlock(cacheDir, metaFile, snapFile, ts, cfgHash, projPath);
+  }
+  return contextResponse("SubagentStart", context);
+}

package/src/runtime/lifecycle/aipilot/inject-lessons.ts

@@ -0,0 +1,61 @@
+/**
+ * SubagentStart (matcher "") for the ai-pilot scope: inject cached lessons
+ * (known project issues) into every agent. Ports `lessons-cache-inject.ts`.
+ */
+import { homedir } from "node:os";
+import { readdirSync, statSync, unlinkSync } from "node:fs";
+import { contextResponse } from "../../../adapters/claude";
+import { cacheDirFor, projectHash } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import { detectStack } from "./source-scan";
+import { aggregateLocalLessons, loadGlobalLessons, mergeLessons } from "./lessons";
+import type { LessonEntry } from "./types";
+
+const MAX_AGE_MS = 30 * 86_400_000;
+const MAX_LESSONS = 10;
+
+/** Remove JSON files older than 30 days from `dir` (best effort). */
+function pruneOldFiles(dir: string, now: number): void {
+  try {
+    const cutoff = now - MAX_AGE_MS;
+    for (const f of readdirSync(dir).filter((n) => n.endsWith(".json"))) {
+      const path = `${dir}/${f}`;
+      try { if (statSync(path).mtimeMs < cutoff) unlinkSync(path); } catch { /* skip */ }
+    }
+  } catch { /* dir may not exist */ }
+}
+
+/** Render lessons as a numbered known-issues list. */
+function formatLessonList(lessons: LessonEntry[]): string {
+  return lessons.map((l, i) => {
+    const code = l.code?.line?.length ? `\n     Code: ${l.code.line.join(" | ").slice(0, 200)}` : "";
+    return `${i + 1}. [${l.count}x] | ${l.pattern ?? "unknown"} -> ${l.fix ?? "see docs"}${code}`;
+  }).join("\n");
+}
+
+/**
+ * SubagentStart lessons injection: aggregate local + global lessons, or "".
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (possibly empty).
+ */
+export async function injectLessonsCache(cwd: string, home: string = homedir(), now: number = Date.now()): Promise<string> {
+  const projectPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const pHash = projectHash(projectPath);
+  const cacheDir = cacheDirFor("lessons", projectPath, home);
+  const stack = detectStack(projectPath);
+
+  pruneOldFiles(cacheDir, now);
+  let localLessons: LessonEntry[] = [];
+  try { localLessons = await aggregateLocalLessons(cacheDir); } catch { /* none */ }
+  const globalLessons = await loadGlobalLessons(stack, home);
+  if (localLessons.length === 0 && globalLessons.length === 0) return "";
+
+  const merged = mergeLessons(localLessons, globalLessons).slice(0, MAX_LESSONS);
+  if (merged.length === 0) return "";
+  logCacheEvent("lessons", "hit", pHash, { count: merged.length, stack }, home);
+
+  const ctx = `## KNOWN PROJECT ISSUES (from previous sniper validations)\nThese errors have been found and fixed before. AVOID them:\n${formatLessonList(merged)}\n\nINSTRUCTION: Check your code against these known issues BEFORE submitting.`;
+  return contextResponse("SubagentStart", ctx);
+}

package/src/runtime/lifecycle/aipilot/inject-test.ts

@@ -0,0 +1,48 @@
+/**
+ * SubagentStart (matcher "sniper") for the ai-pilot scope: tell sniper which
+ * source files changed vs. already-validated. Ports `test-cache-inject.ts`.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile } from "../../../util/json-io";
+import { contextResponse } from "../../../adapters/claude";
+import { cacheDirFor, cacheAge, fileChecksum } from "./cache-base";
+import { scanSourceFiles } from "./source-scan";
+import type { TestCache } from "./types";
+
+const TTL_SECONDS = 172_800;
+
+/**
+ * SubagentStart for sniper: inject the changed-file list, or "" when nothing
+ * useful to say (no cache / no unchanged files).
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (possibly empty).
+ */
+export async function injectTestCache(cwd: string, home: string = homedir(), now: number = Date.now()): Promise<string> {
+  const projectPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const resultsPath = join(cacheDirFor("tests", projectPath, home), "results.json");
+  const cache = await readJsonFile<TestCache>(resultsPath);
+  if (!cache?.files || Object.keys(cache.files).length === 0) return "";
+
+  const srcFiles = await scanSourceFiles(projectPath);
+  if (srcFiles.length === 0) return "";
+
+  const changed: string[] = [];
+  let unchanged = 0;
+  for (const filepath of srcFiles) {
+    const relPath = filepath.replace(`${projectPath}/`, "");
+    const cached = cache.files[relPath];
+    if (!cached) { changed.push(relPath); continue; }
+    const currentSum = (await fileChecksum(filepath)).slice(0, 16);
+    if (currentSum !== cached.checksum) { changed.push(relPath); continue; }
+    if (cached.last_tested && cacheAge(cached.last_tested, now) > TTL_SECONDS) { changed.push(relPath); continue; }
+    unchanged++;
+  }
+  if (unchanged === 0) return "";
+
+  const changedList = changed.map((f) => `- ${f}`).join("\n");
+  const ctx = `## TEST CACHE (${unchanged}/${srcFiles.length} files already validated)\nOnly run linters on these CHANGED files:\n${changedList}\nSKIP linting on ${unchanged} unchanged files - already PASS.`;
+  return contextResponse("SubagentStart", ctx);
+}

package/src/runtime/lifecycle/aipilot/lesson-archive.ts

@@ -0,0 +1,60 @@
+/**
+ * Stage 1 — cap→archive split for LESSON.md. When deduped bullets exceed CAP the
+ * OLDEST excess is MOVED (never deleted) to LESSON-archive.md, EXCEPT a
+ * `[TRIGGERS …]` bullet younger than STALE_DAYS: archiving it would blind the
+ * PreToolUse trigger index (src/policy/lessons/trigger-index reads LESSON.md), so
+ * it stays even past the cap. Pure: this module decides the partition and renders
+ * the archive block; the fail-safe, archive-first file write is the caller's job.
+ */
+import { CAP, DAY_MS, STALE_DAYS, type Block, hasTrigger } from "./lesson-parse";
+
+/** Sort key: undated bullets sort oldest, so malformed entries archive first. */
+function age(b: Block): number { return Number.isNaN(b.ts) ? -Infinity : b.ts; }
+
+/** A TRIGGERS bullet is protected from archival until older than STALE_DAYS. */
+function isProtected(b: Block, staleBefore: number): boolean {
+  return hasTrigger(b) && !(b.ts <= staleBefore);
+}
+
+/**
+ * Partition deduped `blocks` (newest-first file order) into the bullets that
+ * stay in LESSON.md and the oldest excess to archive. Archives only enough to
+ * reach CAP, skipping protected TRIGGERS bullets (so the file MAY stay slightly
+ * over cap by design). Order is preserved in both halves; `keep ∪ archive` is
+ * exactly `blocks` with no loss and no mutation.
+ * @param blocks - Deduped bullets, newest first.
+ * @param now - Clock (ms) for the STALE_DAYS protection window.
+ * @returns `{ keep, archive }` — a lossless partition of `blocks`.
+ */
+export function splitAtCap(blocks: Block[], now: number): { keep: Block[]; archive: Block[] } {
+  if (blocks.length <= CAP) return { keep: blocks, archive: [] };
+  const staleBefore = now - STALE_DAYS * DAY_MS;
+  const oldestFirst = [...blocks].sort((a, b) => age(a) - age(b));
+  const toArchive = new Set<Block>();
+  let excess = blocks.length - CAP;
+  for (const b of oldestFirst) {
+    if (excess <= 0) break;
+    if (isProtected(b, staleBefore)) continue;
+    toArchive.add(b);
+    excess--;
+  }
+  return {
+    keep: blocks.filter((b) => !toArchive.has(b)),
+    archive: blocks.filter((b) => toArchive.has(b)),
+  };
+}
+
+/**
+ * Render `archive` bullets as a dated block to PREPEND to LESSON-archive.md
+ * (newest archive session on top). Bullets are emitted BYTE-IDENTICAL (raw lines
+ * rejoined) — zero mutation, so the move stays reversible/auditable.
+ * @param archive - Bullets chosen by {@link splitAtCap}.
+ * @param now - Clock (ms) for the archival header date.
+ * @returns The block text (trailing newline), or "" when nothing is archived.
+ */
+export function formatArchive(archive: Block[], now: number): string {
+  if (archive.length === 0) return "";
+  const day = new Date(now).toISOString().slice(0, 10);
+  const header = `<!-- archived ${day}: ${archive.length} bullet(s) moved from LESSON.md at cap ${CAP} -->`;
+  return `${header}\n${archive.map((b) => b.raw.join("\n")).join("\n\n")}\n`;
+}

package/src/runtime/lifecycle/aipilot/lesson-inject.ts

@@ -0,0 +1,98 @@
+/**
+ * Stage 2 — compress the LESSON.md SessionStart/SubagentStart block (the big
+ * token win). The RECENT_FULL newest bullets pass verbatim; every older bullet
+ * collapses to ONE line — its date plus the FIRST SENTENCE of the actionable
+ * rule after the bullet's LAST "→" (the file's `narrative → rule` format), or of
+ * the whole bullet when there is no arrow, hard-capped at RULE_CAP chars. The
+ * FILE keeps full bullets (human source of truth); only this injected view is
+ * compressed, so compression applies even under the cap.
+ */
+import { type Block, parse } from "./lesson-parse";
+
+/**
+ * Newest bullets kept verbatim. Rationale: the most recent lessons are the ones
+ * still tied to live work and worth full narrative context. Real bullets run
+ * 0.5–1.5 kB each, so 10 (not 15) verbatim clears the >70% shrink target on the
+ * live file while still preserving the actively-relevant recent set whole.
+ */
+export const RECENT_FULL = 10;
+
+/** Max chars of a distilled rule — keeps every compressed bullet to one line. */
+export const RULE_CAP = 200;
+
+/**
+ * Min readable length of a distilled rule. The old "text after the LAST →" rule
+ * produced illegible stubs when a bullet ended on a short trailing arrow segment
+ * (e.g. `- [2026-07-02 00:02] lecture).`, 30 chars). Below this we fall back to
+ * the whole rule's first sentence rather than ship a meaningless fragment.
+ */
+export const MIN_RULE = 40;
+
+/** The `[YYYY-MM-DD HH:MM]` (or date-only) stamp of a bullet, "" if absent. */
+function stamp(block: Block): string {
+  const m = (block.raw[0] ?? "").match(/\[(\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2})?)\]/);
+  return m?.[1] ?? "";
+}
+
+/** Bullet text: raw lines joined, leading "- ", date stamp & TRIGGERS lines stripped. */
+function bodyText(block: Block): string {
+  const kept = block.raw.filter((l) => !/^\s*\[TRIGGERS\s/.test(l));
+  return kept.join(" ").replace(/^-\s*/, "").replace(/\[\d{4}-\d{2}-\d{2}[^\]]*\]\s*/, "").trim();
+}
+
+/** First sentence of `s` (split on a period + whitespace), whole string if none. */
+function firstSentence(s: string): string {
+  return (s.split(/(?<=\.)\s/)[0] ?? s).trim();
+}
+
+/**
+ * The bullet's `narrative → rule` delimiter: a SPACED arrow only. A GLUED arrow
+ * between tokens (e.g. `120s→300s`, `s→3`) is prose the author wrote, never a
+ * delimiter — matching on `→` alone chopped rules mid-token (bug: `300s) pensant
+ * corriger…`). Also used to split rule-internal clauses.
+ */
+const RULE_ARROW = /\s+→\s+/;
+
+/**
+ * Distil the actionable rule from a bullet body. With no spaced arrow the whole
+ * bullet is the rule → its first sentence. Otherwise the rule is everything after
+ * the FIRST spaced arrow; its spaced-arrow-delimited segments are kept whole
+ * except for TRAILING short asides (< {@link MIN_RULE} chars, e.g. `→ (cf.
+ * lecture).`) which are dropped — so an arrow used as PROSE inside a rule (`maps
+ * X → Y doit…`) is preserved intact rather than chopped at the arrow. When the
+ * kept rule is still under {@link MIN_RULE} chars, fall back to the first sentence
+ * of the WHOLE rule part (never the narrative), avoiding an illegible stub.
+ */
+function distillRule(text: string): string {
+  const sep = text.search(RULE_ARROW);
+  if (sep < 0) return firstSentence(text);
+  const rulePart = text.slice(sep).replace(RULE_ARROW, "").trim();
+  const segments = rulePart.split(RULE_ARROW).map((s) => s.trim()).filter(Boolean);
+  while (segments.length > 1 && (segments[segments.length - 1]?.length ?? 0) < MIN_RULE) segments.pop();
+  const rule = firstSentence(segments.join(" → "));
+  return rule.length >= MIN_RULE ? rule : firstSentence(rulePart);
+}
+
+/** Collapse one older bullet to `- [date] <rule>`: {@link distillRule}, capped. */
+function compressBullet(block: Block): string {
+  let rule = distillRule(bodyText(block));
+  if (rule.length > RULE_CAP) rule = `${rule.slice(0, RULE_CAP - 1).trimEnd()}…`;
+  const date = stamp(block);
+  return `- ${date ? `[${date}] ` : ""}${rule}`;
+}
+
+/**
+ * Build the compressed injection body for `content`. The preamble comments are
+ * dropped (format docs, noise for the reader); the `recentFull` newest bullets
+ * stay whole, every older bullet becomes one distilled rule-line.
+ * @param content - Raw LESSON.md text.
+ * @param recentFull - Count of newest bullets to keep verbatim.
+ * @returns The compressed block (bullets only), or the trimmed content when there are no bullets.
+ */
+export function compressInjection(content: string, recentFull: number = RECENT_FULL): string {
+  const { blocks } = parse(content);
+  if (blocks.length === 0) return content.trim();
+  const full = blocks.slice(0, recentFull).map((b) => b.raw.join("\n"));
+  const rest = blocks.slice(recentFull).map(compressBullet);
+  return [...full, ...rest].join("\n");
+}

package/src/runtime/lifecycle/aipilot/lesson-parse.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared, LLM-free primitives for LESSON.md curation: bullet parsing, timestamp
+ * extraction, tokenization/Jaccard (dedup), cited-path detection, and the
+ * cap/stale constants. Consumed by curate-lessons (dedup), lesson-archive
+ * (cap→archive) and lesson-inject (compressed SessionStart block) — one source
+ * of truth so the three stages can never disagree on what a "bullet" is.
+ */
+
+/** Bullet count above which the oldest lessons are archived out of LESSON.md. */
+export const CAP = 50;
+/** Age (days) past which a lesson is eligible for archival / stale-flagging. */
+export const STALE_DAYS = 90;
+/** Milliseconds in a day. */
+export const DAY_MS = 86400000;
+/** Case-sensitive decision-time tag line (`[TRIGGERS …]`) — opus-lessons format. */
+export const TRIG: RegExp = /^\[TRIGGERS\s+.+\]$/;
+
+/** A bullet plus any continuation lines (e.g. a `[TRIGGERS …]` line). */
+export interface Block { raw: string[]; ts: number; tokens: Set<string>; }
+
+/** Epoch ms for a `[YYYY-MM-DD HH:MM]` stamp; `NaN` if absent or out of range. */
+export function parseTs(line: string): number {
+  const m = line.match(/\[(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}))?/);
+  if (!m) return NaN;
+  const mo = +(m[2] ?? 0), d = +(m[3] ?? 0);
+  if (mo < 1 || mo > 12 || d < 1 || d > 31) return NaN;
+  return Date.UTC(+(m[1] ?? 0), mo - 1, d, +(m[4] ?? 0), +(m[5] ?? 0));
+}
+
+/** Content words (>=4 chars), timestamp & TRIGGERS marker stripped. */
+export function tokenize(text: string): Set<string> {
+  return new Set(
+    text.toLowerCase()
+      .replace(/\[triggers[^\]]*\]/g, " ")
+      .replace(/\[\d{4}-\d{2}-\d{2}[^\]]*\]/g, " ")
+      .replace(/[^a-z0-9àâäéèêëîïôöùûüç/._-]+/gi, " ")
+      .split(/\s+/).filter((t) => t.length >= 4),
+  );
+}
+
+/** Jaccard overlap of two token sets (0 when both empty). */
+export function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  const inter = [...a].filter((t) => b.has(t)).length;
+  return inter / (a.size + b.size - inter);
+}
+
+/** Repo-relative cited paths (slash + extension) referenced in a block. */
+export function citedPaths(text: string): string[] {
+  const out = new Set<string>();
+  for (const m of text.matchAll(/`([^`]+)`/g)) { if (m[1]) out.add(m[1]); }
+  for (const m of text.matchAll(/[\w./@-]+\.\w{1,5}/g)) { if (m[0]) out.add(m[0]); }
+  return [...out].filter((p) => p.includes("/") && /\.\w{1,5}$/.test(p));
+}
+
+/** True when a block carries a `[TRIGGERS …]` continuation line. */
+export function hasTrigger(b: Block): boolean {
+  return b.raw.some((l) => TRIG.test(l.trim()));
+}
+
+/** Split content into a verbatim preamble and one Block per `- ` bullet. */
+export function parse(content: string): { preamble: string; blocks: Block[] } {
+  const lines = content.split("\n");
+  const blocks: Block[] = [];
+  let i = 0;
+  while (i < lines.length && !/^-\s/.test(lines[i] ?? "")) i++;
+  const preamble = lines.slice(0, i).join("\n");
+  for (; i < lines.length; i++) {
+    const l = lines[i] ?? "", last = blocks[blocks.length - 1];
+    if (/^-\s/.test(l)) blocks.push({ raw: [l], ts: parseTs(l), tokens: tokenize(l) });
+    else if (l.trim() && last) last.raw.push(l);
+  }
+  return { preamble, blocks };
+}