@fusengine/harness 0.1.80 → 0.1.83

package/dist/index-DBgnIZn9.d.mts

@@ -0,0 +1,756 @@
+import { t as Prompt } from "./types-C0-igRKr.mjs";
+import { t as AuthEntry } from "./doc-helpers-BGCzP9VF.mjs";
+import { t as RefMeta } from "./types-CY5qT2X1.mjs";
+//#region src/policy/detect-project.d.ts
+/** Project types detected from filesystem indicators. */
+type ProjectType = "nextjs" | "nuxt" | "angular" | "svelte" | "vue" | "react" | "tailwind" | "laravel" | "rails" | "django" | "python" | "go" | "rust" | "swift" | "java" | "scala" | "elixir" | "ruby" | "generic";
+/** Keywords that signal a development task (APEX trigger). */
+declare const DEV_KEYWORDS: RegExp;
+/** True when the prompt invokes the /apex command. */
+declare function isApexCommand(prompt: string): boolean;
+/** Modular architecture variants layered on top of the framework. */
+type ModularArchitecture = "fusecore" | "nextjs-modular" | null;
+/**
+ * Detect a project-internal modular architecture (a sub-architecture the
+ * framework-level {@link detectProjectType} doesn't capture): Fusengine's
+ * FuseCore (Laravel) or a `modules/`-based Next.js layout.
+ */
+declare function detectModularArchitecture(dir: string): ModularArchitecture;
+/**
+ * Resolve the skill a detected modular architecture forces.
+ *
+ * Ports the Python `check-nextjs-skill.py` / `check-laravel-skill.py` gates:
+ * when the project is detected on disk as a modular architecture, a specific
+ * skill is required ('solid-nextjs' for nextjs-modular, 'fusecore' for
+ * fusecore). Returns `null` when no modular architecture is detected.
+ *
+ * @param cwd - Project root directory to scan.
+ * @returns The forced skill name, or `null` when none applies.
+ */
+declare function requiredArchSkill(cwd: string): string | null;
+/** Detect the project type by scanning config files in `dir`. */
+declare function detectProjectType(dir: string): ProjectType;
+//#endregion
+//#region src/policy/detect-framework.d.ts
+/**
+ * Detect a file's framework as the intersection of the REAL project (its nearest
+ * manifest's capabilities) and the file's own extension/content signal. A
+ * backend `.ts` in a react project is `generic` (no react signal) — fixing the
+ * old extension-only default that flagged every `.ts` as react. Fail-open: any
+ * error yields `"generic"`, never throws. Return values stay within the label
+ * union ("react" | "nextjs" | "tanstack-start" | "laravel" | "swift" |
+ * "tailwind" | "java" | "go" | "ruby" | "rust" | "generic") — `tanstack-start`
+ * added 2026-07 (owner spec: first-class framework, Next.js-equivalent).
+ * @param filePath - Path of the file being written/edited.
+ * @param content - Its (incoming) content, for JS content signals.
+ * @param cwd - Root to resolve a relative `filePath` against (default cwd).
+ * @returns A framework label from the union.
+ */
+declare function detectFramework(filePath: string, content: string, cwd?: string): string;
+//#endregion
+//#region src/policy/file-size.d.ts
+/**
+ * Fixed marketplace plugins root — parity with Python `enforce-file-size.py`'s
+ * literal, unexpanded `~/...` string. Exported: reused by
+ * `policy/apex.ts::solidReadGate` for its "no reference matched" deny message.
+ */
+declare const PLUGINS_DIR = "~/.claude/plugins/marketplaces/fusengine-plugins/plugins";
+/**
+ * Skill-dir fragment per framework — parity with Python
+ * `enforce-file-size.py::get_solid_ref()` (falls back to `generic/`). Exported:
+ * reused by `policy/apex.ts::solidReadGate` (see {@link PLUGINS_DIR}).
+ */
+declare const SOLID_REF: Record<string, string>;
+/** Verdict from {@link evaluateFileSize}. */
+interface FileSizeVerdict {
+  ok: boolean;
+  lines: number;
+  max: number;
+  message: string | null;
+}
+/**
+ * Count physical lines — parity with the Python `enforce-file-size.py`
+ * (`sum(1 for _ in f)`): every line counts (blanks and comments included), and a
+ * single trailing newline does not add a phantom line. The SOLID ceiling is
+ * measured on raw file length, not substantive code, to match the upstream plugin.
+ */
+declare function countLines(content: string): number;
+/**
+ * Count non-empty, non-comment lines — parity with the Python `count_code_lines`
+ * shared by the framework-specific SOLID validators: `_shared/scripts/validate_solid_common.py`
+ * (imported by `nextjs-expert/scripts/validate-nextjs-solid.py` and
+ * `swift-apple-expert/scripts/validate-swift-solid.py`), duplicated verbatim in
+ * `react-expert/scripts/validate-react-solid.py` / `laravel-expert/scripts/validate-laravel-solid.py`.
+ * Strips blank lines and lines starting with `//` or `*` — a SINGLE fixed rule
+ * for all 4 callers (the Python `comment` param defaults to, and every real
+ * call site leaves it at, `"//"` — never per-language despite covering
+ * ts/tsx/js/jsx, php and swift).
+ *
+ * Deliberately distinct from two other "code-only" counters already in this
+ * repo, neither of which is a faithful substitute here:
+ *  - `countLoc` (`runtime/lifecycle/check-file-size.ts`): a genuinely
+ *    per-language table (PHP additionally strips `#`, Python strips
+ *    `#`/`"""`/`'''`) — ported from the unrelated `solid/scripts/check-file-size.py`.
+ *  - `countCodeLines` (`runtime/lifecycle/aipilot/solid-compliance.ts`): also
+ *    strips `#` — ported from `ai-pilot/scripts/check-solid-compliance.py`.
+ * Reusing either would silently strip PHP `#`/Python-style comments that the
+ * real react/nextjs/laravel/swift validators do NOT strip.
+ * @param content - The file content to measure.
+ */
+declare function countFrameworkCodeLines(content: string): number;
+/**
+ * Evaluate a file's line count against the SOLID limit.
+ * @param lines - the file's line count
+ * @param max - the limit (defaults to `resolveMaxLines()`)
+ */
+declare function evaluateFileSize(lines: number, max?: number, filePath?: string, framework?: string, displayLines?: number): FileSizeVerdict;
+//#endregion
+//#region src/policy/patterns.d.ts
+/** Destructive git operations to block outright. */
+declare const GIT_BLOCKED: ReadonlyArray<RegExp>;
+/** Git operations that warrant a confirmation prompt. */
+declare const GIT_ASK: ReadonlyArray<RegExp>;
+/** System-level package installs (need confirmation). */
+declare const SYSTEM_INSTALL: ReadonlyArray<RegExp>;
+/** Project-level package installs. */
+declare const PROJECT_INSTALL: ReadonlyArray<RegExp>;
+/** True when `cmd` matches any pattern in `patterns`. */
+declare function matchPatterns(cmd: string, patterns: ReadonlyArray<RegExp>): boolean;
+/** Git commands exempt from confirmation when Ralph mode is on (parity git-guard.py RALPH_SAFE). */
+declare const RALPH_SAFE: ReadonlyArray<string>;
+/**
+ * OPT-IN autonomous "Ralph" mode: OFF unless `RALPH_MODE` is `1`/`true`, read
+ * fresh on each call. Only the env var activates it — the Python source also
+ * auto-enabled on a `.claude/ralph/prd.json` file or a `feature/*` branch, but
+ * those silent activations are dropped here: a mode that removes git/install
+ * confirmations must never turn on implicitly (owner: default OFF, env opt-in).
+ */
+declare function isRalphMode(): boolean;
+//#endregion
+//#region src/policy/interfaces/types.d.ts
+/** Harness-agnostic input to {@link evaluate}. */
+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). */
+interface PolicyResult {
+  decision: "allow" | "deny" | "warn";
+  message: string | null;
+  prompt?: Prompt;
+  meta?: Record<string, unknown>;
+}
+//#endregion
+//#region src/policy/evaluate.d.ts
+/**
+ * Evaluate a single tool-use against the bundled policies, returning a pure
+ * decision plus a portable {@link Prompt}. Adapters translate the prompt into
+ * their harness's native response (Claude `permissionDecision`, etc.).
+ */
+declare function evaluate(ctx: PolicyContext): PolicyResult;
+//#endregion
+//#region src/policy/apex-gates.d.ts
+/** Gate: the routed SOLID references for this edit must have been read within the TTL. */
+declare const solidReadGate: ApexGate;
+/** Gate: the required prior agents (explore + research) must have run within the window. */
+declare const freshnessGate: ApexGate;
+//#endregion
+//#region src/policy/apex.d.ts
+/**
+ * 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).
+ */
+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. */
+type ApexGate = (ctx: ApexContext) => Prompt | null;
+/** Gate: BOTH Context7 AND Exa (or a web fallback alone) must have been consulted this session. */
+declare const docConsultedGate: ApexGate;
+/** Gate: brainstorming must precede creating new files when flagged. */
+declare const brainstormGate: ApexGate;
+/** Gates that run BEFORE Check 1 (harness-specific brainstorm + agent freshness, pre-dating enforce-apex-phases). */
+declare const PRE_AUTH_GATES: ReadonlyArray<ApexGate>;
+/** Gates that run AFTER Check 1: Check 2 (doc consulted once per session) then the SOLID refs. */
+declare const POST_AUTH_GATES: ReadonlyArray<ApexGate>;
+/**
+ * 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.
+ */
+declare const APEX_GATES: ReadonlyArray<ApexGate>;
+/**
+ * Run the APEX gates (chain-of-responsibility): the first failing gate's prompt
+ * wins; null means every gate passed (allow).
+ */
+declare function evaluateApex(ctx: ApexContext, gates?: ReadonlyArray<ApexGate>): Prompt | null;
+//#endregion
+//#region src/policy/guards/context.d.ts
+/** Context handed to every guard in the chain. */
+interface GuardContext {
+  tool: string;
+  filePath?: string;
+  content?: string;
+  command?: string;
+}
+/** A single guard: returns a blocking/asking Prompt, or null to continue. */
+type Guard = (ctx: GuardContext) => Prompt | null;
+//#endregion
+//#region src/policy/guards/security.d.ts
+/** A pattern paired with the violation label to name in the deny/ask reason. */
+interface LabeledPattern {
+  re: RegExp;
+  label: string;
+}
+/** Critical patterns that must always be blocked — parity `security_rules.py`'s cumulated violation names. */
+declare const CRITICAL_PATTERNS: LabeledPattern[];
+/** Patterns that warrant explicit confirmation before running — parity `security_rules.py`'s ask-level violation names. */
+declare const ASK_PATTERNS: LabeledPattern[];
+/**
+ * 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)`).
+ */
+declare function securityGuard(ctx: GuardContext): Prompt | null;
+//#endregion
+//#region src/policy/guards/protected-path.d.ts
+/**
+ * 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.
+ */
+declare const PROTECTED_FRAGMENTS: readonly string[];
+/**
+ * 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.
+ */
+declare const PROTECTED_GIT_RE: RegExp;
+/**
+ * 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.
+ */
+declare function protectedPathGuard(ctx: GuardContext): Prompt | null;
+//#endregion
+//#region src/policy/guards/bash-write-patterns.d.ts
+/** Redirect (`>`/`>>`) targeting a code-file extension. */
+declare const CODE_REDIRECT: RegExp;
+/**
+ * Interpreters / tools that mutate source in place, plus heredoc-into-file —
+ * split into labeled sub-patterns (parity bash-write-guard.py `DENY_PATTERNS`,
+ * each with its own `desc`) so the deny reason names which motif matched
+ * instead of a single generic message. Every command-named motif is
+ * {@link CMD}-anchored (start/separator + optional wrapper chain); only the
+ * structural heredoc-into-file motif is position-free.
+ */
+declare const CODE_MUTATORS: readonly {
+  re: RegExp;
+  desc: string;
+}[];
+/** Redirect to a non-code file. Excludes `/dev/null`, `2>`/`N>` and `>&N` fd
+ * redirects via the `(?<![0-9&])` lookbehind + `(?!…|&)` (parity has_file_redirect). */
+declare const FILE_REDIRECT: RegExp;
+/** Other ambiguous file writers (ASK): `tee <file>` (not `tee -a`/path) and `dd … of=` —
+ * labeled sub-patterns (parity bash-write-guard.py `ASK_PATTERNS`). */
+declare const ASK_WRITERS: readonly {
+  re: RegExp;
+  desc: string;
+}[];
+/** Commands whose first token never writes, skipped when a real redirect is
+ * present (parity bash-write-guard.py `SAFE_PREFIXES`). */
+declare const SAFE_PREFIXES: readonly string[];
+/**
+ * Session-state directory the freshness/APEX gates rely on. Any Bash command
+ * touching it is a hook-bypass vector, so it is blocked outright — a blunt
+ * substring match (read OR write), parity with bash-write-guard.py DENY_PATTERNS
+ * `fusengine-cache/sessions` (rebranded to the harness cache path).
+ */
+declare const SESSION_STATE_FRAGMENT = ".fuse-harness/cache/sessions";
+//#endregion
+//#region src/policy/guards/bash-write.d.ts
+/**
+ * Blocks shell commands that mutate code files in place (and heredocs/redirects
+ * to source files); asks before other file-writing shell commands unless the
+ * target is a harness-owned safe path. Forces use of the Write/Edit tool so
+ * APEX/SOLID checks are not bypassed.
+ *
+ * The code-write detectors (CODE_MUTATORS, CODE_COMMAND_WRITE) run BEFORE the
+ * SAFE_PREFIXES short-circuit: they are command-position anchored
+ * (bash-command-anchor.ts), so a transparent wrapper (`env sed -i src/x.ts`,
+ * `timeout 5 patch`, `cp a b; tee src/y.ts`) can no longer smuggle a code write
+ * past its safe first token, while a quoted mention (`git commit -m "fix sed -i"`)
+ * still falls through. The short-circuit becomes the terminal allow — "first
+ * token never writes, nothing above matched".
+ */
+declare function bashWriteGuard(ctx: GuardContext): Prompt | null;
+//#endregion
+//#region src/policy/guards/interface-separation.d.ts
+/** TS/JS component files: top-level `interface`/`type Foo`. */
+declare const TS_DECL_RE: RegExp;
+/** Python view models: class subclassing a schema/protocol base. */
+declare const PY_MODEL_RE: RegExp;
+/**
+ * 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).
+ */
+declare const PHP_DECL_RE: RegExp;
+/** Swift views: top-level `protocol Foo`. */
+declare const SWIFT_PROTO_RE: RegExp;
+/** Go handlers/controllers: top-level `type Foo interface`. */
+declare const GO_DECL_RE: RegExp;
+/** Java/Kotlin controllers/handlers: top-level `interface`/`record`. */
+declare const JAVA_DECL_RE: RegExp;
+/** Rust: top-level `trait Foo` declaration (captures the name for impl co-location). */
+declare const RUST_DECL_RE: RegExp;
+/**
+ * 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/`).
+ */
+declare function interfaceSeparationGuard(ctx: GuardContext): Prompt | null;
+//#endregion
+//#region src/policy/guards/install.d.ts
+/**
+ * Asks for confirmation before a dependency or system package install. In Ralph
+ * mode (opt-in `RALPH_MODE`) a PROJECT install is auto-approved for autonomous
+ * runs (parity install-guard.py:52), but a SYSTEM install always asks.
+ */
+declare function installGuard(ctx: GuardContext): Prompt | null;
+//#endregion
+//#region src/policy/guards/index.d.ts
+/** Ordered guard chain: critical/security + protected first, then writes/installs. */
+declare const GUARDS: ReadonlyArray<Guard>;
+/** Block prompt returned when a guard or gate throws (fail-closed). */
+declare const FAIL_CLOSED: Prompt;
+/** Register a user guard — runs AFTER the privileged core chain (two-tier). */
+declare function registerGuard(guard: Guard): void;
+/** Remove all registered user guards (mainly for tests). */
+declare function clearUserGuards(): void;
+/**
+ * Run the guard chain — privileged core guards first, then user guards — and
+ * return the first firing Prompt, else null. Fail-closed: a guard that throws
+ * blocks (never silently passes).
+ */
+declare function runGuards(ctx: GuardContext): Prompt | null;
+//#endregion
+//#region src/policy/creation-intent.d.ts
+/**
+ * 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`.
+ */
+declare function detectCreationIntent(prompt: string): boolean;
+//#endregion
+//#region src/policy/verbosity.d.ts
+/** Max results an exa MCP call may request. */
+declare const MAX_EXA_RESULTS = 3;
+/** Max token budget for exa `tokensNum` / context7 `tokens`. */
+declare const MAX_TOKENS = 2e3;
+/**
+ * Cap an MCP call's verbosity — exa `numResults` ≤ 3 (+ `tokensNum` ≤ 2000),
+ * Context7 `tokens` ≤ 2000. Returns the capped input (a mutation for the harness
+ * to apply) when a change is needed, else null.
+ */
+declare function capVerbosity(tool: string, input: Record<string, unknown>): Record<string, unknown> | null;
+//#endregion
+//#region src/policy/framework-solid.d.ts
+/**
+ * Framework-specific SOLID gate. Dispatches by extension/path to the matching
+ * validator (React, Next.js, Laravel, Swift, Go, Rust) and returns a blocking
+ * {@link Prompt} when any BLOCKING rule fires, or `null` when clean. Excluded
+ * build/dependency paths (node_modules, dist, build, .next, vendor, .build,
+ * DerivedData, Pods) early-return `null` to avoid false positives. Go and Rust
+ * have no exclusion list yet (no vendor/target FPs reported) — additive only.
+ * @param filePath - absolute path of the file being written/edited
+ * @param content - the file (or new) content under validation
+ * @param fileLines - full on-disk line count (set on Edit so a partial
+ *   `new_string` snippet still judges the whole file, mirroring the base
+ *   file-size guard / Python `get_full_file_content`). Omit on Write.
+ */
+declare function frameworkSolidGate(filePath: string, content: string, fileLines?: number): Prompt | null;
+//#endregion
+//#region src/policy/skill-trigger-patterns.d.ts
+/** Map of required sub-skill name → triggering code patterns, keyed by framework. */
+declare const SKILL_TRIGGERS: Readonly<Record<string, Readonly<Record<string, ReadonlyArray<string>>>>>;
+//#endregion
+//#region src/policy/skill-triggers.d.ts
+/**
+ * Detect which sub-skills the written `content` requires for a `framework`.
+ * Faithful to the Python `detect_required_skills`: first matching pattern per
+ * skill wins. Most frameworks match case-insensitively (source `re.IGNORECASE`);
+ * `swift` matches case-sensitively (see {@link CASE_SENSITIVE_FRAMEWORKS}).
+ * @param framework - "react" | "nextjs" | "laravel" | "swift".
+ * @param content - the code being written.
+ * @returns required sub-skill names (empty when framework unknown / no match).
+ */
+declare function detectRequiredSkills(framework: string, content: string): string[];
+/**
+ * True when `filePath`/`content` match the Python Tailwind gate's trigger
+ * condition. React/Next.js components embed Tailwind utility classes in
+ * `className` — this check fires IN ADDITION TO the primary framework gate,
+ * never instead of it: {@link detectFramework} keeps returning "react"/
+ * "nextjs" for these files (framework SOLID rules stay correct).
+ */
+declare function usesTailwindUtilities(filePath: string, content: string): boolean;
+/**
+ * Block when a required sub-skill's `skills/<name>/` path is absent from
+ * `refsRead`. Mirrors `specific_skill_consulted`, which confirms a skill was
+ * read by checking the tracking file contains `skills/<name>/`.
+ * @param framework - "react" | "nextjs" | "laravel".
+ * @param content - the code being written.
+ * @param refsRead - in-session read reference paths.
+ * @param forcedSkill - a skill the detected modular architecture forces (optional).
+ * @param cwd - project root; when set and not a shadcn project, `*-shadcn`
+ *   requirements are skipped (ports the Python `is_shadcn_project` filter).
+ * @param filePath - the file being written; when it's a `.tsx`/`.jsx` file
+ *   with Tailwind utility classes in `className`, the "tailwind" domain
+ *   skills are merged in alongside `framework`'s own (ports the separate
+ *   `check-tailwind-skill.py` gate, independent of react/nextjs).
+ * @returns a `block` Prompt naming the missing sub-skills, or `null` when satisfied.
+ */
+declare function skillTriggerGate(framework: string, content: string, refsRead: readonly string[], forcedSkill?: string | null, cwd?: string, filePath?: string): Prompt | null;
+//#endregion
+//#region src/policy/detect-claude-md-project-type.d.ts
+/**
+ * Detect the project type from the cwd, reproducing the legacy Python logic:
+ * package.json containing "next" → nextjs, else "react" → react; else
+ * composer.json+artisan → laravel; else Package.swift / *.xcodeproj → swift;
+ * else generic.
+ * @param cwd - Project root to scan.
+ * @returns The detected project type label.
+ */
+declare function detectClaudeMdProjectType(cwd: string): ProjectType;
+//#endregion
+//#region src/policy/claude-md-context.d.ts
+/** Dev-verb regex (FR/EN) that triggers the APEX preamble (case-insensitive). */
+declare const DEV_VERBS: RegExp;
+/**
+ * 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.
+ */
+declare function buildApexInstruction(projectType: ProjectType, maxLines: number, id?: string): string;
+/**
+ * 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.
+ */
+declare function buildClaudeMdContext(prompt: string, cwd: string, id?: string): string | null;
+//#endregion
+//#region src/policy/apex-task-context.d.ts
+/** Parsed task state injected into a Task sub-agent prompt. */
+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}.
+ */
+declare function loadApexTaskState(taskFile: string): ApexTaskState;
+/**
+ * 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.
+ */
+declare function buildApexTaskContext(state: ApexTaskState, maxLines: number, id?: string): string;
+/**
+ * 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.
+ */
+declare function buildApexTaskInjection(projectRoot: string, id?: string): string | null;
+//#endregion
+//#region src/policy/cartographer/indicators.d.ts
+/**
+ * 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. */
+declare const PROJECT_INDICATORS: ReadonlySet<string>;
+/** Directory names skipped entirely during the tree walk. */
+declare const EXCLUDE_DIRS: ReadonlySet<string>;
+//#endregion
+//#region src/policy/cartographer/frontmatter.d.ts
+/**
+ * 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 "".
+ */
+declare function parseField(text: string, field: string): string;
+/**
+ * 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 "".
+ */
+declare function parseBodyDesc(text: string, maxLen?: number): string;
+//#endregion
+//#region src/policy/cartographer/entry.d.ts
+/**
+ * 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. */
+interface TreeEntry {
+  prefix: string;
+  name: string;
+  path: string;
+  desc: string;
+}
+/**
+ * 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.
+ */
+declare function parseEntry(line: string): TreeEntry | null;
+/**
+ * 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.
+ */
+declare function parseEnrichment(line: string): [string, string] | null;
+//#endregion
+//#region src/policy/cartographer/describe.d.ts
+/**
+ * First `# ` Markdown heading text (sans hashes), sliced to 60. "" when none.
+ * @param text - The document text.
+ * @returns The heading text, or "".
+ */
+declare function firstHeading(text: string): string;
+/**
+ * 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 "".
+ */
+declare function firstComment(text: string): string;
+/**
+ * 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 "".
+ */
+declare function descFromText(suffix: string, text: string, mdField: string): string;
+//#endregion
+//#region src/policy/seo/validate.d.ts
+/** True when `path` is an HTML-like file the SEO hook should validate. */
+declare function isHtmlLike(path: string): boolean;
+/**
+ * Report the SEO elements missing from HTML-like content (title, meta
+ * description, OG title/description/image, canonical, JSON-LD schema).
+ * @param html - The file content.
+ * @returns The missing element labels (empty when complete).
+ */
+declare function missingSeoElements(html: string): string[];
+//#endregion
+//#region src/policy/conventions/strip.d.ts
+/**
+ * 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. */
+type LexProfile = "c" | "py" | "rb" | "php";
+/**
+ * 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.
+ */
+declare function maskCommentsAndStrings(content: string, profile: LexProfile): string;
+/**
+ * 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.
+ */
+declare function maskCommentsOnly(content: string, profile: LexProfile): string;
+//#endregion
+//#region src/policy/conventions/langs.d.ts
+/** Language family a convention rule applies to, or null when out of scope. */
+type LangFamily = "ts" | "py" | "go" | "rs" | "java" | "php" | "swift" | "rb" | "vue";
+/** Language family for a file path (by extension), or null when unsupported. */
+declare function langOfPath(filePath: string): LangFamily | null;
+/** Lexical profile for masking, derived from the language family. */
+declare function lexProfileOf(lang: LangFamily): LexProfile;
+/** True for dotfiles/dependency dirs never subject to conventions. */
+declare function isVendorPath(filePath: string): boolean;
+/** Path predicates — canonical convention directories. */
+declare const isInterfacesPath: (p: string) => boolean;
+declare const isTypesPath: (p: string) => boolean;
+declare const isHooksPath: (p: string) => boolean;
+declare const isStoresPath: (p: string) => boolean;
+declare const isQueryPath: (p: string) => boolean;
+declare const isComponentsPath: (p: string) => boolean;
+//#endregion
+//#region src/policy/conventions/interfaces.d.ts
+/** Detection level: historical semantics (hard deny) vs advisory widening. */
+type InterfaceDeclLevel = "legacy" | "extended";
+/**
+ * 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).
+ */
+declare function interfaceDeclLevel(filePath: string, content: string): InterfaceDeclLevel | 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).
+ */
+declare function declaresInterface(filePath: string, content: string): boolean;
+/**
+ * True when a TS-family file declares an EXPORTED type alias (masked scan).
+ * @param content - Raw file content.
+ */
+declare function declaresExportedTypeAlias(content: string): boolean;
+//#endregion
+//#region src/policy/conventions/react-hooks.d.ts
+/**
+ * True when the file declares an exported custom `use*` hook (masked scan).
+ * @param content - Raw file content.
+ */
+declare function declaresCustomHook(content: string): boolean;
+//#endregion
+//#region src/policy/conventions/stores.d.ts
+/** Store library whose declarations are being scanned. */
+type StoreLib = "zustand" | "pinia";
+/**
+ * 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.
+ */
+declare function declaresStore(content: string, lib: StoreLib): boolean;
+/**
+ * Count store declarations in one file (multi-store advisory: one per domain).
+ * @param content - Raw file content.
+ * @param lib - Store library to count.
+ */
+declare function countStores(content: string, lib: StoreLib): number;
+//#endregion
+//#region src/policy/conventions/query.d.ts
+/**
+ * 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.
+ */
+declare function importsTanstackQuery(content: string): boolean;
+/**
+ * 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.
+ */
+declare function declaresQueryHook(content: string): boolean;
+/**
+ * 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).
+ */
+declare function queryCapActive(filePath: string): boolean;
+//#endregion
+export { detectCreationIntent as $, countFrameworkCodeLines as $t, TreeEntry as A, APEX_GATES as At, loadApexTaskState as B, evaluate as Bt, maskCommentsAndStrings as C, protectedPathGuard as Ct, descFromText as D, securityGuard as Dt, missingSeoElements as E, LabeledPattern as Et, EXCLUDE_DIRS as F, brainstormGate as Ft, detectRequiredSkills as G, PROJECT_INSTALL as Gt, buildApexInstruction as H, PolicyResult as Ht, PROJECT_INDICATORS as I, docConsultedGate as It, SKILL_TRIGGERS as J, isRalphMode as Jt, skillTriggerGate as K, RALPH_SAFE as Kt, ApexTaskState as L, evaluateApex as Lt, parseEntry as M, ApexGate as Mt, parseBodyDesc as N, POST_AUTH_GATES as Nt, firstComment as O, Guard as Ot, parseField as P, PRE_AUTH_GATES as Pt, capVerbosity as Q, SOLID_REF as Qt, buildApexTaskContext as R, freshnessGate as Rt, LexProfile as S, PROTECTED_GIT_RE as St, isHtmlLike as T, CRITICAL_PATTERNS as Tt, buildClaudeMdContext as U, GIT_ASK as Ut, DEV_VERBS as V, PolicyContext as Vt, detectClaudeMdProjectType as W, GIT_BLOCKED as Wt, MAX_EXA_RESULTS as X, FileSizeVerdict as Xt, frameworkSolidGate as Y, matchPatterns as Yt, MAX_TOKENS as Z, PLUGINS_DIR as Zt, isStoresPath as _, CODE_REDIRECT as _t, countStores as a, ProjectType as an, installGuard as at, langOfPath as b, SESSION_STATE_FRAGMENT as bt, InterfaceDeclLevel as c, isApexCommand as cn, PHP_DECL_RE as ct, interfaceDeclLevel as d, SWIFT_PROTO_RE as dt, countLines as en, FAIL_CLOSED as et, LangFamily as f, TS_DECL_RE as ft, isQueryPath as g, CODE_MUTATORS as gt, isInterfacesPath as h, ASK_WRITERS as ht, StoreLib as i, ModularArchitecture as in, runGuards as it, parseEnrichment as j, ApexContext as jt, firstHeading as k, GuardContext as kt, declaresExportedTypeAlias as l, requiredArchSkill as ln, PY_MODEL_RE as lt, isHooksPath as m, bashWriteGuard as mt, importsTanstackQuery as n, detectFramework as nn, clearUserGuards as nt, declaresStore as o, detectModularArchitecture as on, GO_DECL_RE as ot, isComponentsPath as p, interfaceSeparationGuard as pt, usesTailwindUtilities as q, SYSTEM_INSTALL as qt, queryCapActive as r, DEV_KEYWORDS as rn, registerGuard as rt, declaresCustomHook as s, detectProjectType as sn, JAVA_DECL_RE as st, declaresQueryHook as t, evaluateFileSize as tn, GUARDS as tt, declaresInterface as u, RUST_DECL_RE as ut, isTypesPath as v, FILE_REDIRECT as vt, maskCommentsOnly as w, ASK_PATTERNS as wt, lexProfileOf as x, PROTECTED_FRAGMENTS as xt, isVendorPath as y, SAFE_PREFIXES as yt, buildApexTaskInjection as z, solidReadGate as zt };