@fusengine/harness 0.1.90 → 0.1.92

package/src/policy/guards/interface-separation.ts

@@ -0,0 +1,100 @@
+import type { Prompt } from "../../prompt/types";
+import type { GuardContext } from "./context";
+import { moduleAwarePath } from "../module-layout";
+import { maskCommentsAndStrings } from "../conventions/strip";
+import { langOfPath, lexProfileOf } from "../conventions/langs";
+import { declaresExportedTypeAlias } from "../conventions/interfaces";
+import { rolloutVerdict } from "../conventions/verdict";
+import { extendedInterfaceViolation } from "./interface-separation-ext";
+
+/** TS/JS component files: top-level `interface`/`type Foo`. */
+export const TS_DECL_RE: RegExp = /^\s*(export\s+)?(interface|type)\s+[A-Z]/m;
+/** Python view models: class subclassing a schema/protocol base. */
+export const PY_MODEL_RE: RegExp = /^\s*class\s+\w+\s*\([^)]*\b(?:BaseModel|TypedDict|Protocol)\b/m;
+/**
+ * PHP controllers: top-level `interface`, `abstract class`, or a concrete
+ * `class …Interface/DTO/Request`. Union of the TS-only `abstract class` rule
+ * and the Python rule (`class [A-Z].*(Interface|DTO|Request)`, enforce-interfaces.py:16).
+ */
+export const PHP_DECL_RE: RegExp = /^\s*(?:abstract\s+class\b|interface\b|class\s+[A-Z].*(?:Interface|DTO|Request))/m;
+/** Swift views: top-level `protocol Foo`. */
+export const SWIFT_PROTO_RE: RegExp = /^\s*protocol\s+[A-Z]/m;
+/** Go handlers/controllers: top-level `type Foo interface`. */
+export const GO_DECL_RE: RegExp = /^\s*type\s+[A-Z]\w*\s+interface\b/m;
+/** Java/Kotlin controllers/handlers: top-level `interface`/`record`. */
+export const JAVA_DECL_RE: RegExp = /^\s*(?:public\s+|private\s+|protected\s+|internal\s+)?(?:interface|record)\s+[A-Z]/m;
+/** Rust: top-level `trait Foo` declaration (captures the name for impl co-location). */
+export const RUST_DECL_RE: RegExp = /^\s*(?:pub(?:\(\w+\))?\s+)?trait\s+([A-Z]\w*)/m;
+
+/**
+ * Blocks top-level interface/type/protocol declarations in component, view or
+ * controller files (Interface Segregation), when BOTH the path category AND
+ * the content pattern match. Content is MASKED first (conventions/strip.ts):
+ * declarations in comments/strings/templates/heredocs never trigger. Legacy
+ * regexes keep their exact values (parity tests) — every case that blocked
+ * before still blocks with the same message (byte-parity). Two extension
+ * classes ship ADVISORY via {@link rolloutVerdict} (`FUSE_CONVENTIONS_MODE`,
+ * Amendment 5): exported type aliases redirected to `src/types/` (Amendment 2),
+ * and the widenings of `interface-separation-ext.ts` (public protocol,
+ * sealed/fun interface, unexported Go top-level). Rust `impl<T>` stays a
+ * known FN. Parity: the Python port inspected `Write` only; we also fire on
+ * `Edit`, and fragments accept singular+plural dirs (`view/` + `views/`).
+ */
+export function interfaceSeparationGuard(ctx: GuardContext): Prompt | null {
+  if (ctx.tool !== "Write" && ctx.tool !== "Edit") return null;
+  const path: string | undefined = ctx.filePath;
+  const content: string | undefined = ctx.content;
+  if (!path || !content) return null;
+  const lang = langOfPath(path);
+  const masked = maskCommentsAndStrings(content, lexProfileOf(lang ?? "ts"));
+
+  const blockWith = (msg: string, action: string): Prompt => ({
+    kind: "block",
+    title: "Separate the interface",
+    reason: `SOLID VIOLATION: ${msg}`,
+    actions: [action],
+  });
+
+  const inAny = (...frags: string[]): boolean =>
+    // Segment-anchored: `view/` must be a real dir — `overview/`, `livetest-app/`
+    // never match (same FP class as solid-transcript G3); fragment at path start OK.
+    frags.some((f) => path.includes(`/${f}`) || path.startsWith(f));
+  if (/\.(tsx|jsx|vue|svelte)$/.test(path) && TS_DECL_RE.test(masked)) {
+    if (!/^\s*(export\s+)?(declare\s+)?interface\s+\w/.test(masked) && declaresExportedTypeAlias(content)) {
+      return rolloutVerdict(blockWith(
+        "Type alias in component file. Move to modules/[feature]/src/types/",
+        "Move the type alias to modules/[feature]/src/types/",
+      ), true);
+    }
+    return blockWith(
+      "Interface/type in component file. Move to modules/[feature]/src/interfaces/",
+      "Move the interface/type to modules/[feature]/src/interfaces/",
+    );
+  }
+  if (/\.py$/.test(path) && inAny("view/", "views/", "controller/", "controllers/", "route/", "routes/") && PY_MODEL_RE.test(masked)) {
+    return blockWith("Type class in view file. Move to src/interfaces/", "Move the type class to src/interfaces/");
+  }
+  if (/\.go$/.test(path) && inAny("handler/", "handlers/", "controller/", "controllers/") && GO_DECL_RE.test(masked)) {
+    return blockWith("Interface in handler file. Move to internal/interfaces/", "Move the interface to internal/interfaces/");
+  }
+  if (/\.(java|kt)$/.test(path) && inAny("controller/", "controllers/", "handler/", "handlers/") && JAVA_DECL_RE.test(masked)) {
+    return blockWith("Interface in controller file. Move to interfaces/ package", "Move the interface to the interfaces/ package");
+  }
+  if (/\.php$/.test(path) && inAny("Controller/", "Controllers/", "Handler/", "Handlers/") && PHP_DECL_RE.test(masked)) {
+    return blockWith("Interface in controller file. Move to app/Contracts/", "Move the interface to app/Contracts/");
+  }
+  if (/\.swift$/.test(path) && inAny("View/", "Views/", "Component/", "Components/") && SWIFT_PROTO_RE.test(masked)) {
+    return blockWith("Protocol in view file. Move to Sources/Interfaces/", "Move the protocol to Sources/Interfaces/");
+  }
+  if (/\.rs$/.test(path) && !inAny("traits/", "interfaces/") && !path.endsWith("traits.rs")) {
+    const m = RUST_DECL_RE.exec(masked);
+    const name = m?.[1];
+    if (name && new RegExp(`impl\\s+${name}\\s+for\\s+\\w+`).test(masked)) {
+      const dest = moduleAwarePath(path, "traits.rs", "a dedicated traits.rs / interfaces module");
+      return blockWith(`Trait declared alongside its implementation. Move the trait to ${dest}`, `Move the trait to ${dest}`);
+    }
+  }
+  const ext = extendedInterfaceViolation(path, content);
+  if (ext) return rolloutVerdict(blockWith(ext.msg, ext.action), true);
+  return null;
+}

