@fusengine/harness 0.1.89 → 0.1.91

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

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

package/src/policy/apex.ts

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

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

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

package/src/policy/cartographer/describe.ts

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

package/src/policy/cartographer/entry.ts

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

package/src/policy/cartographer/frontmatter.ts

@@ -0,0 +1,48 @@
+/**
+ * Frontmatter parsing — pure text helpers (no fs). Ports `parse_frontmatter.py`.
+ */
+
+const BLOCK_SCALARS: ReadonlySet<string> = new Set(["|", ">", "|+", "|-", ">+", ">-"]);
+
+/** Escape regex metacharacters in an arbitrary field name. */
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extract a single frontmatter field's value from `text`. Strips surrounding
+ * quotes; skips YAML block-scalar markers. Returns "" when absent.
+ * @param text - The full document text.
+ * @param field - The frontmatter key to read.
+ * @returns The field value, or "".
+ */
+export function parseField(text: string, field: string): string {
+  const fm = /^---\s*\n([\s\S]*?)\n---/.exec(text);
+  if (!fm || fm[1] === undefined) return "";
+  const lineRe = new RegExp(`^${escapeRe(field)}\\s*:\\s*(.+)$`);
+  for (const line of fm[1].split("\n")) {
+    const m = lineRe.exec(line);
+    if (!m || m[1] === undefined) continue;
+    const val = m[1].trim().replace(/^["']|["']$/g, "");
+    if (BLOCK_SCALARS.has(val)) continue;
+    return val;
+  }
+  return "";
+}
+
+/**
+ * Derive a short description from the body following the frontmatter: the first
+ * non-empty trimmed line, sliced to `maxLen`. Returns "" when none.
+ * @param text - The full document text.
+ * @param maxLen - Maximum length of the returned description.
+ * @returns The body-derived description, or "".
+ */
+export function parseBodyDesc(text: string, maxLen: number = 60): string {
+  const m = /^---\s*\n[\s\S]*?\n---\s*\n([\s\S]*)/.exec(text);
+  if (!m || m[1] === undefined) return "";
+  for (const raw of m[1].split("\n")) {
+    const line = raw.trim();
+    if (line) return line.slice(0, maxLen);
+  }
+  return "";
+}

package/src/policy/cartographer/indicators.ts

@@ -0,0 +1,34 @@
+/**
+ * Cartographer indicators — pure data sets used to detect a project root and to
+ * exclude noise directories when walking a tree. Ports the constant tables from
+ * `generate_project_map.py` / `write_recursive.py`.
+ */
+
+/** Filenames whose presence marks a directory as a project root. */
+export const PROJECT_INDICATORS: ReadonlySet<string> = new Set([
+  "package.json", "deno.json", "bun.lockb", "bun.lock", "tsconfig.json",
+  "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "pnpm-workspace.yaml",
+  "composer.json", "artisan", "Cargo.toml", "rust-toolchain.toml", "go.mod",
+  "pyproject.toml", "setup.py", "setup.cfg", "Pipfile", "requirements.txt",
+  "environment.yml", "Gemfile", "Package.swift", "Podfile", "pubspec.yaml",
+  "pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", "build.sbt",
+  "Makefile", "CMakeLists.txt", "meson.build", "configure.ac",
+  "Directory.Build.props", "global.json", "mix.exs", "rebar.config",
+  "project.clj", "deps.edn", "stack.yaml", "cabal.project", "dune-project",
+  "build.zig", "gleam.toml", "v.mod", "Project.toml", "DESCRIPTION", "cpanfile",
+  "Makefile.PL", ".luacheckrc", "astro.config.mjs", "next.config.js",
+  "next.config.mjs", "nuxt.config.ts", "vite.config.ts", "next.config.ts",
+  "angular.json", "svelte.config.js", "svelte.config.ts", "main.tf",
+  "ansible.cfg", "pulumi.yaml", "cdk.json", "Chart.yaml", "wrangler.toml",
+  "fly.toml", "turbo.json", "nx.json", "BUILD", "WORKSPACE", "Justfile",
+  "Taskfile.yml", "docker-compose.yml", "docker-compose.yaml", "compose.yml",
+  "compose.yaml", "Dockerfile", ".git",
+]);
+
+/** Directory names skipped entirely during the tree walk. */
+export const EXCLUDE_DIRS: ReadonlySet<string> = new Set([
+  "node_modules", ".git", ".next", ".nuxt", "dist", "build", ".output",
+  "vendor", "__pycache__", ".venv", "venv", ".cartographer", ".claude",
+  ".ruff_cache", ".DS_Store", "coverage", ".turbo", ".vercel", ".netlify",
+  "Pods", "DerivedData", ".build", ".swiftpm",
+]);

package/src/policy/claude-md-context.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveMaxLines } from "../config/limits";
+import { DEV_KEYWORDS, type ProjectType } from "./detect-project";
+import { getExpertAgent } from "./expert-agents";
+import { apexDocName, apexPlanTool, harnessHomeSegment } from "./apex-target";
+import { detectClaudeMdProjectType } from "./detect-claude-md-project-type";
+
+export { detectClaudeMdProjectType };
+
+/** Dev-verb regex (FR/EN) that triggers the APEX preamble (case-insensitive). */
+export const DEV_VERBS: RegExp =
+  /(cr[ée]er|impl[ée]menter|ajouter|d[ée]velopper|construire|build|refactor|migrer|implement|create|add|develop)/i;
+
+/**
+ * Build the APEX instruction preamble for a development task.
+ * @param projectType - Detected project type label.
+ * @param maxLines - SOLID per-file line ceiling.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The APEX instruction text.
+ */
+export function buildApexInstruction(projectType: ProjectType, maxLines: number, id: string = "claude-code"): string {
+  const expertAgent = getExpertAgent(projectType);
+  const seg = harnessHomeSegment(id);
+  const planTool = apexPlanTool(id);
+  return (
+    `INSTRUCTION: This is a development task. Use APEX methodology:\n\n` +
+    `**TRACKING FILE**: [project]/${seg}/apex/task.json — create it yourself via apex-methodology Step 0 (init-tracking) if missing\n\n` +
+    `1. **ANALYZE** (MANDATORY - 3 AGENTS IN PARALLEL):\n` +
+    `   - explore-codebase + research-expert + ${expertAgent} (framework expertise)\n` +
+    `   - Project type detected: ${projectType}\n\n` +
+    `2. **PLAN**: Use ${planTool} to break down tasks (<${maxLines} lines per file)\n\n` +
+    `3. **EXECUTE**: ${expertAgent}, follow SOLID principles, split at ${maxLines - 10} lines\n\n` +
+    `4. **eLICIT**: self-review with NAMED elicitation techniques (apex ref 03.5-elicit) — fix findings BEFORE validation\n\n` +
+    `5. **VERIFY**: functional check — run it, confirm references⇔declarations consistency\n\n` +
+    `6. **eXAMINE**: Run sniper agent after ANY modification\n\n` +
+    `**GATE**: eLicit + Verify BEFORE sniper — NEVER skip.\n\n` +
+    `**IMPORTANT**: Read ${seg}/apex/task.json to check documentation status before writing code.`
+  );
+}
+
+/**
+ * Build the UserPromptSubmit injection text: read the target's root
+ * instructions doc (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, ...) and,
+ * when the prompt matches a dev verb, prepend the APEX instruction. Returns
+ * `null` when the doc is absent/unreadable (the hook then emits nothing).
+ * @param prompt - The raw user prompt.
+ * @param cwd - Project root (for project-type detection).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The injection text, or `null` to emit nothing.
+ */
+export function buildClaudeMdContext(prompt: string, cwd: string, id: string = "claude-code"): string | null {
+  const docName = apexDocName(id);
+  const claudeMd = join(homedir(), harnessHomeSegment(id), docName);
+  if (!existsSync(claudeMd)) return null;
+  let claudeContent: string;
+  try {
+    claudeContent = readFileSync(claudeMd, "utf-8");
+  } catch {
+    return null;
+  }
+  if (!DEV_VERBS.test(prompt) && !DEV_KEYWORDS.test(prompt)) return `# ${docName}\n${claudeContent}`;
+  const apex = buildApexInstruction(detectClaudeMdProjectType(cwd), resolveMaxLines(), id);
+  return `${apex}\n\n# ${docName}\n${claudeContent}`;
+}

package/src/policy/conventions/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Convention detectors (canonical module structure: interfaces, types,
+ * hooks, stores, query) — masked-content, per-language, single source for
+ * every convention gate.
+ */
+export * from "./strip";
+export * from "./langs";
+export * from "./interfaces";
+export * from "./react-hooks";
+export * from "./stores";
+export * from "./query";

package/src/policy/conventions/interfaces.ts

@@ -0,0 +1,71 @@
+/**
+ * Interface/type-contract declaration detection, per language, over MASKED
+ * content (see `strip.ts` — comments and strings never match). Single source
+ * consumed by every interface gate; the four historical layers each carried
+ * their own regexes (alias `type X =` false positives, unanchored
+ * `class.*ABC`, missed `public protocol`/`sealed interface`/generics).
+ *
+ * Rule symmetry (owner spec): an EXPORTED contract belongs to its directory
+ * (interfaces/ resp. types/); a non-exported local declaration is allowed.
+ *
+ * Each detection carries a LEVEL: `"legacy"` (the exact historical semantics,
+ * hard deny byte-identical) vs `"extended"` (syntax widenings — Go
+ * `interface{` without the space, Python `Protocol` — advisory-first via
+ * `FUSE_CONVENTIONS_MODE`, owner Amendment 5). Go anchors at column 0: an
+ * interface declared INSIDE a function (indented, a true false positive — a
+ * local type cannot move to internal/interfaces/) never matches.
+ */
+import { langOfPath, lexProfileOf, type LangFamily } from "./langs";
+import { maskCommentsAndStrings } from "./strip";
+
+/** Detection level: historical semantics (hard deny) vs advisory widening. */
+export type InterfaceDeclLevel = "legacy" | "extended";
+
+const LEGACY_RE: Partial<Record<LangFamily, RegExp>> = {
+  ts: /^\s*export\s+(?:declare\s+)?interface\s+\w+/m,
+  py: /^\s*class\s+\w+\s*\([^)]*\b(?:ABC|ABCMeta)\b/m,
+  go: /^type\s+\w+\s+interface\s+\{/m,
+  rs: /^\s*(?:pub\s+)?trait\s+\w+/m,
+  java: /^\s*(?:(?:public|sealed|final|abstract)\s+)*(?:interface|@FunctionalInterface)\s*\w*|^\s*fun\s+interface\s+\w+/m,
+  php: /^\s*(?:abstract\s+class|interface)\s+\w+/m,
+  swift: /^\s*(?:(?:public|open|internal|private|fileprivate)\s+)?protocol\s+\w+/m,
+};
+
+const EXTENDED_RE: Partial<Record<LangFamily, RegExp>> = {
+  py: /^\s*class\s+\w+\s*\([^)]*\bProtocol\b/m,
+  go: /^type\s+\w+\s+interface\b/m,
+};
+
+/** Exported TS type alias (`export type X = …`) — belongs in `src/types/`. */
+const TYPE_ALIAS_RE = /^\s*export\s+type\s+\w+\s*[=<]/m;
+
+/**
+ * Classify the interface declaration level of a file (masked scan), or null.
+ * @param filePath - File path (extension selects the language).
+ * @param content - Raw file content (masked internally).
+ */
+export function interfaceDeclLevel(filePath: string, content: string): InterfaceDeclLevel | null {
+  const lang = langOfPath(filePath);
+  if (!lang) return null;
+  const masked = maskCommentsAndStrings(content, lexProfileOf(lang));
+  if (LEGACY_RE[lang]?.test(masked)) return "legacy";
+  if (EXTENDED_RE[lang]?.test(masked)) return "extended";
+  return null;
+}
+
+/**
+ * True when the file declares an interface-like contract at any level.
+ * @param filePath - File path (extension selects the language).
+ * @param content - Raw file content (masked internally).
+ */
+export function declaresInterface(filePath: string, content: string): boolean {
+  return interfaceDeclLevel(filePath, content) !== null;
+}
+
+/**
+ * True when a TS-family file declares an EXPORTED type alias (masked scan).
+ * @param content - Raw file content.
+ */
+export function declaresExportedTypeAlias(content: string): boolean {
+  return TYPE_ALIAS_RE.test(maskCommentsAndStrings(content, "c"));
+}

package/src/policy/conventions/langs.ts

@@ -0,0 +1,53 @@
+/**
+ * Language detection and canonical convention paths. Single source for
+ * "which family does this extension belong to" and "is this path already in
+ * the right convention directory" — every convention gate (interfaces,
+ * types, hooks, stores, query) consumes these predicates instead of
+ * re-deriving its own path rules.
+ *
+ * Canonical module structure (owner spec, 2026-07):
+ *   modules/<feature>/components/      reusable module components
+ *   modules/<feature>/src/interfaces/  interface Foo { } contracts
+ *   modules/<feature>/src/types/       exported type aliases
+ *   modules/<feature>/src/hooks/       custom use* hooks
+ *   modules/<feature>/src/stores/      *.store.ts (Zustand, Pinia)
+ *   modules/<feature>/src/query/       TanStack Query definitions
+ * (+ modules/cores/… for cross-feature code)
+ */
+import type { LexProfile } from "./strip";
+
+/** Language family a convention rule applies to, or null when out of scope. */
+export type LangFamily = "ts" | "py" | "go" | "rs" | "java" | "php" | "swift" | "rb" | "vue";
+
+const EXT_LANG: Record<string, LangFamily> = {
+  ts: "ts", tsx: "ts", js: "ts", jsx: "ts", mts: "ts", mjs: "ts", astro: "ts", svelte: "ts",
+  py: "py", go: "go", rs: "rs", java: "java", kt: "java",
+  php: "php", swift: "swift", rb: "rb", vue: "vue",
+};
+
+/** Language family for a file path (by extension), or null when unsupported. */
+export function langOfPath(filePath: string): LangFamily | null {
+  const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
+  return EXT_LANG[ext] ?? null;
+}
+
+/** Lexical profile for masking, derived from the language family. */
+export function lexProfileOf(lang: LangFamily): LexProfile {
+  if (lang === "py") return "py";
+  if (lang === "rb") return "rb";
+  if (lang === "php") return "php";
+  return "c";
+}
+
+/** True for dotfiles/dependency dirs never subject to conventions. */
+export function isVendorPath(filePath: string): boolean {
+  return /(^|\/)(node_modules|vendor|dist|build|\.next|coverage)\//.test(filePath);
+}
+
+/** Path predicates — canonical convention directories. */
+export const isInterfacesPath = (p: string): boolean => /\/(interfaces|Contracts|Protocols|traits)\//.test(p) || p.endsWith("traits.rs");
+export const isTypesPath = (p: string): boolean => p.includes("/types/") || p.endsWith(".d.ts");
+export const isHooksPath = (p: string): boolean => p.includes("/hooks/") || p.includes("/composables/");
+export const isStoresPath = (p: string): boolean => p.includes("/stores/");
+export const isQueryPath = (p: string): boolean => p.includes("/query/");
+export const isComponentsPath = (p: string): boolean => p.includes("/components/");