@fusengine/harness 0.1.90 → 0.1.91

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

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

@@ -0,0 +1,72 @@
+/**
+ * Lesson aggregation, dedup, merge, and edit categorization for the ai-pilot
+ * scope. Ported from the ai-pilot plugin's `cache/lesson-aggregator.ts` +
+ * `cache/lesson-helpers.ts` (now removed).
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { readJsonFile } from "../../../util/json-io";
+import { cacheBaseDir } from "./cache-base";
+import type { EditEntry, LessonEntry } from "./types";
+
+/** Deduplicate lessons by `error_type:pattern`, summing counts. */
+export function dedupLessons(lessons: LessonEntry[]): LessonEntry[] {
+  const groups = new Map<string, LessonEntry[]>();
+  for (const l of lessons) {
+    const key = `${l.error_type}:${l.pattern}`;
+    const group = groups.get(key);
+    if (group) group.push(l); else groups.set(key, [l]);
+  }
+  return [...groups.values()].map((entries) => {
+    const first = entries[0] as LessonEntry;
+    return {
+      error_type: first.error_type,
+      pattern: first.pattern,
+      fix: first.fix,
+      last_seen: first.last_seen,
+      count: entries.reduce((s, e) => s + e.count, 0),
+      files: [...new Set(entries.flatMap((e) => e.files))],
+      code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) },
+    };
+  }).sort((a, b) => b.count - a.count);
+}
+
+/** Aggregate all local lesson JSON files into a flat deduplicated list. */
+export async function aggregateLocalLessons(cacheDir: string): Promise<LessonEntry[]> {
+  if (!existsSync(cacheDir)) return [];
+  const files = readdirSync(cacheDir).filter((f) => f.endsWith(".json"));
+  const all: LessonEntry[] = [];
+  for (const f of files) {
+    const data = await readJsonFile<{ errors?: LessonEntry[] }>(join(cacheDir, f));
+    if (data?.errors) all.push(...data.errors);
+  }
+  return dedupLessons(all);
+}
+
+/** Load global lessons for a stack (stack-specific + universal). */
+export async function loadGlobalLessons(stack: string, home: string = homedir()): Promise<LessonEntry[]> {
+  const globalDir = join(cacheBaseDir(home), "lessons", "_global");
+  const result: LessonEntry[] = [];
+  for (const name of [`${stack}.json`, "universal.json"]) {
+    const data = await readJsonFile<LessonEntry[]>(join(globalDir, name));
+    if (data) result.push(...data);
+  }
+  return result;
+}
+
+/** Merge local + global lessons, dedup by type+pattern, sort by count desc. */
+export function mergeLessons(local: LessonEntry[], global: LessonEntry[]): LessonEntry[] {
+  return dedupLessons([...local, ...global]);
+}
+
+/** Categorize an edit entry by analyzing the new code content. */
+export function categorizeEdit(edit: EditEntry): string {
+  const n = edit.newStr.toLowerCase();
+  if (n.includes("use client")) return "missing_directive";
+  if (n.includes("displayname")) return "missing_display_name";
+  if (/onkeydown|tabindex|role=/.test(n)) return "missing_a11y";
+  if (/try|catch/.test(n)) return "missing_error_handling";
+  if (/\?\?|if.*null/.test(n)) return "null_safety";
+  return "code_fix";
+}

package/src/runtime/lifecycle/aipilot/promote-global-lessons.ts

