@fusengine/harness 0.1.90 → 0.1.92

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/");

package/src/policy/conventions/query.ts

@@ -0,0 +1,49 @@
+/**
+ * TanStack Query definition detection over MASKED content (React and Vue
+ * variants share the call names; the family scoping is the gate's job, via
+ * project deps). Canonical home: `src/query/` — one file per domain. Only
+ * DEFINITIONS are gated; inline consumption of a hook defined in `query/`
+ * stays allowed.
+ */
+import { maskCommentsAndStrings } from "./strip";
+import { nearestManifestDir, projectCaps } from "../nearest-manifest";
+import { dirname, resolve } from "node:path";
+
+/** Import line of a TanStack Query package (raw scan: masking blanks the module string). */
+const QUERY_IMPORT_RE = /^\s*import\s+[^;]*@tanstack\/[\w-]*query[\w-]*/m;
+
+/** A TanStack Query definition call. */
+const QUERY_CALL_RE = /\b(?:useQuery|useMutation|useInfiniteQuery|queryOptions)\s*(?:<[^()]*>)?\s*\(/;
+
+/** Exported declaration (`export const|function`) — a defined query hook. */
+const EXPORT_DECL_RE = /^\s*export\s+(?:const|function)\s+\w+/m;
+
+/**
+ * True when the file imports a TanStack Query package (raw scan, anchored to
+ * real import lines so `// import …` comments cannot match).
+ * @param content - Raw file content.
+ */
+export function importsTanstackQuery(content: string): boolean {
+  return QUERY_IMPORT_RE.test(content);
+}
+
+/**
+ * True when the file DEFINES an exported query/mutation hook (export +
+ * query call, masked scan) — as opposed to merely consuming one inline.
+ * @param content - Raw file content.
+ */
+export function declaresQueryHook(content: string): boolean {
+  const masked = maskCommentsAndStrings(content, "c");
+  return QUERY_CALL_RE.test(masked) && EXPORT_DECL_RE.test(masked);
+}
+
+/**
+ * True when the nearest manifest of `filePath` declares a TanStack Query
+ * dependency (`@tanstack/react-query` or `@tanstack/vue-query`) — the
+ * cap gate of every query convention (owner: no cap, no query rule).
+ * @param filePath - The file being judged (its nearest manifest wins).
+ */
+export function queryCapActive(filePath: string): boolean {
+  const caps = projectCaps(nearestManifestDir(dirname(resolve(filePath))));
+  return caps.has("tanstack-query") || caps.has("vue-query");
+}

package/src/policy/conventions/react-hooks.ts

@@ -0,0 +1,18 @@
+/**
+ * Custom React hook declaration detection over MASKED content. Historical
+ * rule (`framework-solid-gates.ts`): an exported custom hook belongs in
+ * `hooks/` — the regex was naive (`^export (function|const) use[A-Z]`,
+ * missing `export default`, `async`, and matching inside comments/strings).
+ */
+import { maskCommentsAndStrings } from "./strip";
+
+/** Exported custom hook: `export [default] [async] function|const useX`. */
+const HOOK_DECL_RE = /^\s*export\s+(?:default\s+)?(?:async\s+)?(?:function|const)\s+use[A-Z]\w*/m;
+
+/**
+ * True when the file declares an exported custom `use*` hook (masked scan).
+ * @param content - Raw file content.
+ */
+export function declaresCustomHook(content: string): boolean {
+  return HOOK_DECL_RE.test(maskCommentsAndStrings(content, "c"));
+}

package/src/policy/conventions/store-or-query.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared store/query-definition exemption (owner F0.2): a file is governed
+ * by the store/query conventions — NOT by the hook-location rule — ONLY when
+ * its signature is validated AND its ecosystem is confirmed:
+ * - store: the real `zustand`/`pinia` import (or the v5 curried signature);
+ * - query: a TanStack Query definition AND the `@tanstack/*-query` cap in
+ *   the nearest manifest. Without the cap, a fake `useQuery(` caller is just
+ *   a hook — the legacy hook rule applies, byte-identical.
+ */
+import { declaresStore } from "./stores";
+import { declaresQueryHook, queryCapActive } from "./query";
+
+/**
+ * True when the file is a store or query definition (exempt from hook rules).
+ * @param filePath - The file being judged (manifest resolution for the cap).
+ * @param content - Its RAW content (detectors mask internally).
+ */
+export function isStoreOrQueryDefinition(filePath: string, content: string): boolean {
+  if (declaresStore(content, "zustand") || declaresStore(content, "pinia")) return true;
+  return declaresQueryHook(content) && queryCapActive(filePath);
+}

package/src/policy/conventions/stores.ts

@@ -0,0 +1,56 @@
+/**
+ * State-store declaration detection over MASKED content — Zustand (React
+ * family) and Pinia (Vue family), per the owner's framework scoping: a rule
+ * only fires inside its own family (the gate checks the project deps, this
+ * module only reads content). Canonical home: `src/stores/`, `*.store.ts`,
+ * one store per domain, budget = ratio 0.4 of the global line limit.
+ *
+ * Signature-strict (audit lesson): `Object.create(` and home-made
+ * `create(` factories never match — Zustand requires the `zustand` import
+ * (or the v5 curried `create<T>()(...)` call), Pinia requires the `pinia`
+ * import alongside `defineStore(`.
+ */
+import { maskCommentsAndStrings, maskCommentsOnly } from "./strip";
+
+/** Store library whose declarations are being scanned. */
+export type StoreLib = "zustand" | "pinia";
+
+/** Import line of the store package — comments masked (a `// import …` line
+ * never matches), strings KEPT (masking would blank the module literal). */
+const STORE_IMPORT_RE: Record<StoreLib, RegExp> = {
+  zustand: /^\s*import\s+[^;]*from\s+['"]zustand/m,
+  pinia: /^\s*import\s+[^;]*from\s+['"]pinia/m,
+};
+
+/** Zustand v5 curried declaration: `export const useX = create<S>()(`. */
+const ZUSTAND_CURRIED_RE = /^\s*export\s+const\s+\w+\s*=\s*create\s*<[^=]*>\s*\(\s*\)\s*\(/m;
+/** Zustand declaration with import context: `export const useX = create(`. */
+const ZUSTAND_DECL_RE = /^\s*export\s+const\s+\w+\s*=\s*create(?:Store)?\s*(?:<[^(]+>)?\s*\(/m;
+/** Pinia declaration: `export const useX = defineStore(`. */
+const PINIA_DECL_RE = /^\s*export\s+const\s+\w+\s*=\s*defineStore\s*\(/m;
+
+/**
+ * True when the file declares a store of the given library (masked scan,
+ * signature-strict).
+ * @param content - Raw file content.
+ * @param lib - Store library to detect.
+ */
+export function declaresStore(content: string, lib: StoreLib): boolean {
+  const masked = maskCommentsAndStrings(content, "c");
+  const importable = maskCommentsOnly(content, "c");
+  if (lib === "pinia") return STORE_IMPORT_RE.pinia.test(importable) && PINIA_DECL_RE.test(masked);
+  return ZUSTAND_CURRIED_RE.test(masked) || (STORE_IMPORT_RE.zustand.test(importable) && ZUSTAND_DECL_RE.test(masked));
+}
+
+/**
+ * Count store declarations in one file (multi-store advisory: one per domain).
+ * @param content - Raw file content.
+ * @param lib - Store library to count.
+ */
+export function countStores(content: string, lib: StoreLib): number {
+  const masked = maskCommentsAndStrings(content, "c");
+  const re = lib === "pinia" ? PINIA_DECL_RE : ZUSTAND_DECL_RE;
+  const curried = masked.match(new RegExp(ZUSTAND_CURRIED_RE.source, "gm"))?.length ?? 0;
+  const plain = masked.match(new RegExp(re.source, "gm"))?.length ?? 0;
+  return lib === "pinia" ? plain : Math.max(curried, plain);
+}

package/src/policy/conventions/strip.ts

@@ -0,0 +1,87 @@
+/**
+ * Lexical comment/string masking for convention detectors. Every convention
+ * rule (interfaces, types, hooks, stores, query) matches against MASKED
+ * content so a declaration-looking line inside a comment, string, template
+ * literal, or heredoc can never trigger a verdict. Masking replaces the
+ * covered CHARACTERS with spaces but keeps every newline: line offsets and
+ * `^…/m` anchors stay valid, and the output has the same line count.
+ * Not a parser — a per-family state machine (c-like, python, ruby, php).
+ */
+
+/** Lexical profile of a language family. */
+export type LexProfile = "c" | "py" | "rb" | "php";
+
+/** Mask PHP heredoc/nowdoc blocks (`<<<TAG` … terminator line), offsets kept. */
+function maskHeredocs(content: string): string {
+  return content.replace(/<<<['"]?(\w+)['"]?\r?\n[\s\S]*?^\1;?$/gm, (block) => block.replace(/[^\n]/g, " "));
+}
+
+/**
+ * Mask comments and strings of `content` according to its lexical profile.
+ * @param content - Source text.
+ * @param profile - Lexical family (see `langs.ts` `lexProfileOf`).
+ * @returns Same-length text with comment/string interiors blanked.
+ */
+export function maskCommentsAndStrings(content: string, profile: LexProfile): string {
+  return maskScan(content, profile, false);
+}
+
+/**
+ * Mask COMMENTS only (strings kept) — for detectors whose signal IS a string
+ * literal (module imports like `from "zustand"`): a `// import …` comment
+ * cannot match, while the real import line stays readable.
+ * @param content - Source text.
+ * @param profile - Lexical family.
+ * @returns Same-length text with comment interiors blanked.
+ */
+export function maskCommentsOnly(content: string, profile: LexProfile): string {
+  return maskScan(content, profile, true);
+}
+
+/** Shared scanner; `keepStrings` skips the string-masking branch. */
+function maskScan(content: string, profile: LexProfile, keepStrings: boolean): string {
+  if (profile === "php") content = maskHeredocs(content);
+  const out = content.split("");
+  const blank = (i: number) => { if (out[i] !== "\n") out[i] = " "; };
+  const isPy = profile === "py" || profile === "rb";
+  let i = 0;
+  while (i < out.length) {
+    const two = content.slice(i, i + 2);
+    if (!isPy && two === "//") { while (i < out.length && out[i] !== "\n") blank(i++); continue; }
+    if (isPy && out[i] === "#") { while (i < out.length && out[i] !== "\n") blank(i++); continue; }
+    if (profile === "php" && out[i] === "#") { while (i < out.length && out[i] !== "\n") blank(i++); continue; }
+    if (!isPy && two === "/*") { const end = content.indexOf("*/", i + 2); const stop = end === -1 ? out.length : end + 2; while (i < stop) blank(i++); continue; }
+    if (isPy && (content.startsWith("'''", i) || content.startsWith('"""', i))) {
+      const q = content.slice(i, i + 3);
+      const end = content.indexOf(q, i + 3);
+      const stop = end === -1 ? out.length : end + 3;
+      while (i < stop) blank(i++);
+      continue;
+    }
+    if (!keepStrings && (out[i] === "'" || out[i] === '"' || (profile === "c" && out[i] === "`"))) {
+      const q = out[i] as string;
+      // Unterminated-quote guard: a single/double quote never opens a string
+      // past its own line (JS/TS has no multiline plain strings — a JSX
+      // apostrophe like `Don't` must not swallow the rest of the file), and
+      // an unterminated template literal masks nothing (unpaired backtick).
+      let j = i + 1, closed = -1;
+      while (j < out.length && out[j] !== "\n") {
+        if (out[j] === "\\") { j += 2; continue; }
+        if (out[j] === q) { closed = j; break; }
+        j++;
+      }
+      if (q === "`") {
+        if (closed !== -1) { while (i <= closed) blank(i++); continue; }
+        const end = content.indexOf("`", i + 1);
+        if (end !== -1) { while (i <= end) blank(i++); continue; }
+        i++;
+        continue;
+      }
+      if (closed === -1) { i++; continue; }
+      while (i <= closed) blank(i++);
+      continue;
+    }
+    i++;
+  }
+  return out.join("");
+}

package/src/policy/conventions/verdict.ts

@@ -0,0 +1,38 @@
+/**
+ * Rollout control for NEW convention denies (owner decision, inverted
+ * 2026-07): new convention rules BLOCK by default — `FUSE_CONVENTIONS_MODE`
+ * is an opt-OUT. Set it to `advisory` to observe without blocking (`inform`
+ * output); any absent or invalid value means `deny`. Denies that already
+ * existed before the conventions module are unaffected (byte-parity); this
+ * module only ever MODULATES the new ones.
+ */
+import type { Prompt } from "../../prompt/types";
+
+/** Rollout mode for new convention denies. */
+export type ConventionsMode = "advisory" | "deny";
+
+/**
+ * Current rollout mode: `advisory` ONLY on the exact explicit value —
+ * anything else (absent, typo, empty) is `deny` (owner decision: deny-first).
+ * @param env - Environment (defaults to `process.env`).
+ */
+export function conventionsMode(env: Record<string, string | undefined> = process.env): ConventionsMode {
+  return env.FUSE_CONVENTIONS_MODE === "advisory" ? "advisory" : "deny";
+}
+
+/**
+ * Resolve a convention verdict under the rollout flag: a NEW rule yields an
+ * `inform` prompt in advisory mode (explicit opt-out), the blocking prompt
+ * otherwise; an EXISTING rule always yields the blocking prompt unchanged.
+ * @param prompt - The blocking prompt the rule would emit.
+ * @param isNew - True when the rule is new (post-conventions module).
+ * @param env - Environment (defaults to `process.env`).
+ */
+export function rolloutVerdict(
+  prompt: Prompt,
+  isNew: boolean,
+  env: Record<string, string | undefined> = process.env,
+): Prompt {
+  if (!isNew || conventionsMode(env) === "deny") return prompt;
+  return { kind: "inform", title: prompt.title, reason: prompt.reason, actions: prompt.actions };
+}

package/src/policy/creation-intent.ts

@@ -0,0 +1,11 @@
+const CREATE_RE = /\b(?:create|implement|add|build|new|feature|component|generate|make|develop|scaffold)\b/i;
+const SKIP_RE = /\b(?:fix|bug|debug|update|refactor|rename|move|delete|remove|commit|push|status|edit|modify|change|adjust|tweak|existing|current)\b/i;
+
+/**
+ * True when a prompt expresses creation intent (a new feature/component) and is
+ * not a fix/refactor — the signal that brainstorming should precede creation.
+ * The harness calls this on UserPromptSubmit, then `recordBrainstormRequired`.
+ */
+export function detectCreationIntent(prompt: string): boolean {
+  return CREATE_RE.test(prompt) && !SKIP_RE.test(prompt);
+}