@fusengine/harness 0.1.80 → 0.1.83

package/dist/tracking/index.d.mts

@@ -1,19 +1,29 @@
-import { a as recordAgent, c as recordRefRead, d as trivialCount, i as emptyTrack, l as recordTarget, n as SessionTrack, o as recordBrainstormRequired, r as agentsFresh, s as recordDoc, t as AgentQuality, u as recordTrivialEdit } from "../session-state-CY4iohn_.mjs";
-
+import { a as recordAgent, c as recordRefRead, d as trivialCount, i as emptyTrack, l as recordTarget, n as SessionTrack, o as recordBrainstormRequired, r as agentsFresh, s as recordDoc, t as AgentQuality, u as recordTrivialEdit } from "../session-state-D5gLr66m.mjs";
 //#region src/tracking/store.d.ts
+/** Journal mode is the default; `FUSE_TRACK_JOURNAL=0` reverts to the legacy locked RMW (see the module NOTE: =0 ignores the uncompacted journal — recoverable, keep the `.log`). */
+declare function trackJournalEnabled(): boolean;
 /**
-* Load and verify a session track from a signed envelope file.
-*
-* Returns {@link emptyTrack} (fail closed) when the file is absent, corrupt, or
-* fails MAC validation — so the gates re-require real agents rather than trust a
-* forged track. Only a MAC mismatch triggers fail-closed; the nonce is advisory
-* and is never checked during load.
-*/
+ * Load a session track: the verified legacy snapshot (the migration base — an
+ * old `track-<sid>.json` with no log reads exactly as before) with the journal
+ * folded on top. Fail closed on tampering (envelope MAC, per-line MAC).
+ */
 declare function loadTrack(file: string): Promise<SessionTrack>;
 /**
-* Sign and persist a session track as a tamper-evident envelope, then write the
-* advisory nonce watermark.
-*/
+ * Persist a session track. Journal mode appends the diff as signed events;
+ * legacy mode signs and persists the tamper-evident envelope, then writes the
+ * advisory nonce watermark.
+ */
 declare function saveTrack(file: string, track: SessionTrack): Promise<void>;
+/**
+ * Mutate a session track. Journal mode: load (snapshot ⊕ log), run `mutate`,
+ * append the resulting events — lock-free, so a write is only ever lost to a
+ * genuine I/O error (reported as `false`). Legacy mode: locked RMW; on lock
+ * contention the write is SKIPPED (fail-open, stderr logged) and `false` is
+ * returned — a named lost write, never a crash.
+ * @param file - The session track file.
+ * @param mutate - Pure mutation over the freshly loaded track.
+ * @returns True when the write landed.
+ */
+declare function withTrack(file: string, mutate: (track: SessionTrack) => SessionTrack | Promise<SessionTrack>): Promise<boolean>;
 //#endregion
-export { AgentQuality, SessionTrack, agentsFresh, emptyTrack, loadTrack, recordAgent, recordBrainstormRequired, recordDoc, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trivialCount };
+export { AgentQuality, SessionTrack, agentsFresh, emptyTrack, loadTrack, recordAgent, recordBrainstormRequired, recordDoc, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trackJournalEnabled, trivialCount, withTrack };

package/dist/tracking/index.mjs

@@ -1,2 +1,2 @@
-import { c as recordAgent, d as recordRefRead, f as recordTarget, l as recordBrainstormRequired, m as trivialCount, n as saveTrack, o as agentsFresh, p as recordTrivialEdit, s as emptyTrack, t as loadTrack, u as recordDoc } from "../store-nDZ3eLBQ.mjs";
-export { agentsFresh, emptyTrack, loadTrack, recordAgent, recordBrainstormRequired, recordDoc, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trivialCount };
+import { S as trivialCount, _ as recordBrainstormRequired, b as recordTarget, g as recordAgent, h as emptyTrack, i as withTrack, m as agentsFresh, n as saveTrack, r as trackJournalEnabled, t as loadTrack, v as recordDoc, x as recordTrivialEdit, y as recordRefRead } from "../store-Dw08Amqh.mjs";
+export { agentsFresh, emptyTrack, loadTrack, recordAgent, recordBrainstormRequired, recordDoc, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trackJournalEnabled, trivialCount, withTrack };