@@ -0,0 +1,92 @@
+/**
+ * Promote high-frequency project lessons (occurrence count >= 3) to the global,
+ * stack-scoped cache (`cache/lessons/_global/<stack>.json`, cap 25).
+ * Ports the ai-pilot `promote-global-lessons.ts` (a spawned subprocess) as an
+ * in-process call from `cacheSniperLessons`. Pure side-effect.
+ */
+import { homedir } from "node:os";
+import { mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { cacheBaseDir } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import type { LessonEntry } from "./types";
+
+/** A promoted global lesson tagged with the project hashes that produced it. */
+export interface GlobalLesson extends LessonEntry {
+  source_projects: string[];
+}
+
+const MIN_COUNT = 3;
+const MAX_GLOBAL = 25;
+
+/** Group lessons by `error_type:pattern`. */
+function groupByKey<T extends LessonEntry>(lessons: T[]): T[][] {
+  const groups = new Map<string, T[]>();
+  for (const l of lessons) {
+    const key = `${l.error_type}:${l.pattern}`;
+    (groups.get(key) ?? groups.set(key, []).get(key)!).push(l);
+  }
+  return [...groups.values()];
+}
+
+/** Read every project lesson file's `errors` into one flat (un-deduped) list. */
+async function aggregateErrors(cacheDir: string): Promise<LessonEntry[]> {
+  let files: string[];
+  try { files = readdirSync(cacheDir).filter((f) => f.endsWith(".json")); } catch { return []; }
+  const all: LessonEntry[] = [];
+  for (const f of files) {
+    const data = await readJsonFile<{ errors?: LessonEntry[] }>(join(cacheDir, f));
+    if (data?.errors) all.push(...data.errors);
+  }
+  return all;
+}
+
+/** Keep groups seen >= MIN_COUNT times, collapsed to a single lesson each. */
+function filterFrequent(lessons: LessonEntry[]): LessonEntry[] {
+  return groupByKey(lessons).filter((e) => e.length >= MIN_COUNT).map((entries) => {
+    const first = entries[0] as LessonEntry;
+    return {
+      error_type: first.error_type, pattern: first.pattern, fix: first.fix, last_seen: first.last_seen,
+      count: entries.length,
+      files: [...new Set(entries.flatMap((e) => e.files))],
+      code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) },
+    };
+  });
+}
+
+/** Merge tagged candidates into existing global lessons; dedup, sum, sort, cap. */
+function mergeGlobal(existing: GlobalLesson[], candidates: LessonEntry[], projHash: string): GlobalLesson[] {
+  const tagged: GlobalLesson[] = candidates.map((c) => ({ ...c, source_projects: [projHash] }));
+  return groupByKey([...existing, ...tagged]).map((entries) => {
+    const first = entries[0] as GlobalLesson;
+    return {
+      error_type: first.error_type, pattern: first.pattern, fix: first.fix, last_seen: first.last_seen,
+      count: entries.reduce((sum, e) => sum + e.count, 0),
+      files: [...new Set(entries.flatMap((e) => e.files))],
+      code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) },
+      source_projects: [...new Set(entries.flatMap((e) => e.source_projects ?? []))],
+    };
+  }).sort((a, b) => b.count - a.count).slice(0, MAX_GLOBAL);
+}
+
+/**
+ * Promote high-frequency lessons from `cacheDir` to the global stack file.
+ * @param cacheDir - Per-project lessons cache dir to scan.
+ * @param stack - Detected project stack (`nextjs`, `laravel`, …, `universal`).
+ * @param projHash - Source project hash (tags promoted entries).
+ * @param home - Home dir (defaults to `~`).
+ */
+export async function promoteGlobalLessons(cacheDir: string, stack: string, projHash: string, home: string = homedir()): Promise<void> {
+  const candidates = filterFrequent(await aggregateErrors(cacheDir));
+  if (candidates.length === 0) return;
+
+  const globalDir = join(cacheBaseDir(home), "lessons", "_global");
+  mkdirSync(globalDir, { recursive: true });
+  const globalFile = join(globalDir, `${stack}.json`);
+  const existing = (await readJsonFile<GlobalLesson[]>(globalFile)) ?? [];
+  const merged = mergeGlobal(existing, candidates, projHash);
+
+  await writeJsonFile(globalFile, merged, true);
+  logCacheEvent("lessons", "promoted", projHash, { count: merged.length, stack }, home);
+}