package/src/policy/guards/protected-path.ts

@@ -0,0 +1,100 @@
+import type { Prompt } from "../../prompt/types";
+import type { GuardContext } from "./context";
+import { shellOutputRedirects } from "./bash-write-redirects";
+
+/**
+ * Path fragments that mark a location as internal/generated state.
+ *
+ * Parity with safe_paths.py: `~/.fuse-harness/cache` is a *writable*
+ * cache the harness owns (lessons, MCP cache, per-type state) — only the
+ * `cache/sessions` subtree is protected, not the whole cache.
+ */
+export const PROTECTED_FRAGMENTS: readonly string[] = [
+  ".claude/plugins/marketplaces",
+  ".claude/plugins/cache",
+  ".claude/logs/00-apex",
+  ".fuse-harness/cache/sessions",
+  ".claude/apex/",
+  ".harness/track",
+  ".harness/memory/state",
+  // Precondition of the neverApproval exemption (evaluate.ts): blocks a Codex
+  // agent from self-elevating via its own allow rule — sandbox_mode never
+  // covers the user's ~/.codex/, only a project-local one.
+  ".codex/config.toml",
+  ".codex/rules/",
+];
+
+/**
+ * Matches a real `.git` directory segment (`/.git/`, `~/.git`, leading or
+ * trailing `.git`) without matching unrelated names like `foo.git/` or
+ * `.github/`. Kept separate from the substring fragments for precise scoping.
+ */
+export const PROTECTED_GIT_RE: RegExp = /(?:^|[/~\s])\.git(?:\/|$)/;
+
+/** Standard block response for any protected-path violation. */
+const BLOCK: Prompt = {
+  kind: "block",
+  title: "Protected path",
+  reason: "This is internal/generated enforcement state — do not edit it directly.",
+  actions: ["Edit the source, not the generated/cache/state copy"],
+};
+
+/** Returns true if `str` references a protected fragment or a real `.git` segment. */
+function containsProtected(str: string): boolean {
+  return PROTECTED_FRAGMENTS.some((f: string): boolean => str.includes(f)) || PROTECTED_GIT_RE.test(str);
+}
+
+/** Strips surrounding quotes from a captured shell token. */
+function unquote(t: string): string {
+  return t.replace(/^['"]|['"]$/g, "");
+}
+
+/**
+ * Extracts the genuine write *targets* of a shell command, so a protected path
+ * appearing only as a *read source* (e.g. `grep x .claude/apex/ > out.txt`,
+ * `cat .git/config > /dev/null`) is not mistaken for a write.
+ *
+ * Covers `>` / `>>` redirects (skipping `2>`, `&>`, `1>` fd-redirects and
+ * `/dev/null`), `tee`, `dd of=`, and the destination / in-place file of
+ * `cp` / `mv` / `sed -i` / `perl -i` (last path token of the segment).
+ * Best-effort: obfuscated shell (base64, indirection, process substitution)
+ * can still evade this — residual risk, mitigated by the freshness gate.
+ */
+function extractWriteTargets(cmd: string): string[] {
+  const out: string[] = [];
+  const push = (t: string | undefined): void => {
+    const v: string = unquote((t ?? "").trim());
+    if (v && v !== "/dev/null") out.push(v);
+  };
+  for (const redirect of shellOutputRedirects(cmd)) push(redirect.target);
+  for (const m of cmd.matchAll(/\btee\b(?:\s+-\S+)*\s+('[^']+'|"[^"]+"|\S+)/g)) push(m[1]);
+  for (const m of cmd.matchAll(/\bdd\b[^|;&]*\bof=('[^']+'|"[^"]+"|\S+)/g)) push(m[1]);
+  for (const seg of cmd.split(/[;&|]+/)) {
+    if (!/\b(?:cp|mv)\b|\b(?:sed|perl)\b[^|;&]*\s-i/.test(seg)) continue;
+    const head: string = seg.split(/[<>]/)[0] ?? "";
+    const toks: string[] = head.trim().split(/\s+/).filter((t: string): boolean => Boolean(t) && !t.startsWith("-"));
+    push(toks[toks.length - 1]);
+  }
+  return out;
+}
+
+/**
+ * Blocks direct edits to internal/generated state directories.
+ *
+ * Covers:
+ *  - Write / Edit tool calls whose `filePath` targets a protected fragment.
+ *  - Bash commands whose actual write *target* is a protected fragment
+ *    (read sources are ignored; see `extractWriteTargets`).
+ *
+ * @param ctx - The guard context (tool, filePath, command).
+ * @returns A blocking {@link Prompt}, or null to allow.
+ */
+export function protectedPathGuard(ctx: GuardContext): Prompt | null {
+  if ((ctx.tool === "Write" || ctx.tool === "Edit") && ctx.filePath) {
+    if (containsProtected(ctx.filePath)) return BLOCK;
+  }
+  if (ctx.tool === "Bash" && ctx.command) {
+    if (extractWriteTargets(ctx.command).some(containsProtected)) return BLOCK;
+  }
+  return null;
+}

package/src/policy/guards/security.ts

@@ -0,0 +1,97 @@
+import type { Prompt } from "../../prompt/types";
+import type { GuardContext } from "./context";
+
+/** A pattern paired with the violation label to name in the deny/ask reason. */
+export interface LabeledPattern {
+  re: RegExp;
+  label: string;
+}
+
+/** Critical patterns that must always be blocked — parity `security_rules.py`'s cumulated violation names. */
+export const CRITICAL_PATTERNS: LabeledPattern[] = [
+  { re: /\brm\s+(?:-[a-z]*\s+)*-[a-z]*[rf][a-z]*\s+(?:-[a-z]+\s+)*(?:\/|~)(?:\s|$)/, label: "DANGEROUS PATTERN: recursive delete of / or ~" },
+  { re: /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, label: "DANGEROUS PATTERN: fork bomb" },
+  { re: /\b(?:curl|wget)\b[^|]*\|\s*(?:sudo\s+)?(?:ba|z|da|k)?sh\b/, label: "DANGEROUS PATTERN: remote script piped to a shell" },
+  { re: /\bchmod\s+(?:-[a-zA-Z]+\s+)*777\s+\//, label: "DANGEROUS PATTERN: chmod 777 on /" },
+  { re: /\bmkfs(?:\.[a-z0-9]+)?\b/, label: "CRITICAL: Detected dangerous command 'mkfs'" },
+  { re: /\bdd\b[^\n]*\bof=\/dev\/(?:r?disk|sd|hd|nvme|mmcblk|vd|xvd)/i, label: "CRITICAL: Detected dangerous command 'dd if='" },
+  { re: /\bshred\b/, label: "CRITICAL: Detected dangerous command 'shred'" },
+  { re: /\bfdisk\b/, label: "CRITICAL: Detected dangerous command 'fdisk'" },
+  { re: /\bdiskutil\s+(?:erase|partitionDisk)/i, label: "CRITICAL: Detected dangerous command 'diskutil erase'" },
+  { re: /(?:>|>>)\s*\/dev\/(?:sda|hda|nvme)/, label: "DANGEROUS PATTERN: redirect to a raw disk device" },
+  { re: /\brm\s+(?:-[a-z]*\s+)*-[a-z]*[rf][a-z]*\s+(?:-[a-z]+\s+)*\/(?:etc|usr|var|bin|sbin|boot|lib)\b/, label: "DANGEROUS PATTERN: recursive delete of a system directory" },
+  // Privilege escalation — DENY (parity: security_rules.PRIVILEGE_COMMANDS, has_critical=True).
+  { re: /(?:^|[\s;|&])sudo(?:[\s;|&]|$)/, label: "PRIVILEGE ESCALATION: sudo" },
+  { re: /(?:^|[\s;|&])su(?:[\s;|&]|$)/, label: "PRIVILEGE ESCALATION: su" },
+  { re: /(?:^|[\s;|&])doas(?:[\s;|&]|$)/, label: "PRIVILEGE ESCALATION: doas" },
+  { re: /(?:^|[\s;|&])passwd(?:[\s;|&]|$)/, label: "PRIVILEGE ESCALATION: passwd" },
+  // `del` — DENY (parity: security_rules.CRITICAL_COMMANDS token match).
+  { re: /(?:^|[\s;|&])del(?:[\s;|&]|$)/, label: "CRITICAL: Detected dangerous command 'del'" },
+];
+
+/** Patterns that warrant explicit confirmation before running — parity `security_rules.py`'s ask-level violation names. */
+export const ASK_PATTERNS: LabeledPattern[] = [
+  { re: /\bchmod\s+(?:-[a-zA-Z]+\s+)*777\b/, label: "DANGEROUS PATTERN: chmod 777" },
+  { re: /\bchown\s+-R\b/, label: "DANGEROUS PATTERN: recursive chown" },
+  { re: /\beval\s/, label: "DANGEROUS PATTERN: eval" },
+  { re: /(?:>|>>|\btee\b)\s*\/etc\//, label: "DANGEROUS PATTERN: write to /etc" },
+  { re: /\brm\s/, label: "DELETE: 'rm' permanently deletes - confirmation required" },
+  { re: /\bunlink\s/, label: "DELETE: 'unlink' command detected - confirmation required" },
+];
+
+/**
+ * Strip heredoc bodies so their content isn't matched as a command (false positives).
+ * Two-phase scan: a backreference-free opener regex finds `<<[-]DELIM`, then the body
+ * is cut up to the closing delimiter via `indexOf` — O(n), no catastrophic backtracking.
+ */
+function stripHeredoc(cmd: string): string {
+  const opener = /<<-?\s*['"]?(\w+)['"]?/g;
+  let out = cmd;
+  let m: RegExpExecArray | null;
+  while ((m = opener.exec(out)) !== null) {
+    const delim: string = m[1] ?? "";
+    // Closer may be indented (the `<<-` form strips leading tabs); `\b` ends the word.
+    const closer = new RegExp(`\\n[ \\t]*${delim}\\b`);
+    const rest: string = out.slice(m.index + m[0].length);
+    const hit: RegExpMatchArray | null = closer.exec(rest);
+    if (!hit || hit.index === undefined) break;
+    const end: number = m.index + m[0].length + hit.index + hit[0].length;
+    out = `${out.slice(0, m.index)} ${out.slice(end)}`;
+    opener.lastIndex = m.index;
+  }
+  return out;
+}
+
+/**
+ * Guards against dangerous Bash commands. Parity `security_rules.validate_command`
+ * + `security-guard.py`: ACCUMULATE every matched violation, then deny when any
+ * critical matched else ask, joining all violation labels in the reason. The
+ * generic `rm` ask is exempt when the command targets a trash location (parity
+ * `not re.search('trash', cmd)`).
+ */
+export function securityGuard(ctx: GuardContext): Prompt | null {
+  if (ctx.tool !== "Bash" || !ctx.command) return null;
+  const cmd: string = stripHeredoc(ctx.command);
+  const hasTrash: boolean = /trash/i.test(cmd);
+
+  const critical: string[] = CRITICAL_PATTERNS.filter(({ re }) => re.test(cmd)).map((p) => p.label);
+  const ask: string[] = ASK_PATTERNS.filter(
+    ({ re, label }) => re.test(cmd) && !(hasTrash && label.startsWith("DELETE: 'rm'")),
+  ).map((p) => p.label);
+  if (critical.length === 0 && ask.length === 0) return null;
+
+  if (critical.length > 0) {
+    return {
+      kind: "block",
+      title: "Dangerous command",
+      reason: `${[...critical, ...ask].join(", ")}.`,
+      actions: ["Remove the destructive command", "Scope the operation to a specific safe path"],
+    };
+  }
+  return {
+    kind: "ask",
+    title: "Dangerous command",
+    reason: `${ask.join(", ")}.`,
+    actions: ["Confirm this command is intended", "Run with least privilege"],
+  };
+}

package/src/policy/index.ts

@@ -0,0 +1,19 @@
+export * from "./detect-project";
+export * from "./detect-framework";
+export * from "./file-size";
+export * from "./patterns";
+export * from "./evaluate";
+export * from "./apex";
+export * from "./guards";
+export * from "./creation-intent";
+export * from "./verbosity";
+export * from "./framework-solid";
+export * from "./skill-triggers";
+export * from "./claude-md-context";
+export * from "./apex-task-context";
+export * from "./cartographer/indicators";
+export * from "./cartographer/frontmatter";
+export * from "./cartographer/entry";
+export * from "./cartographer/describe";
+export * from "./seo/validate";
+export * from "./conventions/index";

package/src/policy/interfaces/types.ts

@@ -0,0 +1,46 @@
+import type { Prompt } from "../../prompt/types";
+
+/** Harness-agnostic input to {@link evaluate}. */
+export interface PolicyContext {
+  /** Tool name (e.g. "Write", "Edit", "Bash"). */
+  tool: string;
+  filePath?: string;
+  content?: string;
+  command?: string;
+  /** Optional override for the SOLID max-lines limit. */
+  maxLines?: number;
+  /** Subagent type — `Explore`/`Plan` are exempt from the file-size gate. */
+  agentType?: string;
+  /** Line count of the existing on-disk file (so an Edit on an oversized file blocks). */
+  existingLines?: number;
+  /** Edit only: full on-disk content, read once by the runtime (runtime/gate-helpers.ts::existingLineCounts) — lets evaluate() compute the exact post-edit line count instead of judging the stale pre-edit count alone. Undefined when unreadable/missing (fail-closed to the existingLines-only behavior). */
+  existingContent?: string;
+  /** Edit only: the tool_input.old_string being replaced (runtime/normalize.ts). Undefined for Write (no such field) — fail-closed. */
+  oldString?: string;
+  /** Edit only: the tool_input.replace_all flag — every occurrence of old_string is replaced, not just the first. */
+  isReplaceAll?: boolean;
+
+  /** Codex-only, populated by handle-pre.ts from the resolved `permission_mode` of an `approval_policy=never` session (adapters/codex/permission-mode.ts) — auto-approve gate, wired through evaluate.ts's anti-chaining check. */
+  neverApproval?: boolean;
+}
+
+/** Harness-agnostic policy decision (+ a portable prompt for adapters to render). */
+export interface PolicyResult {
+  decision: "allow" | "deny" | "warn";
+  message: string | null;
+  prompt?: Prompt;
+  meta?: Record<string, unknown>;
+}
+
+/** Phrasing for the "view pending / mark in-progress / mark done" step trio (APEX task-context injection, steps 3/4/7). See `apex-target-steps.ts`. */
+export interface ApexTaskSteps {
+  step3: string;
+  step4: string;
+  step7: string;
+}
+
+/** Phrasing for the "before starting / when done" pair (APEX sub-agent injection, SubagentStart). See `apex-target-steps.ts`. */
+export interface ApexAgentSteps {
+  beforeStart: string;
+  whenDone: string;
+}

package/src/policy/js-gate-route.ts

@@ -0,0 +1,51 @@
+import { dirname, resolve } from "node:path";
+import { nearestManifestDir, projectCaps, type Cap } from "./nearest-manifest";
+
+/**
+ * JS framework the SOLID gate routes on, resolved MANIFEST-FIRST (H1), or
+ * `null` when the project declares no JS-framework capability — the caller
+ * then falls back to the legacy content-marker routing, byte-identical.
+ */
+export type JsGateRoute = "nextjs" | "react" | null;
+
+/**
+ * Per-process memo of manifest-dir → capabilities. Hook invocations are
+ * short-lived processes, so a stale manifest is impossible in production; the
+ * memo only saves a re-read when one process judges several files (tests).
+ */
+const capsCache = new Map<string, Set<Cap>>();
+
+/** Resolve the nearest manifest's capabilities for `filePath` (memoized per dir). */
+function capsFor(filePath: string, cwd: string): Set<Cap> {
+  const dir = nearestManifestDir(dirname(resolve(cwd, filePath)));
+  if (!dir) return new Set();
+  const hit = capsCache.get(dir);
+  if (hit) return hit;
+  const caps = projectCaps(dir);
+  capsCache.set(dir, caps);
+  return caps;
+}
+
+/**
+ * Pick the JS gate from the PROJECT's declared framework, not the file's
+ * content markers (H1): a bare client component (hooks but no `next` marker)
+ * in a Next.js app must still hit nextGate's `'use client'` rule — content
+ * routing sent it to reactGate and the file landed, crashing at runtime.
+ * `nextjs` wins over `react` (every Next app ships react); a TanStack
+ * Start/Router or plain-react project routes to reactGate. Fail-open: any
+ * error, or no JS-framework capability (no manifest, backend, vue), yields
+ * `null` so the legacy NEXT_RE content routing applies, byte-identical.
+ * @param filePath - Path of the file being written/edited.
+ * @param cwd - Root to resolve a relative `filePath` against (default cwd).
+ * @returns The gate route, or null for the legacy content-based fallback.
+ */
+export function jsGateRoute(filePath: string, cwd: string = process.cwd()): JsGateRoute {
+  try {
+    const caps = capsFor(filePath, cwd);
+    if (caps.has("nextjs")) return "nextjs";
+    if (caps.has("react") || caps.has("tanstack-start") || caps.has("tanstack-router")) return "react";
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/policy/lessons/trigger-index.ts

@@ -0,0 +1,84 @@
+/**
+ * Compile the triggered-lesson index from `MEMORY/LESSON.md`. A lesson is a
+ * bullet (`- [YYYY-MM-DD HH:MM] ...`); it opts into decision-time injection by
+ * ending with a `[TRIGGERS tool:.. path:.. error:.. keyword:..]` line. Lessons
+ * WITHOUT that tag are skipped here (they keep the SessionStart block behavior —
+ * zero regression). Parsed once per file version (mtime-memoized).
+ */
+import { readFileSync, statSync } from "node:fs";
+import type { LessonEntry, Triggers } from "./types";
+
+/** Matches a trailing `[TRIGGERS ...]` line (its body captured). */
+const TRIGGER_RE = /^\[TRIGGERS\s+(.+?)\]$/;
+
+/** Comma list for `key:` in a trigger body (values are space-delimited). */
+function list(body: string, key: string): string[] {
+  const m = body.match(new RegExp(`\\b${key}:([^\\s\\]]+)`));
+  const val = m?.[1];
+  return val ? val.split(",").filter(Boolean) : [];
+}
+
+/** Parse a `[TRIGGERS ...]` body into predicates (error is a single regex). */
+function parseTriggers(body: string): Triggers {
+  const err = body.match(/\berror:([^\s\]]+)/);
+  return { tools: list(body, "tool"), paths: list(body, "path"), error: err?.[1], keywords: list(body, "keyword") };
+}
+
+/** Collapse to a single ≤3-line compact string (cap length). */
+function compact(text: string): string {
+  const one = text.replace(/\s+/g, " ").trim();
+  return one.length > 280 ? `${one.slice(0, 277)}…` : one;
+}
+
+/**
+ * Parse LESSON.md content into triggered entries. A bullet's text spans its
+ * `- ` line plus any following non-blank continuation lines up to the next
+ * bullet; a `[TRIGGERS ...]` continuation line arms it.
+ * @param content - Raw LESSON.md text.
+ * @returns Entries that declared triggers (others skipped).
+ */
+export function parseLessons(content: string): LessonEntry[] {
+  const lines = content.split("\n");
+  const out: LessonEntry[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined || !line.startsWith("- ")) continue;
+    let text = line.slice(2);
+    let triggers: Triggers | null = null;
+    for (let j = i + 1; j < lines.length; j++) {
+      const cont = lines[j];
+      if (cont === undefined || cont.trim() === "" || cont.startsWith("- ")) break;
+      const body = cont.trim().match(TRIGGER_RE)?.[1];
+      if (body !== undefined) triggers = parseTriggers(body);
+      else text += ` ${cont.trim()}`;
+    }
+    if (triggers) out.push({ text: compact(text), triggers });
+  }
+  return out;
+}
+
+let memo: { key: string; entries: LessonEntry[] } | null = null;
+
+/**
+ * Compile (once per file version) the triggered-lesson index from `file`.
+ * Memoized by path+mtime: re-parses only when LESSON.md changes.
+ * @param file - Absolute path to MEMORY/LESSON.md.
+ * @returns The compiled entries (missing/unreadable file → empty).
+ */
+export function lessonIndex(file: string): LessonEntry[] {
+  let key: string;
+  try {
+    key = `${file}:${statSync(file).mtimeMs}`;
+  } catch {
+    return [];
+  }
+  if (memo?.key === key) return memo.entries;
+  let entries: LessonEntry[] = [];
+  try {
+    entries = parseLessons(readFileSync(file, "utf-8"));
+  } catch {
+    entries = [];
+  }
+  memo = { key, entries };
+  return entries;
+}

package/src/policy/lessons/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Interfaces for the decision-time lesson engine: a lesson may carry an optional
+ * `[TRIGGERS ...]` tag that indexes it by tool/path/error/keyword so the ONE
+ * relevant lesson can be injected at the PreToolUse it applies to (instead of
+ * the whole LESSON.md block dumped at SessionStart).
+ */
+
+/** Parsed predicates from a lesson's optional `[TRIGGERS ...]` tag. */
+export interface Triggers {
+  /** Exact tool names (e.g. `Write`, `Bash`) — highest-specificity match. */
+  readonly tools: readonly string[];
+  /** Globs (`*`, `**`) matched against `tool_input.file_path`. */
+  readonly paths: readonly string[];
+  /** Regex source matched against a prior error, when supplied. */
+  readonly error?: string;
+  /** Substrings matched against the JSON of `tool_input` — lowest specificity. */
+  readonly keywords: readonly string[];
+}
+
+/** A compiled lesson: compact text (≤3 lines) plus its trigger predicates. */
+export interface LessonEntry {
+  readonly text: string;
+  readonly triggers: Triggers;
+}
+
+/**
+ * Cooldown gate reused from `../../runtime/inject-dedup`: `true` = emit now
+ * (first hit / window elapsed), `false` = still inside the window. Injected so
+ * the gate never grows its own window mechanism (team DRY).
+ */
+export type OncePerWindow = (key: string, windowMs: number) => boolean;

package/src/policy/module-layout.ts

@@ -0,0 +1,31 @@
+/**
+ * Module-aware suggestion helper, shared by every framework SOLID gate
+ * (react/next/laravel/swift/go/rust). Detection is purely path-based — no
+ * filesystem access — so it works identically for both Write (full content,
+ * real path) and Edit (snippet, real path).
+ */
+
+/** Matches a `modules/<name>/` path segment anywhere in the file path. */
+const MODULE_SEGMENT_RE: RegExp = /(?:^|\/)modules\/([^/]+)\//;
+
+/**
+ * Extract the module name from a `modules/<name>/…` path segment.
+ * @param filePath - path of the file under validation
+ * @returns the module name, or `undefined` when the file isn't inside `modules/<name>/`
+ */
+export function moduleName(filePath: string): string | undefined {
+  return MODULE_SEGMENT_RE.exec(filePath)?.[1];
+}
+
+/**
+ * Build a module-aware destination suggestion. When `filePath` sits inside a
+ * `modules/<name>/` directory, nests `subpath` under that module; otherwise
+ * falls back to the language's own default convention.
+ * @param filePath - path of the file under validation
+ * @param subpath - subpath to nest inside `modules/<name>/` when a module is detected
+ * @param fallback - suggestion to use when no module is detected
+ */
+export function moduleAwarePath(filePath: string, subpath: string, fallback: string): string {
+  const name = moduleName(filePath);
+  return name ? `modules/${name}/${subpath}` : fallback;
+}

package/src/policy/nearest-manifest.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { detectProjectType } from "./detect-project";
+
+/** Real project capabilities inferred from a manifest's deps + config files. */
+export type Cap =
+  | "react" | "nextjs" | "vue" | "svelte" | "angular" | "nuxt"
+  | "laravel" | "swift" | "tailwind"
+  | "tanstack-start" | "tanstack-router" | "tanstack-query" | "vue-query"
+  | "zustand" | "pinia";
+
+/** Manifest filenames that anchor a project root (any one marks the dir). */
+const MANIFESTS = ["package.json", "composer.json", "Package.swift", "Cargo.toml", "go.mod", "pyproject.toml"];
+
+/**
+ * Walk up from `startDir` to the NEAREST ancestor holding any manifest file.
+ * Unlike {@link projectRootOrNull} (which prefers the `.git` boundary and would
+ * skip a nested `scripts/package.json`), this returns the closest manifest dir,
+ * so an inner monorepo package wins over the repo root.
+ * @param startDir - Directory to begin the walk-up from.
+ * @returns The nearest manifest directory, or `null` at the filesystem root.
+ */
+export function nearestManifestDir(startDir: string): string | null {
+  let current = resolve(startDir);
+  for (;;) {
+    if (MANIFESTS.some((m) => existsSync(join(current, m)))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * Read the REAL capabilities of the project rooted at `dir`: JS-framework deps
+ * from `package.json` (which {@link detectProjectType} does NOT scan), plus the
+ * non-JS/config signals detectProjectType already covers (laravel/swift/
+ * tailwind) — reused, not duplicated. Fail-open: any parse error yields whatever
+ * was gathered so far, never throws.
+ * @param dir - A manifest directory (from {@link nearestManifestDir}), or null.
+ * @returns The set of detected capabilities (empty when `dir` is null).
+ */
+export function projectCaps(dir: string | null): Set<Cap> {
+  const caps = new Set<Cap>();
+  if (!dir) return caps;
+  try {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if ("react" in deps || "react-dom" in deps) caps.add("react");
+      if ("next" in deps) caps.add("nextjs");
+      if ("vue" in deps) caps.add("vue");
+      if ("svelte" in deps) caps.add("svelte");
+      if ("@angular/core" in deps) caps.add("angular");
+      if ("nuxt" in deps) caps.add("nuxt");
+      if ("tailwindcss" in deps) caps.add("tailwind");
+      if ("@tanstack/react-start" in deps) caps.add("tanstack-start");
+      if ("@tanstack/react-router" in deps) caps.add("tanstack-router");
+      if ("@tanstack/react-query" in deps) caps.add("tanstack-query");
+      if ("@tanstack/vue-query" in deps) caps.add("vue-query");
+      if ("zustand" in deps) caps.add("zustand");
+      if ("pinia" in deps) caps.add("pinia");
+    }
+    const type = detectProjectType(dir);
+    if (type === "laravel") caps.add("laravel");
+    if (type === "swift") caps.add("swift");
+    if (type === "tailwind") caps.add("tailwind");
+  } catch {
+    // fail-open: return what we have
+  }
+  return caps;
+}