package/dist/{types-DVbIl9md.d.mts → types-C0-igRKr.d.mts}

@@ -2,10 +2,10 @@
 /** How a policy outcome should surface in a harness. */
 type PromptKind = "ask" | "block" | "inform";
 /**
-* Portable, harness-agnostic representation of a policy outcome as a prompt.
-* Adapters render this into their harness's native shape (a Claude
-* `permissionDecision`, a Cursor block, a CLI exit + message, ...).
-*/
+ * Portable, harness-agnostic representation of a policy outcome as a prompt.
+ * Adapters render this into their harness's native shape (a Claude
+ * `permissionDecision`, a Cursor block, a CLI exit + message, ...).
+ */
 interface Prompt {
   kind: PromptKind;
   /** Short title, e.g. "SOLID file-size limit". */
@@ -15,10 +15,10 @@ interface Prompt {
   /** Concrete next actions to proceed. */
   actions?: string[];
   /**
-  * User-facing notice (Python `hook_output.allow_pass`/`post_pass` parity):
-  * shown to the HUMAN — Claude Code's `systemMessage` — never to the agent,
-  * unlike `reason`/additionalContext. Excluded from {@link formatPrompt}.
-  */
+   * User-facing notice (Python `hook_output.allow_pass`/`post_pass` parity):
+   * shown to the HUMAN — Claude Code's `systemMessage` — never to the agent,
+   * unlike `reason`/additionalContext. Excluded from {@link formatPrompt}.
+   */
   userMessage?: string;
 }
 /** Render a {@link Prompt} as a consistent, agent-readable memo block. */

package/dist/types-DvXTI71X.d.mts

@@ -0,0 +1,15 @@
+//#region src/detect/interfaces/types.d.ts
+/** Known AI coding harnesses detectable at runtime. */
+type HarnessId = "claude-code" | "codex" | "cursor" | "cline" | "gemini-cli" | "opencode" | "windsurf" | "copilot" | "aider" | "kiro" | "goose" | "amp" | "hermes" | "kimi" | "unknown";
+/** Integration mode: `hook` = native lifecycle hooks; `cli` = run as an external step. */
+type HarnessMode = "hook" | "cli";
+/** How the harness was identified. */
+type HarnessVia = "agent-std" | "ai-agent-std" | "env" | "fallback";
+/** Result of {@link detectHarness}. */
+interface HarnessInfo {
+  id: HarnessId;
+  mode: HarnessMode;
+  via: HarnessVia;
+}
+//#endregion
+export { HarnessVia as i, HarnessInfo as n, HarnessMode as r, HarnessId as t };

package/dist/util/index.d.mts

@@ -1,2 +1,2 @@
-import { a as compactJson, i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "../index-BEMumjOw.mjs";
+import { a as compactJson, i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "../index-p9fLrSOD.mjs";
 export { compactJson, isCodeFile, projectRoot, projectRootOrNull, walkUpFor };

package/dist/{validate-CkmquRDV.mjs → validate-Bf-EsbDh.mjs}

@@ -1,11 +1,11 @@
-import { r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
-import { c as ttlLabel, t as HOME_DIR } from "./dotenv-B26N_uGr.mjs";
-import { R as DEV_KEYWORDS, g as moduleAwarePath } from "./evaluate-ClfbCDiY.mjs";
-import { d as countFrameworkCodeLines, l as PLUGINS_DIR, u as SOLID_REF } from "./home-state-BXf38Zi1.mjs";
+import { a as resolveMaxLines, c as storeBudget, i as hookBudget } from "./limits-DG5pl-5s.mjs";
+import { c as ttlLabel, t as HOME_DIR } from "./dotenv-DoqNlALG.mjs";
+import { A as moduleAwarePath, S as isHooksPath, T as isStoresPath, _ as rolloutVerdict, at as DEV_KEYWORDS, it as maskCommentsOnly, nt as projectCaps, rt as maskCommentsAndStrings, tt as nearestManifestDir, x as isComponentsPath, y as declaresInterface } from "./evaluate-B4-MhOy_.mjs";
+import { d as countFrameworkCodeLines, l as PLUGINS_DIR, u as SOLID_REF } from "./home-state-oUGFB4ds.mjs";
 import { r as isDocConsulted, t as formatDocDeny } from "./doc-helpers-CWZegVdR.mjs";
 import { t as routeReferences } from "./router-PKVNBHge.mjs";
-import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-CDvR4bbF.mjs";
-import { extname, join } from "node:path";
+import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-DhBGlQe3.mjs";
+import { dirname, extname, join, resolve } from "node:path";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 //#region src/refs/ref-key.ts
@@ -90,7 +90,7 @@ const solidReadGate = (ctx) => {
 	if (missing.length === 0) return null;
 	const optional = routed.optional.map((r) => r.meta.filePath);
 	const reason = [
-		`Read these before editing ${ctx.filePath} (expires every ${ttl}):`,
+		`Read ALL references below (including Optional), then retry — required before editing ${ctx.filePath} (expires every ${ttl}):`,
 		...optional.length ? [`Optional: ${optional.join(", ")}`] : [],
 		`Full skill: ${routed.skillPath}`
 	].join("\n");
@@ -229,12 +229,13 @@ function isExcludedSwiftPath(filePath) {
 /**
 * This harness's own gate-detection source files. They hold the React/Next
 * detection literals as regex source text (client-directive string, hook/
-* event names) — scanning them as JS/TS would self-match the very heuristics
-* they define. Exempt by exact filename, not by directory, so a genuine SOLID
-* violation elsewhere in src/policy/ stays gated by the framework-agnostic
-* line-size check in policy/evaluate.ts, untouched by this exemption.
+* event names, store/query/route signals) — scanning them as JS/TS would
+* self-match the very heuristics they define. Exempt by exact filename or by
+* the conventions/ detector directory, not by broad directory, so a genuine
+* SOLID violation elsewhere in src/policy/ stays gated by the
+* framework-agnostic line-size check in policy/evaluate.ts, untouched.
 */
-const SELF_GATE_EXCLUDE_RE = /(^|\/)src\/policy\/framework-solid-gates(-systems)?\.ts$/;
+const SELF_GATE_EXCLUDE_RE = /(^|\/)src\/policy\/(framework-solid-gates(-systems)?\.ts|framework-solid-extended\.ts|detect-framework\.ts|conventions\/[^/]+\.ts|guards\/interface-separation-ext\.ts)$/;
 /**
 * Whether a JS/TS file path is this harness's own gate-detection source —
 * exempt from the pattern heuristics (not the line-size ceiling) to avoid
@@ -245,13 +246,125 @@ function isSelfGateSourcePath(filePath) {
 	return SELF_GATE_EXCLUDE_RE.test(filePath);
 }
 //#endregion
+//#region src/policy/conventions/stores.ts
+/**
+* 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 line of the store package — comments masked (a `// import …` line
+* never matches), strings KEPT (masking would blank the module literal). */
+const STORE_IMPORT_RE = {
+	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.
+*/
+function declaresStore(content, lib) {
+	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.
+*/
+function countStores(content, lib) {
+	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);
+}
+//#endregion
+//#region src/policy/conventions/query.ts
+/**
+* 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 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.
+*/
+function importsTanstackQuery(content) {
+	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.
+*/
+function declaresQueryHook(content) {
+	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).
+*/
+function queryCapActive(filePath) {
+	const caps = projectCaps(nearestManifestDir(dirname(resolve(filePath))));
+	return caps.has("tanstack-query") || caps.has("vue-query");
+}
+//#endregion
+//#region src/policy/conventions/store-or-query.ts
+/**
+* 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.
+*/
+/**
+* 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).
+*/
+function isStoreOrQueryDefinition(filePath, content) {
+	if (declaresStore(content, "zustand") || declaresStore(content, "pinia")) return true;
+	return declaresQueryHook(content) && queryCapActive(filePath);
+}
+//#endregion
 //#region src/policy/framework-solid-gates.ts
 /** Custom hook export (React): `export function/const use[A-Z]`. */
 const HOOK_RE = /^export (function|const) use[A-Z]/m;
 /** Top-level TS interface/type declaration. */
 const TS_DECL_RE = /^(export )?(interface|type) [A-Z]/m;
 /** Client-only React hooks that require the `'use client'` directive. */
-const CLIENT_HOOK_RE = /(useState|useEffect|useRef|onClick|onChange)/;
+const CLIENT_HOOK_RE = /\b(useState|useEffect|useRef|onClick|onChange)\b/;
 /** PHP top-level `interface` declaration. */
 const PHP_INTERFACE_RE = /^interface /m;
 /** Swift top-level `protocol` declaration. */
@@ -261,6 +374,8 @@ const SWIFT_TYPE_RE = /^(class|struct) [^\n{]* \{/m;
 /** React: line limit, interface separation, custom hooks under `/hooks/`. */
 function reactGate(filePath, content, fileLines) {
 	const v = [];
+	const raw = content;
+	content = maskCommentsAndStrings(content, "c");
 	const max = resolveMaxLines();
 	const lines = fileLines ?? countFrameworkCodeLines(content);
 	if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Split to hooks/, components/, or utils/.`);
@@ -268,13 +383,16 @@ function reactGate(filePath, content, fileLines) {
 		const dest = moduleAwarePath(filePath, "src/interfaces/", "src/interfaces/ or src/types/");
 		v.push(`Interface/type in component. Move to ${dest}.`);
 	}
-	if (HOOK_RE.test(content) && !filePath.includes("/hooks/")) v.push("Custom hook defined outside hooks/ directory. Move to hooks/.");
+	if (HOOK_RE.test(content) && !filePath.includes("/hooks/") && !isStoreOrQueryDefinition(filePath, raw)) v.push("Custom hook defined outside hooks/ directory. Move to hooks/.");
 	return v;
 }
 /** Next.js: adaptive line limit, interface separation, `'use client'`. */
 function nextGate(filePath, content, fileLines) {
 	const v = [];
-	const max = /(page|layout|loading|error|not-found)\.(tsx|ts)$/.test(filePath) ? 150 : 100;
+	const raw = content;
+	content = maskCommentsAndStrings(content, "c");
+	const base = resolveMaxLines();
+	const max = /(page|layout|loading|error|not-found)\.(tsx|ts)$/.test(filePath) ? base + 50 : base;
 	const lines = fileLines ?? countFrameworkCodeLines(content);
 	if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Split to lib/, hooks/, or components/.`);
 	if (/\/(app|components|modules)\//.test(filePath) && !filePath.includes("/interfaces/") && TS_DECL_RE.test(content)) {
@@ -282,7 +400,7 @@ function nextGate(filePath, content, fileLines) {
 		v.push(`Interface/type in component. Move to ${dest}.`);
 	}
 	if (CLIENT_HOOK_RE.test(content)) {
-		const head = content.split("\n").slice(0, 5).join("\n");
+		const head = maskCommentsOnly(raw, "c").split("\n").slice(0, 5).join("\n");
 		if (!head.includes("'use client'") && !head.includes("\"use client\"")) v.push("Client hooks detected but 'use client' directive missing at top.");
 	}
 	return v;
@@ -290,6 +408,7 @@ function nextGate(filePath, content, fileLines) {
 /** Laravel/PHP: line limit, interface outside `/Contracts/`, fat controller (>80). */
 function laravelGate(filePath, content, fileLines) {
 	const v = [];
+	content = maskCommentsAndStrings(content, "php");
 	const lines = fileLines ?? countFrameworkCodeLines(content);
 	const max = resolveMaxLines();
 	if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Split using Services, Actions, or Traits.`);
@@ -303,7 +422,9 @@ function laravelGate(filePath, content, fileLines) {
 /** Swift: adaptive limit, protocol separation, @MainActor, Sendable. */
 function swiftGate(filePath, content, fileLines) {
 	const v = [];
-	const max = /(View|Screen)\.swift$/.test(filePath) ? 150 : 100;
+	content = maskCommentsAndStrings(content, "c");
+	const base = resolveMaxLines();
+	const max = /(View|Screen)\.swift$/.test(filePath) ? base + 50 : base;
 	const lines = fileLines ?? countFrameworkCodeLines(content);
 	if (lines > max) v.push(`File has ${lines} lines (limit: ${max}). Extract to ViewModels, Services, or subviews.`);
 	if (SWIFT_PROTOCOL_RE.test(content) && !filePath.includes("/Protocols/")) {
@@ -347,6 +468,7 @@ const RUST_DERIVE_PARSER_RE = /#\[derive\([^)]*Parser[^)]*\)\]/;
 /** Go: line limit, interface co-located with its (pointer-receiver) implementation. */
 function goGate(filePath, content, fileLines) {
 	const v = [];
+	content = maskCommentsAndStrings(content, "c");
 	const max = resolveMaxLines();
 	const lines = fileLines ?? countFrameworkCodeLines(content);
 	if (lines > max) {
@@ -381,6 +503,8 @@ function isClapArgsOnly(content) {
 /** Rust: line limit, trait co-location, god-main.rs, unsafe without `// SAFETY:`. */
 function rustGate(filePath, content, fileLines) {
 	const v = [];
+	const raw = content;
+	content = maskCommentsAndStrings(content, "c");
 	const max = resolveMaxLines();
 	const lines = fileLines ?? countFrameworkCodeLines(content);
 	if (lines > max) {
@@ -395,10 +519,133 @@ function rustGate(filePath, content, fileLines) {
 		}
 	}
 	if ((RUST_MAIN_RE.test(filePath) || RUST_BIN_RE.test(filePath)) && (RUST_TYPE_DECL_RE.test(content) || RUST_IMPL_RE.test(content)) && !isClapArgsOnly(content)) v.push("Entry point contains business logic — keep main.rs to wiring only (parse args, init, call lib.rs/app::run()).");
-	if (RUST_UNSAFE_RE.test(content) && !RUST_SAFETY_COMMENT_RE.test(content)) v.push("unsafe without a // SAFETY: comment. Justify the invariant above each unsafe block.");
+	if (RUST_UNSAFE_RE.test(content) && !RUST_SAFETY_COMMENT_RE.test(raw)) v.push("unsafe without a // SAFETY: comment. Justify the invariant above each unsafe block.");
 	return v;
 }
 //#endregion
+//#region src/policy/js-gate-route.ts
+/**
+* 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 = /* @__PURE__ */ new Map();
+/** Resolve the nearest manifest's capabilities for `filePath` (memoized per dir). */
+function capsFor(filePath, cwd) {
+	const dir = nearestManifestDir(dirname(resolve(cwd, filePath)));
+	if (!dir) return /* @__PURE__ */ 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.
+*/
+function jsGateRoute(filePath, cwd = process.cwd()) {
+	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;
+	}
+}
+//#endregion
+//#region src/policy/conventions/react-hooks.ts
+/**
+* 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).
+*/
+/** 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.
+*/
+function declaresCustomHook(content) {
+	return HOOK_DECL_RE.test(maskCommentsAndStrings(content, "c"));
+}
+//#endregion
+//#region src/policy/framework-solid-extended.ts
+/**
+* Extended convention violations — the NEW rules of the conventions module
+* (owner Amendments 3-5), all advisory-first: the caller wraps them with
+* {@link rolloutVerdict}, so they surface as non-blocking `inform` until
+* `FUSE_CONVENTIONS_MODE=deny`. Only fires when the legacy gates found
+* nothing (no double-reporting of cases the legacy reactGate already blocks).
+*
+* Rules: (1) custom hook outside `hooks/` — widened to `export default`/
+* `async` syntaxes and to the nextjs/tanstack family (legacy covered react
+* only); (2) hook file over its line budget — `hookBudget`, ratio 0.3 of the
+* global `FUSE_SOLID_MAX_LINES` limit (default 30; one variable drives every
+* budget, owner decision — no per-file-kind env vars); (3) TanStack Start
+* route files kept routing-only (no interface declarations in `src/routes/`);
+* (4) store declared outside `stores/` or over `storeBudget` (ratio 0.4);
+* (5) TanStack Query hook defined in a component/page (only when the
+* `@tanstack/*-query` cap is detected in the nearest manifest — `query/` or
+* `hooks/` are both accepted homes); (6) component file misplaced inside
+* `src/hooks|stores|query|interfaces|types/` (deterministic case only).
+*/
+/** TanStack Start content signal (file routes, server fns, start/router imports). */
+const TANSTACK_RE = /createFileRoute|createServerFn|from ['"]@tanstack\/react-(start|router)/;
+/** A custom-hook source file under a hooks directory. */
+const HOOK_FILE_RE = /(^|\/)use[A-Z][^/]*\.(ts|tsx|js|jsx)$/;
+/**
+* Collect the extended convention violations for a JS/TS-family file.
+* @param filePath - The written/edited file's path.
+* @param content - Its raw content (masked internally).
+* @returns The violation messages (empty when clean or out of scope).
+*/
+function extendedViolations(filePath, content) {
+	const v = [];
+	if (!/\.(tsx|ts|jsx|js|vue)$/.test(filePath)) return v;
+	const masked = maskCommentsAndStrings(content, "c");
+	if (declaresCustomHook(content) && !isHooksPath(filePath) && !isStoreOrQueryDefinition(filePath, content)) v.push("Custom hook defined outside hooks/ directory. Move to modules/[feature]/src/hooks/.");
+	if (isHooksPath(filePath) && HOOK_FILE_RE.test(filePath)) {
+		const max = hookBudget(resolveMaxLines());
+		const lines = countFrameworkCodeLines(masked);
+		if (lines > max) v.push(`Hook file has ${lines} lines (limit: ${max}). Extract smaller hooks.`);
+	}
+	if (filePath.includes("/routes/") && TANSTACK_RE.test(masked) && declaresInterface(filePath, content)) v.push("Route files are routing-only. Move the interface to src/modules/[feature]/src/interfaces/.");
+	const storeLib = declaresStore(content, "zustand") ? "zustand" : declaresStore(content, "pinia") ? "pinia" : null;
+	if (storeLib && !isStoresPath(filePath)) v.push("Store defined outside stores/ directory. Move to modules/[feature]/src/stores/.");
+	if (storeLib && isStoresPath(filePath)) {
+		const max = storeBudget(resolveMaxLines());
+		const lines = countFrameworkCodeLines(masked);
+		if (lines > max) v.push(`Store file has ${lines} lines (limit: ${max}).`);
+	}
+	if (isComponentOrPagePath(filePath) && declaresQueryHook(content) && queryCapActive(filePath)) v.push("Query hook defined outside query/ directory. Move to modules/[feature]/src/query/.");
+	if (/\.(tsx|vue)$/.test(filePath)) {
+		const m = /\/src\/(hooks|stores|query|interfaces|types)\//.exec(filePath);
+		if (m && declaresComponent(masked)) v.push(`Component does not belong in ${m[1]}/. Move to modules/[feature]/components/.`);
+	}
+	return v;
+}
+/** Component/page directories where a store or query DEFINITION is a violation. */
+function isComponentOrPagePath(filePath) {
+	return isComponentsPath(filePath) || /\/(pages|app|routes)\//.test(filePath);
+}
+/** True when the file declares an exported component (function/const, Vue SFC
+* `export default {}` or `defineComponent(` included — audit F0 option). */
+function declaresComponent(masked) {
+	return /^\s*export\s+(?:default\s+)?(?:function|const)\s+[A-Z]\w*/m.test(masked) || /^\s*export\s+default\s*\{/m.test(masked) || /defineComponent\s*\(/.test(masked);
+}
+//#endregion
 //#region src/policy/framework-solid.ts
 /** Next.js detection: directive, runtime types, or a `next` import. */
 const NEXT_RE = /(use client|use server|NextRequest|NextResponse|from ['"]next)/;
@@ -414,6 +661,9 @@ function block(filePath, violations) {
 /** Run the JS/TS gate (React or Next.js), honoring build-artifact exclusions. */
 function jsViolations(filePath, content, fileLines) {
 	if (isExcludedJsPath(filePath) || isSelfGateSourcePath(filePath)) return [];
+	const route = jsGateRoute(filePath);
+	if (route === "nextjs") return nextGate(filePath, content, fileLines);
+	if (route === "react") return reactGate(filePath, content, fileLines);
 	return NEXT_RE.test(content) ? nextGate(filePath, content, fileLines) : reactGate(filePath, content, fileLines);
 }
 /**
@@ -431,6 +681,12 @@ function jsViolations(filePath, content, fileLines) {
 */
 function frameworkSolidGate(filePath, content, fileLines) {
 	if (!filePath || !content) return null;
+	if (filePath.endsWith("routeTree.gen.ts")) return {
+		kind: "block",
+		title: "Generated file",
+		reason: `SOLID VIOLATION in ${filePath}: routeTree.gen.ts is generated by TanStack Router — never edit it directly.`,
+		actions: ["Edit the source route files instead, then regenerate"]
+	};
 	let violations = [];
 	if (filePath.endsWith(".php")) {
 		if (isExcludedPhpPath(filePath)) return null;
@@ -441,7 +697,10 @@ function frameworkSolidGate(filePath, content, fileLines) {
 	} else if (/\.(tsx|ts|jsx|js)$/.test(filePath)) violations = jsViolations(filePath, content, fileLines);
 	else if (filePath.endsWith(".go")) violations = goGate(filePath, content, fileLines);
 	else if (filePath.endsWith(".rs")) violations = rustGate(filePath, content, fileLines);
-	return violations.length ? block(filePath, violations) : null;
+	if (violations.length) return block(filePath, violations);
+	if (!/\.(tsx|ts|jsx|js|vue)$/.test(filePath) || isExcludedJsPath(filePath) || isSelfGateSourcePath(filePath)) return null;
+	const extended = extendedViolations(filePath, content);
+	return extended.length ? rolloutVerdict(block(filePath, extended), true) : null;
 }
 //#endregion
 //#region src/policy/skill-patterns/shadcn.ts
@@ -1648,4 +1907,4 @@ function missingSeoElements(html) {
 	return missing;
 }
 //#endregion
-export { MAX_EXA_RESULTS as A, freshnessGate as B, detectRequiredSkills as C, frameworkSolidGate as D, SKILL_TRIGGERS as E, POST_AUTH_GATES as F, PRE_AUTH_GATES as I, brainstormGate as L, capVerbosity as M, detectCreationIntent as N, isExcludedJsPath as O, APEX_GATES as P, docConsultedGate as R, parseField as S, usesTailwindUtilities as T, solidReadGate as V, detectClaudeMdProjectType as _, firstHeading as a, scanPlugin as b, EXCLUDE_DIRS as c, buildApexTaskInjection as d, loadApexTaskState as f, buildClaudeMdContext as g, buildApexInstruction as h, firstComment as i, MAX_TOKENS as j, isExcludedSwiftPath as k, PROJECT_INDICATORS as l, DEV_VERBS as m, missingSeoElements as n, parseEnrichment as o, apexAgentSteps as p, descFromText as r, parseEntry as s, isHtmlLike as t, buildApexTaskContext as u, apexDocName as v, skillTriggerGate as w, parseBodyDesc as x, harnessHomeSegment as y, evaluateApex as z };
+export { importsTanstackQuery as A, APEX_GATES as B, detectRequiredSkills as C, frameworkSolidGate as D, SKILL_TRIGGERS as E, isExcludedSwiftPath as F, evaluateApex as G, PRE_AUTH_GATES as H, MAX_EXA_RESULTS as I, freshnessGate as K, MAX_TOKENS as L, countStores as M, declaresStore as N, declaresCustomHook as O, isExcludedJsPath as P, capVerbosity as R, parseField as S, usesTailwindUtilities as T, brainstormGate as U, POST_AUTH_GATES as V, docConsultedGate as W, detectClaudeMdProjectType as _, firstHeading as a, scanPlugin as b, EXCLUDE_DIRS as c, buildApexTaskInjection as d, loadApexTaskState as f, buildClaudeMdContext as g, buildApexInstruction as h, firstComment as i, queryCapActive as j, declaresQueryHook as k, PROJECT_INDICATORS as l, DEV_VERBS as m, missingSeoElements as n, parseEnrichment as o, apexAgentSteps as p, solidReadGate as q, descFromText as r, parseEntry as s, isHtmlLike as t, buildApexTaskContext as u, apexDocName as v, skillTriggerGate as w, parseBodyDesc as x, harnessHomeSegment as y, detectCreationIntent as z };